What should go in your Claude.md?

I'll pull the source article and HN thread so the paragraphs stick to real details, not invented numbers.Zander Martineau published a dated map of advice on what belongs in a project CLAUDE.md after noticing that public guidance contradicts itself and is rarely timestamped. The piece was submitted to Hacker News as What should go in your Claude.md, with 4 points and 2 comments at the time of the summary. Martineau frames the core fight as accretion versus ablation: add a rule every time the model slips, versus periodically delete the file and put back only rules that prevent real mistakes.

On mechanics, CLAUDE.md is loaded into every conversation, so only universal rules should live there. Conditional guidance should move into skills or path-scoped files under .claude/rules with a paths glob; hard guarantees should be hooks rather than prose, because markdown is advisory and hooks are deterministic. Anthropic’s own tooling direction matches that split: /doctor trims directory layouts, dependency lists, and architecture overviews that Claude can derive from the repo, and keeps pitfalls, rationale, and non-default conventions. Progressive disclosure that actually saves context is path-scoped rules, skills, nested directory CLAUDE.md files, or plain links; @ imports expand at launch and do not reduce token cost.

For builders, the cost is not abstract. Every line is paid on every turn, ignored rules often mean the file is too long rather than not loud enough, and subagents load the same hierarchy as the main thread, so bloat multiplies under fan-out. Auto memory accretes separately under the project memory index and should be reviewed with the same pruning habit. Scaffolding needed is inverse to model capability: stronger models need less prescription, weaker or mid-tier models need more explicit commands and gotchas but have a tighter instruction budget.

Competitive and interop context is AGENTS.md, the cross-tool agent README stewarded under the Agentic AI Foundation and read natively by Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed, and others. Claude Code still reads CLAUDE.md only and does not fall back to AGENTS.md; the tracker request for native support is a high-reaction open issue. Research cited in the post is modest: hand-written context files help a little, LLM-generated ones (including typical /init output) can hurt, and longer context degrades performance across frontier models, with cost rising either way.

Practical takeaway: treat /init as a draft, delete overview, architecture summary, and file maps, keep non-obvious commands and real gotchas, add a line only after repeated failures, put hard “never” rules in hooks, and put @AGENTS.md on line one of CLAUDE.md so one source of truth covers Claude Code and other agents. Re-ablate when you change models, not only on a calendar. Watch whether Claude Code ships native AGENTS.md support; until then the one-line import is the low-friction fix.