adr
Installation
SKILL.md
An ADR states the decision in force. It holds the rule as it stands, why it holds, what it costs, what lost, and what would reopen it. Agents write, rewrite, merge, and delete ADRs; git holds every earlier wording, and the tree holds only decisions that hold today. The main readers are agents about to change the code a decision governs, so the current rule leads and nothing replaced sits above it.
What earns an ADR
- Write an ADR for a decision that passes both tests. A viable alternative lost for a reason that can be stated, and a future agent without the ADR would plausibly undo the choice.
- A decision that fails either test gets no ADR. Where a reader still needs its reason, it becomes one rule with its reason, about 30 words, in the documentation of the item or module that owns it, or in CLAUDE.md where it is a convention for agents.
- Write the ADR once the decision is made. Options still open live in the planning document or the conversation; the ADR directory holds no proposals.
- Take every reason from evidence: the task, the user's words, a measurement, an issue. A reason the evidence does
not give is written as unknown or as
per <issue>, never inferred — a plausible reason the project never had steers every later reader.