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