The architecture is visible in the code. The rationale behind it often is not. Six months after a system is built, a new engineer can inspect its modules and dependencies but still cannot tell whether an unusual design was deliberate, a temporary compromise, or a workaround for a constraint that no longer applies.
Software architecture researchers have long studied this as architectural knowledge vaporization: design decisions, assumptions and trade-offs gradually disappear even while the software remains. It is a practical problem for engineering teams and, increasingly, for the AI coding agents that work alongside them.
Why a codebase does not explain its own decisions
Consider a service that uses a particular storage engine. Its configuration shows the chosen technology, but the repository may not explain why the team rejected alternatives. Perhaps there was a latency requirement, a data-residency constraint, an operational limitation, or a migration deadline.
Without that rationale, a developer or agent may confidently propose the previously rejected option. The suggestion may be technically reasonable but incompatible with a decision that still applies.
The missing information is not just documentation about what exists. It is a record of why it exists and when the reasoning should be reconsidered.
Architectural decision records are a useful starting point
An Architecture Decision Record (ADR) is a short record of one significant architectural decision. A useful ADR explains the context, the decision, the alternatives considered and the expected consequences. When a decision changes, preserving the original record and linking to its successor helps future readers understand the evolution of the system.
ADRs are particularly effective when they live close to engineering work and are reviewed with the same care as code. They also have limits: someone must write them, keep them current, connect them to the evidence and make their status discoverable.
For an AI coding agent, an old ADR that is easy to retrieve but already superseded can be worse than an absent one. It provides apparently authoritative instructions without explaining that they no longer apply.
A practical way to keep design rationale usable
A lightweight record should answer five questions:
- What was decided? State the choice unambiguously.
- Why? Record the constraints, evidence and major trade-offs.
- What was rejected? Preserve the alternatives that would otherwise be proposed again.
- Who owns it? Identify who can review the record and authorize a change.
- Does it still apply? Make its status, scope and supersession history explicit.
A decision does not have to be frozen forever. It must be possible to revisit it without losing the original context. Keeping relevant evidence connected to the decision makes that review faster and more reliable.
When people and coding agents share the same project
Humans frequently hold architecture rationale in memory. Coding agents are more likely to receive a repository snapshot, a prompt and a narrow task. They can follow the visible implementation while missing the unwritten boundaries around it.
Providing relevant, approved design decisions to both people and connected agents before they start a task reduces the need to reconstruct context. When new constraints or observations emerge during work, the agent can propose an update; a responsible person should review it before it becomes team-wide guidance.
This is the context-in, learning-back workflow behind AuzzurA DM. DM does not execute coding agents or independently verify their results. It prepares applicable context, and connected agents can submit candidate learning for human review.
To see that workflow applied to software work, read coding-agent alignment. To compare decision records with execution tracking, see decision memory versus task management.
Further reading
The original version of this article discussed Kruchten, Lago and van Vliet’s work on architectural knowledge, research on architectural knowledge vaporization, industry guidance on ADRs and Martin Fowler’s Architecture Decision Record. These provide useful background on why decision rationale is a distinct engineering artifact.
If your team’s answer to “why did we build it this way?” still depends on finding the one person who remembers, start with one high-impact ADR. Preserve its trade-offs and link it to the evidence; then decide how that context should reach the next person or agent.
One team. One workflow. One governed loop.
Test AuzzurA with a single agent workflow in 2–4 weeks.