$27

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

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

## 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]