claude-md

CLAUDE.md — the project-root file that claude-code loads as a persistent contract for every session in that project. Per tw93: not a team document, not a knowledge base — a contract whose contents must be true every session (2026-04-27-claude-code-architecture-governance-engineering).

What belongs in it

• How to build, test, run (most important).
• Critical directory structure and module boundaries.
• Code style and naming constraints.
• Non-obvious environment gotchas.
• The NEVER list — things the agent must not do.
• Compact Instructions — what must survive compaction.

What doesn’t

• Long background prose.
• Full API docs (live in code or in Skills’ supporting files).
• Vague aspirations (“write quality code”).
• Anything Claude can infer from reading the repo.
• Low-frequency task knowledge (push to Skills).

Sizing

anthropic‘s own internal CLAUDE.md for working on Claude Code is reported at ~2.5K tokens. Use that as a sanity ceiling; longer means you’re probably writing a wiki, not a contract (2026-04-27-claude-code-architecture-governance-engineering).

Compact Instructions

Default compaction discards re-readable content first, taking architecture decisions and constraint rationale with it. Counter:

## Compact Instructions

When compressing, preserve in priority order:
1. Architecture decisions (NEVER summarize)
2. Modified files and their key changes
3. Current verification status (pass/fail)
4. Open TODOs and rollback notes
5. Tool outputs (can delete, keep pass/fail only)

Composition with rules

CLAUDE.md should hold cross-cutting project contract; path- or language-scoped rules belong in .claude/rules/ (e.g. .claude/rules/core.md, .claude/rules/config.md, .claude/rules/release.md). Putting everything in the root file forces every session to load constraints irrelevant to the current task (2026-04-27-claude-code-architecture-governance-engineering).

Operating habits

• # in chat appends the current message into CLAUDE.md — fastest way to capture a rule the moment you find yourself repeating it.
• “Update your CLAUDE.md so you don’t make that mistake again” — after correcting Claude, ask it to write the constraint into its own file. tw93 reports this works well, but flags that periodic pruning is needed: constraints written for older models may now be limiting (compare the TodoWrite tool’s evolution mentioned on 2026-04-27-claude-code-architecture-governance-engineering).
• /memory to confirm which CLAUDE.md files (project, global, parent dirs) actually loaded into the current session.
• /insight to have Claude scan the current session for unwritten conventions worth promoting into the contract.

Anti-pattern

CLAUDE.md as wiki: every load contaminates the context, and the actually-load-bearing instructions get diluted (2026-04-27-claude-code-architecture-governance-engineering).

The same role in non-Claude-Code Agents

The contract-file pattern generalizes. openclaw‘s system prompt loads in layers from SOUL.md (identity, hard constraints, what “done” means) → AGENTS.md → TOOLS.md → USER.md → MEMORY.md → Skills index (2026-04-27-agent-principles-architecture-engineering). Same instinct as CLAUDE.md: short, hard, executable identity-and-constraints file at the top, with progressively-loaded supplementary content stacked underneath.

The key cross-system claim: the contract file is identity + hard constraints + what-done-means, not knowledge. Knowledge belongs in Skills or files retrieved on demand (context-engineering).

Primary-source corroboration: OpenAI Codex’s AGENTS.md

2026-04-27-harness-engineering-codex-agent-first (Ryan Lopopolo / openai, Apr 2026) is the directly-OpenAI-authored primary source for the same pattern, applied to codex. Two specific contributions to this page:

• The “table of contents, not encyclopedia” framing is verbatim. “我们不再将 AGENTS.md 视为百科全书，而是将其视为内容目录.” (“We no longer treat AGENTS.md as an encyclopedia; we treat it as a table of contents.”) The replacement is a ~100-line AGENTS.md that points into a structured docs/ knowledge base (codebase-as-system-of-record).
• The four named failure modes of “one big AGENTS.md” — context is scarce, too much guidance becomes ineffective, it rots, it’s mechanically unverifiable — directly support the anti-pattern call-out above. They are the same reasons CLAUDE.md-as-wiki fails.

The cross-system pattern now has three concrete instances that converge: claude-code‘s CLAUDE.md, openclaw‘s SOUL.md+stack, and codex‘s AGENTS.md. All three: short, hard, executable, identity + constraints; with knowledge progressively loaded from elsewhere.

The AGENTS.md standard the post links (agents.md) appears to be coalescing as a vendor-neutral name for the same artifact. If the standard ships its own canonical sizing / shape, this page should consolidate against it.