What we write down when we decide something

Most of the expensive work on a small team is not the deciding. It is the third time the same question comes back, with the original reasoning gone and only the outcome left behind, so the outcome looks arbitrary and gets overturned.

The note is three sentences

What we chose. What we chose it over. What would make us change our minds.

The third sentence is the one people skip, and it is the one that makes the note useful later. "We picked this because it was faster" ages badly. "We picked this because the alternative needed a server, and we would revisit it if we ever ran one" tells the next reader exactly when the decision has expired.

Where they live

Next to the code they describe. A decision about how content loads belongs in a comment at the top of the loader, not in a document nobody opens. If the note is more than a paragraph it goes in docs/, and the code points at it.

The test is whether someone who arrives in six months can find the reasoning without asking anyone. If the only route to it is a person, it is not written down; it is remembered, and remembering does not scale past the person.

What we do not write down

Anything the code already says. A comment restating a function signature is a second copy of the truth that will drift from the first. We write down the part that is not in the code: the option we rejected, and why.

That distinction is doing real work. It keeps the notes short enough that people read them.