The Narrowest-Scope Rule: A Fix for Documentation Entropy in Agentic Codebases

Documentation has always decayed, but agentic software development is changing the speed and the stakes. When the reader of your README is a coding agent that will act on every line, a stale instruction is no longer a minor annoyance. It is a directive that gets executed. Rsnbl Facsimile, writing under the handle ajaxStardust, has been circling this problem in a series of posts on what he calls deterministic documentation, and the latest entry proposes a concrete habit to slow the rot: the narrowest-scope rule.

The idea is small enough to state in a sentence. Put each piece of guidance at the most specific location it applies to, and no broader. A rule about one function belongs in that function's comment, not the module header. A rule about one module belongs in that module, not the repository root. A rule that genuinely governs the whole project belongs in a root-level contract file. The discipline is in resisting the gravitational pull toward the top, where every note feels safer and more visible.

Why documentation drifts in the first place

The author frames the failure mode as documentation entropy, and the mechanism is worth spelling out because it explains why good teams still end up with misleading docs. When you write an instruction far away from the code it describes, you create a dependency that no compiler checks. The function gets renamed, the parameter order changes, the validation moves to a different layer, and the note sitting three directories up keeps asserting the old reality. Nobody is lying. The two artifacts simply drifted apart because nothing forced them to move together.

This is contextual drift, and it compounds. Each broadly scoped instruction becomes a small liability that the next engineer, or the next agent, has to verify against the actual code before trusting. Past a certain density, readers stop trusting the documentation entirely and go straight to the source, at which point the docs have negative value. They cost time to maintain and mislead anyone who believes them.

The connection to contract-style comments

The narrowest-scope rule builds on an earlier piece in the same series arguing for root-level contract files, a CONTRACT.md that sits at the top of a repository and tells an agent the non-negotiable rules of the project. Contracts and narrow scope sound like opposites, since one lives at the root and the other pushes everything down toward the leaves, but they solve two halves of the same problem.

A contract captures what is genuinely global: build commands that must never change, security boundaries an agent must not cross, conventions that hold everywhere. The narrowest-scope rule is the filter that keeps the contract from bloating into a dumping ground. Without it, every hard-won lesson migrates upward until the root file is a thousand lines of mixed global law and local trivia, and an agent reading it cannot tell which rules actually bind. Scope discipline is what keeps a contract authoritative.

How it works in practice

The practical test the author suggests is a question you ask of every note before you write it: what is the smallest unit of code for which this statement is true? If the answer is one function, the comment goes on that function. If you find yourself writing a rule whose truth depends on a single parameter, the documentation belongs at that parameter, not in a paragraph at the file's top describing the whole interface.

There is a measurable payoff for agentic workflows specifically. When guidance lives next to the code it governs, an agent editing that code sees the instruction in the same context window as the change it is making. The rule and the implementation move together because they are physically adjacent. A note buried in a distant file may never enter the agent's context at all, which means it is either ignored or, worse, fetched and applied to code it no longer describes.

The trade-off is honest and the author does not hide it. Narrow scoping fragments knowledge. A developer who wants the full picture of a subsystem now has to assemble it from many small comments rather than reading one overview. Discoverability drops. The counterargument is that a single accurate overview is rare and a single stale one is common, so the fragmentation is the price of each fragment staying true. For documentation an agent will execute rather than skim, correctness wins.

Why this matters now

The larger pattern here is that AI tooling is forcing software teams to treat documentation as code that runs, not prose that informs. Conventions that were merely tidy, keeping notes close to their subject, suddenly have teeth, because a misplaced instruction is a bug an agent will faithfully reproduce. The narrowest-scope rule is not a new insight so much as an old instinct made rigorous by new pressure.

Whether the specific terminology catches on matters less than the underlying shift. Teams adopting coding agents are rediscovering that the location of a fact is part of the fact. Put it in the wrong place and it stops being information and starts being noise that the next reader, human or machine, has to spend energy disproving. The author's contribution is to name the discipline clearly enough that a team can actually hold itself to it.

For anyone running agents against a real codebase, the experiment is cheap to try. Pick the most broadly scoped instruction in your repository, ask whether it is true everywhere it currently lives, and watch how often the honest answer is no. That gap, repeated across a project, is the entropy the rule is built to fight.