During our ADLC masterclass dated 13th Nov 2026, we discussed how AI is changing the pace of software development. AI can now generate code faster than our teams can review it. This creates a new challenge: how do we ensure that AI-generated changes meet the engineering standards we expect?
We introduced our Bulletproof repository, a software factory that turns repeatable engineering standards into executable checks. It also brings the evidence from these checks to reviewers, helping them make informed merge decisions.
During the Q&A, one of our audience, Nandha R raised an interesting question:
How would you migrate a brownfield project built on microservices architecture into ADLC (Agent Development Lifecycle)? Since the project is split across multiple repositories, how would you share the context across these repositories with an LLM?
Thanks, Nandha, for bringing this up. We didn't have enough time to explore it during the session, so let's address it here.
This is an interesting problem, especially for teams working with large brownfield systems.
Think about an application built using microservices. Each service has its own repository, business logic, data ownership and responsibilities. Some business workflows span multiple services, and the knowledge required to understand the entire system is scattered across these repositories.
Now, when we introduce AI agents into this ecosystem, how do we give them enough context to make changes without losing the bigger picture?
One obvious thought is to feed all the repositories and their contents into a single LLM. But is that really what we need?
I don't think so.
That means we need a way to make the system's knowledge discoverable and assemble the right context for every engineering task. Let's first understand why feeding the entire system to an LLM is not the right approach.
Stop Trying to Fit the Entire System into an LLM
An LLM has a finite context window. We can provide repository instructions, documentation, source code and other information, but that doesn't mean we should load everything into it.
Consider a simple requirement:
"Allow customers to cancel individual items from an order."
In a microservices architecture, this change might involve Order, Payment and Inventory services.
Does the agent need to understand the implementation of all three services before it can start? Not really.
It first needs to understand how these services interact, which service owns what, and the business rules governing the cancellation workflow. With that understanding, it can inspect the relevant source code, tests and contracts to determine what needs to change.
This brings us to an important distinction: system understanding and implementation understanding are two different things.
We can maintain system understanding through structured Markdown documents that describe service responsibilities, business rules, workflows, dependencies and architectural constraints.
Implementation understanding comes from the source code itself. The agent can inspect the relevant files when it needs to understand or modify a particular behaviour.
We don't need to load every repository into the LLM. We need to discover which parts of the system are relevant to a requirement and provide the agent with that context.
The goal isn't to maximize the amount of context we feed an LLM. It's to provide the right context for the task at hand.
So where should we maintain this context when the system is distributed across multiple repositories?
Keep Context Close to the Service, and Connect It Centrally

I would approach this by maintaining context at two levels.
1. Microservice-level context
Each microservice should own its context, just as it owns its source code.
For example, the Order Service repository could look something like this:
The ai-context folder contains the knowledge needed to understand the service: its purpose, business capabilities, rules and internal workflows.
The AGENTS.md file serves a different purpose. It tells the coding agent how to work within the repository, including architectural constraints, coding conventions, build commands and testing instructions.
Keeping this context alongside the code also establishes clear ownership. The team maintaining the service is responsible for keeping both in sync.
2. System-level context
Service-level context explains individual services, but it doesn't tell us how the entire system fits together.
For that, I would introduce a separate system-context repository.
Something like this:
This repository maintains the system-level view. It captures:
- The services that exist and the business capabilities they own.
- Dependencies and communication between services.
- How business workflows span service boundaries.
- Business and architectural constraints that apply across services.
- The APIs and events that connect them.
For example, the order cancellation workflow might involve Order, Payment and Inventory services. The system-level context explains how these services collaborate to complete that workflow.
There is an important design principle here: the system-context repository should connect information, not duplicate it.
The Order Service remains the owner of its business rules and API definitions. The central repository references these artifacts and explains how they relate to other services.
This avoids maintaining the same information in multiple places.
We now have two levels of context: each service owns its knowledge, while the central repository connects these individual pieces into a system-wide view.
But how does an AI agent know which services are relevant to a given requirement? That's where the orchestrator comes in.
How Does the Orchestrator Bring It All Together?

We shouldn't expect developers to identify the affected microservices before asking for a feature. They should be able to describe what they want in business terms.
This is where I would introduce an orchestrator as the interaction layer between the developer and the AI engineering ecosystem.
Let's take our earlier example:
"Allow customers to cancel individual items from an order."
The developer submits this requirement to the orchestrator. It analyses the requirement and consults the system-level context to identify the relevant workflows and services.
The service catalog provides service ownership information, workflow documentation identifies participating services, and the dependency map and contract index explain how they interact.
For our order cancellation example, the orchestrator might identify that Order Service owns the order lifecycle, Payment Service handles refunds, and Inventory Service manages stock reservations.
It then retrieves the relevant service-level context and makes the necessary API and event contracts available to the coding agents. The agents can inspect the actual source code and tests when they need implementation details.
Where Do the Repositories Live?
The orchestrator also needs a predictable way to locate the repositories it has identified.
I would establish a common workspace structure for the application. For example:
This is a logical workspace arrangement, not a monorepo. Each service and the system-context repository remains an independent Git repository, with its own history and release cycle.
The orchestrator needs to run in an environment with access to this workspace so it can clone, inspect and modify the relevant repositories.
The central service catalog maintains each repository's Git URL and its relative location within the workspace. When a requirement comes in, the orchestrator looks up the relevant services and resolves their local paths.
We don't need to clone every repository upfront. The orchestrator can clone repositories as needed and reuse existing local checkouts whenever they are available.
For concurrent tasks, isolated Git worktrees can prevent changes from one task interfering with another.
From Context Discovery to Code Changes
With the relevant repositories and context identified, the orchestrator prepares an execution plan and delegates the work to coding agents.
Each agent works within its respective repository, using the service-level context and selectively inspecting source code and tests to implement the required changes.
Once the changes are complete, each agent can raise a PR in its repository. The orchestrator tracks these PRs as part of the same engineering task, giving the developer a unified view of a change spanning multiple services.
For a more reliable production setup, an integration/review agent can validate cross-service contracts and end-to-end behaviour before the changes pass through the engineering gates.
The developer no longer needs to gather context from multiple repositories or coordinate every agent manually. The orchestrator connects the system-level understanding with the service-level implementation work.
However, this approach depends on one important thing: the context must remain accurate as the code evolves. Otherwise, the orchestrator will make decisions based on an outdated understanding of the system.
Keeping the Context in Sync with Code

The context we maintain today must accurately reflect the system tomorrow.
Microservices evolve. APIs change, dependencies are introduced, business rules change and workflows become more complex. If our context doesn't evolve with the code, agents will eventually work with outdated information.
I would make context updates part of the PR process.
Whenever a developer raises a PR, an automated process should analyse the changes and identify the context documents that may need updating.
For example, an API change might affect the service's contract documentation and the central contract index. A change to business logic might require an update to a service-level rule or a system-level workflow.
The process would look like this:
- Detect changes: Identify changes to business logic, APIs, events, database structures and service dependencies.
- Propose context updates: Generate updates to the relevant service-level and system-level documents.
- Review together: Review the code and context changes as part of the PR process.
- Merge together: Merge both once the changes are approved.
For larger systems, we can add a scheduled GitHub Actions workflow to this process. A nightly scan can look for context drift across repositories, use an AI agent to propose updates and raise PRs for the respective teams to review. This provides an additional reconciliation mechanism; it doesn't replace PR-based updates.
There is one important distinction: not all context can be generated automatically.
Facts such as API definitions, service dependencies and event contracts can often be extracted from code. But the reasoning behind a business rule, the intent of a workflow or the trade-offs behind an architectural decision may not be obvious from the implementation. These details still need input and review from people who understand the business and architecture.
Service-level context updates can be reviewed alongside the service PR. When a change affects cross-service workflows or relationships, the corresponding update to the central system-context repository should be linked to that PR.
This way, documentation doesn't become a separate activity that someone might remember to do later.
The code and the context that explains it evolve together, and both are reviewed before the change becomes part of the system.
How to Get Started with an Existing Brownfield System
We don't need to transform the entire application or document every microservice before introducing this approach.
I would start with one business workflow that spans a few services.
Here's how I would approach it:
- Start with one business capability: Pick an existing workflow, such as order cancellation or order fulfilment, and identify the services involved.
- Establish service-level context: Add structured Markdown documentation to those repositories, covering service responsibilities, business rules, workflows and architectural constraints.
- Build system-level context: Create the central service catalog and document how the services interact within the selected workflow.
- Introduce the orchestrator: Let developers submit requirements through the orchestrator. Use the available context to identify relevant services and assemble the information needed for each task.
- Keep the context updated: Introduce PR-based context updates and gradually automate the process as the approach matures.
Once this works for one workflow, we can extend the same approach to other parts of the application.
We can also introduce engineering quality gates incrementally through an approach like our Bulletproof repository. This ensures that changes generated by agents meet the engineering standards we expect.
Bringing It All Together
Coming back to Nandha's original question, we don't need to consolidate our microservices into one repository or feed the entire application into a single LLM.
We need to make system knowledge discoverable, keep service knowledge close to its source, and connect it through a central system-level context.
The orchestrator uses this context to understand developer intent, identify relevant services and give coding agents the information they need to make changes.
As the system evolves, the context evolves with it through the same engineering process.
The goal isn't to make one LLM understand the entire enterprise system. It's to make sure every agent has access to the right knowledge when it needs it.


When to Hire CodeWalnut?