Architecture Decision Records

When to Activate

• User explicitly says "let's record this decision" or "ADR this"
• User chooses between significant alternatives (framework, library, pattern, database, API design)
• User says "we decided to..." or "the reason we're doing X instead of Y is..."
• User asks "why did we choose X?" (read existing ADRs)
• During planning phases when architectural trade-offs are discussed

ADR Format

# ADR-NNNN: [Decision Title]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]

## Context

What is the issue that we're seeing that is motivating this decision or change?

[2-5 sentences describing the situation, constraints, and forces at play]

## Decision

What is the change that we're proposing and/or doing?

[1-3 sentences stating the decision clearly]

## Alternatives Considered

### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]

### Alternative 2: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]

## Consequences

What becomes easier or more difficult to do because of this change?

### Positive
- [benefit 1]
- [benefit 2]

### Negative
- [trade-off 1]
- [trade-off 2]

### Risks
- [risk and mitigation]

Workflow

Capturing a New ADR

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

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

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

• 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