Put a README in Every Folder and Make AI Read It First: A Directory Index That Stops AI from Editing the Wrong Files
AI assistants now read codebases as often as humans do, and without explicit indexing they waste context on exploration and edit the wrong modules. A per-directory README is a low-cost workflow change that works with existing tools, no new frameworks or plugins needed.
AI coding assistants routinely edit the wrong files. The cause is structural: same-name files are indistinguishable, cross-layer changes carry no cost impulse, and breadth-first exploration burns context tokens before AI even finds the right target. Layered READMEs fix this by giving AI a map before it starts probing.
The rules are three: one README per directory layer, each covering only its direct children, and AI must read it before editing—going up at most two levels. Each README follows a five-field template: one-sentence responsibility, direct file list, boundaries, entry commands, and change alerts. Prompt engineering turns "read first" into a hard constraint with explicit conditions, actions, and the rule that code wins over stale docs.
A measurement on a 14-directory demo tree shows 64.3% coverage when only 9 READMEs exist, with all gaps at the leaf `src` level—exactly where AI errs most. The provided Node script audits coverage, exits non-zero on gaps, and can block merges in CI. READMEs complement AGENTS.md by indexing rather than constraining; a rollout order starts at root, then layers two and three, then CI enforcement.
The author's refusal to cite efficiency percentages in favor of a single reproducible metric (directory coverage) is the right instinct—most AI productivity claims lack defined baselines and are useless.
The measurement reveals a genuine mismatch: humans naturally document the top-level structure, but AI's failure density concentrates at deep leaf directories where filenames look alike.
Making "code wins over README" an explicit prompt rule is a rare acknowledgment that documentation can become a liability when AI treats it as authoritative.
The division of labor between README and AGENTS.md hinges on enforcement mechanism, not content: AGENTS.md has built-in nearest-first resolution, while README depends entirely on prompt engineering to be read.
I agree with positioning the README as a directory index for AI. Here's a way to keep it from rotting: during review, every time you spot the AI editing the wrong place, immediately write 'who owns this area and what shouldn't go here' into the README for that layer, rather than simply correcting it once in a comment. This way, the index gets built up one mistake at a time, capturing the traps actually hit, and it remains even after whoever built it leaves. Also, does the gap checker ever consider checking for stale references — files listed in the README that no longer exist?
Great approach — turning corrections into index entries on the spot is indeed the key to preventing rot. About stale references: right now the gap checker mainly looks for files in the directory not covered by the README; what you're describing — README entries for files that no longer exist — is the exact opposite. That's a good suggestion; I'll add a two-way check so both extra files and missing files get reported.