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.

Comments should explain why code behaves a certain way, not restate what it does. Document non-obvious intent, known gotchas, and constraints, and avoid TODO comments, commented-out code, and comments on self-explanatory functions.

No, old ADRs capture historical context and should be kept. When a decision changes, write a new ADR that references and supersedes the old one, following the lifecycle from proposed to accepted to superseded or deprecated.

A README should include a one-paragraph project description, quick start steps, a commands table, an architecture overview linking to ADRs, and contributing guidelines. It must explain how to run the project.