Your Coding Agent Can Read the Repository. Does It Know the Architecture?

Michael Egner — Tue, 13 Oct 2026 10:30:00 +0000

AI coding agents can inspect a repository, but in existing distributed systems the architecture context they need often lives elsewhere. Using Pitstop, I show how AIP gives Claude Code evidence-qualified context for a small event change and makes explicit what still needs inspection.

A seemingly small event change

The task looked ordinary:

In MaintenanceJobFinished, replace StartTime and EndTime with a single Duration field. The workshop only needs to report how long a job took. Plan the change.

At first sight, this looks like a local event-contract change. A coding agent can find the event and search the repository for usages of the two fields.

But before changing a shared event, another question matters:

What else should be inspected before making this change?

That is where architecture context becomes useful.

AIP changes the inspection boundary

I ran the task against the hosted Live AIP Demo.

For WorkshopManagementAPI, AIP established that the service publishes through the Pitstop messaging destination and resolved five receiving services.

One of them was ReportingService.

That matters because ReportingService is deliberately added in the demo fork and is not listed as a consumer in the upstream Pitstop documentation.

AIP does not claim that ReportingService consumes MaintenanceJobFinished specifically. Its evidence establishes a narrower fact: the service is a receiver on the same messaging destination and therefore belongs inside the boundary that should be investigated.

For the coding task, that was enough:

The agent now had five concrete receiver services to consider before changing the event.

Architecture context had changed the next action before any code was edited.

Figure 1. AIP establishes five receiver services for WorkshopManagementAPI and exposes the evidence behind that architecture context.

Then the agent read the code

AIP did not tell the agent how to implement the change.

It told the agent where it needed to look.

The agent then clearly separated its own findings from AIP evidence:

My reading of the code (not AIP evidence)

That inspection found direct dependencies on StartTime and EndTime, left some receivers unresolved pending deeper inspection, and uncovered another risk inside WorkshopManagementAPI: the service is event-sourced, so already-stored MaintenanceJobFinished events still contain the old fields and must remain replayable.

The problem was no longer simply:

replace two fields with one

It had become:

change a distributed event contract without breaking existing consumers or historical events.

That is the important transition in the story.

Figure 2. After AIP establishes the inspection boundary, the agent performs its own code analysis. It finds direct field dependencies, keeps unresolved receivers explicit, and identifies stored-event replay as an additional compatibility risk.

The plan changed

The agent's first implementation step was not to edit the event.

It was to inspect the receivers AIP had identified and determine how each one handles the message.

Only after that did the plan move to implementation and compatibility.

Because the old event shape may still exist in persisted events and consumers, the agent proposed an incremental migration rather than assuming the contract could be replaced in one step.

The important point is not the exact migration technique.

It is that better architecture context changed the plan.

A task that initially looked local turned out to cross several service boundaries and include a historical-event compatibility problem.

Architecture evidence and code evidence answer different questions

The agent still searched the repository. That was necessary.

But source inspection and architecture evidence answer different questions.

Code can tell the agent how StartTime and EndTime are used.

It cannot, by itself, establish which service relationships are relevant in a particular running system.

AIP can establish those architecture relationships.

It cannot, from that fact alone, claim what a receiver does with a particular event or field.

The distinction is simple:

Architecture evidence tells the agent where to inspect.

Code inspection tells the agent what the implementation does.

For this change, both were necessary.

Where the evidence stops matters

The strongest part of the Claude response may be what it did not claim.

AIP did not know which receivers read StartTime or EndTime. It also did not establish which receivers consume MaintenanceJobFinished specifically.

So the agent did not infer that ReportingService must depend on those fields merely because AIP placed it on the same messaging path.

Instead, it carried the uncertainty into the plan and marked the service for further inspection.

That behavior matters in existing systems.

A language model can produce a plausible explanation for missing information very easily. Architecture intelligence should help it distinguish:

what is established

from

what still needs investigation

AIP did not identify "the breaking consumers."

It identified the architecture boundary the agent needed to investigate.

The agent then used the code to determine what was actually affected.

What matters for the change

Coding agents already know how to inspect code.

The harder problem in an existing distributed system is often deciding where to inspect before changing it.

The Pitstop example suggests a useful division of responsibility.

AIP establishes reusable, evidence-qualified architecture context.

The coding agent uses that context to inspect the implementation and plan a bounded change.

Tests, builds, migrations and other deterministic tools verify the implementation.

AIP does not need to become the coding agent or the verification toolchain.

Its job is narrower:

Help the agent establish the architecture context that matters for the next bounded change without reconstructing that context from scratch.

And equally important:

Make clear what the available evidence does not establish.

Try it

The hosted Live AIP Demo is public and read-only, with no account or token required. You need Claude Code 2.1.292 or later.

git clone https://github.com/EdwinVW/pitstop.git
cd pitstop
git checkout 306b5fbd0febceb6b0d0706f152a0520ca1a993a

claude plugin marketplace add michaelegner/architecture-intelligence-platform
claude plugin install aip@aip-plugins

In Claude Code, run:

/plugin configure aip@aip-plugins

Set:

aip_mcp_url = https://mcp.daip.io/mcp
aip_token   = empty

Then restart Claude Code.

Ask the following, using yesterday's UTC date:

In the Pitstop service WorkshopManagementAPI, replace the StartTime and EndTime fields of the MaintenanceJobFinished event with a single Duration field. Plan the change. Use environment pitstop-demo and the window <YYYY-MM-DD>T00:00:00Z to <YYYY-MM-DD>T23:59:59Z

Full setup and troubleshooting: Try it hosted

Architecture Intelligence Platform on GitHub

DEV Community: Michael Egner