paulund/documentation-and-adrs

Core Workflow

1. Decide if an ADR is needed — write one when the decision is:

   • Hard to reverse (framework, database, auth strategy, API architecture)
   • Surprising — the chosen option is not the obvious first choice
   • A genuine trade-off where alternatives were seriously considered

2. Fill the ADR template — save to docs/adrs/ADR-NNN-<slug>.md:

   # ADR-NNN: <Title>
   
   ## Status
   Accepted | Superseded by ADR-XXX | Deprecated
   
   ## Date
   YYYY-MM-DD
   
   ## Context
   What situation or constraint forced this decision?
   
   ## Decision
   What we chose and why.
   
   ## Alternatives Considered
   What was rejected and why — be specific.
   
   ## Consequences
   What becomes easier, what becomes harder, what we're betting on.
   

3. Comment the why, not the what — inline comments explain non-obvious intent, constraints, or known gotchas. Never restate what the code already says.

4. README covers quick start — every project needs: one-paragraph description, quick start steps, command table (dev / test / build / lint), architecture overview, contributing guide.

5. Changelog for shipped features — follow Keep a Changelog format: Added / Fixed / Changed / Removed sections per version.

6. Agent context files stay current — keep AGENTS.md, CONTEXT.md, and spec files updated. Agents use them to avoid re-deciding what's already been decided.

Common Rationalizations

| Rationalization | Reality | |---|---| | "The code is self-documenting" | Code shows what. It doesn't show why, what alternatives were rejected, or what constraints apply. | | "ADRs are overhead" | A 10-minute ADR prevents a 2-hour debate about the same decision 6 months later. | | "Nobody reads docs" | Agents do. Future engineers do. Your 3-months-later self does. | | "We'll write docs when the API stabilises" | APIs stabilise faster when you document them. The doc is the first test of the design. | | "Comments get outdated" | Comments on why are stable. Comments on what get outdated — that's why you only write the former. |

Red Flags

• [ ] Architectural decisions with no written rationale
• [ ] Public APIs with no documentation or types
• [ ] README that doesn't explain how to run the project
• [ ] Commented-out code instead of deletion
• [ ] TODO comments left for weeks
• [ ] AGENTS.md or CONTEXT.md out of date with the current architecture

Verification

After documenting:

• [ ] ADRs exist for all significant architectural decisions made in this work
• [ ] README covers quick start, command table, and architecture overview
• [ ] API functions have parameter and return type documentation
• [ ] Known gotchas are documented inline where they matter
• [ ] No commented-out code remains
• [ ] Agent context files are current and accurate

Constraints

MUST DO

• Write ADRs for hard-to-reverse, surprising, or genuine trade-off decisions.
• Store ADRs in docs/adrs/ with sequential numbering.
• Never delete old ADRs — they capture historical context. Supersede them with a new ADR.
• Comment only the why, never the what.

MUST NOT DO

• Document obvious code.
• Add comments that restate what the code already says.
• Leave TODO comments for things that should just be done now.
• Leave commented-out code — git has history.