Every engineering organization loses knowledge the same way: the person who knew why a decision was made leaves, and six months later a team relitigates a choice that was settled with good reasons nobody wrote down. Architecture Decision Records (ADRs) are the standard cure - short documents that capture a decision and its rationale. The problem is that humans, under deadline, do not write them. So we taught agents to.
What an ADR captures
A good ADR is small and specific. It records the context that forced a decision, the options considered, the choice made, and the consequences accepted. The value is not the conclusion - it is the reasoning, because the reasoning is what lets a future engineer understand whether the decision still holds when circumstances change.
Why agents are well suited to this
The reason ADRs go unwritten is friction: at the moment a decision is made, everyone wants to move on to implementation, and writing it up feels like overhead. Agents remove that friction. An agent that is already part of the design conversation has the context to draft the record while it is fresh - the options that were on the table, the trade-off that decided it, the constraints in play. The human reviews and corrects rather than starting from a blank page, which is the difference between an ADR getting written and not.
Note: The agent drafts; the human owns. An auto-generated record nobody reviews is just plausible-sounding text. The point is to lower the cost of capture, not to remove human judgment from it.
Lifecycle, not a write-once file
Decisions are not permanent, and neither are ADRs. A record has a status - proposed, accepted, superseded, deprecated - and the interesting work is managing that lifecycle. When a new decision overrides an old one, the old ADR is marked superseded with a pointer to its replacement, so the history stays intact instead of being silently overwritten. An agent maintaining this keeps the decision log coherent: nothing is lost, and the current state is always clear.
Decisions that feed retrieval
The step that makes this more than tidy documentation is connecting ADRs to retrieval. When decisions are captured in a consistent, structured form, they become part of the knowledge an agent can search. The next time someone - or some agent - asks "why do we use this messaging pattern?", the answer is retrieved from the actual decision record, not guessed. Institutional memory stops being a wiki nobody reads and becomes a queryable substrate the whole system draws on.
Wrapping up
The knowledge that evaporates when people leave is almost always decision rationale, and the reason it evaporates is that capturing it has always been friction nobody had time for. Letting agents draft ADRs while context is fresh, keeping those records in a managed lifecycle, and feeding them into retrieval turns scattered tribal knowledge into durable, queryable institutional memory. The decisions you make today stay explainable long after the meeting is forgotten.
Want to build an engineering org that remembers? Let's talk.
