Your Coding Agent Understands the Repository. Does It Understand the System?
Part 1 of the ArchContext series: why AI-assisted development needs shared, versioned architecture context
A coding agent opens a repository.
It reads the source code, explores the tests, identifies the framework, and proposes an implementation. The result looks technically reasonable.
There is only one problem:
The feature affects three repositories.
The agent does not know that another service owns part of the business process. It has not seen the Architecture Decision Record that requires asynchronous communication. It does not know that one of the apparent requirements was superseded last week.
The agent understands the repository in front of it.
It does not necessarily understand the system.
This limitation is not unique to AI. Developers face the same problem when architecture knowledge is scattered across diagrams, wikis, meetings, pull requests, chat messages, and the memories of a few senior engineers.
Coding agents simply make the gap more visible—and potentially more expensive.
They can generate implementation changes faster than teams can detect that those changes contradict the wider architecture.
That is the problem I am exploring with ArchContext: a local Model Context Protocol server that gives developers and LLM agents access to shared, structured, and versioned software architecture context.
Its purpose is simple:
Make architectural intent available at the moment a developer or coding agent is making an implementation decision.
Architecture Rarely Disappears All at Once
Most teams do not deliberately abandon their architecture.
Architecture becomes inaccurate gradually.
A decision changes, but the original diagram remains.
A new repository appears without a clear description of its responsibilities.
A requirement is clarified during a meeting but never connected to the implementation.
An integration contract evolves, while another team continues working from an older assumption.
Eventually, the source code and the architecture documentation tell different stories.
When that happens, developers naturally trust the code. It is executable, recent, and directly connected to delivery.
The architecture becomes historical background.
This problem becomes harder in systems distributed across several Git repositories.
A single feature may require coordinated changes to:
a frontend application;
a backend API;
an event consumer;
a shared contracts repository;
an infrastructure repository;
and an external integration.
Each repository contains only a local view of the system.
The architectural intent exists somewhere between them.
Larger Prompts Are Not the Solution
One response is to copy more context into the prompt:
Implement the feature in the loyalty service.
Remember that balances must be calculated from transactions.
Do not update a mutable customer balance.
Invoice retries must be idempotent.
Follow our Java backend guidelines.
The customer portal depends on the response contract.
This may work for one task.
It does not create a sustainable team workflow.
The same information will be copied into several conversations. Developers will shorten it, reinterpret it, or forget part of it. Different coding agents may use different instruction files and proprietary formats.
Architecture becomes duplicated across prompts.
Even worse, those prompts are rarely versioned alongside the architectural decisions they represent.
The team ends up with several partial versions of the truth.
What If Agents Could Ask the Architecture?
Instead of placing all architectural knowledge inside every prompt, an agent should be able to retrieve the context it needs.
For example:
Use ArchContext to explain the solution and identify the
repositories involved in the active loyalty-points specification.
Or:
Before modifying this repository, retrieve the applicable
requirements, acceptance criteria, ADRs, and engineering guidelines.
Or:
Explain what changed in SPEC-001 since the previous implementation.
The agent should receive a focused answer:
what the solution is trying to achieve;
what responsibility the current repository owns;
which requirements are active;
how completion is evaluated;
which architectural decisions apply;
what other repositories participate;
and what the team has explicitly excluded.
That is the role of ArchContext.
It exposes architecture context through MCP tools so that an LLM can retrieve it as part of its normal workflow.
The developer does not need to search through several documents or manually build a giant context prompt.
The Intended Experience
The primary interaction with ArchContext is not editing architecture files manually.
It is a conversation with an MCP-connected LLM agent.
An architect might say:
Create a specification for earning loyalty points from paid invoices.
The solution must keep an auditable transaction ledger.
The loyalty API owns point registration and balance queries.
Authentication and point redemption are out of scope.
The agent can use ArchContext’s controlled write tools to create the relevant architectural context.
Later, a developer might ask:
Get the implementation briefing for the active loyalty-points
specification and the loyalty-points-api repository.
The agent can retrieve the repository-specific context before touching the source code.
When the architecture evolves, the architect can say:
Clarify that processing the same invoice more than once for the
same customer must not increase the balance.
Relate this change to the append-only ledger decision and add
an acceptance criterion covering retries.
The LLM translates that intent into structured MCP operations.
ArchContext validates and persists the change.
Git records the result so the team can review what changed.
The interaction looks like this:
Architect or developer
↓ natural language
LLM agent
↓ controlled MCP tools
ArchContext
↓ validated persistence
Versioned architecture workspace
↓ Git
Other developers and their agents
The underlying context remains transparent and inspectable, but manually editing its persistence format is not the normal workflow.
Why Git Still Matters
MCP provides access to the architecture.
Git provides collaboration and history.
When architecture context is stored in a Git workspace, architectural changes can be:
reviewed through pull requests;
compared through diffs;
connected to implementation work;
traced to an author and commit;
reverted;
branched;
and discussed by the team.
Suppose an architect introduces invoice idempotency.
The team should be able to review that change independently from the resulting code:
What behavior was added?
Why was it needed?
Which decision motivated it?
Which repositories are affected?
Which acceptance criterion proves that it works?
The implementation may eventually contain a database uniqueness constraint and a retry test.
Those details do not explain the entire decision.
The versioned architecture context preserves the intent behind them.
Why MCP Matters
A team should not have to rewrite its architecture for every AI product.
One developer may prefer an IDE-integrated agent. Another may use a terminal-based coding agent. A third may use a local model.
ArchContext keeps the shared context outside those clients.
As long as a client can communicate through MCP, it can retrieve the same architectural source.
That reduces dependence on:
one model provider;
one IDE;
one proprietary instruction format;
or one agent-specific memory system.
The architecture belongs to the team.
The agent is a consumer of it.
A Practical Example: Loyalty Points
I created the ArchContext Loyalty Points Exercise to demonstrate the idea.
The example is a small Quarkus application for registering loyalty points and querying customer balances.
The implementation is deliberately simple.
The important part is the sequence represented by the Git history:
architect: add initial ArchContext context
developer: implement initial loyalty points API
architect: clarify invoice idempotency
developer: implement invoice idempotency
The initial architecture establishes an append-only points ledger.
Instead of mutating a customer balance, the system records each points transaction and derives the balance from those records.
The first implementation follows that decision.
Then a new question emerges:
What happens when the same invoice is submitted twice?
Retries are normal in distributed systems. If the application blindly appends another points transaction, the customer’s balance is increased twice.
The architecture is clarified first.
The active specification gains:
an idempotency requirement;
an acceptance criterion for repeated requests;
an implementation impact for the loyalty API;
and a change-log entry explaining the relationship with the append-only ledger decision.
The implementation changes afterward.
It adds:
uniqueness for the customer and invoice combination;
detection of an existing transaction;
an idempotent response;
and tests proving that retries do not increase the balance.
The important sequence is:
Architectural intent changes
↓
Shared context is updated through MCP
↓
The change is reviewed and versioned
↓
The implementation agent retrieves the new briefing
↓
Source code and tests are updated
Architecture is not reconstructed after delivery.
It becomes an input to delivery.
Not Architecture by Autopilot
ArchContext is not intended to make an LLM the architect.
It does not replace:
collaborative design;
domain modelling;
technical leadership;
diagrams;
code review;
engineering judgment;
or conversations between teams.
An agent may help structure a decision, identify inconsistencies, or update a specification. Humans still decide whether the resulting architecture is appropriate.
ArchContext also does not guarantee that an implementation agent will produce correct code.
Its role is narrower:
Give humans and agents access to the same architectural intent, boundaries, and history.
Better context does not eliminate the need for review.
It reduces the amount of architectural knowledge that must be guessed.
Architecture at Implementation Time
Architecture is most valuable when it is available during implementation.
Not only during a design workshop.
Not hidden in a wiki.
Not dependent on the memory of one architect.
And not copied into configuration for one particular coding assistant.
The faster implementation becomes, the more important it is to preserve:
intent;
ownership;
constraints;
relationships;
and the reasons behind change.
Git gives the team a collaborative history.
MCP gives agents a standard way to access it.
ArchContext connects both so that architecture can evolve alongside the system it is intended to guide.
In the next article, I will explain how ArchContext works as an agent-facing architecture layer: how agents retrieve focused briefings, update context through controlled tools, validate changes, and keep implementation agents from receiving obsolete requirements.