Architecture Decision Records

Workflow

Capturing a New ADR

When a decision moment is detected:

1. Initialize (first time only) — if docs/adr/ does not exist, ask the user for confirmation before creating the directory, a README.md seeded with the index table header (see ADR Index Format below), and a blank template.md for manual use. Do not create files without explicit consent.
2. Identify the decision — extract the core architectural choice being made
3. Gather context — what problem prompted this? What constraints exist?
4. Document alternatives — what other options were considered? Why were they rejected?
5. State consequences — what are the trade-offs? What becomes easier/harder?
6. Assign a number — scan existing ADRs in docs/adr/ and increment
7. Confirm and write — present the draft ADR to the user for review. Only write to docs/adr/NNNN-decision-title.md after explicit approval. If the user declines, discard the draft without writing any files.
8. Update the index — append to docs/adr/README.md

Reading Existing ADRs

When a user asks "why did we choose X?":

1. Check if docs/adr/ exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?"
2. If it exists, scan docs/adr/README.md index for relevant entries
3. Read matching ADR files and present the Context and Decision sections
4. If no match is found, respond: "No ADR found for that decision. Would you like to record one now?"

ADR Directory Structure

docs/
└── adr/
    ├── README.md              ← index of all ADRs
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← blank template for manual use

ADR Index Format

# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |

Decision Detection Signals

Watch for these patterns in conversation that indicate an architectural decision:

Explicit signals

• "Let's go with X"
• "We should use X instead of Y"
• "The trade-off is worth it because..."
• "Record this as an ADR"

Implicit signals (suggest recording an ADR — do not auto-create without user confirmation)

• Comparing two frameworks or libraries and reaching a conclusion
• Making a database schema design choice with stated rationale
• Choosing between architectural patterns (monolith vs microservices, REST vs GraphQL)
• Deciding on authentication/authorization strategy
• Selecting deployment infrastructure after evaluating alternatives

What Makes a Good ADR

Do

• Be specific — "Use Prisma ORM" not "use an ORM"
• Record the why — the rationale matters more than the what
• Include rejected alternatives — future developers need to know what was considered
• State consequences honestly — every decision has trade-offs
• Keep it short — an ADR should be readable in 2 minutes
• Use present tense — "We use X" not "We will use X"

Don't

• Record trivial decisions — variable naming or formatting choices don't need ADRs
• Write essays — if the context section exceeds 10 lines, it's too long
• Omit alternatives — "we just picked it" is not a valid rationale
• Backfill without marking it — if recording a past decision, note the original date
• Let ADRs go stale — superseded decisions should reference their replacement

ADR Lifecycle

proposed → accepted → [deprecated | superseded by ADR-NNNN]

• proposed: decision is under discussion, not yet committed
• accepted: decision is in effect and being followed
• deprecated: decision is no longer relevant (e.g., feature removed)
• superseded: a newer ADR replaces this one (always link the replacement)

Categories of Decisions Worth Recording

Integration with Other Skills

• Planner agent: when the planner proposes architecture changes, suggest creating an ADR
• Code reviewer agent: flag PRs that introduce architectural changes without a corresponding ADR