documentation-and-adrs

To write an Architecture Decision Record, create a document in docs/decisions/ containing concise sections for context, decision, alternatives, and consequences. This preserves the trade-offs behind technical choices for future engineers and automated agents.

The Architecture Decision Record lifecycle tracks transitions from PROPOSED to ACCEPTED, and finally to SUPERSEDED or DEPRECATED. This status progression manages decision states within a code repository.

Document API changes by recording why interfaces changed, the trade-offs considered, and compatibility consequences for consumers. This public-interface rationale prevents repeated debates and maintains stable interfaces for downstream users.

Create onboarding documentation by writing concise explanations and known gotchas to accelerate new contributors. These notes function as agent-facing rules in a code repository to guide automated agents with project context.

Use an ADR template for architectural decisions involving multiple alternatives and broad consequences, while inline documentation explains specific implementation intent. Both maintain human-readable histories but ADRs capture high-level design rationale.

You need a docs/decisions/ directory to store Architecture Decision Records. This structured location ensures future engineers and automated agents can reliably discover and review the context behind technical choices.