Skip to content
Klay

Record the decision, not the mechanism

When you make a decision that was not obvious, write down why — the code already says what.

EngineersSystem designersVibe codersci-generic

Anyone can read the code and see what it does. What no reader can recover is the option you rejected and the reason, and that is exactly what the next person needs before they 'simplify' your work back into the bug it was avoiding. A short record attached to the decision is the highest-return writing in software, and almost nobody does it.

What goes wrong: A load-bearing workaround gets refactored away by someone who could not see what it was for, and the original bug returns months later wearing a new hat.

What agents change: An agent reads your repository as its entire briefing and will confidently undo anything whose reason is not written down where it can see it.

You are violating it when

  • A comment explains what the line does rather than why it exists.
  • Nobody can say why a surprising piece of code is that way.
  • There is no record of decisions anywhere in the repo.

The usual objection: That comments go stale so writing them is pointless. Mechanism comments go stale because the mechanism changes; a reason stays true even when the code around it is rewritten.

The useful artifact is a small trace of judgment: what was uncertain, what alternative was considered, and why this path won. It can live in an ADR, a design-system record, a change description, or a nearby comment, but its value is the same: it preserves the context that is not visible in the final implementation.

This works because code is only the surviving mechanism. It shows the branch that was taken, not the branch that was deliberately avoided. Without that missing branch, a later maintainer can mistake a constraint for clutter, remove a workaround, or reopen a settled debate. A short rationale turns the repository into a usable interface for future change.

The misconception is that comments go stale, so writing them is wasted effort. Mechanism comments often do go stale because they describe moving parts. Rationale is different: the reason a trade-off was made can remain true even after the implementation changes, and if it becomes false, that is exactly the moment worth recording.

When an agent is editing the code, the repository becomes its briefing packet. If the reason is absent, the agent will infer intent from structure alone and may confidently replace a load-bearing oddity with the obvious-looking version that caused trouble before.

Install it

npx klay practices add write-down-why
  • docs/decisions/0001-record-decisions.mdcreate
    # 1. Record architecture decisions

Date: REPLACE-ME
Status: accepted

## Context

Anyone can read the code and see what it does. What no reader can recover is
the option that was rejected and the reason it was rejected.

Without that record, the next person to touch a surprising piece of code has
two choices: leave it alone because it looks load-bearing, or "simplify" it back
into the bug it was avoiding. Both are expensive. The second is expensive
months later, which is worse.
  • AGENTS.mdappend-block
    ## Write down why

- Comment the reason, not the mechanism. The code already says what it does.
- When you work around a bug, a platform limit or a surprising behaviour, record it where the reader will be standing when they wonder.
- Before deleting or "simplifying" something surprising, look for the reason first. If there isn't one recorded, ask rather than assume there was none.
- Decisions that span more than one file go in `docs/decisions/`.

The previews are the first lines of each file; the command writes them in full. Existing files are never overwritten.

How you know it stuck

npx klay practices audit reports this check for this practice:

  • decision-records-present

Where this comes from

  1. Writing good CL descriptionsGoogle Engineering Practices · Official docsPlaces rationale in the change history, the lowest-friction record attached to real code.
  2. Architecture Decision RecordMartin Fowler · Named authorityDefines decision records around future readers, trade-offs, and why the system took this shape.
  3. Context AnchoringMartin Fowler · Named authorityConnects repository context to AI assistance, where missing rationale becomes missing briefing.
  4. Design system decision records | Technology Radar | ThoughtworksThoughtworks Technology Radar · Engineering blogShows the same habit working beyond architecture, reducing onboarding friction and repeated debate.
  5. Democratising Software Architecture • Eoin Woods • GOTO 2023GOTO Conferences · Engineering blogAdds the organizational angle: broad decision authority needs written reasoning to remain coherent.

Questions

Is this a full ADR process?
It can be a paragraph in a file. The ceremony is optional; the record is not.
Where does it go?
Next to what it explains. A file header for a file-level decision, docs/decisions for one that spans several.