Architecture Decision Record Generator

Analyze a codebase or conversation to produce Architecture Decision Records (ADRs) — structured documents that capture the WHY behind technical choices so future developers understand the reasoning.

Use when: "document this decision", "create an ADR", "why did we choose X", "record our architecture decision", or when a significant technical choice is being made.

What is an ADR?

A short document capturing one significant architectural decision: the context, the decision itself, the alternatives considered, and the consequences. ADRs form a decision log that prevents the same debates from recurring and helps new team members understand the codebase.

When to Create an ADR

• Choosing a framework, database, or major library
• Defining API contracts or data schemas
• Setting team conventions (testing strategy, branching model, deployment process)
• Making a trade-off (performance vs maintainability, monolith vs microservices)
• Adopting or dropping a tool
• Any decision someone might later ask "why did we do it this way?"

Analysis Steps

1. Identify the Decision

From conversation or code review, extract:

• What was decided
• When (date or PR/commit reference)
• Who was involved (if known)

2. Reconstruct Context

# Check git history for related changes
git log --oneline --all --grep="\x3Ckeyword>" | head -20

# Find when a dependency was added
git log --all --diff-filter=A -- package.json | head -5
git log -p --all -S '\x3Cpackage-name>' -- package.json | head -40

# Look for prior discussion in docs
grep -ri "decision\|chose\|alternative\|trade-off\|migrate" docs/ README.md CONTRIBUTING.md 2>/dev/null

# Check for existing ADRs
find . -type f -name "*.md" -path "*/adr/*" -o -name "*decision*" 2>/dev/null
ls docs/adr/ docs/decisions/ doc/architecture/ 2>/dev/null

3. Analyze Alternatives

For framework/library decisions:

# What else was evaluated? Check for traces
grep -ri "considered\|vs\|compared\|evaluated\|alternative" docs/ 2>/dev/null
git log --all --oneline | grep -i "try\|experiment\|spike\|poc\|prototype" | head -10

# Check if multiple solutions were tried
git log --all --oneline --diff-filter=D -- '**/package.json' | head -10

4. Assess Consequences

Read the current implementation to understand what the decision enabled or constrained:

# How deeply is the choice embedded?
grep -rc "\x3Cframework-import>" --include="*.{ts,js,py,go}" . 2>/dev/null | sort -t: -k2 -rn | head -10

# Are there workarounds that suggest regret?
grep -ri "hack\|workaround\|todo\|fixme\|technical debt" --include="*.{ts,js,py,go}" . 2>/dev/null | head -20

ADR Template

Use the Michael Nygard format (industry standard):

# ADR-{NNN}: {Title — short, noun-phrase}

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Deciders:** [names or roles]

## Context

What is the issue that we're seeing that is motivating this decision or change?
Describe the forces at play: technical constraints, business requirements, team capabilities, timeline pressure.

## Decision

State the decision clearly in full sentences.
"We will use PostgreSQL as our primary database."
"We will adopt a monorepo structure using Turborepo."

## Alternatives Considered

### Alternative A: [name]
- **Pros:** ...
- **Cons:** ...
- **Why not:** ...

### Alternative B: [name]
- **Pros:** ...
- **Cons:** ...
- **Why not:** ...

## Consequences

### Positive
- What becomes easier or possible because of this decision

### Negative
- What becomes harder, more expensive, or is now ruled out
- What technical debt does this introduce

### Risks
- What could go wrong
- Under what conditions would we reconsider this decision

## References

- Links to relevant PRs, issues, benchmarks, or external resources

File Organization

Standard locations (create if none exist):

docs/adr/
  0001-use-postgresql.md
  0002-adopt-monorepo.md
  0003-api-versioning-strategy.md
  README.md          # index of all ADRs with one-line summaries

Index format for README.md:

# Architecture Decision Records

| # | Decision | Status | Date |
|---|----------|--------|------|
| 1 | [Use PostgreSQL](0001-use-postgresql.md) | Accepted | 2026-01-15 |
| 2 | [Adopt monorepo](0002-adopt-monorepo.md) | Accepted | 2026-02-01 |

Tips

• Keep ADRs short — 1-2 pages max. If it's longer, the decision is too big (split it).
• Write ADRs at decision time, not after. Retrospective ADRs lose the "alternatives considered" context.
• ADRs are immutable once accepted. If a decision changes, create a new ADR that supersedes the old one.
• Number them sequentially. Never reuse numbers.
• Store them in the repo, next to the code they govern.
• Review ADRs in PRs — they deserve the same scrutiny as code.