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.0 KiB

Raw Blame History

ADR-0001: Раскладка спецификаций, решений и задач

Принято: 2026-06-01 Статус: частично заменён ADR-0002 — маршрут design-спек переехал из .scratch/ в docs/specs/. Остальные решения (ADR, CONTEXT.md, issue-tracker) в силе.

Решение

Рабочую документацию разносим по времени жизни:

Транзиентные спеки фич — markdown в .scratch/<feature>/PRD.md, коммитятся (.scratch/ не в .gitignore). Снимок понимания на момент работы, не для перечитывания. Продюсер — to-prd.
Долговечные решения — ADR в docs/adr/NNNN-<slug>.md. Глубина по весу решения: однострочник для обратимого, с вариантами и последствиями — для необратимого.
Доменный язык — глоссарий CONTEXT.md в корне. ADR и CONTEXT.md ведёт grill-with-docs.
Issue-tracker — локальный markdown в .scratch/, без GitHub Issues. Триаж пробуем с дефолтными метками; to-issues пока не применяем — для текущего объёма работ задачи редко распадаются на независимые вертикальные срезы.

Контекст

Раньше и спеку, и решение нёс один громоздкий spec-документ: он плохо заменял ADR — слишком объёмен и привязан к фиче. Разделение слоёв: спека — «что строим сейчас», ADR — «какое решение приняли и почему», глоссарий — «как называем сущности».

Рассмотренные варианты

docs/specs/ закоммичено — спеки среди курируемых доков. Отклонено: транзиентные артефакты засоряют docs/, который навигирует читатель.
.scratch/ в .gitignore — спеки эфемерны. Отклонено: по необратимым решениям рассуждение за ними надо сохранить, а минимальный ADR его не держит.
GitHub Issues как трекер — отклонено пока: поток держим локально, файлами.

Последствия

.scratch/ не вносим в .gitignore — иначе теряется история спек и задач.
Если ADR окажутся самодостаточными, спеки можно будет гитигнорить — переключение одной строкой, без слома схемы.

3.0 KiB Raw Blame History