documentation-and-adrs

An ADR documents the context, decision, alternatives considered, and consequences of a significant technical choice. Store it in docs/decisions/ with sequential numbering, and match any existing project convention for location, format, and headings before applying defaults.

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. Trivial or easily reversible choices do not need one.

Comments should explain the why, not the what: non-obvious intent, constraints, and known gotchas. Avoid restating self-explanatory code, leaving stale TODOs, or keeping commented-out code that version control already preserves.

No, old ADRs capture historical context and should be kept. 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 engineers and agents enough context to run and understand the project.