Writing a Good CLAUDE.md

HumanLayer blog (Kyle / @0xblacklight, 2025-11-25): a prescriptive guide to authoring the CLAUDE.md file — the project-context document Claude Code loads into every session. From HumanLayer, the team behind the 12-factor-agents framework. It’s opinion grounded in cited research (the instruction-following ceiling below) rather than a benchmarked study — T3, but a well-argued one from a named agent-engineering shop.

The premise

Because an LLM is stateless and knows only what’s in the current window, CLAUDE.md is the one document that onboards the agent to the codebase every session — the single highest-leverage file, since it touches every phase of every workflow. That leverage is exactly why it must be edited by hand, not generated.

The counter-intuitive claim: Claude often ignores CLAUDE.md

Kyle’s sharpest point is a mechanism: Claude Code’s own system prompt carries a reminder telling the model to disregard context it judges irrelevant to the task at hand. So instructions in CLAUDE.md that aren’t universally applicable get silently skipped — the file is loaded but not obeyed. The fix isn’t more emphasis (ALL-CAPS, “IMPORTANT”), it’s only writing instructions that apply broadly; anything task-specific belongs somewhere the agent pulls in on demand.

The instruction ceiling

He cites research that frontier LLMs reliably follow only ~150–200 instructions, and that as the count climbs, adherence degrades uniformly across all of them — not just the ones added last. So every marginal line in CLAUDE.md taxes obedience to the rest. This is the hard-numbers backing for the context-rot “minimize the always-loaded context” discipline: a bloated instruction file doesn’t just waste tokens, it lowers compliance with the instructions that matter.

The recommendations

Cover WHAT, WHY, HOW — architecture overview, project purpose, and the core workflow; skip the rest.
Keep it short — under 300 lines as a ceiling; HumanLayer’s own is under 60.
Universality over completeness — include only broadly-applicable guidance; a rule that fires on one task doesn’t belong.
Progressive disclosure — reference task-specific docs/skills the agent loads when needed, rather than inlining everything.
Don’t put style rules in it — delegate formatting to a linter/auto-fixer (he names Biome), and enforce process with Hooks (run outside the main context) or Slash Commands, not prose the model has to remember.
Never auto-generate it — /init-style generation produces bloated, low-signal files; because this is the highest-leverage point in the whole setup, craft it manually.

Where it sits

This is the authoring manual for the file the governed-context playbook tells you to curate — same discipline (minimal, high-signal, push detail into skills/hooks), argued from the CLAUDE.md side with two claims that thread doesn’t state: the “Claude ignores non-universal instructions” mechanism and the 150–200-instruction ceiling. It also stakes out the never-auto-generate pole, in direct tension with the docs-as-build-artifact sources that do auto-write CLAUDE.md/AGENTS.md (openwiki, autowiki-factory) — see synthesis. Cross-tool note: the piece frames the advice as Claude-specific but applies it to OpenCode, Zed, Cursor, and Codex too, echoing the AGENTS.md convergence.

claude-md · humanlayer · kyle-0xblacklight · context-rot · governed-context-claude-code · agents-md · agentskills-spec · agent-skills · openwiki · autowiki-factory · anthropic