Organizing a repository so AI agents can navigate it

Organizing a repository so AI agents can navigate it mostly means doing the things that help a new human colleague, more consistently: a short map at the top, one obvious test command, a predictable layout, small modules with clear names, and documented entry points. An agent arriving in a repository has no memory of it. It reads what it can find, searches for names and builds a picture from fragments. Everything that makes that picture quicker to build and harder to get wrong pays off on every task, with every tool. None of it depends on a particular agent or instruction file format; it is about the repository itself. Instruction files are covered in alternatives to CLAUDE.md, and how much an agent should read per task in bounded task context. This article is about the code and layout those files point to.

A short README map

The top-level README should answer, in about a screen: what this repository is, how it is laid out, how to run it, how to test it and what not to touch.

The layout part is the most useful for agents. Give one line per top-level directory: src/billing holds invoice and payment logic; src/export holds CSV and PDF exports; scripts holds one-off maintenance scripts that are not part of the app; vendor holds third-party code that must not be edited. An agent that reads this before searching finds the right module first and stops treating vendored code as yours.

State what is generated. If a directory is produced by a build step or a code generator, say so and name the command that regenerates it. Agents will otherwise edit generated files by hand, and the edit vanishes on the next build.

Keep the map current. A wrong map is worse than none, because the agent trusts it. Review it when you add or move a top-level directory, and keep it short enough that reviewing it is not a chore.

One obvious test command

An agent's main way to check its work is to run tests, so make that easy to get right. There should be one documented command that runs the whole suite, and ideally one that runs a fast subset. Put both in the README and make them work from the repository root without setup steps that live only in someone's head.

Tests have to fail honestly. A suite with known failures teaches agents, and people, to ignore red output. If some tests are broken and cannot be fixed now, list them where the agent will see them, with the reason, and keep reporting them as failures rather than silently skipping them. BRAIN FLUID's own validation report does this: five legacy tests fail at setup on a retired interface, and the report lists them as failures and does not count them as coverage.

Make test output readable: a clear summary line with counts, and failures that name the test and the assertion. An agent that cannot tell from the output whether it passed will guess. Flaky tests cause the same problem in a different way.

Consistent layout and small modules

Agents navigate by search. They look for a name, open the files that match and read around the hits. A layout that makes search effective helps them more than most documentation.

Use names that say what things are: invoice_totals.py rather than utils2.py, and one concept per module. Very large files force an agent to read thousands of lines to find one function, and it may edit from a partial view. Keep tests next to, or mirrored from, the code they test, so tests/billing/test_invoice_totals.py is where anyone would look.

Prefer explicit over clever. Imports that name the module make dependencies searchable; dynamic imports, string-based registration and heavy metaprogramming hide them. If a plugin system loads modules by name from configuration, document where that configuration lives, because a search for the module's callers will not find it.

Be consistent. If one feature folder has routes, services and tests, the next one should too. Agents copy the patterns they see, so a consistent repository gets consistent changes, and an inconsistent one gets a third pattern.

Documented entry points and boundaries

Tell the reader where execution starts: the main application entry, command-line entry points, scheduled jobs and how configuration is loaded. An agent asked to change startup behavior that cannot find the entry point will add a second one.

Document boundaries that are not obvious from the code. Which modules are shared by several features, so changes there need wider checks. Which directories belong to another team or are mirrored from another repository. Which public interfaces must not change without a version bump. A short note at the top of a shared module, saying who imports it and what to run after changing it, heads off the most common agent mistake: a local fix to shared code.

This matters more because some tools select context by following explicit relationships rather than by guessing meaning. BRAIN FLUID's task context, for example, is assembled from the card, its dependencies, references and linked material within a size bound, and it is not semantic search [N11]. Relationships nobody wrote down are invisible to that kind of selection, and relationship versus semantic retrieval explains the trade-off.

QUESTIONS

What should a README include for AI coding agents?

What the repository is, one line per top-level directory, how to run and test it, which directories are generated or vendored and must not be edited by hand, and where the entry points are. Keep it to about a screen. The same README serves human newcomers, which is a good test: if a new colleague would be lost, so will an agent.

Do AI coding agents work better with small files?

Generally yes, up to a point. Smaller files with one concept each are easier to find by search and easier to read completely, so the agent edits with the whole file in view. Splitting too far brings its own problem: a single change then touches many tiny files. Aim for files a person could read in a few minutes.

Should generated code be committed in a repository that AI agents work in?

Either choice works if it is documented. If generated files are committed, mark them clearly, with a header comment and a README note naming the command that regenerates them, so agents do not edit them by hand. If they are not committed, make sure the build regenerates them before tests run, or agents will report missing files and try to create them.

RELATED GUIDES

• What is a project management harness?

RELATED HARNESS PAGES

• CLAUDE.md alternatives CLAUDE.md alternatives compared: what a project instruction file does well, where it stops, and what a project harness like BRAIN FLUID adds.
• Bounded task context Bounded task context: give an agent the slice of a project one task needs, chosen by relationship, capped in size, with omissions stated.
• Relationship-based vs semantic retrieval for AI project context Relationship-based vs semantic retrieval for AI project context: declared links vs similarity search, how each misses, and how to combine them.
• Flaky tests and AI coding agents Flaky tests and AI coding agents: how nondeterministic checks cause false completions and false failures, and the retry and quarantine rules that help.
• Why does my AI agent ignore project instructions? Agents skip project instructions that are buried, contradicted, lost to context limits or too vague to act on. How to find which, and fix it.