architecture-decisions

# Architecture Decisions ## Purpose Record why a decision was made, not just what was decided. Code shows the what. The context, the alternatives, and the constraints that made the choice correct at the time are otherwise lost within months. ## When to Use - Choosing a database, framework, protocol, or vendor. - Adopting or abandoning an architectural pattern. - Making a decision that will be expensive to reverse. - Revisiting a decision someone made and nobody can explain. ## Capabilities - ADR authoring in a consistent, greppable format. - Options analysis with honest trade-offs. - Superseding and amending existing decisions without rewriting history. ## Inputs - The decision to be made and the forces acting on it. - The realistic options, including "do nothing". - Constraints: team, time, budget, compliance, existing systems. ## Outputs A numbered ADR in `docs/adr/NNNN-short-title.md` with: - Status: proposed, accepted, superseded by NNNN. - Context: the situation and the forces, written so a new hire understands them. - Decision: what was chosen, in the active voice. - Consequences: what becomes easier, what becomes harder, what is now hard to reverse. ## Workflow 1. **State the forces** — What is pushing on this decision? Latency, cost, team familiarity, compliance, an existing commitment. If there are no forces, there is no decision to record. 2. **List real options** — Including the status quo. An ADR with one option is a justification, not a decision. 3. ...