How Do You Prune and Maintain Your agents.md to Keep Every Token Working Hard Inside a Limited Context Size?

An agents.md file is not a document you write once and forget. Because it loads into the context on every single run, every line in it is a recurring cost, paid on every task the agent touches. Left unattended, these files only grow, accumulating stale advice and redundant lines until they are more overhead than help. Keeping one lean and current is an ongoing discipline, and it is what separates a file that helps from one that quietly hurts.

Why maintenance is not optional

The stakes are higher than they look because of how the file is used. It sits inside a limited context window, competing for space with the actual task, so every wasted token is stolen from the work. A bloated file also buries its own important lines, making the agent less likely to act on them. And a stale line does not just waste space, it actively misleads an agent that trusts it. Maintenance is what keeps all three of these failure modes at bay.

Every line must still earn its place

The test for keeping a line is the same as for adding one: does it change what the agent does? Over time, files fill with lines that no longer matter, advice for code that was deleted, or guidance the model now handles fine on its own. Auditing against this test, and cutting anything that fails it, is the core of pruning. This is the same principle that less context produces better results, applied to the file itself. If removing a line would not change the agent’s behavior, remove it.

Prune stale content first

The most dangerous content is not the useless line but the wrong one. When conventions change, commands get renamed, or architecture is refactored, the agents.md often lags behind, and the agent follows the outdated guidance with full confidence. Hunting down and fixing stale entries is the highest-priority maintenance, because wrong context is worse than missing context. Reviewing the file whenever the underlying reality changes keeps it honest. Stale guidance is a bug in your context, and it deserves the same urgency as a bug in code.

Cut redundancy ruthlessly

Files also bloat through repetition. The same rule gets stated in two places, or guidance that lives in a nested file gets duplicated at the root, which wastes space and creates two things to update. Keeping each fact in exactly one place, the approach that makes a hierarchy of agents.md files work, keeps the whole thing lean. When you find the same guidance twice, delete one copy and trust the other. Redundancy is silent bloat that maintenance should hunt down.

Tighten wording

Beyond removing lines, you can shrink the ones you keep. Verbose explanations can usually be compressed to a crisp directive without losing meaning, since the agent needs the rule, not the essay around it. Replacing a paragraph with a single clear sentence reclaims tokens for the task while keeping the guidance intact. This kind of editing treats the file as prose to be tightened, not just a list to be trimmed. Concision is a form of pruning that keeps content while cutting cost. A sentence you can shorten without losing meaning was too long to begin with.

Audit on a rhythm

Maintenance works best as a habit rather than a rescue mission. Reviewing the agents.md on a regular cadence, or as part of the same pull requests that change the code it describes, keeps it from ever drifting far. A small, frequent trim is far easier than a giant overhaul of a file that has bloated for months. Because the file lives in version control, this review fits naturally into normal development. Little and often beats a rare, painful cleanup.

Watch for behavior drift

The agent itself will tell you when the file needs attention. If it starts using an outdated command, ignoring a rule, or behaving inconsistently, the context it was given is a prime suspect. Treating odd agent behavior as a possible context problem, not just a model problem, points you straight at the file to check. This feedback loop, watching what the agent does and adjusting the context, is a core part of context engineering. Let the agent’s mistakes guide your pruning.

Keep the highest-signal lines

Pruning is not only about removing, it is about protecting what matters. The commands, conventions, and landmines that prevent real mistakes are the lines you defend, even as you cut around them. A well-pruned file is dense with exactly this high-value guidance and free of everything else, which is the whole point of treating it as context engineering. The goal is not the shortest possible file, it is the highest signal per token. Cut the filler, guard the essentials.

Make it a shared responsibility

On a team, an agents.md that only one person tends will drift the moment they get busy. Making its upkeep a shared norm, reviewed like any other file in a pull request, keeps it accurate as the project and the team evolve. When everyone treats the context file as real infrastructure, it stays trustworthy for everyone’s agents. This shared ownership is what keeps a lean file lean over the long run. Context maintenance is a team habit, not a solo chore.

The takeaway

An agents.md earns its keep only if you maintain it, because it taxes every run with its length and misleads with any stale line. Prune what no longer changes behavior, fix outdated guidance first, cut redundancy, tighten wording, and review it on a rhythm as part of normal development. Keep every token working hard, and the file stays a durable asset instead of slowly becoming a liability.

Common questions