Stop Copying Architecture into Prompts
Part 2 of the ArchContext series: how shared architecture context reduced rework, context waste, and the distance from decision to delivery
ArchContext started in the most sophisticated way possible: copy and paste.
Every time I opened a new LLM session, I dumped the same stuff into the prompt.
Requirements. Architectural decisions. Constraints. Repository details.
And for a while, that was good enough.
Then reality happened, everything changes.
A requirement evolved. We reconsidered a decision. A repository suddenly owned something it didn’t own last week.
And just like that, yesterday’s prompt was wrong. So I fixed it.
Then I remembered there was another copy somewhere.
So I fixed that one too.
Then, eventually, I had the obvious problem:
Which copy was actually the latest one?
Working alone, this was already annoying.
Once other people on the team needed the same context, it stopped being annoying. It just didn’t scale.
Private Prompts Do Not Scale
Imagine five developers working on the same system.
Each one has a slightly different idea of what the architecture is.
One has it in a prompt. Another in some notes. Someone else remembers a conversation from three weeks ago.
Then one architectural decision changes.
Now what?
Which version is the real one?
Who tells everyone else?
And, more importantly, what happens when an agent happily starts implementing something based on the old version?
We ran into this problem.
And then we found an uglier one.
Sometimes the architectural decision itself was wrong.
We had to undo it.
Undoing code is easy enough. Git has been solving that problem for decades.
Undoing an idea is different.
Especially when that idea has already leaked into prompts, conversations, local files, agent memory, and probably someone’s head.
You can’t just git revert that.
At some point we realized this wasn’t really a documentation problem.
It was a coordination problem.
Fred Brooks talked about conceptual integrity a long time ago. The basic idea is still annoyingly relevant: if everyone building the system has a different picture of the system, the architecture eventually becomes a mess.
Adding agents doesn’t magically fix that.
Actually, it can make it worse.
An agent will confidently implement whatever context you give it. Give it stale context and you’ll get perfectly reasonable code implementing the wrong idea.
That’s the problem ArchContext is trying to solve.
One architectural context. Shared by the team. Shared by the agents.
And changeable when we discover that yesterday’s brilliant decision wasn’t actually that brilliant.
We didn’t build it because we wanted prettier documentation.
We built it because we were tired of explaining the same decisions again and again.
Because agents were making different assumptions.
Because too much time was being spent correcting things that should never have been implemented in the first place.
And yes, that eventually becomes a business problem.
Every unnecessary iteration costs time.
Every misunderstanding creates rework.
Every stale architectural decision that reaches production makes the next change harder.
So the value isn’t really in having better architecture documents.
It’s in getting from a decision to working software with less nonsense in between.
More Context Is Not Always Better
The first version of the MCP had a very simple strategy: give the agent everything.
At the time, that felt reasonable.
If context is useful, then more context must be better, right?
Well... no.
That idea worked until the project started growing.
An agent working on one user story doesn’t need to know every requirement in the platform.
It doesn’t need the entire history of every architectural decision.
And it definitely doesn’t need details about repositories that have nothing to do with the task.
But that’s what we were giving it.
The result was predictable.
More tokens.
More noise.
And sometimes the one piece of information that actually mattered was buried somewhere in the middle of everything else.
Herbert Simon described the problem long before anyone was talking about LLMs:
“A wealth of information creates a poverty of attention.”
That’s basically what we were doing.
We had more information, but not necessarily better context.
A large context window doesn’t mean every fact deserves to be there.
We had started by asking:
How can we give the agent all our architecture?
Eventually we realized that was the wrong question.
The useful question was:
What does this agent actually need to know to do this task correctly?
That sounds like a small change.
It wasn’t.
It changed the way we designed ArchContext.
Give Each Agent a Job
Imagine one feature touching four repositories:
customer-portalloyalty-apiinvoice-consumerplatform-infrastructure
Although same feature, every repository has different jobs.
The portal doesn’t care about database constraints.
The infrastructure repository doesn’t need to know how the UI behaves.
The consumer probably doesn’t care about half of the decisions that matter to the API.
Yet our first instinct was to give every agent the same context.
That didn’t make much sense.
The portal agent needs to know what the user should experience and which API it can call.
The API agent needs the business rules, persistence constraints, and the contracts it owns.
The consumer needs to understand the event, what happens when processing fails, and whether handling it twice is safe.
Infrastructure needs deployment and runtime requirements.
Despite it is the same feature there are different contexts. That became an important idea in ArchContext.
Instead of asking for “the context of this feature,” we started thinking in terms of:
What does this repository need to know about this feature to do its part correctly?
So a developer—or an agent—can ask something like:
Retrieve the implementation briefing for this feature and this repository.And the answer should contain what actually matters:
what this repository is responsible for;
which requirements apply to it;
which architectural decisions constrain the implementation;
where it connects to the rest of the system;
how we know the work is correct;
and, just as importantly, what it should not build.
That last part matters.
Architecture should give you boundaries and direction.
It shouldn’t tell you what every class should be called.
John Maeda wrote:
“Simplicity is about subtracting the obvious and adding the meaningful.”
That’s pretty close to what we want from focused context.
Not less context just for the sake of being shorter.
Less noise.
The important relationships stay.
Everything else gets out of the way.
Context Has a Price
As the project grew, the prompts got bigger, token consumption grew with it
No surprise there.
More requirements. More decisions. More repositories. More history.
So the MCP returned more context.
The problem was that the task in front of the agent hadn’t necessarily become any harder.
We were just sending more stuff.
And paying for it.
Eventually we realized we were mixing two very different questions:
What do I need to implement this?and:
Why does the architecture look like this?Those are not the same question.
If an agent is implementing a feature, it probably needs the current requirements, the decisions that still apply, the constraints, the contracts, and the acceptance criteria.
It probably doesn’t need the story of how we got there.
An architecture review is different.
There, the old decisions may matter.
The decisions we replaced may matter.
The change history may matter.
So why were we giving both agents the same payload?
We shouldn’t have been.
It wasted tokens, but that wasn’t even the worst part.
It also buried the useful information under context that belonged to a different job.
Looking back, the distinction feels obvious. It wasn’t obvious when we built the first version.
The Largest Model Is Not Always the Right Model
Focused context changed something else for us.
We stopped treating every task as if it needed the smartest model we could get.
Some problems really do need one.
If you’re trying to understand changes across several repositories, argue about boundaries, compare architectural options, or figure out which trade-off hurts less, you want a model that can reason deeply.
That’s where the expensive reasoning is useful.
But once that reasoning is done and captured in ArchContext, the next task may be much simpler.
Change this repository.
Follow this contract.
Implement these acceptance criteria.
Add the tests.
Apply a decision we’ve already made.
Do we really need the strongest model available to rediscover the entire architecture before doing that?
Probably not.
A smaller model can often handle the implementation perfectly well if you give it the right context.
The workflow becomes:
Use the stronger model where the uncertainty is.
Capture the decisions.
Then give a more focused model only what it needs to do the next job.
The important part is that we are not asking every agent to rethink the whole system from scratch.
Of course, this isn’t a clean pipeline.
Code has an annoying habit of exposing things we forgot.
An implementation may reveal a missing requirement, a bad assumption, or a decision that doesn’t survive contact with the actual code.
When that happens, you go back.
Reason again.
Fix the context.
Then continue.
So no, the rule isn’t “big model for architecture, small model for code.”
Some coding problems are hard.
Some architectural decisions are easy.
The point is simpler: use the expensive reasoning where it actually buys you something.
Using the strongest model for every step usually didn’t.
Architecture Must Be Allowed to Change
Requirements change.
Code exposes things we forgot.
Production has an even better habit: it proves that some of our assumptions were wrong.
That’s normal.
The problem starts when the architecture can’t change with them.
Sometimes a decision looked perfectly reasonable when we made it.
Then we implemented it.
And discovered it wasn’t.
Architecture has to survive that.
Martin Fowler has written about evolutionary architecture as something that keeps changing with both requirements and feedback from the code.
That is much closer to what we saw in practice.
The idea that architecture happens first and implementation simply follows it is nice.
Reality is messier.
Code talks back.
And sometimes it says the architecture was wrong.
But changing a decision creates another problem.
What do you do with the old one?
Deleting it is tempting.
It’s also a mistake.
If decision B replaced decision A, the team should still be able to answer a very simple question:
Why?
Fowler makes a similar point with ADRs. An old decision doesn’t disappear just because we changed our minds. It stays in the history and points to what replaced it.
That’s why versioning became important in ArchContext.
We don’t just want to know what the architecture says today.
We want to know how it got there.
Because sometimes the history explains more than the final decision does.
Of course, versioning doesn’t magically solve everything.
Two people can change the architecture at the same time.
Git can tell us when they changed the same line.
But architecture isn’t just text.
Two changes can merge perfectly and still contradict each other.
One says optimize for consistency.
The other says optimize for availability.
No merge algorithm is going to tell you which business trade-off matters more.
Nor should it.
At some point, the humans still have to decide.
That’s not a limitation of ArchContext.
That’s architecture.
From Architecture Context to Business Value
Looking back, the value did not come from storing more architectural information.
It came from improving the flow between a business need and the software delivered in response.
Share the intent.
When teams and agents work from the same problem, responsibilities, and decisions, they spend less time resolving contradictory interpretations. Alignment reduces rework.
Guide value delivery.
When each agent receives only the context relevant to its task and repository, it can act faster and with fewer unnecessary iterations. Focus reduces both token waste and delivery friction.
Evolve through feedback.
When implementation or production reveals a bad assumption, the context can be corrected, reviewed, and redistributed. Learning does not remain inside one conversation or one person’s memory.
The loop is simple:
ArchContext does not create business value by itself.
It helps reduce the distance between the business decision and the coordinated work required to deliver it.
CLEAR and ArchContext
CLEAR describes how I approach architectural work:
Understand the problem, establish direction, execute, adapt and learn.
ArchContext does not replace that reasoning. It makes the result available to the people and agents delivering the software.
CLEAR structures the thinking.
ArchContext distributes it.
This Is Not Finished
The current version works.
It has also exposed its next set of problems.
We need better handling for concurrent context changes. We need to improve conflict resolution. Performance will continue to matter as workspaces grow.
ArchContext is still evolving, it’s a work in progress.
The results we observed did not come from the MCP alone. They came from architecture practice, focused context, engineering skills, appropriate model selection, review, testing, and Git collaboration.
ArchContext helped connect those pieces. We saw better alignment, more consistent LLM-assisted implementations, less context waste, and a shorter path from decision to delivery.
That is enough reason to keep building it.