ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadmin 18a55dd640 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} согласованы, перекрёстные ссылки рабочие.

2026-06-06 16:12:10 +03:00

3.8 KiB

Raw Blame History

ADR-0002: Спеки как durable design-доки в `docs/specs/`

Принято: 2026-06-06 Статус: accepted; заменяет маршрут спек из ADR-0001 (остальные решения 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.

3.8 KiB Raw Blame History Unescape Escape

ADR-0002: Спеки как durable design-доки в docs/specs/