AI coding across several repositories

AI coding across several repositories works when you record the feature once, split it into one task per repository, and write down the order and the contract between them, because each agent session normally sees only the directory it was started in. An agent in the API repository cannot run the web client's tests, does not know which client version is deployed, and may invent the shape of a response it has never seen. Without a shared record, the cross-repository plan lives in your head and the agents work on fragments. The approach below keeps a parent feature that holds the contract, child tasks per repository, explicit dependencies on released versions, and a consistent way to find all of it later. It works with any agent. For several agents in one repository, see multi-agent project coordination; for the layout of a single repository, see organizing a repository for agents.

Why several repositories confuse agents

The problem is not the code in any single repository. It is everything between them. A feature that adds a field to an API and shows it in two clients has a contract: the field's name, its type, when it can be empty and which version introduces it. That contract is defined in one repository and consumed in others, and no single agent session sees both ends.

So the agent guesses. Working in the client, it writes code against the response it expects, and the test fixtures it creates encode that guess. Its tests pass and the integration fails. Working in the API, it renames a field for consistency, unaware that a mobile client already shipped against the old name.

Versions add a second layer. The client may depend on a released package of a shared library, not on the code in the sibling folder. An agent that reads the sibling folder can describe behavior the client does not actually have yet.

None of this is fixed by a smarter agent. It is fixed by writing the contract and the order down where every task can point to them.

One feature, one task per repository

Create a parent record for the feature that holds the contract: the exact field or endpoint, an example request and response, the version where it appears, and the rollout order. Then create one child task per repository. Each child's scope is that repository only, and its text points to the parent's contract rather than paraphrasing it.

A typical order for an additive change: billing-api adds the field behind a flag and publishes a release; web-client reads the field, tolerating its absence; mobile-app does the same; billing-api turns the flag on; a final cleanup task removes the tolerance once all clients are live. Each child depends on the ones before it.

Give each task a check that runs inside its own repository, plus a contract check where you can: a test in the client against a recorded example response taken from the parent, and a test in the API that its response matches the same example. When the example changes, both tests must change, which makes contract drift visible. Use one ID scheme across repositories, so a search for the feature finds every child.

Cross-repository dependencies and versions

Make dependencies point at something that exists: a merged commit, a published package version or a deployed environment, not a branch someone is still working on. A web-client task that depends on billing-api release 4.12 being published is checkable. A task that depends on the API change is not.

When an agent in one repository needs to read another, give it a checkout of the other repository at the version the consumer will actually use, and say so in the task. Starting the agent in a parent folder that contains both repositories is convenient but blurs scope; if you do it, state in the task which repository it may edit and which it may only read.

Keep conventions in each repository rather than assuming an agent will find them in a sibling. If several repositories share a convention, copy the short version into each one's instruction file and keep the full version in one place.

When an upstream piece changes, revisit approvals and checks downstream. Stale approvals after a dependency change explains why a review done against the old contract no longer counts.

Finding the work again

Multi-repository features are hard to reassemble afterwards. Six months later, someone asks why the mobile app handles a missing field, and the answer is spread across three repositories' histories.

A few habits help. Put the parent feature ID in every child task, every branch and every commit message, so a search across repositories by that ID returns the whole feature. Link each child's merged commit or pull request back to the parent when it lands. Record decisions about the contract on the parent, not in one repository's code comments.

Decide whether you want one board across repositories or one per repository. One board makes cross-repository order visible but gets noisy; one per repository keeps each tidy but hides the dependencies between them. Many teams use one board per repository plus a parent record that lists the children. Either way, search has to work across all of them. Finding and organizing work across projects shows one way to set that up.

QUESTIONS

Is a monorepo better than several repositories for AI coding agents?

It removes some problems: an agent can see both ends of a change, and one test command can cover everything. It adds others: the repository is larger, so context is harder to bound and scopes need more care. Few teams should restructure just for agents. Write contracts and dependencies down explicitly either way, because that is what helps most.

Can one AI agent session edit two repositories at once?

Technically yes, if you start it in a folder that contains both, but it makes scope and review harder. Each repository's diff should be reviewed and merged on its own, against its own checks. A cleaner pattern is one write session per repository, with a read-only view of the other at a known version when the agent needs to see it.

How do I track a feature that spans several repositories?

Create a parent record holding the contract and the rollout order, then one child task per repository with its own scope and check. Put the parent ID in every child, branch and commit message. Make each child depend on the published or merged result of the step before it, so the order is recorded rather than remembered.

RELATED GUIDES

• How to find and organize work across projects
• What is a project management harness?

RELATED HARNESS PAGES

• multi-agent project coordination Multi-agent project coordination: keep Claude and Codex work on one project organized with shared cards, scope, authority and review.
• Organizing a repository so AI agents can navigate it Organizing a repository so AI agents can navigate it: a short README map, one test command, consistent layout, small modules, clear entry points.
• When a dependency changes, which approvals go stale? When a dependency changes, which approvals go stale? How evidence tied to source bytes goes stale, and what a stale flag does and does not tell you.
• Declared vs inferred dependencies in change-impact analysis Declared vs inferred dependencies in change-impact analysis: what task links and import graphs each catch, where each is blind, how to combine them.