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,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`         | Не будет сделано                                |
+
+Правый столбец можно поменять под свою лексику. Сейчас — дефолт (строка = имя роли).