documentation-and-adrs

Create a numbered Markdown file in docs/decisions/ with sections for Status, Date, Context, Decision, Alternatives Considered, and Consequences. Record why each alternative was rejected so the reasoning survives even if the decision is later superseded.

Write an ADR when choosing frameworks or major dependencies, designing data models, selecting authentication strategies, deciding API architecture, or making any decision that would be expensive to reverse. Trivial or easily reversible choices do not need one.

Good comments explain why code exists, such as non-obvious constraints or design rationale, while bad comments restate what the code already says. Avoid TODO comments for work you should do now and delete commented-out code instead of leaving it.

No, old ADRs should be kept because they capture historical context. 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 table of available commands, an architecture overview linking to ADRs, and contributing guidelines covering coding standards and the PR process.