ddadmin
18a55dd640
- Зачем:
- воркфлоу эволюционировал: 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} согласованы, перекрёстные ссылки рабочие.
49 lines
3.8 KiB
Markdown
49 lines
3.8 KiB
Markdown
# 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.
|