Architecture decision records deserve a release cycle

Over the last several years professionally, I have been close to my customers’ architecture decision record (ADR) practices. In my day job, I play an integral role in authoring and shaping these and reviewing them as they go from draft to published. They are a foundational deliverable for me and I consider them one of my main work products. ADRs are more important than ever for human and AI consumption. In financial services they double as audit trail and change-management evidence (which is part of why the review and release discipline matters so much there), but the principle applies everywhere. Version control them and run them through a proper release and review cycle, similar to the SDLC or exactly like it.

What an ADR actually is

Michael Nygard proposed the format back in 2011. Five parts (title, status, context, decision, consequences), one decision per record, and short enough that people actually read them. Nygard put it well - “Nobody ever reads large documents, either.”

The status field is important. An ADR is immutable once accepted. You don’t go back and edit it. When a decision gets revisited, you write a new ADR that supersedes the old one. That history lets you trace why the system looks the way it does, not just what it looks like today.

Thoughtworks put lightweight ADRs in Adopt on their Technology Radar, recommending teams store them in source control rather than a wiki. Their take: “for most projects, we see no reason why you wouldn’t want to use this technique.” There are good templates and tooling collected at adr.github.io, and AWS Prescriptive Guidance publishes a solid guide on using ADRs for technical decisions.

Treat them like code

When your ADRs live in the repo, the cross-functional conversation happens in one place. Open a PR when you propose a decision and security, ops, application teams can weigh in right there on the decision itself before anything gets accepted. That conversation was going to happen anyway in Slack or a meeting, but now it’s captured and searchable instead of scattered.

What releasing an ADR looks like

I’ll give an example: consider a situation where you are deciding whether to adopt a queue for async processing between two services. You write an ADR with status proposed and open a PR. The usual reviewers weigh in there. Once the PR merges with status accepted, that decision is released. Months later if the team moves to a different approach, a new ADR supersedes the original, and the old record stays in the repo as history.

A CODEOWNERS entry keeps the right people in the review loop:

docs/decisions/    @architecture-team @security

You can keep a lightweight changelog in the decisions folder (even just a list of ADR numbers, dates, and one-line summaries) so anyone can scan what changed and when without reading every file.

For agents, point them at accepted ADRs only. A line in your CLAUDE.md or AGENTS.md can be as simple as:

Architectural decisions are in docs/decisions/. Follow all ADRs with status: accepted.

That way agents consume reviewed decisions rather than stale proposals or chat transcripts.

Why this matters more now

I run agents on my own projects too. Agents are stateless, so every session starts fresh without any history of past decisions. Git tells an agent what changed but not why. Without good documentation like ADRs in my workflow, I’ve had agents re-propose decisions that were already settled.

The Architecture Without Architects paper calls this “vibe architecting,” where agents make architectural decisions implicitly through prompt interpretation and prompt wording alone produces structurally different systems for the same task. The paper’s proposed remedies include review practices and decision records.

BrainGrid wrote a good piece on ADRs for AI coding agents that gets into why agents need the reasoning behind a decision, not just the final call. And someone in an r/ClaudeCode thread asked how you carry decisions across sessions without dragging along all the chat history - top-voted answer was ADRs.

Human in the loop on architecture

Human in the loop on ADRs is the foundation for successful agentic consumption and for human-to-human, cross-functional collaboration. The reviewed ADR is what your agent should consume. It went through real review and got sign-off from the people who own the decision, which is more than you can say for a prompt or a chat transcript.

I’m taking the enterprise practices I observe at my customers into my own projects and having a lot of success with it.