Writing CLAUDE.md Files That Actually Help

An ETH Zurich paper found that CLAUDE.md files can hurt agent performance. Our experience running 5 parallel Claude agents on the same codebase says the opposite.

The difference is what you put in them.

What Hurts: Auto-Generated Content

When Claude generates its own CLAUDE.md, the result is always bloated with information it already knows. Code conventions it can infer from reading the code. Dependency lists it can get from package.json. File structure it can discover with ls.

This is the version the paper tested. And yes, it makes things worse - you are burning context window on information the agent can derive faster by just reading the codebase.

What Helps: Non-Derivable Context

Hand-written, project-specific context that cannot be derived from reading the files is worth every token:

• "If you see build errors in files you did not edit, wait 30 seconds and retry - another agent is mid-edit." You cannot learn this from the code.
• "Never switch git branches without explicit permission." A convention that prevents disasters.
• "Run swift build after any .swift file change." Project-specific testing pattern.
• "The accessibility module owns these files. The UI module owns those files." Scope boundaries for parallel agents.

The Rule of Thumb

Before adding a line to CLAUDE.md, ask: "Can the agent figure this out by reading the code?" If yes, do not add it. If no, add it.

Good additions:

• Coordination rules between agents
• Project-specific conventions that differ from defaults
• Non-obvious build/test patterns
• Safety guardrails and permission boundaries

Bad additions:

• Code style conventions (the agent can read existing code)
• File structure descriptions (the agent can run ls)
• Dependency lists (the agent can read package.json)
• Obvious patterns (the agent already knows TypeScript conventions)

---

We maintain detailed CLAUDE.md files for Fazm to coordinate parallel agent development. Discussed in r/ClaudeCode.