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>.
47 lines
2.0 KiB
Markdown
47 lines
2.0 KiB
Markdown
# 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:
|
|
|
|
1. **Hard to reverse** — the cost of changing your mind later is meaningful.
|
|
2. **Surprising without context** — a future reader will look at the code and
|
|
wonder "why on earth did they do it this way?"
|
|
3. **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
|
|
|
|
```markdown
|
|
# {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.
|