documentation-and-adrs

An ADR documents a significant technical decision with sections for status, date, context, decision, alternatives considered, and consequences. Store it in docs/decisions/ with sequential numbering, or match your project's existing ADR convention if one exists.

Write an ADR when choosing frameworks or major dependencies, designing data models, selecting authentication strategies, deciding API architecture, or making any decision expensive to reverse. Skip ADRs for trivial or easily reversible choices.

Good comments explain why code exists, such as non-obvious constraints or design rationale. Bad comments restate what the code already says, leave stale TODOs, or preserve commented-out code that version control already tracks.

No, old ADRs should never be deleted because they capture historical context. When a decision changes, write a new ADR that references and supersedes the previous one, following the lifecycle from proposed to accepted to superseded.

Skip documentation for self-explanatory code, throwaway prototypes, and comments that merely restate what the code does. Documentation should capture intent, trade-offs, and constraints that the code itself cannot express.