A cancellation change starts in the Orders repository. Billing needs the reason for the request, and Fulfillment needs it when handling a shipment cancellation. An AI agent can edit a field in each codebase, yet still miss who decides whether a refund is allowed or a shipment can be stopped.
For a team keeping these services in separate repositories, a useful starting point is to make each domain's responsibilities and contracts explicit. Give the agent that context, then connect the repository-specific changes through one review. The next task should inherit the reviewed context and evidence.
The following is an illustrative design, not a report of a customer deployment or measured results. It assumes an external agent environment with authorized access to the repositories and their test tooling.
Define the bounded contexts before describing the repository layout
A bounded context establishes where a domain model and its terminology apply. Martin Fowler's introduction to bounded contexts explains why different parts of a business can use different models of concepts that share a name.
In this example, Orders, Billing, and Fulfillment each have a repository and a bounded context. That is a choice for this example. A repository boundary alone does not establish a domain boundary, and an existing system may have a different mapping.
For our cancellation change, the distinctions look like this:
| Context | Owns | Must learn from another context | Decision it retains |
|---|---|---|---|
| Orders | Cancellation requests and order lifecycle | Payment and shipment outcomes | How those outcomes affect order state |
| Billing | Captures, refunds, and payment records | Cancellation request and reason | Whether a refund is eligible |
| Fulfillment | Picking, dispatch, and shipment records | Cancellation request and reason | Whether work can stop at its current stage |
The word “cancelled” should not silently acquire one meaning across all three. A request can exist while a shipment is already dispatched. A refund may need separate handling. The agent needs those distinctions before it decides which files to touch.
Give each repository a context brief
Create one reviewable brief per context. Its purpose is to help a person or agent locate the authoritative contracts and understand their limits.
For the Orders brief, useful content includes:
- What Orders owns, and which decisions belong to Billing or Fulfillment.
- The accepted cancellation reason values and the meaning of an absent value.
- The event or API contract, with its repository path and source commit.
- Which consumers use it and how they handle retries and unknown values.
- The checks required for a contract change, plus questions still awaiting an owner.
Put a small context map beside that text. Label each connection with the actual message or API contract and its direction. A generic arrow marked “related” gives the agent little help when deciding whether a producer can change before a consumer.
These are suggested contents for this example, not a mandatory document schema. Keep code and executable contracts in Git. Record the commit used to prepare the brief so that a later agent can check whether the explanation still matches the checkout.
Carry a cancellation reason through the system
Suppose the agreed change adds an optional reason to an existing cancellation request. The intended behavior is to carry that reason into Billing's handling record and Fulfillment's stop-request record. Existing refund eligibility and dispatch rules continue to belong to their respective domains.
Before editing, have the agent produce a plan at this level:
| Repository | Proposed change | Evidence needed |
|---|---|---|
| Orders | Accept, validate, and emit the agreed reason field | Request validation and event-contract tests; existing requests without a reason still work |
| Billing | Read and record the reason without changing refund eligibility | Missing and unknown reason behavior, duplicate-request handling, and existing eligibility tests |
| Fulfillment | Read and record the reason while retaining dispatch rules | Missing and unknown reason behavior, repeated requests, and requests after dispatch |
This plan makes an assumption worth reviewing visible: adding the field must be compatible with the deployed consumers. Some consumers reject unfamiliar fields or enum values. The agent must inspect the actual contracts and tests instead of treating “optional” as proof of compatibility.
If the consumers need changes before they can accept the new message, record that release dependency. A candidate sequence is to deploy compatible consumers first and enable the producer afterward, but the actual sequence must follow the system's rollout and rollback rules. Three green pull requests alone do not establish that the deployed combination works.
Use one coordinated task with separate repository changes
The external agent environment needs a known checkout, revision, and permitted operations for each repository. It also needs the repository's own instructions and verification commands. The context briefs provide domain knowledge alongside those sources.
An example task instruction could be:
Carry the cancellation reason through Orders, Billing, and Fulfillment.
First read each context brief and the contracts at the current checkouts.
Report the source versions, repository revisions, and any contradictions.
Prepare the producer/consumer compatibility and release plan.
For each affected repository, make the agreed change and run its required
checks. Prepare one draft PR per repository and link the related changes.
Report failing checks and paths that were not tested.
Prepare a shared review with the context sources, commit references,
test evidence, unresolved questions, and release dependencies.
Leave merge and deployment to the existing approval process.
This is an example instruction for a configured agent, not a runnable command or a promise that a particular tool can access every repository. The operator supplies the Git permissions and execution environment. The work can proceed sequentially; the useful part is the shared goal and explicit boundaries.
When the agent finds a disagreement between a brief and the current API definition, it should show both sources and return the question to the responsible owner. A convenient summary should not override the contract it was meant to explain.
Preserve the context and the cross-repository review
Keep the context briefs in a versioned location that both reviewers and the authorized agent can read. Markdown in Git or a versioned HTML artifact can work; choose a format and access boundary that fit the team. The brief should point to the source contract and commit rather than become a competing contract.
Before using a brief, compare its recorded source commit with the repository revision about to change. If a search index helps find it, inspect the returned version: an updated artifact may be available before its new version is searchable. Resolve stale or missing context before relying on it.
Explicit links between briefs can help navigation. A link alone does not establish a code dependency or prove that the receiving service accepts a contract. The agent still needs to inspect the referenced repositories and tests with its own authorized access.
After the changes are reviewed, preserve one shared change review containing the exact source versions, repository commits, PR references, test-run evidence, release dependencies, and unresolved items. Link that review version from the relevant PRs or decision records. Record later changes as a new version.
An immutable artifact URL does not freeze linked repositories, PRs, test dashboards, or other remote content. Record the specific commit and run identifiers, and retain evidence in the systems responsible for it.
Keep the operational boundaries visible
Shared context is a knowledge-sharing choice. Do not combine briefs with different confidentiality requirements just to make them easier to search. Each person and agent must have permission to read the material they retrieve.
Access to context does not grant repository write access, permission to publish revised briefs, or authority to merge and deploy. The agent environment, Git tools, CI, and release process retain their own credentials and approval boundaries.
A context brief also needs maintenance. After an accepted contract change, update the affected briefs with the new source commits and the decision that explains the change. Otherwise the next AI task starts from a well-presented description of the old system.
For this example, a useful first step is one non-sensitive brief for a repository whose responsibilities are already understood. Review it against the source contract before expanding the workflow to another context.
When one feature spans your repositories, where do reviewers find the consumer compatibility evidence and the release order?
AI disclosure: This article was prepared by an AI agent from an existing editorial draft. The cancellation workflow is illustrative; no cross-repository change or measured result is claimed.
Top comments (0)