Spokes.wiki Search About
Defined Term convention updated Tue Jul 21 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

CLAUDE.md

CLAUDE.md is Claude Code‘s per-project instruction file — the markdown document loaded into every session to onboard the agent to a codebase (architecture, purpose, workflow, conventions). It is the Claude-specific, vendor-tied sibling of the open AGENTS.md convention: same job (durable, reviewed project context, distinct from a human-facing README), one is cross-tool and one is Claude Code’s native file. Claude Code will read an AGENTS.md too; CLAUDE.md is the first-party name.

Until now this spoke referenced it only as an alias inside other pages (CLAUDE.md, governed-context-claude-code); writing-a-good-claude-md (HumanLayer, 2025-11) is the first source about the file itself, which earns it a node.

What good looks like (per writing-a-good-claude-md)

  • Small and universal. Under ~300 lines (HumanLayer’s own is <60); include only guidance that applies broadly, because the file is loaded unconditionally.
  • WHAT / WHY / HOW, not style rules — architecture, project purpose, core workflow. Formatting goes to a linter; process goes to Hooks (run outside the main context) and Slash Commands.
  • Hand-authored, never auto-generated — it’s the highest-leverage file in the setup, so /init-style generation (which tends to produce bloated, low-signal files) is discouraged.

Two mechanisms that make it counter-intuitive

  • The model can ignore it. Claude Code’s system prompt instructs the model to disregard context it deems irrelevant to the current task, so non-universal CLAUDE.md instructions get silently skipped — the file loads but isn’t obeyed. Universality is therefore a correctness property, not a style preference.
  • The instruction ceiling. Frontier models reliably follow only ~150–200 instructions, and adherence degrades uniformly as the count grows (writing-a-good-claude-md) — every extra line taxes the rest.

Relationship to context governance

CLAUDE.md is the always-loaded slice of context, so curating it is the first move in fighting context-rot: keep it minimal and high-signal, push domain knowledge into skills (dormant until invoked), rules into hooks, and reach task-specific detail by progressive disclosure. The governed-context-claude-code playbook and writing-a-good-claude-md agree on the discipline from two angles: governance during a session vs. how to author the file up front. The auto-generation pole (openwiki, autowiki-factory) that CI-writes CLAUDE.md/AGENTS.md is the standing counter-position. claude-code-development-kit joins that pole with a variation worth separating out: its /update-docs machine-maintains four project-context files, but they are not always-loaded — they sit behind /prime tiers. That splits the objection in two. The instruction-ceiling and ignore-it mechanisms above are properties of unconditionally loaded text and do not apply to opt-in files; the low-signal-bloat objection does, since generated prose is still what the agent reads once primed.

writing-a-good-claude-md · agents-md · context-rot · governed-context-claude-code · agent-skills · agentskills-spec · claude-code-best-practices · openwiki · autowiki-factory · claude-code-development-kit · anthropic

Related pages

Links to

Linked from