What actually belongs in CLAUDE.md — and what to move to skills, hooks, or docs A developer argues that CLAUDE.md files grow too large and lose effectiveness, proposing a sorting strategy that moves situational rules to skills, deterministic checks to hooks, and reference material to docs files. The key insight: every line in CLAUDE.md taxes every request, so only invariants that are cheap to state and expensive to violate should stay there. Your CLAUDE.md only grows. Every incident adds a rule, every preference becomes a paragraph, and six months in you have a file that reads like a wiki — and an agent that follows maybe half of it. The uncomfortable mechanics: CLAUDE.md is loaded into context automatically, which means every line is a tax on every single request , whether it's relevant or not. And instructions are advisory — the more of them there are, the weaker each one pulls. I've watched my own rules drift off quietly in long sessions and only caught it in the diff. So the real question isn't "what should I write in CLAUDE.md?" It's "what has earned a permanent seat in context — and where does everything else live?" Claude Code gives you four places to put guidance, and they have very different cost models: | Destination | Loaded | Costs tokens | Enforcement | |---|---|---|---| | CLAUDE.md | every session, automatically | always | advisory | | Skill | body only when the task matches | on demand | advisory, but scoped | | Hook | never enters context as prose | ~zero | deterministic | | docs/ file | when the agent or a rule points at it | on demand | none — it's reference | Here's the sorting test I use, one sentence per destination. Keep it in CLAUDE.md if it's true on every turn, cheap to state, and expensive to violate. Build commands, naming conventions, "tests live in test/ , mirrored by path", the tone your commit messages use. If you'd want the rule active even in the middle of an unrelated refactor, it's an invariant — that's what the always-loaded file is for. Move it to a skill if it starts with "when doing X". Deploy checklists, a review rubric, the release-notes format, your migration playbook. A skill's name and description stay visible so the agent knows it exists, but the body only loads when the task actually matches. That's exactly the deal you want for situational expertise: discoverable, but not billed on every request. Format details: how to write a SKILL.md that actually triggers https://dev.to/rulestack/skillmd-how-to-write-a-claude-code-skill-that-actually-triggers-format-template-27cp . Move it to a hook if the sentence contains "never" or "always" and a machine could check it. Formatting before commit, protected paths, "don't touch .env ", "block pushes to main". Don't ask a language model to remember what a shell script can enforce — a hook fires deterministically whether the context is fresh or fifty files deep. Hook config structure and matchers https://dev.to/rulestack/claude-code-hooks-explained-config-structure-matchers-and-a-copy-paste-pretooluse-guard-58jj . Move it to a docs file if it's something the agent should read, not obey. Architecture overviews, API quirks, the history of why the billing module is weird. Put it in docs/ , and leave one line in CLAUDE.md saying when to read it: "Touching billing? Read docs/billing-history.md first." Reference material rents context only when it's relevant.Three costs stack up on the always-loaded path: Hooks dodge all three. Skills dodge the first two. Docs dodge all three but enforce nothing. CLAUDE.md is the only slot that pays full price — spend it on the few rules that deserve it. myproject — agent guide Commands - Build: pnpm build / Test: pnpm test single file: pnpm test path/to.test.ts - Never run pnpm deploy directly — use the deploy skill. Conventions always - TypeScript strict; no any . Errors are returned, not thrown, in src/core . - Tests mirror source paths. New modules need a test file in the same PR. - Commit messages: imperative mood, reference the issue. Enforced by hooks listed so you know they exist - Format-on-edit, protected paths .env , migrations/ , test gate before commit. Where things live - Architecture: docs/architecture.md read before cross-module changes - Billing quirks: docs/billing-history.md read before touching src/billing When unsure - Prefer asking over guessing on anything in migrations/ . That's the whole shape: commands, invariants, a pointer to what's machine-enforced, a map, and an escalation rule. One screen. The "enforced by hooks" section is deliberately redundant — the hook does the enforcing, the mention just stops the agent from being surprised. .claude/skills/