How Do You Record a Design Decision With Claude?
Right after you decide, while the discussion is still in the session, have Claude draft a one-page Architecture Decision Record in your repo. Then add a one-line pointer so later Claude sessions can find it. Otherwise, the reasoning disappears with the conversation.
We decided [decision] for [system]. Using this conversation and the code in [paths], write an Architecture Decision Record at [docs/adr/NNNN-short-title.md], using the next unused number in that folder. Use these headings: Title, Status (Proposed), Context, Decision, Consequences. State the context as plain facts, including the alternatives we rejected and why. Write the decision in full sentences starting "We will". In Consequences, include the downsides and what we're now committed to. Keep it to one page. If something wasn't actually decided here, write "Not decided" instead of inferring it. Then suggest a one-line note for CLAUDE.md pointing at this file. Don't add it until I approve.
- 1Titlenumbered, and numbers are never reused
- 2Contextask for rejected options here
- 3Decision"We will write events to an outbox table"
- 4Statusmark it superseded, never edit it
- 5Consequencesgood, bad and neutral
Try it now
- 1Send the prompt in the same session as the discussion, before you run
/clear. - 2Read the draft. Check that Consequences names at least one real downside, and that nothing is presented as decided that wasn't.
- 3Approve the
CLAUDE.mdnote, then run/context alland look under Memory files to confirm the file loaded. - 4Run
/clearand askwhy do we use [decision]?. It worked if Claude's answer cites the ADR.
Use it when
Choices a future maintainer will question: anything that looks odd without its history, or that a teammate might undo in good faith. It works in Claude Code, which can write the file directly, and in the Claude app, where you'd copy the draft into your repo yourself.
Skip it when
Easily reversed decisions and anything the code already makes obvious. Anthropic's test for instruction files applies here too: if Claude could find it by reading the code and would actually look, leave it out. Keep ADRs for the few choices that shape the system.
Why it works
Anthropic's memory docs say each Claude Code session begins with a fresh context window, and its best practices name a decision your team made in a meeting as something Claude can't find in the code. An ADR puts that decision in the repo, and both your teammates and Claude can read it. The common format comes from Michael Nygard's 2011 post: a title, context, decision, status and consequences, numbered in order, with numbers never reused, and short enough to digest quickly. Asking now is cheaper, because Claude already has the arguments in context. Later, it has to reconstruct them, and it may rationalize the choice instead.
Example
After choosing an outbox table over a hosted queue, the ADR's Decision reads We will write events to an outbox table in the same transaction as the change, and a worker will deliver them. Its Consequences include Ordering isn't guaranteed across aggregates. Your CLAUDE.md gets one line: Events go through the outbox. Why: docs/adr/0007-event-outbox.md.
Going further
Scope the pointer. A CLAUDE.md line loads in every session, while a file at .claude/rules/events.md with paths: ["src/events/**"] loads only when Claude works on matching files. That matters because the memory docs target under 200 lines per CLAUDE.md. Avoid importing the ADR with @docs/adr/0007.md, since the docs say imports help you organize but don't reduce context cost. And an ADR is still only context. If the rule has no exceptions, such as never publishing directly from a request handler, add a hook that enforces it.
Common mistakes
- Editing an old ADR when the decision changes. Nygard's format keeps the original and marks it superseded, because what the decision once was still matters.
- Listing only benefits in Consequences. His format includes negative and neutral outcomes, and those stop the next person from being surprised.
- Leaving out rejected alternatives. His headings have no slot for them, so ask for them in Context. They save the team from reopening settled questions.
- Assuming every subagent sees your pointer. Anthropic's docs say the built-in
ExploreandPlansubagents skipCLAUDE.mdfiles.
Sources
- Documenting Architecture Decisions, Michael Nygard, Cognitect
- How Claude remembers your project, Claude Code Docs
- Best practices for Claude Code
- Subagents, Claude Code Docs
Checked 6 November 2026. Products change often, so confirm details with the vendor.