How to design a CLAUDE.md that works: 3 scopes, What/Why/How framework, 5 rules
nikola_mr64990 · x · 2026-10-13
A complete architecture guide for writing effective CLAUDE.md files for Claude Code:
- 3 scopes: global (/.claude/CLAUDE.md, personal style), project (./CLAUDE.md, tech stack, build/test commands, team conventions), folder-level overrides; last scope wins on conflicts
- What/Why/How framework: context (purpose, stack, repo map), principles (architecture decisions, naming, anti-patterns), workflows (exact build/test/lint/deploy commands)
- 5 rules: run /init first then curate; stay under 500 lines; use Hooks for 100% enforcement (CLAUDE.md alone is only 70% followed); update monthly; reference files like package. instead of duplicating
Key insight: CLAUDE.md is onboarding docs for your AI teammate, not a README for humans.
More from coding & agent
- Jason Fried: improving existing software with AI has never been more fun — martyamark · 2026-10-14
- TV noise crashes voice agents: task completion falls from 38.7% to 8.6% across 14 stacks — solyarisoftware · 2026-10-14
- Write your own PR descriptions, even when agents write the code — rseroter · 2026-10-14
- AI search startup Exa hits $100M annualized revenue, growing ~10x a year for 3 years — TheIshanGoswami · 2026-10-14
- claude-as-cad: how to build real robots and parts without knowing CAD, by having Claude build its own CAD interface — _krishna_murthy · 2026-10-14
- Antigravity walkthrough for 500 devs at Paris Dev With AI: Agent Manager, IDE, CLI and SDKs — rseroter · 2026-10-14