In this article
A repository is a convenient unit for giving work to a coding agent. It contains the code to change, the local conventions and the tests to run. The architecture of the system may depend on agreements with services owned by other teams, in repositories the agent hasn't opened.
Better documentation in the first repository helps explain that service. It doesn't automatically keep those agreements consistent. One team can change what a published result means while another continues to interpret it the old way. Both repositories can describe their own implementations accurately, and the system can still have a problem between them.
Teams already coordinate changes with their consumers and with the services they depend on. I want an agent to find the constraints that should shape its implementation and identify the owners who need to be involved. Retrieving their records doesn't establish that those teams have agreed to new work or have the capacity to deliver it.
My current preference is to keep service-owned facts beside the code and assemble the wider view from references to those sources. The difficult part is keeping those connections current as the services evolve.
Keep facts with the team that can change them
A service team can maintain its published contract, responsibilities and local design decisions with its implementation. A contract change and its explanation can then be reviewed together. The team still has to do that work; putting a document in the repository doesn't keep it accurate by itself.
Consider a fictional shop adding a feature: customers can correct the delivery address on an order that has not shipped yet. Work starts in order-service, which stores the address and the order's status. One candidate implementation allows the update while the order is awaiting_shipment.
But fulfillment-service copies the address when it starts preparing the shipment and prints its label from that copy. Preparation happens before the order is marked shipped. Updating the order record alone doesn't refresh the prepared shipment. A customer could see their new address on the order page while the parcel still carries the old one on its label.
Even with both repositories available, the agent needs to establish how prepared shipments can be amended before choosing the implementation. An existing fulfillment operation might be enough, with code changes confined to order-service. If fulfillment cannot amend prepared shipments, the teams need to agree on additional work and its delivery timing, or product needs to accept an earlier cutoff for address changes.
The order team owns the definition of its address and status fields. The fulfillment team can document when it takes the copy and what changes it accepts afterward. If a shared decision defines who controls the destination once preparation starts, I'd keep that decision with the people responsible for the agreement and reference it from both repositories.
A central documentation site could make all of this easier to read. I'd still want edits to go through the owners of the underlying facts. A searchable copy is useful as long as it retains its source and version; a second description maintained independently creates another place to reconcile after a change.
Assemble a view across the repositories
The wider view would connect those sources. Fulfillment's documented use of order addresses could lead back to the order contract, while a shared decision could identify the services it governs. The order team wouldn't have to maintain a separate list of every declaration made by other teams.
For a few services, versioned links and scoped searches might be enough. As those references grow, I'd consider a derived index that can follow them in either direction. Its records should point back to the specific revisions of the artifacts that supplied the relationship, so an agent or reviewer can inspect the evidence instead of trusting an unexplained edge.
Teams maintain those source records. An index records their links and provenance; the agent uses the proposed change to choose which records to read. That selection shouldn't become another permanent copy of the architecture.
A declared dependency and an observed call need to remain distinguishable in that index. The declaration describes an expectation; the observation records an interaction in a particular environment and time window. An inferred relationship from code search is a lead to inspect. None should silently overwrite the others or become a claim that every dependency has been found.
The same care applies to decisions. An accepted decision may describe the intended architecture while some services are still being migrated. The agent needs to see what was agreed and what has actually been rolled out. A current decision and an implementation that still follows its predecessor can coexist during that transition.
Start retrieval from the proposed change
I'd start with the task's intent and the service being changed. As the agent investigates, affected interfaces and responsibilities become additional entry points into the wider view.
For the address-editing feature, the order's address and shipment status would lead the agent to investigate fulfillment's preparation workflow and whether prepared shipments can be amended. The timing of that handoff affects whether a proposed update can change the delivery destination. A relevant ownership decision could explain which team must approve changes to that workflow. The agent doesn't need every design document owned by either team.
That selection has to happen early enough to influence the implementation. Waiting for a finished diff would miss the chance to question whether the agent is changing the right service in the first place. If its investigation expands the proposed scope, it should revisit the related decisions before continuing.
The selected context should retain the source references and explain why each item is relevant. A superseded decision can explain how the system got here; the current decision tells us which agreement the proposed change must consider. The task may intentionally change that agreement, but then the decision change needs to be explicit and reviewed with its owner.
If the status is unclear, or the implementation appears to contradict the decision, that is also a question for its owner. The agent shouldn't settle it by treating either code or documentation as universally authoritative.
There will also be missing evidence. A repository the agent cannot access, or a relationship it has only inferred, should remain visible as a gap alongside the selected sources. The agent can ask for the missing evidence without presenting its partial investigation as a review of the whole system.
Keeping the connections current
This is where the proposal needs more than repository synchronization. Fetching the latest files can refresh the index while leaving an agreement between teams unresolved.
Suppose the teams agree to allow address edits only until shipment preparation starts. If fulfillment later starts preparation earlier, customers have less time to edit while an order is still awaiting_shipment. The teams' documents can still link to valid contracts. They need to check whether the shorter window still meets their agreement; a working link won't answer that.
Changes to the artifacts a relationship cites should make it a candidate for re-evaluation. That doesn't prove the agreement broke, and it won't catch a behavioral change no one connected to those artifacts. Where the relationship has an executable expectation, a test can check it. Where a decision is being replaced, the people responsible for that decision need to identify the affected services and make its new status visible.
The team changing a published contract should be able to see which declared relationships need another look and who can answer for them. If the change alters a shared responsibility, the owner of that decision needs to reconcile it with the affected teams. Refreshing the index should not mark that review complete.
Where I'd start
I'd try this with one shared architectural decision and the services it governs. The next change touching that decision would be a small test: can the agent find and apply it before settling on an implementation?
I still don't know how much of this can be kept current at scale. Alongside the agent's result, I'd want to understand the work the owners needed to keep the sources and relationships accurate. That maintenance effort would inform whether to expand the approach.