Why We Cap How Many Projects Run in Parallel

Code documentation tells a future reader what a function does. It almost never tells them why it does it that way instead of some other way - and that missing context is exactly what causes the most expensive mistakes later, when someone changes something that looked safe to change and wasn't.

The Specific Gap We Kept Running Into

We noticed a recurring pattern across projects: a developer would look at an existing piece of logic, conclude it looked unnecessarily complicated or outdated, simplify it, and inadvertently reintroduce a bug that had already been fixed once - because the reasoning behind the original, more complex version existed only in someone's memory, not in writing anywhere. The code was fine. The missing context around the code was the actual problem.

What We Actually Document Now

Not everything needs a decision record - most code is genuinely self-explanatory, and documenting routine choices would just add noise nobody reads. We write a decision record specifically when a choice wasn't the obvious default: when we picked an unusual approach to work around a specific constraint, when we deliberately didn't use a more standard pattern for a reason that isn't visible in the code itself, or when a past bug shaped how something is currently built and reverting that shape would reintroduce the problem.

Each record is short - what the decision was, what alternative was considered and rejected, and why. We deliberately don't write lengthy documents nobody will read under deadline pressure; a decision record that takes ten minutes to write and two minutes to read gets used. One that takes an hour to write gets skipped.

Where These Records Actually Live

Decision records live next to the code they explain - either as a structured comment directly above the relevant logic or in a lightweight decisions log within the project repository, not in a separate wiki that drifts out of sync with the actual codebase over time. If the code moves or gets refactored, the record needs to move with it, and that's far more likely to happen when it's sitting in the same file a developer is already editing.

This Changes What Code Review Actually Catches

When a decision record exists, a reviewer proposing to "simplify" a piece of logic can immediately see it was deliberate and why, rather than only discovering that after the change ships and something breaks. This has directly prevented at least one regression we can point to specifically - a reviewer flagged that a proposed simplification would have removed a safeguard the decision record explained, and the change was revised before merging instead of after an incident.

What This Isn't

This isn't a mandate to document everything exhaustively, and it isn't a replacement for well-named functions and readable code, which still matter as much as they always did. It's specifically aimed at the category of decisions that look wrong or unnecessary out of context but were made deliberately - because that's the exact category that gets "fixed" by someone without the missing context, and the exact category where a short written explanation prevents real, avoidable rework.

Why This Matters More as a Team Grows

Undocumented reasoning is survivable when the same small group of people who made every decision are still around to explain it from memory. It becomes a real liability as a team grows, projects change hands, or enough time passes that memory fades even for the people who were there. We adopted this practice specifically because we'd already hit the point where relying on institutional memory alone was starting to cost us real time.