{"slug": "working-across-repositories-with-ai-without-moving-to-a-monorepo", "title": "Working Across Repositories With AI, Without Moving to a Monorepo", "summary": "An engineer outlined a design for using an AI agent to coordinate a cross-repository change—adding a cancellation reason across Orders, Billing, and Fulfillment—without consolidating the services into a monorepo. The approach gives the agent per-context briefs documenting each domain's responsibilities, contracts, and a context map, then has it produce a reviewable per-repository plan with required evidence before editing. The writeup is explicitly illustrative, not a customer deployment or measured result, and assumes an external agent with authorized repository and test-tooling access.", "body_md": "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.\n\nFor 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.\n\nThe 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.\n\nA bounded context establishes where a domain model and its terminology apply. Martin Fowler's [introduction to bounded contexts](https://martinfowler.com/bliki/BoundedContext.html) explains why different parts of a business can use different models of concepts that share a name.\n\nIn 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.\n\nFor our cancellation change, the distinctions look like this:\n\n| Context | Owns | Must learn from another context | Decision it retains | \n|---|---|---|---|\n| Orders | Cancellation requests and order lifecycle | Payment and shipment outcomes | How those outcomes affect order state | \n| Billing | Captures, refunds, and payment records | Cancellation request and reason | Whether a refund is eligible | \n| Fulfillment | Picking, dispatch, and shipment records | Cancellation request and reason | Whether work can stop at its current stage | \n\nThe 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.\n\nCreate one reviewable brief per context. Its purpose is to help a person or agent locate the authoritative contracts and understand their limits.\n\nFor the Orders brief, useful content includes:\n\nPut 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.\n\nThese 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.\n\nSuppose 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.\n\nBefore editing, have the agent produce a plan at this level:\n\n| Repository | Proposed change | Evidence needed | \n|---|---|---|\n| Orders | Accept, validate, and emit the agreed reason field | Request validation and event-contract tests; existing requests without a reason still work | \n| Billing | Read and record the reason without changing refund eligibility | Missing and unknown reason behavior, duplicate-request handling, and existing eligibility tests | \n| Fulfillment | Read and record the reason while retaining dispatch rules | Missing and unknown reason behavior, repeated requests, and requests after dispatch | \n\nThis 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.\n\nIf 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.\n\nThe 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.\n\nAn example task instruction could be:\n\n```\nCarry the cancellation reason through Orders, Billing, and Fulfillment.\n\nFirst read each context brief and the contracts at the current checkouts.\nReport the source versions, repository revisions, and any contradictions.\nPrepare the producer/consumer compatibility and release plan.\n\nFor each affected repository, make the agreed change and run its required\nchecks. Prepare one draft PR per repository and link the related changes.\nReport failing checks and paths that were not tested.\n\nPrepare a shared review with the context sources, commit references,\ntest evidence, unresolved questions, and release dependencies.\nLeave merge and deployment to the existing approval process.\n```\n\nThis 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.\n\nWhen 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.\n\nKeep 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.\n\nBefore 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.\n\nExplicit 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.\n\nAfter 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.\n\nAn 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.\n\nShared 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.\n\nAccess 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.\n\nA 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.\n\nFor 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.\n\nWhen one feature spans your repositories, where do reviewers find the consumer compatibility evidence and the release order?\n\n*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.*", "url": "https://wpnews.pro/news/working-across-repositories-with-ai-without-moving-to-a-monorepo", "canonical_source": "https://dev.to/yuichi-tanaka/working-across-repositories-with-ai-without-moving-to-a-monorepo-1gh8", "published_at": "2026-11-02 10:09:10+00:00", "updated_at": "2026-11-02 10:22:55.083961+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["Martin Fowler"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/working-across-repositories-with-ai-without-moving-to-a-monorepo", "markdown": "https://wpnews.pro/news/working-across-repositories-with-ai-without-moving-to-a-monorepo.md", "text": "https://wpnews.pro/news/working-across-repositories-with-ai-without-moving-to-a-monorepo.txt", "jsonld": "https://wpnews.pro/news/working-across-repositories-with-ai-without-moving-to-a-monorepo.jsonld"}}