Budget the context, then ship the rails as a package

Your CLAUDE.md is four hundred lines long. You know this because you wrote most of them, one incident at a time. Somebody’s agent deleted a migration, so there is a paragraph about migrations. Somebody shipped a component that ignored the design tokens, so there is a section on design tokens. Each addition was reasonable. The file is now longer than most of the modules it describes.

It also feels like the most productive rail you own, because writing it feels like the work you already know how to do. That feeling is the problem this chapter is about.

Rank the rails by what they guarantee

Anthropic’s own documentation is unusually blunt on this point: an instruction like never edit .env in CLAUDE.md or a skill is “a request, not a guarantee.” Hooks, settings and permissions are a different category. They are code that runs, and they either block the action or they do not.

So the rails you own form a ladder, and the ordering is uncomfortable:

Settings and permissions decide what is possible. Hooks decide what happens at the moment a tool is called. Packaged skills and commands decide what is easy. The instruction file decides what is suggested.

Every rail above the last one is enforcement. The last one is advice. It is also the only one that feels like writing, which is why it is the one that grows to four hundred lines while the hooks directory stays empty.

The move

Make the instruction file a map, put the guarantees in code, and ship the whole set as one versioned package.

The budget is real and you can see it

Context spent on instructions is context not spent on your code, and the amount is measurable rather than theoretical.

The CLAUDE.md in the repository this book is built from runs 83 lines, and Claude Code’s /context command estimates it at 1.2k tokens. Multiply that file by ten, to roughly the size of the sprawling ones, and the estimate goes to 12.4k. Call it fifteen tokens a line. Four hundred lines of accumulated good intentions is around six thousand tokens gone before anybody has looked at a single file.

Anthropic’s guidance is to keep the file under 200 lines, with a warning worth quoting exactly: “Bloated CLAUDE.md files cause Claude to ignore your actual instructions.” The file does not fail gracefully. It fails by diluting the three rules you actually cared about.

And there is a trap in the obvious fix. Splitting the file and pulling the pieces back in with @path imports “helps organization but doesn’t reduce context, since imported files load at launch.” You have tidied your desk without emptying it. A map only buys you anything if the destinations are paths the agent reads when it needs them, not imports that load every time regardless.

OpenAI’s harness team runs it the working way. Their AGENTS.md is “roughly 100 lines” and “serves primarily as a map, with pointers” into a docs/ directory treated as the system of record. The entry point is small; the corpus behind it is not.

What it looks like

BEFORE                          AFTER

CLAUDE.md            412 lines  CLAUDE.md              ~100 lines, a map
  build commands                  build commands
  architecture notes              where to look for what, as paths
  the migrations incident         three rules that actually matter
  the design-token incident
  the .env warning              docs/                  read on demand
  the "always run tests" plea     architecture.md
  ...                             migrations.md
                                  design-tokens.md

.claude/hooks/         empty   .claude/
                                 settings.json         permissions, deny rules
                                 hooks/pre-tool-use     blocks the .env write
                                 skills/, commands/     packaged, versioned

The .env line moved from a paragraph that asks to a hook that refuses. That is the whole transformation, applied to every rule in the file that actually matters. Whatever survives the move is genuinely advisory, and that is what the hundred lines are for.

Then distribute it as one thing. AutoScout24 published how they run this internally: a git repository as “a governed registry of reusable agent capabilities” in the Claude Code plugin marketplace format, with governance and automated quality gates around it. Copy-paste does not version, cannot be rolled back, and drifts silently across repositories. A package does none of those things.

What it costs

Three costs, and I want to be honest that one of them is a judgment call rather than a finding.

A map costs a hop. Pointing at docs/migrations.md instead of inlining the rule means the agent has to go and read it, and sometimes it will not bother. You are trading guaranteed dilution for occasional laziness. That trade is worth it above a couple of hundred lines and probably not worth it below it.

Versioned rails mean version skew. The moment you ship rails as a package, some repository is pinned to last quarter’s version, and your new rule is not running where you think it is.

And the ranking above is mine, not a measurement. It is well supported at the ends: instruction files are documented as advisory, hooks are documented as blocking, and Thoughtworks named agent instruction bloat as a Caution-ring technique in April 2026. But I could not find evidence for the tempting stronger claim, that teams systematically over-invest in instruction files relative to hooks. I believe it from what I have seen. Treat it as an argument, not a statistic.

Try this week

Run /context in your largest repository and find the line for memory files.

That number is your instruction budget, spent, on every single request, before any work happens. If it is over about 3k, you have a four-hundred-line problem.

Then do one conversion rather than a rewrite. Go through the file and find the single rule you would be most upset to see broken. Not the most-written-about one, the most consequential one. Move it out of prose and into a deny rule or a PreToolUse hook, and delete the paragraph that used to ask for it.

You have converted one request into one guarantee. Do that four more times and the rest of the file can be as advisory as it likes, because nothing important depends on it any more.