Most teams put low-level architecture in the wrong place—if they document it at all.
I recently wrote about keeping architecture documentation in Git and making it available to coding agents.
A common pattern I see is teams maintaining a central architecture repository that spans multiple services and platforms. It’s an approach I use as well—but there’s a nuance.
🏯 Architecture Has Layers
Good architecture documentation spans multiple levels.
At a high level, you have:
Business Architecture 👨💼
Capabilities, domains, and high-level concepts.
Solution Architecture 👩🎨
Mapping capabilities to systems.
Defining which systems own what.
What gets replaced.
What gets invested in.
System Architecture 👷
Services, databases, jobs, infrastructure, and how they interact.
These three layers belong in a central architecture repository.
But there is one more layer that many teams forget.
🔍 The Missing Layer
Component Architecture 🧱
This is where architecture stops being abstract and starts becoming actionable.
Things like:
- Why middleware X was chosen over Y
- How a request flows through a handler
- What interfaces exist and why
- What metrics and tracing are required
- How a feature is expected to behave
These decisions are too detailed for a central architecture repo—and too important to leave undocumented.
📦 Put It in the Codebase
Component-level architecture belongs with the code.
Not in a separate repo, not in a wiki, and certainly not only in tribal knowledge.
Why does this matter? Because this is where architecture stops being abstract and becomes a specification.
A specification for engineers, reviewers, and now, coding agents.
🤖 Why This Matters for Agents
Agents don’t understand your system by osmosis the way human engineers do.
They only know what you give them. If your architecture decisions live far away from your code, your agent:
- Misses constraints: Uses technologies that aren’t allowed in your environment
- Guesses at design: Assumes
RESTwhen you expect event-driven messaging - Makes inconsistent choices: Pulls in the wrong libraries or dependencies
But when that context lives in the repo, architecture:
- Evolves with the code
- Is versioned
- Is available at the moment it’s needed
🧠 Final Thought
I’ve always believed the best engineers don’t just understand one codebase; they learn the end-to-end system.
The same applies to agents.
If you want better output from an agent, give it the same level of detail you’d give a senior engineer.