← All build notes Process

The decision log we keep on every project

Scope, decisions and trade-offs are written down beside the working product, so anyone can see why it works the way it does.

ArcLayer teamBuild notesNov 2, 20262 min read

A decision log is a written record of decisions, owners and trade-offs, kept beside the working product. We keep one on every project. When an agent writes most of the code, the code no longer explains the thinking behind it. The log does.

What goes in an entry

An entry is short. It names the decision, the person who owns it, the options that were considered and the trade-off that was accepted. Here is an illustrative entry for a receipt app:

md

## Decision 014 · Scan opens the camera first
Owner: design lead
Decision: the app opens on the camera. Past receipts are one tap away.
Options: receipt list first; camera first; ask on first launch.
Trade-off: returning users tap once more to find an old receipt.
Status: accepted

When to write one

Scope changes, when something is added, cut or postponed.
A new token or component enters the design system.
A trade-off a user will notice, such as speed against accuracy.
Anything a reviewer questioned during review.

Keep it next to the code

Keep the log in the repository as plain Markdown. It is then versioned with the product, and an agent can read it before it starts a task. An agent that can see a decision and its reason is less likely to undo it in the next change.

What it gives the product owner

A founder who takes over a product, or brings in a new team, gets the reasoning along with the code. They can see who decided what, which options were on the table and what was given up.