What the decision has to preserve
Write short ADRs for consequential technical choices, capture trade-offs and rejected alternatives, name owners, link source evidence, and retain supersession history. Make current decisions easy for both developers and agents to find before implementing changes.
Why the record becomes stale
A ticket or meeting can correctly record the outcome while losing the rationale. When assumptions change, the absence of an owner, status and review trigger turns a healthy reassessment into another round of archaeology.
A workflow that survives change
To preserve flexibility, attach the reason and status to the decision rather than freezing the implementation.
ADRs are useful and often sufficient. They become harder to use when decisions also live in product discovery, support incidents, chats, repository instructions and operational policies. A developer may not know which source contains the relevant decision—or which version superseded it. A coding agent may retrieve an apparently relevant ADR from the wrong project or environment. DM’s direction is a closed loop between approved architectural knowledge and the work that can change it: Context comes into the task; candidate learning comes back for human review before it becomes a current record.
- Before work: the coding agent receives the current, in-scope, permitted ADRs, rules and constraints for its task.
- During and after work: the agent can report material implementation decisions, tests, changed assumptions and follow-ups—not every microscopic coding choice.
- Review: candidate ADR changes are linked to the diff and evidence. A human approver decides whether they become current records or supersede earlier ones.
- Next task: the accepted update becomes part of the governed context available to the next human or agent. Agent-assisted write-back can make drafting and proposing ADR updates happen on the same cadence as development. It should not silently make every agent choice official architecture. Keeping the approval gate visible is what makes the speed useful rather than dangerous.
Where AuzzurA DM fits
DM is designed to connect ADRs and related evidence to approved decision records, track supersession, and help surface applicable constraints before human or agent development work. It complements Git-hosted ADRs rather than replacing version control.
When to revisit the choice
Should old ADRs be deleted? Normally preserve their history and mark them superseded so the reasoning remains auditable.
A decision should remain revisitable. The record needs an owner and a trigger to question its assumptions without erasing the earlier reasoning.
A first step for your team
Choose one hard-to-reverse architecture choice; create or update its ADR with alternatives, consequences, owner and an explicit review condition.
Further reading
The scenarios above are illustrative, not customer case studies. Forum posts reflect individual experiences, not representative statistics. DM product capabilities are described as design intent and should be checked against the current release before publication.
Put shared context to work.
DM is AuzzurA’s Beta product for human + AI teams. Sign up or sign in through the DM portal.