Claude Code 如何載入 CLAUDE.md 與 Skills，並以按需載入管理上下文

In the first article of this series we put four 2026 context-engineering principles on one map. This one covers the first of them: how Claude Code actually loads context, why extra context costs accuracy and not just tokens, and what we did about it on our own systems.

TL;DR.

1. The root CLAUDE.md is the exception. It enters the context at the start of the session and is included in full in every request.
2. Skills load only their name and description at first. The body loads when the skill triggers. This is just-in-time context: pointers stay in the window, and the content is pulled in as the work goes.
3. We applied the same principle to our own files: one routing rule (Task Complexity Levels), and a root file cut from 238 lines to about 80.
4. On our systems we noticed that the agent started using fewer tokens, especially in cross-service development.

The problem: a monolith in every request

When we started building our own harness and moving development to an agentic SDLC, the first wall we hit was context management inside our services. We have dozens of services, and each one has its own CLAUDE.md. Before we could fix that, we had to understand how Claude works with context in the first place.

A typical root file was about 238 lines long and loaded in full into every request. The agent needs to fix one test in a service, and the context already holds the schemas, configs, and migration notes of every module in that service. If a task touches three services, three of these files end up in the context in full, even though only a small part of each is needed.

On top of that, the agent still did not know which parts mattered for the task, so it rebuilt the picture from scratch: it grepped through message-queue configs, read proto files, and opened go.mod. And we paid for all of that in tokens on every turn.

Extra context costs accuracy, not just tokens

Anthropic calls this context rot: a model has a limited "attention budget," and the more tokens sit in the window, the worse it gets at finding what it needs. Hence their principle: keep the smallest possible set of high-signal tokens in context.

A note on scale: one root file will not break a model, and the length effects were measured on contexts of several thousand tokens and up. But an agent's context accumulates: files it has read, grep output, and turn history pile up on top of the monolith. The monolith becomes a layer of noise at the base of every request.

How Claude Code loads context

Claude Code builds its context in layers, and almost every layer loads only when it is actually needed.

The root CLAUDE.md is the exception. It enters the context at the start of the session and is included in full in every request. 238 lines is roughly 1,500 tokens that the model sees on every turn, whatever the task is about.

A CLAUDE.md in a nested directory, such as internal/<subsystem>/CLAUDE.md, loads automatically, but only when the agent starts working with files in that directory. Other documents, such as docs/context/*.md, never load on their own: the agent reads them when the task calls for it.

Skills work the same way, just in three steps. At startup, only each skill's name and description enter the context: tens of tokens, about 100 at most. The SKILL.md body loads when the skill triggers, and nested files load later still, if the body references them.

So everything except the root CLAUDE.md loads on demand. That one exception is exactly where the leverage is.

Just-in-time context

Anthropic calls this behavior just-in-time context: the window holds lightweight identifiers (paths, links, a compact index), and heavy data is pulled in as the work goes.

One important detail: the root map loads upfront, so it is not just-in-time itself. It is the index that makes just-in-time possible: the agent uses it to find module files and docs/context/*. The job of the root file is to be a compact map, not to contain the whole territory.

Skills are ready-made proof that the approach works: Claude Code already keeps only their name and description in the window. Our 238-line CLAUDE.md broke a rule that the tool itself already follows.

One routing level is enough

Progressive disclosure means revealing detail in stages. The finding from arXiv:2607.17598 is narrow and practical: one routing level is enough, and a second one "never helps and sometimes breaks accuracy." So you need one level, not a decision tree.

What we did

We wrote that routing level down as an instruction in the root CLAUDE.md and called it Task Complexity Levels:

The agent picks the level itself. We only wrote down the rule.

The file layout: pointers on top, details loaded on demand.

# Loaded into every request, so we keep it compact:
#   root CLAUDE.md = a navigation map (~80 lines), not a manual

<service-root>/
├── CLAUDE.md                 # map + Task Complexity Levels   (POINTERS, upfront)
├── docs/context/
│   ├── service.yaml          # machine-readable index          (DETAILS, on demand)
│   ├── integrations.md       # cross-service links             (DETAILS, level 4)
│   ├── systemPatterns.md     # architecture patterns           (DETAILS, level 3)
│   └── errors.md             # production error catalog        (DETAILS, on incident)
└── internal/<subsystem>/
    └── CLAUDE.md             # module details                  (DETAILS, auto-loaded)

The root file shrank from about 238 lines to about 80. That is roughly 900 fewer tokens in every request, before the agent reads a single detail file.

Third-party benchmarks point the same way: RepoGraph reports an average relative gain of 32.8% in resolve rate across four methods on SWE-bench-Lite (arXiv:2410.14684), and in "Less Context, Better Agents" the share of complete answers rose from 71.0% to 91.6% while tokens dropped by 62.6% (arXiv:2606.10209).

Cline Memory Bank, minus its main rule

We took the file set from Cline Memory Bank (projectBrief, productContext, systemPatterns, techContext), where context is already split by how often it changes. But we dropped its central rule: "I MUST read ALL memory bank files at the start of EVERY task." That rule loads every detail upfront, which is exactly what we were moving away from. Same files, opposite loading strategy.

Tradeoffs

• A human writes the map. It pays off: in the ETH study, files written by developers beat generated ones (p=0.038), while generated files mostly add cost (arXiv:2602.11988).
• The agent picks the level. That is a real decision, and the agent can get it wrong, which is why there is only one level and no tree.
• The map assumes the detail files are up to date. If integrations.md is stale, a level 4 task will rely on wrong data. Keeping files fresh needs its own mechanism, and that is the topic of a later article in this series.
• The root map still loads every time. The win is not loading nothing. It is an 80-line index instead of a 238-line monolith. If the map grows, the win disappears.

Why fewer tokens does not automatically mean less money is the subject of the next article.

Conclusion

A context file should be an index that triggers just-in-time loading, not cargo that sits in the window all day. The right question is not "how many lines should CLAUDE.md have," but "what belongs in the window on every request (pointers), and what should load on demand (details)." Answer that, and the line count takes care of itself.

Next in the series: how trimming context affects answer quality, and why fewer tokens does not mean a smaller bill.

Sources

• Anthropic: just-in-time context / effective context engineering (Anthropic Engineering; "Equipping agents with Agent Skills")
• Progressive disclosure: arXiv:2607.17598 ("Is Progressive Disclosure All You Need for Long-Context Agents?")
• Repo-map benchmark: RepoGraph (arXiv:2410.14684)
• Less but more relevant: "Less Context, Better Agents" (arXiv:2606.10209)
• Hand-written beats generated: "Evaluating AGENTS.md" (arXiv:2602.11988)
• Irrelevant context distracts: Shi et al., "Large Language Models Can Be Easily Distracted by Irrelevant Context" (ICML 2023, arXiv:2302.00093)
• Position in context: Liu et al., "Lost in the Middle: How Language Models Use Long Contexts" (TACL, arXiv:2307.03172)
• Effect of length: "Context Length Alone Hurts LLM Performance Despite Perfect Retrieval" (arXiv:2510.05381)
• Chroma, "Context Rot: How Increasing Input Tokens Impacts LLM Performance" (research.trychroma.com/context-rot)
• Anthropic, "Effective context engineering for AI agents" (context rot, attention budget)
• Cline Memory Bank (Nick Baumann): github.com/cline/prompts