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.
This commit is contained in:
2026-06-01 23:29:50 +03:00
parent dc0e6f9452
commit aecbf392d9
5 changed files with 135 additions and 0 deletions
+40
View File
@@ -0,0 +1,40 @@
# 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 окажутся самодостаточными, спеки можно будет гитигнорить — переключение
одной строкой, без слома схемы.