When an AI agent writes part of the code, the diff records the result but does not preserve the reason for the choice. An engineering decision record should keep the problem, alternatives, evidence that was checked, the person who accepted the decision, and what would make the team reopen it.
That does not mean saving the entire conversation with the agent. It means turning a durable decision into a short, versioned, searchable document. A lean AGENTS.md for coding agents remains the place for stable instructions. The decision record keeps the history of why.
Short answer
- Record choices that change structure, quality, operations, or a hard-to-reverse boundary.
- Separate the agent's proposal, verified evidence, and the accepted human decision.
- Include rejected alternatives, trade-offs, confidence, and the condition for reopening the record.
- Keep the file in the repository and supersede accepted decisions with a new linked record.
- Use CI to check presence and shape, not to declare that technical judgment is correct.
Why a diff is not a decision record
A diff explains which lines changed. It does not explain why the team chose a queue instead of a synchronous call, accepted weaker consistency, or rejected an agent suggestion. After a few sessions, the code preserves the choice while the reasoning may have disappeared from the available context.
Microsoft defines an architecture decision record as a record of how and why a system reached its current shape. Its guidance recommends context, alternatives, rationale, consequences, confidence, and status, and says that a changed decision should be replaced by a new linked record (Microsoft, ADR guidance). Agent participation adds fields that keep a suggestion from looking like verified knowledge.
Recent practitioner discussion describes the problem in direct language: decisions disappear across long sessions, compaction, and different agents. In a discussion on r/ClaudeCode, participants mention a short DECISIONS.md, the reason for rejection, and an instruction to read the file. That is a language and failure-mode signal, not proof that one format improves engineering metrics.
Which decisions deserve a record?
Do not turn every syntax choice into an ADR. Record what changes system behavior or the work of the next maintainer. A useful filter is whether someone could make the opposite choice without knowing a risk the team has already discussed.
| Record it when the choice... | Example with an agent | Evidence that belongs in the record |
|---|---|---|
| changes system structure | moves processing into a worker and queue | diagram, contract test, or operational constraint |
| changes a quality attribute | accepts eventual consistency to reduce coupling | requirement, available measurement, or declared limit |
| is hard to reverse | chooses an event format or database | alternatives, migration cost, and dependencies |
| fixes an agent boundary | allows reads but requires approval before writes | policy, permission test, and owner |
| rejects an important hypothesis | avoids a tool or model for a task | rejection reason and condition that would change it |
The Microsoft Engineering Playbook recommends a decision log because decisions and consequences are easily lost inside large documents. The record can be short. The key is that context and consequence should not depend on session memory.
Do not confuse this history with an execution record. The coding-agent observability guide for CI explains what happened during a run. The decision record explains why the system should follow that path.
What fields should an AI-aware decision record add?
A traditional ADR needs a problem, options, decision, trade-offs, and status. An agent-assisted workflow should add the provenance of the proposal and the state of the evidence. Record what the agent suggested, what a person checked, and who accepted the risk.
Use docs/decisions/ or the equivalent directory:
---
status: accepted
date: 2026-11-15
owner: name-or-team
confidence: medium
validUntil: 2027-11-15
supersedes: null
---
# Use an idempotency key at the order boundary
## Context
The worker may receive the same message after a timeout.
## Options considered
- Accept the last write and reconcile later.
- Reject duplicates with an idempotency key.
## Decision
We will check the idempotency key before the mutation.
## Evidence
- Test: `npm test -- idempotency`
- There is no distributed-load measurement yet.
## AI participation
The agent proposed both options and generated a first test.
A person reviewed the retry case, ran the suite, and accepted the trade-off.
## Consequences
We gain a duplicate barrier, but we must expire keys.
## Reopen when
The delivery contract changes or expiration causes collisions.
The important fields are context, rejected alternatives, decision and consequences, evidence, AI participation, owner, confidence, validity, and the condition for reopening. Keep confidence: low when the evidence is weak. The Microsoft ADR guide explicitly recommends recording confidence even when it is low. A position paper on epistemic status and temporal validity makes a similar research argument, but it is not an adopted standard or validation of this template.
How do you separate an agent proposal from a human decision?
Use three states:
- Proposal: the agent summarized options, suggested an implementation, or produced a fixture.
- Verification: a person checked the contract, ran relevant tests, and verified that the evidence answers the question.
- Decision: an accountable person accepted the result, trade-off, and limits.
An agent can fill a draft. It should not assign its own confidence or turn a passing test into architectural approval. If verification was not run, say so. If only one scenario was covered, name the gap.
This also helps a portfolio. The portfolio README that shows engineering judgment presents a choice to a reader. The repository record preserves the process for the team and future sessions. They are related documents with different jobs.
An AI software engineer portfolio can point to these records as evidence of judgment, but a public page does not replace the project's operational documentation.
How should you store and update the records?
Start with a versioned directory and one file per decision:
docs/decisions/
0001-use-idempotency-key.md
0002-run-agent-read-only-by-default.md
Link the record from the README, area documentation, or code comment that depends on it. Do not paste the entire record into AGENTS.md: operating instructions and decision history age in different ways.
After acceptance, treat the record as append-only. If the context changes, create another file with status: superseded, link the two, and explain what changed. Quietly editing the old decision removes the history you meant to preserve. Do not create a record for every prompt. Use one for a choice that changes direction, risk, or a contract another agent must follow.
How can CI validate the format?
CI can check that a record is readable and complete. It cannot prove that the choice is good. The script below is illustrative but executable with Node.js and no dependencies:
import { readFileSync } from "node:fs";
const file = process.argv[2];
if (!file) {
console.error("Usage: node scripts/check-decision-record.mjs <file>");
process.exit(2);
}
const text = readFileSync(file, "utf8");
const required = [
"Context",
"Options considered",
"Decision",
"Evidence",
"AI participation",
"Consequences",
"Reopen when",
];
const missing = required.filter(
(heading) => !new RegExp(`^## ${heading}$`, "im").test(text),
);
if (missing.length > 0) {
console.error(`Missing sections: ${missing.join(", ")}`);
process.exit(1);
}
console.log(`Decision record is structurally complete: ${file}`);
Save it as scripts/check-decision-record.mjs and run node scripts/check-decision-record.mjs docs/decisions/0001-use-idempotency-key.md. Prerequisites are Node.js with ES module support and a Markdown file using the headings. Run it once with the complete example and once after removing a section. If the repository uses strict YAML frontmatter, add a parser and checks for status, owner, and confidence; this example does not validate YAML, facts, evidence quality, links, or human authorization.
The important test remains outside the script: can someone who missed the conversation understand the problem, find the rejected alternative, repeat the verification, and tell when the decision expires? A green check cannot close that gap.
Common failures and limits
Record only the result. “We use a queue” does not explain the constraint, cost, or rejected option.
Let the agent write the final decision alone. Automation can draft and point to evidence. Acceptance needs an accountable person or team.
Turn confidence into a decorative score. high without a test or verifiable argument is not proof.
Put everything in one memory file. Separate stable instructions, accepted decisions, and working notes.
Edit the past to make the story neat. If the choice changes, mark the old one superseded and write the new one.
Assume the record replaces tests. Documentation makes reasoning auditable. It does not validate security or measure load by itself.
Closing
A decision record for AI-assisted code is not an agent diary. It is a technical-accountability artifact that makes the problem, alternatives, evidence, tool participation, human decision, and reopening condition visible.
Start with docs/decisions/, a short template, and a supersession rule. Link each decision to the code or pull request that depends on it. If volume justifies it, validate the shape in CI. A check cannot replace the judgment about whether the evidence supports the choice.
How this article was produced
Samuel Fajreldines is responsible for this article. The research compared current Microsoft ADR guidance, a versioned engineering decision log, a position paper about decision validity, and recent public discussion about context loss in coding agents. Discussions were used for language and reported failure modes, not technical proof. The diagram is an original SVG and the validator was checked locally with Node.js using a fictional record, without measuring a real team, calling a model, or running a production benchmark. AI assistance supported discovery, organization, drafting, localization, and consistency review. The author uses RemoteCode as a work tool, but it did not run production tests or provide operational experience.
Sources consulted
- Microsoft Learn, “Maintain an architecture decision record (ADR)”, accessed 2026-11-15.
- Microsoft Engineering Playbook, “Design Decision Log”, accessed 2026-11-15.
- Sankalp Gilda and Shlok Gilda, “AI-Assisted Engineering Should Track the Epistemic Status and Temporal Validity of Architectural Decisions”, position paper, accessed 2026-11-15.