documentation-and-adrs

An ADR documents the status, date, context, decision, alternatives considered, and consequences of a significant technical choice. Store it in docs/decisions/ with sequential numbering, or match your project's existing ADR convention for location and format.

Write an ADR when choosing frameworks, databases, authentication strategies, API architectures, or any decision expensive to reverse. Skip ADRs for trivial or easily reversible choices.

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.

Comment the why, not the what: explain non-obvious intent, constraints, and known gotchas rather than restating what the code does. Avoid TODO comments for work you should do now and delete commented-out code instead of leaving it.

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 engineers and agents enough context to run and understand the project.