A feature request that touches one repository is a coding task. A feature request that crosses a frontend, an API, a shared package, infrastructure, and CI is an expedition.
The failure mode is familiar: open every repository, ask an agent to “implement the change everywhere,” and receive a plausible-looking patch that misses a contract, assumes an environment variable exists, or updates one version number while leaving three others behind.
A better power-user pattern is to treat Claude Code as a dispatch system. Instead of issuing one broad instruction, you send a sequence of small, artifact-producing missions. Every mission has a target, an expected output, a boundary, and a way to verify its result.
This is not about making the agent work more slowly. It is about preventing uncertainty from spreading across repositories faster than you can inspect it.
The dispatch model
A dispatch workflow has five stages:
- Map the system — identify repositories, ownership, contracts, and deployment paths.
- Collect evidence — create compact artifacts that explain the current behavior.
- Change one contract at a time — make implementation work follow explicit dependencies.
- Verify at boundaries — test the joins between systems, not only each project in isolation.
- Package the outcome — leave behind reviewable notes, commands, and rollout requirements.
Claude Code is especially effective here because it can navigate local files, run commands, inspect Git history, and keep its work anchored in the actual repository state. The key is to give it a job that produces something you can examine before it receives the next job.
Think of each dispatch as a sealed envelope. The agent should not need to guess why it exists, what files are in scope, or what “done” means.
Start with a repository manifest, not a coding prompt
Before changing code, create a local directory for the initiative. It can live outside the repositories or in a temporary engineering workspace.
The first Claude Code dispatch is reconnaissance:
Inspect the repositories listed in
manifest.md. Do not modify files. Identify the entry points, package or project names, runtime configuration sources, CI workflows, deployment mechanism, and any code that consumes or produces the billing contract. Write findings tosystem-map.md, with file paths and brief evidence for every claim.
This request sounds restrained because it is. Its value comes from what it forbids: implementation before orientation.
A useful manifest.md records more than repository paths. Include the default branch, primary language, local startup command, test command, and owner. For a TypeScript system, that might mean a Next.js application, a Node.js API, a shared npm package, and a Docker-based worker. For a .NET estate, it may include the API solution, a shared C# contract library, and deployment definitions.
The result is a system map that is concrete enough to challenge. If Claude says the API reads BILLING_PROVIDER_KEY from a Docker Compose file, you can open that file. If it cannot cite a path, treat the claim as unverified.
Use evidence packets to control context
Multi-repo work often fails because the agent is given a large amount of source code but very little decision context. The fix is not necessarily a larger prompt. It is an evidence packet.
An evidence packet is a short Markdown file containing the minimum facts required for the next mission:
- the user-facing behavior to add or change;
- the current API request and response shape;
- relevant database constraints or migration conventions;
- compatibility requirements;
- exact repository paths involved;
- known unknowns;
- commands already run and their results.
For example, after mapping a payment flow, ask Claude Code to produce a contract packet:
Read
system-map.mdand inspect only the files needed to trace invoice status from persistence through the API to the web UI. Do not edit code. Createcontracts.mdcontaining the current field names, nullable behavior, enum values, serialization rules, and callers. Separate observed facts from recommendations.
That final sentence matters. An agent’s recommendation can be useful, but it must not masquerade as repository truth.
This packet becomes reusable context for subsequent dispatches. Rather than repeatedly asking Claude Code to rediscover the architecture, you point it at a stable, human-reviewable summary. The prompt gets shorter while the work gets more reliable.
Sequence work by contract direction
For cross-repository changes, the order of implementation should follow the direction of the contract.
If the database is authoritative, begin with the schema and persistence model. If an external provider defines the contract, begin with its payload translation layer. If a shared package owns types, update that package before asking consumers to adapt.
A dependable sequence looks like this:
- Define or update the domain representation.
- Expose it through the API or shared library.
- Update asynchronous consumers, workers, or event publishers.
- Update the frontend or downstream services.
- Update runtime configuration and deployment definitions.
Each step should be its own Claude Code dispatch. Avoid “make all necessary changes” as an instruction. It hides the dependency graph just when you need it to be visible.
A focused implementation dispatch might read:
In the API repository only, add
paymentStatusto the invoice response according tocontracts.md. Preserve backward compatibility for existing clients. Add or update tests for serialization and authorization behavior. Do not modify the database schema, frontend, CI files, or unrelated formatting. Run the documented API test command and report changed files, test output, and unresolved assumptions.
This structure gives Claude Code room to solve the engineering problem while sharply limiting collateral work. It also creates a clean Git diff. Reviewers can understand one contract movement at a time.
Make the agent prove its assumptions in the terminal
The most valuable Claude Code output is not generated code. It is evidence.
Power users routinely ask the agent to prove assumptions with commands before changing behavior. For example:
- Search all consumers before renaming a REST API field.
- Inspect migration history before adding a new database constraint.
- Run a type check before and after changing a shared TypeScript interface.
- Query workflow files before assuming a CI secret is available.
- Examine Docker build contexts before editing a runtime environment variable.
Use explicit language such as:
Before editing, verify whether
InvoiceStatusis serialized as a string or integer in production-facing endpoints. Cite the relevant configuration and tests. If the answer is ambiguous, stop and report the ambiguity instead of choosing a representation.
“Stop and report” is a powerful operational instruction. It turns uncertainty into an escalation instead of an invisible design decision.
For risky changes, require a proof table in the agent’s final report:
| Claim | Evidence | Confidence |
| --- | --- | --- |
| Existing clients can omit paymentStatus | API integration test path | High |
| Worker recognizes the new state | No matching consumer found | Low |
This is not paperwork for its own sake. It tells you where a code review should concentrate.
Verify seams, not just repositories
A green test suite in every repository can still describe a broken system. Cross-repository defects live at seams: a JSON property differs by casing, an event version is not deployed, a generated client is stale, or a CI job builds a package from the wrong branch.
Create a verification.md file with tests organized around handoffs:
Then dispatch a verification mission:
Using
verification.md, run the highest-value local checks across the listed repositories. Do not change implementation code unless a test fixture or test command is demonstrably incorrect. Record commands, exit codes, failures, and gaps inverification-results.md.
Notice that this task does not ask Claude Code to “fix everything.” Verification deserves its own mode of thinking. When implementation and diagnosis are blended together, an agent can repair a symptom while concealing a broken assumption.
Close with an integration brief
The final deliverable should not be a collection of diffs alone. Ask Claude Code to create an integration brief for the pull requests or release ticket.
It should answer:
- What changed in each repository?
- Which repository must merge or deploy first?
- Are there compatibility windows or feature flags?
- Which environment variables, secrets, migrations, or package versions are required?
- What was verified locally, and what requires staging or production-like infrastructure?
- What remains uncertain?
This turns the agent from a patch generator into a contributor to engineering operations. It also gives future maintainers a record of why the repositories changed together.
The practical rule
When work crosses boundaries, do not give Claude Code a larger task. Give it a better dispatch sequence.
Map first. Capture evidence. Move one contract at a time. Demand terminal-backed proof. Verify seams. End with a release-ready brief.
The result is not merely safer AI-assisted coding. It is a workflow that makes distributed software systems easier for humans to reason about too.
No comments yet. Be the first to share your thoughts!