Running /init to generate a CLAUDE.md file has become a standard ritual for developers using AI coding agents. The pitch is easy to like: one command scans your repository and writes a guide covering your stack, structure, and conventions. But that "one-click" configuration is a dead end. It degrades agent performance instead of improving it.
Running /init creates redundant, stale, and expensive context that burdens the model's
reasoning.
By flooding the system prompt with discoverable data, you force the agent into inference reconciliation — it must resolve the static markdown file against the actual source of truth in your code.
That redundancy dilutes context and raises operational costs with no matching gain in accuracy.
What /init actually generates — and why most of it is redundant
Run /init and the agent usually spins up a sub-agent to scan the whole repository. That scan produces a high-level overview, command listings from package.json, and general architecture descriptions. On recent models the pattern is consistent: Sonnet 4.5 generates these overviews 100% of the time, GPT-5.2 in 99% of cases.
All of it is redundant. Coding agents scan package.json, tsconfig.json, and directory trees on their own before the first user prompt is even processed. Copy that "source of truth" into a markdown file and you pay a reconciliation penalty: the agent processes the same facts twice — once from the code, once from the CLAUDE.md — which drives up reasoning token counts and slows execution.
Theo's "Lawn" project experiment makes this concrete. A task ran in 1 minute 11 seconds with no CLAUDE.md. The same task, weighed down by a freshly generated /init file, took 1 minute 29 seconds — a 25% time penalty. The agent spent more time navigating its own redundant summary than reading the actual codebase. If it can already discover that a project uses Next.js or Effect during its exploration phase, writing that into a global file adds nothing and only increases token pressure.
How Claude uses context: the instruction budget and the always-loaded problem
Agentic workflows run on an instruction budget. Modern LLMs have huge context windows for data, but the number of instructions they can follow at once is limited — generally 300 to 400 rules. Every line in a CLAUDE.md counts as a global instruction the agent has to track for the entire session.
The globality problem is that these instructions load for every task, regardless of relevance. A rule about React component patterns stays in the context window even while the agent runs a backend database migration or updates documentation. The result is context dilution: the agent's attention splits between the current task and irrelevant global constraints.
| Phase | Purpose | Flexibility |
|---|---|---|
| System Prompt | Hardwired instructions, MCP tools, and CLAUDE.md content | Not flexible: hardwired at the start of every session |
| Exploration | Just-in-time discovery of file structures and dependencies | High: loads only what the specific task requires |
| Implementation | Writing code and modifying the file system | High: scales with the complexity of the change |
| Testing | Running feedback loops, unit tests, and debugging | High: can balloon if the implementation fails |
Because the System Prompt phase is fixed, every extra line in the CLAUDE.md eats directly into the capacity left for Exploration and Implementation. Engineering for efficiency means keeping that fixed context as small as possible, so there is more room for task-specific reasoning.
The real cost: more tokens, lower quality, stale docs
The Lulla et al. (2026) study puts numbers on the gap between auto-generated and human-maintained context. Human-authored files — the ones that capture a project's specific "gotchas" — cut wall-clock runtime by 28.64% and output token consumption by 16.58%. The ETH Zurich study points the other way for generated files: LLM-written context dropped task success by 2–3% while raising operational costs by more than 20%.
The dip usually traces back to the "pink elephant" problem — anchoring bias. If an auto-generated CLAUDE.md names a legacy technology like tRPC in its overview, the model leans toward that pattern on every prompt. Even when tRPC covers only 5% of the repo, its place in the global context makes the agent weigh it for every new feature, often pulling the model away from the modern standards the rest of the code already uses.
Documentation rot turns these files into liabilities. Unlike source code, which a compiler verifies, a CLAUDE.md is a static artifact. Move a service or rename a directory without updating the file and the agent is misled — it tries to open paths that no longer exist or follows deprecated patterns, burning tokens in failed execution loops. Stale context is worse than no context; it hands the agent a false map of the terrain.
What a good CLAUDE.md should contain (and what it shouldn't)
To earn a line in a CLAUDE.md, a piece of information has to clear three bars: it has to matter operationally, apply globally, and be impossible for the agent to discover by reading code. The uv vs. pip package-manager choice is the textbook case. An agent sees a requirements.txt, defaults to pip, and never learns about the strict internal requirement to use uv. ETH Zurich found that when uv was named explicitly, agents reached for it 1.6 times per task; when it was left out, usage fell below 0.01.
A high-performance CLAUDE.md is nearly empty, focusing only on environment-specific landmines:
# Project Rules
- You are on WSL on Windows (handles specific path resolution issues).
- Use uv for all package management; do not use pip.
- The auth module uses a custom middleware pattern; do not refactor to standard Express.What to exclude:
- Command listings: the agent reads
package.jsonscripts faster and more accurately than a summary. - Architecture summaries: "this is a Next.js app" wastes tokens; the agent sees
next.config.js. - File references: avoid specific paths that change during refactoring.
- General patterns: if a linter enforces the pattern, the global file doesn't need to.
For the full picture of what does belong in the file, see our guide to CLAUDE.md best practices.
Instead of /init: grow your CLAUDE.md organically
The most efficient developers treat CLAUDE.md as a corrections file. Start with an empty document. Add a targeted instruction only when the agent makes a mistake or trips over a non-obvious convention. Every line then earns its place through real friction.
A better mental model: treat the file as a diagnostic tool. Drop in an instruction like "If you encounter something surprising or confusing in this project, flag it." The flags it raises point at codebase smells. Often the right move is not to update the CLAUDE.md at all but to fix the underlying code, reorganize the directory structure, or add a linter rule — anything that makes the codebase self-documenting for the agent.
For teams running agents at scale, automated optimization beats writing the file by hand. Arize AI ran an optimization loop — an LLM gives feedback on its own failures — and got a 5.19% accuracy boost on cross-repo tests and 10.87% on in-repo tasks. The gap between what we think an agent needs and what actually moves the needle is wide.
Better architecture: layered context engineering
The flat, monolithic file is the bottleneck. Senior engineers are moving toward the ACE framework (Agentic Context Engineering), which beat static files by 12.3% in recent benchmarks. It splits context into three layers:
- The protocol file. This is the new role for CLAUDE.md — not a summary but a routing document. It lists available personas, available skills, and the absolute minimum of undiscoverable environmental facts (like the WSL pathing issue).
- Focused personas and skills. Task-specific instruction sets loaded only when needed. A frontend agent debugging CSS should not load backend database-optimization context, which keeps the instruction budget free of irrelevant rules.
- Maintenance subagents. Specialized agents whose sole job is to keep the protocol file and skill sets accurate as the codebase evolves, preventing documentation rot.
FAQ
Does a root CLAUDE.md scale to complex repos? No. In large codebases a single file conflates concerns across disparate modules. Use a routing layer or directory-level context files so the agent only receives instructions relevant to the local module, preventing context dilution.
Should I use subagents instead of a large CLAUDE.md? Yes. Subagents allow task-specific context loading. A maintenance subagent keeps context fresh while specialized subagents handle implementation, protecting the orchestrator's instruction budget and cutting token consumption by 16.58% or more.
Is the cost increase from /init files really that significant? Yes. Across thousands of tasks in a CI/CD or automated-review pipeline, a 20% cost increase from redundant context compounds fast — and you pay it for no performance gain and often a 3% drop in success rates.
How do I handle non-obvious "landmines" without /init? Add them manually as they surface. Treat the CLAUDE.md as a living record of earned corrections. If an agent tries to refactor a legacy module that must stay untouched, that is when the instruction earns its place in the file.