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
parent dc0e6f9452
commit aecbf392d9
5 changed files with 135 additions and 0 deletions
@@ -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 окажутся самодостаточными, спеки можно будет гитигнорить — переключение
+  одной строкой, без слома схемы.
@@ -0,0 +1,43 @@
+# Domain docs
+
+Как инженерные скиллы должны читать доменную документацию этого репозитория при
+исследовании кода.
+
+## Перед исследованием кода прочитать
+
+- `CONTEXT.md` в корне — глоссарий проекта (доменный язык).
+- `docs/adr/` — ADR, затрагивающие область, в которой собираешься работать.
+
+Если файла нет — **молча продолжай**. Не сигналить об отсутствии и не предлагать
+создать заранее. Продюсер (`grill-with-docs`) создаёт их лениво, когда термин или
+решение реально кристаллизуются.
+
+## Раскладка
+
+Single-context (один контекст на репозиторий):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-<slug>.md
+│   └── 0002-<slug>.md
+└── ...
+```
+
+## Использовать лексику глоссария
+
+Когда вывод называет доменное понятие (заголовок спеки, гипотеза, имя теста,
+рефактор-предложение) — использовать термин так, как он определён в `CONTEXT.md`.
+Не уходить в синонимы, которые глоссарий помечает `_Avoid_`.
+
+Если нужного понятия в глоссарии ещё нет — это сигнал: либо изобретаешь язык,
+которого в проекте нет (пересмотреть), либо реальный пробел (отметить для
+`grill-with-docs`).
+
+## Флагать конфликты с ADR
+
+Если вывод противоречит существующему ADR — явно об этом сказать, а не молча
+переопределять:
+
+> _Противоречит ADR-0003 (<тема>) — но стоит переоткрыть, потому что…_
@@ -0,0 +1,22 @@
+# Issue tracker: локальный markdown
+
+Задачи и PRD этого репозитория живут markdown-файлами в `.scratch/`. GitHub Issues
+не используются — не вызывать `gh issue create`. Файлы в `.scratch/` коммитятся
+(`.scratch/` не в `.gitignore`).
+
+## Соглашения
+
+- Одна фича — один каталог: `.scratch/<feature-slug>/`
+- PRD фичи — `.scratch/<feature-slug>/PRD.md` (по сути транзиентная спека: снимок
+  понимания на момент работы; долговечные решения идут в ADR — см. `docs/agents/domain.md`)
+- Задачи реализации — `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, нумерация с `01`
+- Состояние триажа — строкой `Status:` у верха файла задачи (строки ролей — в `triage-labels.md`)
+- Комментарии и история — в конец файла под заголовком `## Comments`
+
+## Когда скилл говорит «опубликовать в issue tracker»
+
+Создать файл в `.scratch/<feature-slug>/` (каталог создать при необходимости).
+
+## Когда скилл говорит «достать тикет»
+
+Прочитать файл по указанному пути. Обычно путь или номер задачи передаёт пользователь.
@@ -0,0 +1,14 @@
+# Triage labels
+
+Скиллы оперируют пятью каноническими ролями триажа. Здесь они сопоставлены со
+строками, которые реально используются в этом репозитории (в строке `Status:` файла задачи).
+
+| Роль в mattpocock/skills | Строка у нас      | Значение                                       |
+| ------------------------ | ----------------- | ---------------------------------------------- |
+| `needs-triage`           | `needs-triage`    | Мейнтейнеру нужно оценить задачу               |
+| `needs-info`             | `needs-info`      | Ждём от репортёра дополнительную информацию     |
+| `ready-for-agent`        | `ready-for-agent` | Полностью специфицировано, можно отдать агенту  |
+| `ready-for-human`        | `ready-for-human` | Нужна ручная реализация человеком               |
+| `wontfix`                | `wontfix`         | Не будет сделано                                |
+
+Правый столбец можно поменять под свою лексику. Сейчас — дефолт (строка = имя роли).