docs(adr): спеки в docs/specs, handoff'ы в .scratch/handoffs

- Зачем:
  - воркфлоу эволюционировал: design-спекам нужен durable-дом, а handoff'ам —
    стабильное место вместо эфемерного /tmp.
- Что:
  - ADR-0002: design-спеки переезжают в docs/specs/YYYY-MM-DD-*.md (superseding ADR-0001).
  - ADR-0003: handoff'ы — одноразовые леса́ в .scratch/handoffs/, коммитятся, уборка best-effort.
  - ADR-0001 помечен как частично заменённый; AGENTS.md описывает место handoff'ов.
- Проверка:
  - docs/adr/000{1,2,3} согласованы, перекрёстные ссылки рабочие.
This commit is contained in:
2026-06-06 16:12:10 +03:00
parent 0dd88183b7
commit 18a55dd640
4 changed files with 85 additions and 0 deletions
@@ -0,0 +1,48 @@
# ADR-0002: Спеки как durable design-доки в `docs/specs/`
Принято: 2026-06-06
Статус: accepted; заменяет маршрут спек из [ADR-0001](./0001-spec-adr-issue-layout.md)
(остальные решения ADR-0001 — ADR, `CONTEXT.md`, issue-tracker — в силе).
## Решение
Design-спеки (инженерная аргументация «что строим и почему», без реализации)
живут в `docs/specs/YYYY-MM-DD-<slug>.md` — датированные, с статус-заголовком
(`Draft | Accepted | Implemented | Superseded`). `.scratch/` остаётся для
по-настоящему эфемерного (todo, черновые заметки), а не для курируемых спек.
ADR — для кратких durable-решений; `CONTEXT.md` — словарь.
## Контекст
ADR-0001 (2026-06-01) маршрутизировал все спеки в `.scratch/` как транзиентные
снимки «не для перечитывания» — таким был грилл-поток Мэтта Покока, который тогда
осваивался. С тех пор воркфлоу эволюционировал: появился гибридный скилл
`brainstorm-with-docs` (Покок + obra/superpowers), и выделился **второй жанр**
спека как durable-аргументация архитектуры, которую перечитывают. ADR-0001 этот
жанр не предусматривал. Репозиторий учебный (и для студентов, и для собственного
исследовательского трека владельца), поэтому design-доки сами по себе —
учебный материал, а следы принятия решений ценны: отсюда отдельный
superseding-ADR, а не правка ADR-0001 на месте.
## Рассмотренные варианты
- **Оставить `.scratch/` для всех спек (status quo ADR-0001).** Отклонено:
durable-аргументацию перечитывают, а каталог «не для перечитывания» её прячет —
ровно та боль, что привела к пересмотру.
- **`docs/specs/` для durable-спек (принято).** Реверс отклонения из ADR-0001.
Тогда спека считалась только транзиентной, и `docs/specs/` отклонили как
«засорение курируемых доков». Страх clutter снимается датой в имени (снимок на
момент) + статус-заголовком + правилом «кристаллизовавшееся решение выносим
короткой ADR».
- **Два уровня (`.scratch/` транзиентные + `docs/specs/` durable, по каждой
спеке).** Отклонено: требует суждения «durable?» на каждую спеку и двух домов;
для репо такого размера overhead не окупается, граница плывёт.
## Последствия
- `docs/specs/` создаётся лениво; первая спека — редизайн Superset-дашборда.
- Дисциплина: статус-заголовок в каждой спеке; краткое решение дублируется
короткой ADR, если переживёт спеку.
- ADR-0001 получает forward-pointer на этот ADR (история не стирается).
- `to-prd`/`.scratch/PRD.md` остаётся для продуктовых требований; инженерные
design-решения идут спекой, не PRD.