Keeping Agent Instruction Files Lean ♻️

When you first start wiring AI agents into your repo, the temptation is predictable. You have a single instruction file that boots with the agent, so you begin putting everything there. CLAUDE.md. AGENTS.md. Whatever gets loaded at startup becomes the obvious home for conventions, notes, reminders, and half-formed ideas.

At first, this feels efficient. The agent always sees the rules. Nothing gets lost.

Then the file grows.

Instruction files are loaded into context on every session. Every time. That means each additional paragraph costs tokens before a single line of code changes. As the file expands, something more subtle happens as well. The signal starts to blur. Important conventions sit next to historical commentary, deferred ideas, operational trivia, and details that matter once a quarter. The agent technically reads all of it, but weighting is not magic. Large blocks of text dilute priority.

We ran into this in our monorepo after a few weeks of steady agent-driven work. Nothing dramatic broke. It just became harder to reason about what actually needed to live in always-loaded context. That was the real friction.

The adjustment was straightforward. We started classifying what we were about to add before adding it.

The Four-Way Filter

Now, before anything goes into an instruction file, we ask which category it belongs to.

1. Stable convention or architectural fact

This category earns a permanent seat. Things like commit format, branch naming, how secrets are managed, which test command to run, and where migrations live. These shape every session. They are stable, broadly relevant, and usually compact. If a rule influences most interactions with the repo, it belongs in the always-loaded context.

2. Open work item or deferral

Open items do not belong in the instruction file. They go in docs/TODOs.md, split by service if necessary. The agent can read that file when it is actively working on related code. It does not need the backlog injected into context on every boot. Instruction files are poor substitutes for project management, and mixing the two quietly increases noise.

3. Detailed reference

This is where instruction files tend to bloat. Deployment procedures, Docker layer behavior, health check tuning, platform quirks, build caching notes. All of it matters. Most of it is situational.

These now live under docs/. The instruction file contains a single pointer line such as:

• For API deployment details, see docs/api-deployment.md
• For UI deployment details, see docs/ui-deployment.md

That is enough. When the agent is modifying deployment logic, it can pull the document explicitly. When it is fixing a test, it does not spend tokens reading about Docker layers. The difference seems small, but across dozens of sessions it compounds.

4. Session-specific or transient notes

Some information simply should not be persisted. Notes about the current task, temporary debugging observations, half-formed thoughts about a refactor. If it will not matter next week, it does not belong in a file that loads forever. Let it live in the session where it was useful.

What Changed

Our instruction files are now short enough to scan in under thirty seconds. They read more like guardrails than a wiki. The heavier operational knowledge lives in docs/, where it can grow without polluting every agent session. The TODO list lives separately. Startup context stays narrow and predictable.

The Unexpected Benefit

We run multiple agents against the same repo. When one agent documents a deployment quirk in docs/api-deployment.md, the other agent can find it later. It is simply another file in the tree.

The docs/ directory has become a form of shared memory. It is not permanently loaded into anyone’s context window, but it is available when needed. An agent that writes down what it learns is effectively leaving notes for future sessions and for other agents working in parallel. That pattern emerged naturally once we stopped overloading the instruction file.

The Rule of Thumb

When I am about to add more than a couple of lines to an instruction file, I pause and ask whether the information is always relevant or only occasionally relevant. If it is situational, it probably belongs in docs/ with a pointer from the instruction file.

Instruction files work best when they are small enough to read in half a minute. Once they exceed that, the signal-to-noise ratio is already shifting in the wrong direction. Keeping them tight is less about aesthetics and more about preserving clarity at startup.