AI Systems Atlas

G-14Repo Conventions as Context

/coding-agents/repo-conventions

A checked-in instructions file that loads every session — how a codebase tells an agent its rules.

Step-by-step walkthrough7 steps
  1. A repository knows things no model can infer: which script to run, which directory is generated, which pattern is banned.
  2. So write them down in the tree, where they version with the code that made them true.
  3. Every session loads it. Nobody has to remember to paste the conventions in.
  4. Commands and traps earn their place — the things that are expensive to discover and cheap to state.
  5. Restating what the code already says does not. It goes stale on the first refactor and misleads every session after.
  6. Because it is a checked-in file, it changes through review — the same gate as the code it describes.
  7. The agent follows the house style without being told, and the file is how the house says what its style is.
Key insight

Put in it what is expensive to discover and cheap to state: the build command, the generated directory, the pattern that looks fine and breaks production. Because it is in the tree, it changes through review, like the code it describes.

Failure mode

Restating what the code already says. Those lines go stale on the first refactor and then actively mislead every session, which is worse than never having written them.

Further reading
RelatedResearcher + ImplementerFiles as external contextRepo indexingHooks & lifecycle events

Elsewhere in the atlas

Harnesses →Security →Evals →Context →Tools →Ops →