steid

1.8 KBRaw

1	# NNNN — Short imperative title
2
3	Status: proposed \| accepted \| superseded by [NNNN](NNNN-slug.md) · Date: YYYY-MM-DD
4
5	## Context
6
7	The situation that forces a choice. What's true right now, what pressure it creates,
8	and what breaks if nothing changes. Write enough that someone who wasn't there can
9	tell whether this still applies — including the constraints that turn out to matter
10	later (team size, scale, dependencies, deadlines).
11
12	No decision here. Just the facts.
13
14	## Decision
15
16	What was chosen, stated plainly and in the active voice. One or two sentences is
17	usually right.
18
19	## Alternatives considered
20
21	What else was on the table and why it lost. This is the part future-you actually
22	needs — a rejected option with no recorded reason gets re-litigated every six months.
23
24	- Option — why not.
25
26	## Consequences
27
28	What follows, good and bad. Be honest about the costs; a record listing only benefits
29	is marketing, not a decision.
30
31	- What this makes easy
32	- What this makes hard
33	- New dependencies, obligations, or known holes it opens
34	- How reversible it is, and what reversing would cost
35
36	---
37
38	## How to use this directory
39
40	- One file per decision, numbered sequentially: `0001-slug.md`. Numbers are never
41	reused, and files are never deleted — a decision that stops applying gets its status
42	changed to superseded, with a link to the one that replaced it. The trail of
43	wrong turns is the point.
44	- Write one when a choice would be expensive to reverse, when it constrains future
45	work, or when the reasoning wouldn't be obvious from reading the code. Skip it for
46	anything the code makes self-evident.
47	- Write it when the decision is made, not afterwards. Reconstructed rationale is
48	mostly fiction.
49	- Link to the record from wherever the choice shows up — `ROADMAP.md`,
50	`architecture.md` — rather than restating the reasoning in both places.