0001 · Record architecture decisions

Status: Accepted · 2026-09-22

Context

CoDNA is open source. People who did not attend the conversation will read the schema and ask why it is shaped this way — and a decision whose reasoning is lost gets re-litigated, or worse, reversed by someone who assumed there was no reason.

Decision

Every decision that would be expensive to reverse gets a numbered record here: context, decision, consequences, and the alternatives that were rejected with why.

Records are immutable once accepted. A reversal is a new record that supersedes the old one, which is marked accordingly. Editing history to look consistent destroys the only thing that makes these worth keeping.

Consequences

• A pull request that contradicts an ADR has to say so.
• The rejected-alternatives section is the most valuable part and the most often skipped, so it is mandatory.

Alternatives rejected

Comments in the code. They explain how, not why, and they disappear in the refactor that the reasoning was supposed to constrain.

A wiki page per topic. Gets edited until it describes only the present, losing the sequence that explains it.