From aecbf392d933897654eeabbcad29ad4fbf693f60 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Mon, 1 Jun 2026 23:29:50 +0300 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=D0=BF=D0=BE=D0=B4=D0=BA=D0=BB?= =?UTF-8?q?=D1=8E=D1=87=D0=B5=D0=BD=D0=B0=20doc/issue-=D0=BC=D0=B5=D1=82?= =?UTF-8?q?=D0=BE=D0=B4=D0=BE=D0=BB=D0=BE=D0=B3=D0=B8=D1=8F=20Pocock=20?= =?UTF-8?q?=D0=B8=20=D0=B7=D0=B0=D1=84=D0=B8=D0=BA=D1=81=D0=B8=D1=80=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0=D0=BD=D0=B0=20=D1=80=D0=B0=D1=81=D0=BA=D0=BB=D0=B0?= =?UTF-8?q?=D0=B4=D0=BA=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - развести документацию по времени жизни: транзиентные спеки отдельно от долговечных решений (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. --- AGENTS.md | 16 ++++++++++ docs/adr/0001-spec-adr-issue-layout.md | 40 ++++++++++++++++++++++++ docs/agents/domain.md | 43 ++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 22 +++++++++++++ docs/agents/triage-labels.md | 14 +++++++++ 5 files changed, 135 insertions(+) create mode 100644 docs/adr/0001-spec-adr-issue-layout.md create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md diff --git a/AGENTS.md b/AGENTS.md index 2d366f5..ca3d65f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,22 @@ - Минимальный порядок: `resolve-library-id` -> `query-docs`. - Принятое решение фиксировать в коде и/или документации (кратко: что проверили и почему выбрали именно этот вариант). +## Agent skills + +Конфигурация для инженерных скиллов (набор Matt Pocock). Подробности — в `docs/agents/`. + +### Issue tracker + +Локальный markdown: задачи и PRD живут файлами в `.scratch//` (коммитятся, `.scratch/` не в `.gitignore`). GitHub Issues не используются. См. `docs/agents/issue-tracker.md`. + +### Triage labels + +Пять канонических ролей, строки совпадают с именами (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). См. `docs/agents/triage-labels.md`. + +### Domain docs + +Single-context: `CONTEXT.md` и `docs/adr/` в корне репозитория. См. `docs/agents/domain.md`. + ## Навигация по документации - [README.md](./README.md) — пользовательский quick start и обзор. diff --git a/docs/adr/0001-spec-adr-issue-layout.md b/docs/adr/0001-spec-adr-issue-layout.md new file mode 100644 index 0000000..3376196 --- /dev/null +++ b/docs/adr/0001-spec-adr-issue-layout.md @@ -0,0 +1,40 @@ +# ADR-0001: Раскладка спецификаций, решений и задач + +Принято: 2026-06-01 + +## Решение + +Рабочую документацию разносим по времени жизни: + +- **Транзиентные спеки фич** — markdown в `.scratch//PRD.md`, коммитятся + (`.scratch/` не в `.gitignore`). Снимок понимания на момент работы, не для + перечитывания. Продюсер — `to-prd`. +- **Долговечные решения** — ADR в `docs/adr/NNNN-.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 окажутся самодостаточными, спеки можно будет гитигнорить — переключение + одной строкой, без слома схемы. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..d8a50a7 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,43 @@ +# Domain docs + +Как инженерные скиллы должны читать доменную документацию этого репозитория при +исследовании кода. + +## Перед исследованием кода прочитать + +- `CONTEXT.md` в корне — глоссарий проекта (доменный язык). +- `docs/adr/` — ADR, затрагивающие область, в которой собираешься работать. + +Если файла нет — **молча продолжай**. Не сигналить об отсутствии и не предлагать +создать заранее. Продюсер (`grill-with-docs`) создаёт их лениво, когда термин или +решение реально кристаллизуются. + +## Раскладка + +Single-context (один контекст на репозиторий): + +``` +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-.md +│ └── 0002-.md +└── ... +``` + +## Использовать лексику глоссария + +Когда вывод называет доменное понятие (заголовок спеки, гипотеза, имя теста, +рефактор-предложение) — использовать термин так, как он определён в `CONTEXT.md`. +Не уходить в синонимы, которые глоссарий помечает `_Avoid_`. + +Если нужного понятия в глоссарии ещё нет — это сигнал: либо изобретаешь язык, +которого в проекте нет (пересмотреть), либо реальный пробел (отметить для +`grill-with-docs`). + +## Флагать конфликты с ADR + +Если вывод противоречит существующему ADR — явно об этом сказать, а не молча +переопределять: + +> _Противоречит ADR-0003 (<тема>) — но стоит переоткрыть, потому что…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..7a1fa05 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,22 @@ +# Issue tracker: локальный markdown + +Задачи и PRD этого репозитория живут markdown-файлами в `.scratch/`. GitHub Issues +не используются — не вызывать `gh issue create`. Файлы в `.scratch/` коммитятся +(`.scratch/` не в `.gitignore`). + +## Соглашения + +- Одна фича — один каталог: `.scratch//` +- PRD фичи — `.scratch//PRD.md` (по сути транзиентная спека: снимок + понимания на момент работы; долговечные решения идут в ADR — см. `docs/agents/domain.md`) +- Задачи реализации — `.scratch//issues/-.md`, нумерация с `01` +- Состояние триажа — строкой `Status:` у верха файла задачи (строки ролей — в `triage-labels.md`) +- Комментарии и история — в конец файла под заголовком `## Comments` + +## Когда скилл говорит «опубликовать в issue tracker» + +Создать файл в `.scratch//` (каталог создать при необходимости). + +## Когда скилл говорит «достать тикет» + +Прочитать файл по указанному пути. Обычно путь или номер задачи передаёт пользователь. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..72c7dc3 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -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` | Не будет сделано | + +Правый столбец можно поменять под свою лексику. Сейчас — дефолт (строка = имя роли).