跪拜 Guibai
← All articles
AI Programming

Put a README in Every Folder and Make AI Read It First: A Directory Index That Stops AI from Editing the Wrong Files

By ENCI ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

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.

Summary

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.

Takeaways
— AI coding assistants default to breadth-first exploration—ls, guess, open, close—which burns context tokens before finding the right file.
— Same-name files like `apps/api/src/utils.ts` and `packages/core/src/utils.ts` are indistinguishable in search results, causing AI to pick the wrong target.
— The three rules are: one README per layer, write only direct children (not grandchildren), and require AI to read both the current and parent directory README before editing, max two levels up.
— Each README follows a five-field template: one-sentence responsibility, direct file list, boundaries, entry commands, and change alerts.
— The prompt must be a hard constraint with condition + action + exception; the rule "code wins over README on conflict" prevents AI from treating stale docs as authority.
— A measurable run on a 14-directory tree showed 64.3% coverage with the 5 gaps all at the `src` leaf layer, confirming humans write READMEs for the top while AI errs at the bottom.
— The gap-checker script exits with code 1 on missing READMEs, so it can block commits or merge in CI; output sorts gaps by depth so the deepest ones get fixed first.
— README serves as index while AGENTS.md serves as constraints; mixing both into one file breaks AI's reading expectation and should be avoided.
— Rollout order: root README first, then second layer, then `src/`, then CI enforcement, then prompt rules. Leaf directories below that get filled on demand.
Conclusions

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.

Concepts & terms
Directory coverage
A measurable metric: number of directories with a README divided by total directories, skipping artifact dirs like node_modules and dist. Used to enforce README presence across a repo.
Nearest-first effective mechanism (AGENTS.md)
AGENTS.md files resolve by proximity: AI looks up from the file being edited, and the closest AGENTS.md wins, allowing subdirectories to override parent-level rules.
From the discussion
Featured comments
shushenghong 1 likes

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?

ENCI

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.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗