A few simple numbers reveal the efficiency bottleneck in AI coding tools: in a test covering 14 directories and nine READMEs, the share of cases in which AI correctly identified the target file rose from 35.7% to 64.3%. This suggests that completing the repository’s “map” may reduce erroneous changes more effectively than simply switching to a stronger model.
What This Is
This approach turns the README from a project introduction into a directory index: a file listing that explains the responsibilities and boundaries of a particular layer of code. A separate README is maintained for each subdirectory. The recommended rule is to read the target directory and its parent README before making any changes. Each README should describe only immediate files and direct subdirectories, avoiding duplicated information.
It requires no new framework or plugin. The core is to require AI Coding—AI reading and modifying code—to gather context—the background information needed for the current task—before taking action. As a result, AI spends less time searching files without a clear objective and gains a better understanding of which layer should contain a particular piece of logic.
Industry View
We believe this is more reliable than simply telling AI to “be more careful,” because it converts implicit team rules into readable files and makes the system easier for new team members to understand. Even so, 64.3% is still far below the standard required for dependable automation. When READMEs are outdated, responsibilities overlap, or descriptions are vague, AI can still be misled by an incorrect index.
Another risk is the maintenance burden. As directories and responsibilities continue to change, documentation without an owner and a mechanism for regular updates will quickly become a second source of outdated information. A safer implementation sequence is to cover the core directories first, then add checks for missing documentation to continuous integration (CI, the automated process of checking code changes), rather than attempting to document the entire repository in one go.
Impact on Regular People
For enterprise IT: It adds a governance layer to AI coding with a low technical barrier, making it suitable for initial trials on internal projects with clear permissions and well-established tests, rather than giving AI direct control over core systems.
For individual professionals: People using AI coding tools will have an increasingly strong reason to improve directory documentation. The ability to define clear responsibility boundaries will gradually affect how efficiently and credibly teams adopt AI.
For the consumer market: It will not directly produce new software features, but it may indirectly reduce code-maintenance costs and make AI coding services affordable for more small and medium-sized teams.