---
name: architecture-decision-log
description: "Capture an architectural decision the moment it's made, not after it's been forgotten: what was decided, the alternatives that lost, and why. Use whenever a project chooses between real alternatives (framework, data store, auth strategy, API shape) and the reasoning is worth keeping. Feeds the handbook's own Decisions page format instead of a separate, easily-ignored docs folder."
---

# Architecture Decision Log

Write down the decision, what it beat, and why, in the same place the handbook already keeps its own hard calls, so the reasoning survives past the conversation that produced it.

## Phases

Work through these in order.

### 1. Detect

Notice the decision moment: a stated conclusion after comparing alternatives, not a trivial or purely stylistic choice.

Read: [decisions](https://selwynuy.dev/d/decisions.md)

### 2. Record

Write the decision, the alternatives considered with why each lost, and the consequences (including the real trade-offs, not just the upside), in the handbook's Decisions format.

Read: [decisions](https://selwynuy.dev/d/decisions.md), [nextjs-fit-check](https://selwynuy.dev/d/nextjs-fit-check.md)

### 3. Tag

Mark how firm the call is (non-negotiable, strong default, or opinion still under review) so a future reader knows how hard to hold the line.

Read: [decisions](https://selwynuy.dev/d/decisions.md)

## Bundled files

- `references/decision-entry-schema.md` (reference): The fields a decision entry needs: the call, what it beat and why, consequences, and its firmness tag.

---

Part of Architecture Decision Log from Selwyn Uy's Next.js Handbook. Full page: https://selwynuy.dev/skills/architecture-decision-log