documentation-and-adrs

Documentation and ADRs

Code shows what was built. Documentation is the only place that explains why it was built this way and what alternatives were rejected — that context is what future humans and agents actually need and can't recover from the code alone.

When to Use

• Making a significant architectural decision
• Choosing between competing approaches
• Adding or changing a public API
• Shipping a feature that changes user-facing behavior
• Onboarding a new engineer or agent to the project
• Finding yourself explaining the same rationale repeatedly

Skip it for: obvious code, comments that restate what the code already says, and throwaway prototypes.

Architecture Decision Records (ADRs)

ADRs capture the reasoning behind a significant technical decision — the highest-value documentation available for its cost to write.

When to Write One

Choosing a framework, library, or major dependency; designing a data model or schema; selecting an auth strategy; deciding between API architectures; choosing infrastructure or hosting; any decision that would be expensive to reverse.

Template

Store ADRs under docs/adr/ (or docs/decisions/ — either is a common convention; use whichever this repo already has, and pick one consistently if neither exists yet), numbered sequentially:

# ADR-001: Use PostgreSQL for primary database

## Status
Accepted | Superseded by ADR-XXX | Deprecated

## Date
2025-01-15

## Context
[Requirements and constraints that made a decision necessary]

## Decision
[What was decided, stated plainly]

## Alternatives Considered

### Option A
- Pros: ...
- Cons: ...
- Rejected: [specific reason]

## Consequences
[What this decision commits the team to, including new risks or new capabilities]

Lifecycle

PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED). Never delete an old ADR — it's the historical record of why the previous decision was made, and a new decision should be written as a new ADR that explicitly references and supersedes it, not an edit to the old one.