How we lay out repos for agents

This is how we organise the code a code agent works on. It is an opinion, not a requirement — vroxy does not care how your repositories are arranged. But agents behave noticeably better with this shape, and the reason is worth understanding even if you land somewhere else.

The shape

One parent folder, every repo a sibling inside it, one instructions file at the top:

myproduct/
  AGENTS.md          <- the rules that apply everywhere
  CLAUDE.md          -> symlink to AGENTS.md
  myproduct_web/     <- its own git repo
    AGENTS.md        <- what is true only here
  myproduct_mobile/  <- its own git repo
    AGENTS.md
  myproduct_docs/

The parent is not a git repo. Each subfolder is.

Why the parent matters

Agents look for an instructions file by walking up from their working directory. Put one at the parent and it loads no matter which repo the agent started in — so a rule you only want to write once (“never publish to npm before launch”, “run the tests that cover the change”) lives in exactly one place.

It also makes cross-repo work possible at all. Our mobile app and our web API ship as one product; a change to one is usually a change to both. With the repos as siblings, an agent editing myproduct_web/app/... can read ../myproduct_mobile/lib/... in the same breath, and a rule like “a bug fixed here must be fixed in the mirrored implementation” is something it can actually carry out rather than a wish.

Why both filenames

Different tools look for different names — AGENTS.md is becoming the convention, CLAUDE.md is what Claude Code reads. Rather than maintain two files that drift apart, make one real and symlink the other:

ln -s AGENTS.md CLAUDE.md

Now there is one set of rules and no way for them to disagree.

What goes in which file

The split that has worked for us:

• Parent AGENTS.md — things true of the whole product. What each repo is and how they relate. Rules about how to work: what to verify before claiming something is done, what never leaves the database, how long to wait before giving up on a command.
• Repo AGENTS.md — things true only there. The stack, the test runners, the conventions a newcomer would otherwise violate, the decisions that look wrong until you know why.

The parent is the one that is not versioned, so anything a single repo genuinely depends on gets restated in that repo’s own file. Say it twice rather than lose it.

Write down the mistakes

The most valuable lines in ours are not descriptions of the system. They are the traps, written down the day someone fell into one:

Bite tests: snapshot the file, never git checkout it back. On an untracked file the checkout no-ops and your deliberate break survives; on a tracked file it restores to HEAD and destroys uncommitted work.

An agent reading that avoids an afternoon someone else already lost. A rule with the reason attached also survives being questioned — without the why, the next person deletes it as superstition.

If you do it differently

Plenty of teams use a monorepo, or keep repos unrelated on disk, and both are fine. The parts worth keeping whatever your layout:

• One instructions file per repo, at its root.
• Symlink the other filename rather than duplicating it.
• Put the why next to every rule.
• Update it the same day something goes wrong, not at the end of the quarter.