Stop Putting Everything in CLAUDE.md

Quick answer: Keep CLAUDE.md for facts and constraints every task needs: the repository's purpose, architectural invariants, safety boundaries, canonical commands, and the definition of done. Move long procedures, checklists, examples, and specialist knowledge into Skills or linked reference files that an agent can load when the task needs them. A small always-on instruction layer leaves more room for the code and the actual problem.

CLAUDE.md is useful because it is persistent. It is also tempting to turn it into the place where every hard-won lesson, deployment recipe, debugging transcript, and code example goes to live forever. That feels safe: if the instructions are in the file, the agent will see them.

The trade-off is that a permanent instruction file becomes another context consumer. The agent has to carry yesterday's deployment checklist while fixing today's parser, and it has to decide which of a hundred rules matter before it can do any work. The result is not a knowledge base. It is a crowded control panel.

The better rule is simple: persistent context should be a constitution, not an encyclopedia.

What belongs in the root instruction file

The root file should answer questions whose answers remain true across nearly every task:

• What is this repository and which directories are in scope?
• Which architectural boundaries must never be crossed?
• Which commands are canonical for tests, builds, and formatting?
• What safety or privacy constraints apply to every change?
• What does “done” mean before a task can be handed back?

These are invariants. They are valuable before the first file is opened and after the hundredth task. If a rule is only relevant to App Store metadata, Android edge-to-edge layouts, or a particular release lane, it probably does not belong in the root file.

What should become a Skill

Procedures are different from invariants. A procedure has a trigger, a sequence, and usually a collection of examples or references. It is useful when a particular kind of work begins, not on every turn.

That is the boundary Claude Code's Skills documentation draws: a Skill can hold repeated instructions, a checklist, or a multi-step procedure, and its body loads when the Skill is used. The same documentation recommends creating a Skill when a section of CLAUDE.md has grown into a procedure rather than a fact.

A useful repository layout looks like this:

CLAUDE.md
.claude/
  skills/
    release/
      SKILL.md
      references/
        app-store-checklist.md
    android-safe-areas/
      SKILL.md
docs/
  architecture.md
  testing.md

The root file can say that releases require the release Skill and that docs/testing.md is canonical. The release Skill can carry the exact sequence, failure recovery, and evidence checklist. The architecture document can explain the decision in enough depth that a future maintainer can understand it without loading it into every coding task.

A migration checklist

Do not start by deleting half the file. Move one section at a time and preserve the rule's meaning.

1. Label every paragraph as an invariant, procedure, reference, example, or historical note.
2. Keep invariants in CLAUDE.md and move procedures into named Skills.
3. Move long explanations and source material into docs/ or a Skill's references.
4. Give each Skill a specific description so the agent can distinguish it from neighboring Skills.
5. Add links from the root file to the new entry points.
6. Run a few representative tasks in a clean session and check that the right Skill activates.
7. Remove duplicate copies once the new location is proven.

The last step matters. A root file that says “read this 600-line document” has not really reduced always-on complexity. It has only hidden it behind a mandatory detour.

The test for a good instruction

Ask two questions: “Would this still be true for an unrelated task?” and “Does the agent need this before it knows what kind of task it is doing?” If the answer to both is no, the rule is a candidate for progressive disclosure.

That does not mean less documentation. It means documentation with an access pattern. The high-value constraints remain visible. The specialist knowledge is still versioned beside the code. The agent gets depth when the task warrants it, instead of paying the full context cost before it has chosen a direction.

For the next step, see how to build a large agent knowledge base without a large context window and why your coding instructions need CI.