documentation-and-adrs

An ADR documents a significant technical decision with sections for status, date, context, decision, alternatives considered, and consequences. Store ADRs 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, such as non-obvious constraints or design rationale. Avoid comments that restate what the code does, leftover TODOs for work you should do now, and commented-out code that version control already preserves.

No, old ADRs should be kept 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 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. This gives new developers and agents everything needed to run and understand the project.