ddadmin
aecbf392d9
- Зачем:
- развести документацию по времени жизни: транзиентные спеки отдельно от
долговечных решений (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.
41 lines
2.7 KiB
Markdown
41 lines
2.7 KiB
Markdown
# 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 окажутся самодостаточными, спеки можно будет гитигнорить — переключение
|
|
одной строкой, без слома схемы.
|