How to Have an Agent Implement from an ADR Alone?

If you only paste “roughly do this” in chat, the agent fills in scope, alternatives, and pass criteria on its own. Agent ADR implementation shrinks that fill-in by making one Architecture Decision Record (ADR) (or a small set) the only implementation spec, and keeping code plus verification inside that document’s boundaries.

This post covers only required sections? · how to limit code scope? · verification steps?. No product pitches, pricing, or affiliates. Grounding: the MADR template (Context / Options / Decision Outcome / Consequences / Confirmation) and Nygard-style ADR’s minimal Context · Decision · Consequences.

What sections must the ADR include?

One-line answer: For agent delegation, an ADR needs at least Context and Problem Statement · Considered Options · Decision Outcome (+ Consequences) · Confirmation (how we verify). A title-and-status sticky note is not a spec.

From the MADR full template, the parts an agent actually consumes:

Section	Signal to the agent	If missing
Context and Problem Statement	What to solve; what is out of goal	“Improves” neighboring modules
Decision Drivers (recommended)	Qualities, constraints, KO criteria	Picks options by taste
Considered Options	The menu (including rejected ones)	Invents a fourth option
Decision Outcome	Chosen option + because	Quietly swaps the choice mid-impl
Consequences	Good / Bad outcomes	Scope creep while “fixing” side effects in code
Confirmation	Review, tests, arch rules	Declares done when “it runs”

Even on MADR bare, do not leave Context · Considered Options · Decision Outcome · Consequences empty. For agents, treat Confirmation as effectively required—without a reproducible “how we know it matches,” you cannot gate Done.

Metadata (status, date, deciders) is for humans and audit. Hand the agent accepted (or equivalent) ADRs only; exclude proposed / deprecated from delegation.

Copy-paste agent preamble:

You implement ONLY what ADR-NNNN decides.
Do not reopen Considered Options.
Do not invent a 4th option.
Out of scope = anything not required by Decision Outcome + Confirmation.
If ADR text conflicts with existing code, STOP and report the conflict; do not “fix by rewriting neighbors”.

Boundary: An ADR is a decision record, not a full API spec. Put interface detail in linked OpenAPI/skeletons under More Information; keep Decision Outcome to choice and rationale.

How do you limit code scope?

One-line answer: State allowed paths, forbidden paths, and definition of done in the ADR, and pin the same path allowlist + “no reopening options” wording in the agent Skill/Rule. “Figure it out across the whole repo” is not a scope.

Practical limit axes:

Axis	Write in ADR / prompt	Failure signal
Paths	Only `src/billing/`, `tests/billing/`	Diffs in unrelated packages
Decision lock	Chosen option name unchanged	Swaps library/pattern
Non-goals	“No migration, rename, or repo-wide format”	Large cleanup commits
Dependencies	No new packages, or an allowlist	Undocumented dep adds
Interfaces	No public API signature changes (when applicable)	Cascading call-site edits
Commits	One ADR = one logical change (or stated N commits)	Mixed junk

Add an Implementation Boundary block at the bottom (or under More Information):

## Implementation Boundary (agent)
- Allow paths: src/payments/retry/**, tests/payments/retry/**
- Forbid: src/payments/legacy/**, infra/**, package.json dependency bumps
- Must implement: Decision Outcome “exponential backoff with jitter”
- Must NOT: switch to linear backoff; add new HTTP client
- DoD: Confirmation section checklist all green

Copy the same block into the Skill so doc and agent instructions stay one source. If the two diverge, the agent follows the wider wording.

When something is out of scope:

On out-of-scope discovery:
1. STOP editing.
2. Quote the ADR section that lacks guidance (or conflicts).
3. Propose at most one follow-up ADR title — do not implement it.
4. Leave the tree only with in-boundary changes (or restore).

Do not: “Refactor everything first, then align to the ADR.” Order is ADR accepted → implement inside the boundary → Confirmation.

What are the verification steps?

One-line answer: Turn MADR Confirmation into reproducible commands and a checklist, and accept Done only when the same commands exit 0 in the agent Done hook. “Looks good in chat” is not verification.

Split Confirmation into agent gates:

Static / architecture rules — e.g. forbidden layer imports, only allowed modules (team rules, ArchUnit-style checks, custom lint).
Unit / contract tests — tests named for the Decision Outcome behavior must pass.
Boundary diff check — fail if git diff --name-only leaves the allow paths.
No option regression — fail if symbols/config from a rejected option reappear (simple grep or a test).
Human review points — checklist that Consequences’ Bad items show up in code/ops runbooks.

Done gate skeleton:

Gate (all must exit 0 before done):
  ./scripts/adr-confirm.sh ADR-00NN
  # internally:
  #  - path allowlist vs git diff
  #  - tests named/marked for this ADR
  #  - optional architecture rule pack
Report: failing step name + ADR Confirmation quote.

adr-confirm.sh may parse the Confirmation checklist from the ADR file or read a maintained adr/NNN-confirm.yaml. What matters is that Confirmation in the doc and the script point at the same items.

Status rules:

ADR status	Agent implementation	Notes
`proposed`	Do not delegate	Human decision pending
`accepted`	In-boundary impl + Confirmation	Default
`deprecated` / `superseded by …`	No implement/extend	Follow-up ADR only
Mid-impl: decision insufficient	STOP + ask	Do not invent filler

One-line wrap-up: Agent ADR implementation = accepted ADR with MADR-required sections · Implementation Boundary locks code scope · Confirmation runs as a script gate. Chat instructions alone do not replace it.

FAQ

Is Nygard’s Context / Decision / Consequences enough?

Yes—but for agent delegation, still list Options in at least one line and attach Confirmation (or an equivalent test list). With only three sections, agents reopen the choice too easily.

Can I hand several ADRs at once?

Prefer one (or a few with clear dependency) per turn/PR. If several, state apply order and which ADR wins on conflict in the preamble. Without order, the agent mixes them for convenience.

What if code already exists ahead of the ADR?

Either capture as-is into an accepted ADR, or STOP on mismatch. Letting the agent rewrite the ADR to match the code collapses the decision log.

What if Confirmation is only “human review”?

Gate machine-checkable items first; leave human review as the residual checklist. If everything is subjective, you cannot automate agent Done.

Sources

MADR — Markdown Architectural Decision Records — full template: Context, Drivers, Options, Decision Outcome, Consequences, Confirmation
MADR template (GitHub) — bare / minimal / full templates
Michael Nygard, “Documenting Architecture Decisions” — Context / Decision / Consequences minimal skeleton (common citation)
Team practice: wire Implementation Boundary + adr-confirm.sh into the Done hook — tables in body