ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadmin aecbf392d9 docs(agents): подключена doc/issue-методология Pocock и зафиксирована раскладка

- Зачем:
  - развести документацию по времени жизни: транзиентные спеки отдельно от
    долговечных решений (ADR) и доменного словаря (CONTEXT.md), вместо одного
    громоздкого spec-документа.
- Что:
  - добавлен блок Agent skills в AGENTS.md (issue tracker / triage / domain docs).
  - созданы docs/agents/{issue-tracker,triage-labels,domain}.md: локальный
    markdown-трекер в .scratch/, дефолтные triage-метки, single-context раскладка.
  - зафиксировано решение как docs/adr/0001-spec-adr-issue-layout.md.
- Проверка:
  - git show --stat HEAD; прочитать AGENTS.md и docs/adr/0001-spec-adr-issue-layout.md.

2026-06-01 23:29:50 +03:00

2.7 KiB

Raw Blame History

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

Принято: 2026-06-01

Решение

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

Транзиентные спеки фич — 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 окажутся самодостаточными, спеки можно будет гитигнорить — переключение одной строкой, без слома схемы.

2.7 KiB Raw Blame History