ddadmin
f24b342123
- Зачем:
- внешнее ревью выявило риск двойной записи решений (spec/ADR) и
терминологическую путаницу; правки документные, поведение не меняют.
- Что:
- adr.md и spec.md: добавлен lifetime-критерий ADR vs spec (ADR — для
решений, переживающих спеку; локальные остаются в спеке).
- spec.md: разведены Options considered (до выбора) и Decisions (после).
- SKILL.md: блок <validation> переименован в <self_review>, чтобы не
путать с секцией ## Validation в spec.md.
- README.md: честнее описано авто-срабатывание на Codex.
- SKILL.md: у SEAM зафиксирован TODO(F1) про строку дивергенции
(отложена ради чистого baseline на обкатке).
- Проверка:
- python3 yaml-парс frontmatter; нет висячих ссылок на <validation>.
2.0 KiB
ADR — Architectural Decision Record
ADRs live in docs/adr/ with sequential numbering: 0001-slug.md,
0002-slug.md, etc. Create docs/adr/ lazily — only when the first ADR is
needed. To number a new one, scan docs/adr/ for the highest number and add one.
When to offer an ADR
Offer one only when all three are true:
- Hard to reverse — the cost of changing your mind later is meaningful.
- Surprising without context — a future reader will look at the code and wonder "why on earth did they do it this way?"
- The result of a real trade-off — there were genuine alternatives and one was picked for specific reasons.
If any of the three is missing, skip it. Easy to reverse → you'll just reverse it. Not surprising → nobody will wonder. No real alternative → nothing to record beyond "we did the obvious thing". Do not create an ADR for every small choice.
Lifetime test (ADR vs spec). A spec is transient — it describes what's being built now and goes stale once the work is done. An ADR is durable — it outlives the spec. So record a decision in an ADR only when it stays relevant after the spec that introduced it is obsolete. Decisions local to the current work belong in the spec's "Decisions and rejected alternatives" section, not here.
Template
# {Short title of the decision}
{1-3 sentences: what's the context, what we decided, and why.}
That's it. An ADR can be a single paragraph. The value is recording that a decision was made and why — not in filling out sections.
Optional sections
Add these only when they earn their place (most ADRs won't need them):
- Status frontmatter (
proposed | accepted | deprecated | superseded by ADR-NNNN) — useful when decisions get revisited. - Considered options — only when the rejected alternatives are worth remembering (otherwise someone re-proposes them in six months).
- Consequences — only when non-obvious downstream effects need calling out.