# 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.