Your coding agent is missing one thing: architectural context.
I’ve been a big believer in Architecture Decision Records (ADRs) long before coding agents came along.
Documenting decisions gives engineers context:
Why is the system designed a certain way? What constraints existed at the time? What tradeoffs were made?
That context matters. It also matters for agents.
🤖 Agents Need Context Too
Unlike human engineers, agents don’t get context from hallway conversations, shadowing others, or tribal knowledge.
They only know what you capture. The best way to capture architectural context? Write it down as a decision record—and make it accessible to agents.
The only question is, what’s the best way to make decision records accessible?
🏗️ Option 1: MCP Server
If your ADRs live in a wiki or documentation system, you can expose them through an MCP server.
This works well when documentation is spread across teams or multiple systems that need to be aggregated.
You want a unified interface for agents.
MCP is a good approach, but it comes with some infrastructure overhead.
🧱 Option 2: Keep ADRs in Git
I’ve long preferred storing ADRs in Git.
It provides versioning, review workflows, automated validation, and is where engineering work happens.
Storing ADRs in Git, ideally alongside your code, is the fastest way to give agents usable context.
The challenge is that architecture often spans multiple services and repositories. So many centralize their architecture into a single repository, which is not where your code lives.
🌉 Bridging the Gap
Most modern coding agents let you include additional directories or sources at runtime, either through slash commands or CLI options.
That means you can: open your codebase, include your architecture repository, and run the agent with context.
Just adding another directory gives your agent an understanding of system constraints, architecture decisions, technology choices, and surrounding systems. These are not things an agent can reliably infer from code alone.
💡 Final Thought: Why Context Matters
With architectural context, agents produce code that aligns with your system.
When engineers understand the system end to end, they make better decisions. The same applies to agents.
If you want better results, give better context.