documentation-and-adrs

Record architecture decisions by writing ADRs in docs/decisions with sequential numbering, documenting context, alternatives, and consequences. This gives future agents the context needed to operate effectively without re-litigating changes.

An ADR is an architecture decision record that captures the why and trade-offs behind technical changes. You need to write one when making major framework selections, data model designs, security strategy decisions, or lifecycle changes to shipped public APIs.

Manage the ADR lifecycle by moving records through a PROPOSED to ACCEPTED status, eventually marking them superseded or deprecated. This sequential lifecycle ensures decision rationale remains transparent and prevents outdated context from misleading future agents.

Writing architecture documentation establishes engineering governance by forcing teams to record constraints and alternatives. This prevents re-litigation of settled decisions by ensuring the rationale behind framework and schema changes is permanently accessible.

Document inline gotchas by focusing on the why and non-obvious intent rather than restating what the code does. This approach provides engineering governance by capturing decision rationale directly alongside the affected public API or schema logic.

Teams re-litigate architectural decisions when the constraints, alternatives, and consequences behind major framework or data model changes are not recorded. Writing ADRs with full context ensures future engineers and agents build on existing rationale instead of guessing.