Decision Records for AI Teams: Why Every Spec Change Needs an Audit Trail

Decision records are short documents that capture one decision, why the team made it, and what it costs. For AI teams, they answer the question every spec change raises later: who proposed this, who approved it, and why?

Your agents can open a dozen pull requests before lunch, and each one carries a reason that lives only in a chat window. Six months later, someone asks why the retry limit is three, and nobody remembers because the agent's context is gone. A decision record fixes that, and it keeps the auditor happy too.

What are decision records?

The best-known form is the architecture decision record, or ADR. Michael Nygard described it in his 2011 post Documenting Architecture Decisions. His point was simple: teams lose track of the motivation behind past choices, so new people either follow rules blindly or reverse them without knowing the cost.

Nygard's format has five parts: title, context, decision, status, and consequences. He suggested the whole document should run one or two pages. When a decision gets reversed, the old record stays and is marked superseded, with a pointer to the new one.

The community site adr.github.io defines an ADR as a record that captures a single architectural decision and its rationale. The collection of ADRs in a project forms its decision log. That log is the history of why your system looks the way it does.

How do teams use ADRs today?

ADRs moved from one consultant's blog to mainstream practice. The Thoughtworks Technology Radar placed lightweight ADRs in its Adopt ring in 2017 and again in 2018. It recommended storing them in source control instead of a wiki, so the record lives next to the code it explains.

Cloud providers wrote the practice into their own guidance. AWS Prescriptive Guidance on the ADR process walks through four statuses: proposed, accepted, rejected, and superseded. Reviewers read each ADR in a dedicated slot of about 10 to 15 minutes, then the owner works through the comments.

“When the team accepts an ADR, it becomes immutable.”

That rule matters more than any template field. You never edit history. If the team learns something new, it writes a new record that supersedes the old one, and the trail stays intact.

Why do AI agents raise the stakes for decision records?

ADRs were built for a world where a few senior engineers made a few big calls per quarter. AI agents flip that math. They propose changes constantly, and the reasoning behind each one often disappears when the session ends.

Agent use is climbing fast. In a Stack Overflow pulse survey of 1,100 developers fielded in April 2026, 59% said they use AI agents at work, up from 31% in 2025. Daily use jumped from 14% to 37%.

Teams are not handing over the keys, though. The same survey found 63% rarely or never let agents run fully on autopilot, and 60% block agents from making unapproved system changes. People want agents in the loop and humans on the decision.

Trust is the reason. In the 2025 Stack Overflow Developer Survey, 87% agreed they worry about the accuracy of information from AI agents. And 66% named AI answers that are "almost right, but not quite" as their top frustration.

What happens to agent pull requests today?

Agents already ship a lot of changes to real projects. A 2026 empirical study of agentic pull requests from Polytechnique Montréal examined 9,428 agent PRs across 489 popular Python repositories. Of those, 7,293 were merged.

Merge rates varied widely by agent. Human PRs in the same repositories merged at about 85%, while model-adjusted rates for agents ranged from 43% to 84%. Several agents, notably Copilot, Cursor, and Devin, drew more review comments than human PRs, and Devin and Copilot PRs carried more commits, which the authors suggest may reflect follow-up revisions.

Every merged agent PR is a decision someone made, even if they made it in 30 seconds. Every rejected one is a decision too. Without a record, you cannot tell which reasons held up and which were guesses.

What does the EU AI Act say about record keeping?

Regulators now expect a paper trail for AI. Article 12 of the EU AI Act says high-risk AI systems must technically allow for the "automatic recording of events (logs)" over the lifetime of the system. Those logs should help identify risks or substantial modifications, support post-market monitoring, and track how the system operates in practice.

Article 14 adds human oversight. High-risk systems must be designed so people can effectively oversee them, understand their limits, and override or reverse their output. People must also stay aware of the pull to over-rely on what the system recommends.

Most coding agents are not high-risk systems under the Act. But the direction is clear: logs, named human deciders, and the power to reverse a change are becoming the baseline for AI governance audit trails. Teams that keep decision records now will not scramble later.

How is a decision card different from an ADR or a commit message?

A commit message tells you what changed. An ADR tells you why, but at one or two pages it is too heavy to write for every agent proposal. A decision card sits in between: an ADR sized for review.

Crema defines a decision card as who this is for, why we're doing this, the change, the limits, and the spec text, on one screen. A reviewer can read it, decide, and move on inside one focused session. That makes it practical at agent volume.

You do not have to pick one. Keep ADRs for big architecture calls, use decision cards for every spec change, and let commit messages do their job in code. Each layer answers a different question.

What should a decision record template include?

A good ADR template for AI teams blends Nygard's five parts with the fields agents make necessary. Keep every field short. If a field needs more than a few sentences, the change is probably too big for one record.

What should you log when an agent proposed the change?

Agent proposals need a few extra fields that human ADRs rarely track. The goal is an audit trail for AI agents that a new teammate, or an auditor, can read cold. Log these every time.

• Proposer: Which agent or person drafted the change, including the agent name and the human who ran it.
• Controls in effect: The agent controls active at the time, such as which sections it could change and its limits on words, tests, dependencies, and proposals per week.
• Decider: The named human who accepted or rejected the change. An agent can propose, but a person decides.
• Time: When the proposal was opened and when the decision was made.
• Reason: Why the decider said yes or no, in one or two sentences.
• Supersedes: Which earlier decision, if any, this one replaces.

This list mirrors how Crema handles it. Crema Spec keeps an append-only audit trail of who drafted, who decided, when, and why. Permissions are set per proposer in a repo file and revoked with a one-line change, so the controls in effect are themselves on the record.

How do you start keeping decision records on an AI team?

You can start this week with nothing but a folder and a template. The hard part is the habit, not the tooling. Follow these steps.

1. Create a decisions folder in the same repo as your spec, as the Thoughtworks Radar recommends.
2. Copy the template table above into a file and trim any field your team will not fill in.
3. Require a record for every spec change, whether a person or an agent proposed it.
4. Name a human decider on every record, and never let an agent approve its own proposal.
5. Write down your agent controls in the repo so each record can point to the rules in effect.
6. Treat accepted records as immutable and write a new one to supersede, never edit.
7. Review the decision log once a month to spot patterns, reversals, and drift.

If your specs already sprawl, read what spec drift is and how it starts first. Decision records work best on top of spec-driven development, where the spec is the single source of truth. For the bigger picture, see how software factories run on specs.