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 subagent 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.
