From 4354cc4146fca1a717b5f12e94f1fd2d25213a68 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Sun, 9 Aug 2026 16:58:51 +0300 Subject: [PATCH] =?UTF-8?q?healthcheck:=20=D1=83=20=D1=81=D1=83=D0=B4?= =?UTF-8?q?=D0=B5=D0=B9=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82?= =?UTF-8?q?=D0=BE=D0=B2=20=D0=BF=D0=BE=D1=8F=D0=B2=D0=B8=D0=BB=D1=81=D1=8F?= =?UTF-8?q?=20=D1=81=D0=B2=D0=BE=D0=B9=20=D1=81=D0=BA=D0=B8=D0=BB=D0=BB=20?= =?UTF-8?q?=D0=B8=20=D1=81=D0=B2=D0=BE=D0=B9=20=D0=BC=D0=BE=D0=BC=D0=B5?= =?UTF-8?q?=D0=BD=D1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit doc-consistency и doc-code-drift звались шагом сессии между спринтами. Сессия стала грумингом, груминг судит задачи, а не документы, и звать чужих агентов не вправе — они в av-dev-docs. На живом проекте их не звал бы никто, кроме разовых adopt и upgrade. Момент назван у владельца. Разрез с canon check проверяемый: машина сверяет форму, healthcheck — утверждения. Почему скилл, а не просто описания агентов: двоим нужна оркестровка — позвать обоих на весь канон разом, передать doc-code-drift раздел запретов, разобрать урожай порциями, назвать границы покрытия и кого именно позвал. Этого агент о себе не знает. doc-wording внутрь не взят: ему оркестровка не нужна, и ритм другой — он нужен там, где текст только что писали. Заодно из shared/plugin-boundary.md и README убран счётчик скиллов: он протух дважды за день. --- .claude-plugin/marketplace.json | 2 +- DECISIONS.md | 40 ++++++ README.md | 13 +- TODO.md | 5 - av-dev-code/skills/review/SKILL.md | 2 +- av-dev-docs/.claude-plugin/plugin.json | 2 +- av-dev-docs/agents/doc-code-drift.md | 2 +- av-dev-docs/agents/doc-consistency.md | 2 +- av-dev-docs/skills/canon/SKILL.md | 22 ++- av-dev-docs/skills/canon/references/canon.md | 9 +- av-dev-docs/skills/docs/SKILL.md | 13 +- av-dev-docs/skills/healthcheck/SKILL.md | 138 +++++++++++++++++++ av-dev-tasks/skills/groom/SKILL.md | 5 +- shared/plugin-boundary.md | 4 +- 14 files changed, 218 insertions(+), 41 deletions(-) create mode 100644 av-dev-docs/skills/healthcheck/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3872e25..bac4eec 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,7 +8,7 @@ { "name": "av-dev-docs", "source": "./av-dev-docs", - "description": "Документация проекта: канон раскладки docs/ и CLAUDE.md, роли документов, правило единственного дома. check / adopt / upgrade со скриптом docs.py, старт проекта интервью по брифу, ведение содержимого по ходу разработки. Ничего не выполняет сам и никакого пайплайна не требует." + "description": "Документация проекта: канон раскладки docs/ и CLAUDE.md, роли документов, правило единственного дома. check / adopt / upgrade со скриптом docs.py, старт проекта интервью по брифу, ведение содержимого по ходу разработки, healthcheck — сверка документов между собой и с кодом судом двух агентов. Ничего не выполняет сам и никакого пайплайна не требует." }, { "name": "av-dev-tasks", diff --git a/DECISIONS.md b/DECISIONS.md index 85bc171..8e31614 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -3553,3 +3553,43 @@ change нет — берём источником актуальные спек 192. **Версия в прозе, которую не читает машина, протухает молча.** Дом канона назвал себя версией 7 при текущей 11: сверка шла по константе скрипта, а заголовок документа не сверял никто. + +## 58. Судьи документов получили свой скилл — `healthcheck` (2026-08-09) + +**АЕАКР. Момент вызова был свойством чужого ритуала и исчез вместе с ним.** +`doc-consistency` и `doc-code-drift` звались шагом сессии между спринтами. Сессия +стала грумингом, груминг судит задачи, а не документы, и звать чужих агентов он +не вправе — они живут в `av-dev-docs`. На живом проекте их не звал бы **никто**, +кроме разовых `adopt` и `upgrade`. + +Чинить это возвратом вызова в груминг было нельзя: это ровно то нарушение +границы, которое там и обнаружилось (вызов агента чужого плагина по имени, без +ветки «плагина нет»). Момент нужно было назвать **у владельца** — и оказалось, +что владельца-то у них и нет: `canon` их звал, но владел раскладкой, а не +суждением. + +**Скилл `av-dev-docs:healthcheck`.** Предмет — то, чего машина не видит: +разошлись ли документы между собой и с кодом. Разрез с `canon check` проверяемый: +**машина сверяет форму, healthcheck — утверждения.** «Раздел есть» проверит +скрипт; «написано, что зависимость одна, а в манифесте их три» — суждение. + +**Почему скилл, а не просто описание агентов.** Триггер у агента и так есть — его +`description`. Но двоим нужна **оркестровка**: позвать обоих на весь канон разом, +передать `doc-code-drift` раздел запретов, разобрать урожай порциями, назвать +границы покрытия и то, кого именно позвал. Этого агент о себе не знает. + +**`doc-wording` внутрь не взят, и это разрез, а не забывчивость.** Ему +оркестровка не нужна: он один и работает по названному списку документов. И ритм +другой — он нужен там, где текст только что писали, а не там, где он год лежал. +Скилл, собравший всех троих «потому что все про документы», склеил бы разные +вопросы под одним вызовом. + +### Что из этого следует + +193. **Момент вызова — такая же собственность, как сам инструмент.** Агент, + чей момент назначен чужим ритуалом, теряет его вместе с ритуалом и + замолкает беззвучно: он исправен, его просто никто не зовёт. +194. **Оркестровка — вот что отличает скилл от агента.** Одному исполнителю с + ясным входом скилл не нужен, его находит описание. Скилл заводят там, где + надо решить, кого звать, что передать, в каком объёме и что делать с + результатом. diff --git a/README.md b/README.md index 4d80251..b7b4eb6 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,12 @@ - `canon` — привести проект к канону документов: `check` / `adopt` / `upgrade`, плюс скрипт `docs.py`. Там же лежит копия языка проектных текстов — информационный стиль, англицизмы, жаргон; дом у него общий, - `shared/language.md`. Смысловую часть, которой скрипт не видит, судят три - агента: `doc-consistency` (документы между собой и с openspec), - `doc-code-drift` (документы против кода) и `doc-wording` (язык документов); + `shared/language.md`; + - `healthcheck` — здоровье документации **судом, а не машиной**: не разошлись + ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — + `doc-consistency` (документы между собой и с openspec) и `doc-code-drift` + (факты против кода) — и разбирает урожай порциями. Дорого, поэтому не на + каждой задаче; язык документов вычитывает отдельный агент `doc-wording`; - `docs` — содержимое канона по ходу разработки: ADR из архивного `design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка архитектуры. @@ -93,8 +96,8 @@ flowchart TB Зависимости **односторонние: `av-dev-code` знает про `av-dev-docs` и `av-dev-tasks`, обратно — нет.** Между собой эти двое тоже не связаны жёстко: каждый работает без другого. Как именно зовут соседа и что делают, когда вызов не -разрешился, — `shared/plugin-boundary.md`: правило нужно шести скиллам в двух -плагинах, и ни один им не владеет. То, что нужно нескольким дословно — граница +разрешился, — `shared/plugin-boundary.md`: правило нужно большинству скиллов, и +ни один плагин им не владеет. То, что нужно нескольким дословно — граница плагинов, язык проектных текстов, словарь сопровождения, — живёт домом в `shared/` и уезжает в каждый плагин помеченной копией. diff --git a/TODO.md b/TODO.md index 195cca5..02c25ca 100644 --- a/TODO.md +++ b/TODO.md @@ -71,11 +71,6 @@ сам разбор. Наблюдение к первому прогону: **не выродился ли шаг 4 в «оставить как есть»** — признак тот, что доклад не называет ни одного движения с доводом -- [ ] `av-dev-docs:canon` больше не имеет момента для двух своих агентов. - `doc-consistency` и `doc-code-drift` звались шагом сессии раз в спринт; - сессии нет, груминг их звать не вправе (чужой плагин), и на живом проекте - их теперь не зовёт **никто**, кроме `adopt` и `upgrade`. Момент называет - их владелец — решить, какой ## 3. Калибровка — блокирует переезд jellybit diff --git a/av-dev-code/skills/review/SKILL.md b/av-dev-code/skills/review/SKILL.md index 81e4d6e..2d5f149 100644 --- a/av-dev-code/skills/review/SKILL.md +++ b/av-dev-code/skills/review/SKILL.md @@ -153,7 +153,7 @@ description: "Конвейер ревью изменения, устроенны читал решения, а эксплуатационный и `specs` — числа. Цена решения записана в каноне и повторяется здесь, потому что платит её конвейер: **расхождение изменения с записанным решением прогоном не ловится**, это работа сверки -документации (`av-dev-docs`, агент `doc-consistency`) на сессии между спринтами. +документации — скилл `av-dev-docs:healthcheck`. Строка об этом обязательна в границах покрытия каждого прогона. **Своя тема проекта бывает двух происхождений, и обе законны:** документ, который diff --git a/av-dev-docs/.claude-plugin/plugin.json b/av-dev-docs/.claude-plugin/plugin.json index f734bd1..bf92207 100644 --- a/av-dev-docs/.claude-plugin/plugin.json +++ b/av-dev-docs/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "av-dev-docs", - "description": "Документация проекта: канон раскладки (CLAUDE.md плюс docs/ — паспорт, архитектура, схема БД, безопасность, конвенции, разведка, ADR, журнал ревью), роли документов и правило единственного дома. Три операции одной машиной сравнения — check, adopt, upgrade — со скриптом docs.py; заведение нового проекта интервью по брифу; ведение содержимого по ходу разработки: синк после сделанной задачи, ADR промоутом из архивного design.md, записка разведки, запись дефекта в журнал ревью. Смысловое, чего скрипт не видит, судят три агента: doc-consistency, doc-code-drift, doc-wording. Задач не ведёт — это плагин av-dev-tasks, и он опционален.", + "description": "Документация проекта: канон раскладки (CLAUDE.md плюс docs/ — паспорт, архитектура, схема БД, безопасность, конвенции, разведка, ADR, журнал ревью), роли документов и правило единственного дома. Три операции одной машиной сравнения — check, adopt, upgrade — со скриптом docs.py; заведение нового проекта интервью по брифу; ведение содержимого по ходу разработки: синк после сделанной задачи, ADR промоутом из архивного design.md, записка разведки, запись дефекта в журнал ревью. Смысловое, чего скрипт не видит, судит скилл healthcheck двумя агентами разом — doc-consistency (документы между собой и с openspec) и doc-code-drift (факты против кода); язык документов вычитывает агент doc-wording. Задач не ведёт — это плагин av-dev-tasks, и он опционален.", "author": { "name": "Anton Vakhrushev", "email": "anwinged@gmail.com" diff --git a/av-dev-docs/agents/doc-code-drift.md b/av-dev-docs/agents/doc-code-drift.md index 54b87db..cc7d03f 100644 --- a/av-dev-docs/agents/doc-code-drift.md +++ b/av-dev-docs/agents/doc-code-drift.md @@ -1,6 +1,6 @@ --- name: doc-code-drift -description: "Сверка документов канона с кодом по закрытому перечню проверяемых фактов: имя основной ветки и команды из CLAUDE.md, запреты с путями, testdata и временный каталог, путь миграций из .pm.json, внешние зависимости поимённо в architecture.md против манифеста, настройки с числовым значением в database.md против конфига и кода, единые точки проекта против реального числа реализаций, capability против существующих модулей. Отвечает на «этот факт ещё верен», а не «эта архитектура правильная». Читает весь репозиторий, гоняет только читающие команды. Отдаёт готовые формулировки и ничего не правит сам. Согласованность документов между собой смотрит агент doc-consistency. Использовать на сессии между спринтами, а также после приведения проекта к канону (adopt) и после повышения версии канона (upgrade). Только чтение." +description: "Сверка документов канона с кодом по закрытому перечню проверяемых фактов: имя основной ветки и команды из CLAUDE.md, запреты с путями, testdata и временный каталог, путь миграций из .pm.json, внешние зависимости поимённо в architecture.md против манифеста, настройки с числовым значением в database.md против конфига и кода, единые точки проекта против реального числа реализаций, capability против существующих модулей. Отвечает на «этот факт ещё верен», а не «эта архитектура правильная». Читает весь репозиторий, гоняет только читающие команды. Отдаёт готовые формулировки и ничего не правит сам. Согласованность документов между собой смотрит агент doc-consistency. Зовётся скиллом av-dev-docs:healthcheck — на весь канон разом; он же зовётся шагом adopt и шагом upgrade. Только чтение." tools: Read, Grep, Glob, Bash model: sonnet color: green diff --git a/av-dev-docs/agents/doc-consistency.md b/av-dev-docs/agents/doc-consistency.md index 95133c2..85ad5c5 100644 --- a/av-dev-docs/agents/doc-consistency.md +++ b/av-dev-docs/agents/doc-consistency.md @@ -1,6 +1,6 @@ --- name: doc-consistency -description: "Сверка документов канона между собой и с openspec: один факт, живущий в двух домах, прямое противоречие между документами (периметр, зависимости, обратимость), поведение системы, осевшее в architecture.md вместо спек, capability без обзора или с пересказом требований, число без провенанса в research, ADR без ссылки на архивный design.md и без парного статуса при замене, заглушка вместо честной строки в пустом слоте. Читает docs/ и openspec/, кода не читает. Отдаёт готовые формулировки и ничего не правит сам. Соответствие документов коду смотрит агент doc-code-drift, язык — doc-wording. Использовать на сессии между спринтами, а также после приведения проекта к канону (adopt) и после повышения версии канона (upgrade), на весь канон разом; на отдельной задаче не звать. Только чтение." +description: "Сверка документов канона между собой и с openspec: один факт, живущий в двух домах, прямое противоречие между документами (периметр, зависимости, обратимость), поведение системы, осевшее в architecture.md вместо спек, capability без обзора или с пересказом требований, число без провенанса в research, ADR без ссылки на архивный design.md и без парного статуса при замене, заглушка вместо честной строки в пустом слоте. Читает docs/ и openspec/, кода не читает. Отдаёт готовые формулировки и ничего не правит сам. Соответствие документов коду смотрит агент doc-code-drift, язык — doc-wording. Зовётся скиллом av-dev-docs:healthcheck — на весь канон разом; он же зовётся шагом adopt и шагом upgrade. На отдельной задаче и на синке документации не звать. Только чтение." tools: Read, Grep, Glob model: opus color: yellow diff --git a/av-dev-docs/skills/canon/SKILL.md b/av-dev-docs/skills/canon/SKILL.md index 9bf33fc..34133f4 100644 --- a/av-dev-docs/skills/canon/SKILL.md +++ b/av-dev-docs/skills/canon/SKILL.md @@ -127,15 +127,13 @@ capability: незаполненный канон это переходное с ## `check` 1. `docs.py check`, при наличии базы диффа — с `--base`. -2. **Агентов на каждом `check` не зови.** Оба — `doc-consistency` и - `doc-code-drift` — зовутся раз в спринт (шаг сессии), а также шагом 6 `adopt` - и шагом 6 `upgrade`, на весь канон разом. Они дороги: `doc-consistency` — тем, - что на `opus` (сличение утверждений это суждение), `doc-code-drift` — тем, что - читает репозиторий целиком, хотя сам идёт на `sonnet`. Позвал - `doc-code-drift` — передай ему раздел запретов `CLAUDE.md`. -3. Доклад: вывод скрипта строкой исхода, находки агентов поимённо, **граница - покрытия** — что смотрели и чего не смотрели, и **кого из двоих позвал**: - доклад, умолчавший об этом, читается как «сверено». +2. **Судей документов на каждом `check` не зови.** Ими владеет отдельный скилл — + `av-dev-docs:healthcheck`, — и там же записано, когда его звать: он дорог, и + прогон по каждому `check` не окупается. `check` отвечает на «сходится ли + форма», `healthcheck` — на «не разошлись ли утверждения». +3. Доклад: вывод скрипта строкой исхода и **граница покрытия** — что смотрели и + чего не смотрели. Если суждение здесь нужно, скажи это строкой и предложи + `healthcheck`, а не зови агентов сам. Дрейф раскладки чинится переносом; смысловые находки — это либо правка документа, либо задача, если работы больше чем на абзац. @@ -229,8 +227,8 @@ capability), `openspec/config.yaml`. проекте обычно самый урожайный — правило единственного дома до адаптации никто не проверял. -Зови **`doc-consistency`** (документы между собой и с openspec) и -**`doc-code-drift`** (факты против кода). Разбирай порциями, а не одним заходом. +Вызови Skill **`av-dev-docs:healthcheck`** — он зовёт обоих судей на весь канон +разом и держит разбор урожая порциями. **Передай им объявленное переходное состояние из шага 5** — иначе честная строка в незаполненном слоте вернётся находкой, а это не поломка, а объявленный долг. @@ -245,7 +243,7 @@ capability), `openspec/config.yaml`. применяются по порядку. 4. Подними `canon` в `docs/.pm.json` до текущей. 5. `docs.py check`. -6. **Позови обоих судей** — `doc-consistency` и `doc-code-drift`. +6. **Позови судей** — Skill `av-dev-docs:healthcheck`. Записи журнала описывают **что сделать проекту**. Если запись этого не говорит — это дефект журнала, и о нём надо сказать, а не догадываться. diff --git a/av-dev-docs/skills/canon/references/canon.md b/av-dev-docs/skills/canon/references/canon.md index b234e88..ae15baf 100644 --- a/av-dev-docs/skills/canon/references/canon.md +++ b/av-dev-docs/skills/canon/references/canon.md @@ -149,8 +149,8 @@ openspec/ Цена этого решения записана, а не подразумевается: **расхождение изменения с записанным решением прогоном больше не ловится.** Раньше архитектурный проход читал `adr/` и мог сказать «здесь отменено решение ADR-2026-03-11, а парного -статуса нет»; теперь это скажет только `doc-consistency` на сессии между -спринтами. Сделка сознательная — ADR объясняет прошлое, а не предъявляет +статуса нет»; теперь это скажет только `doc-consistency`, а зовёт его скилл +`healthcheck`. Сделка сознательная — ADR объясняет прошлое, а не предъявляет требование к изменению, и чтение всего каталога решений на каждой задаче оплачивалось на каждой, а срабатывало на единицах. @@ -521,8 +521,9 @@ kebab-case.** Причина не эстетическая: имя файла с читающие команды. Слитый агент делал бы одну половину поверхностной; тот же разрез, что между `task-form` и `task-wording`. -**Зовутся оба одинаково — раз в спринт на сессии, а также после `adopt` и после -`upgrade`, на весь канон разом.** Не на синке документации: `doc-consistency` на +**Зовутся оба одинаково и одним скиллом — `av-dev-docs:healthcheck`, на весь +канон разом; шагом `adopt` и шагом `upgrade` его зовёт `canon`.** Не на синке +документации: `doc-consistency` на `opus` по каждой сделанной задаче не окупается, а расхождение между двумя документами по определению требует двух, и на большинстве задач синк правит один. Пачка, отбираемая работой, вдобавок не видит того, чего работа не касалась, — а именно diff --git a/av-dev-docs/skills/docs/SKILL.md b/av-dev-docs/skills/docs/SKILL.md index 7384cbe..f85acad 100644 --- a/av-dev-docs/skills/docs/SKILL.md +++ b/av-dev-docs/skills/docs/SKILL.md @@ -62,12 +62,13 @@ description: Вести содержимое документов канона `security.md` не знает про новый эндпоинт. Поймать это на своей же правке нельзя, и судит это агент `doc-consistency`. -**Но синк его не зовёт.** Оба судьи документов — `doc-consistency` и -`doc-code-drift` — зовутся раз в спринт, шагом сессии, на весь канон разом. -Причина в цене: `doc-consistency` на `opus` по каждой сделанной задаче — самая -дорогая церемония процесса, а `doc-code-drift` хоть и на `sonnet`, но читает -репозиторий целиком. К тому же расхождение между двумя документами по определению -требует двух документов, а на большинстве задач синк правит один. +**Но синк его не зовёт.** Обоими судьями документов владеет скилл +`av-dev-docs:healthcheck`, и зовут их на весь канон разом, а не на пачку, +отобранную работой. Причина в цене: `doc-consistency` на `opus` по каждой +сделанной задаче — самая дорогая церемония процесса, а `doc-code-drift` хоть и на +`sonnet`, но читает репозиторий целиком. К тому же расхождение между двумя +документами по определению требует двух документов, а на большинстве задач синк +правит один. Что теряется: привязка находки к задаче, которая её породила. Что выигрывается, кроме денег: синк перестаёт отбирать пачку, и в неё попадают документы, diff --git a/av-dev-docs/skills/healthcheck/SKILL.md b/av-dev-docs/skills/healthcheck/SKILL.md new file mode 100644 index 0000000..15439a8 --- /dev/null +++ b/av-dev-docs/skills/healthcheck/SKILL.md @@ -0,0 +1,138 @@ +--- +name: healthcheck +description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без провенанса) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию канона проверяет скилл canon, язык документов — агент doc-wording." +--- + +# Здоровье документации + +Проверяет то, **чего машина не видит**: разошлись ли документы между собой и с +кодом. Раскладка, версия, битые ссылки, нетронутые плейсхолдеры — это `canon +check` и его скрипт; здесь начинается там, где кончается `docs.py`. + +Разрез проверяемый: **машина сверяет форму, этот скилл — утверждения**. «В +`architecture.md` есть раздел» проверит скрипт. «В `architecture.md` написано, +что зависимость одна, а в манифесте их три» — суждение, и его выносит агент. + +## Когда звать + +**Зовёт человек**, но признак наблюдаемый, а не календарный: + +- **с прошлой сверки сделан десяток задач.** Документы протухают ровно от + сделанной работы: переименованная цель сборки, ушедшая зависимость, второй + способ делать то, что обзор объявил единственным, факт, дописанный в + `architecture.md` и уже живущий в `CLAUDE.md`; +- **вернулись к проекту после перерыва** — прежде чем опираться на написанное; +- **перед тем как опереться на документ в решении**, если оно дорогое; +- шагом `adopt` и шагом `upgrade` — их зовёт скилл `canon` сам. + +**Не на каждой задаче и не на каждом синке документации.** Цена реальная: +`doc-consistency` идёт на `opus`, потому что сличение утверждений — суждение; +`doc-code-drift` хоть и на `sonnet`, но читает репозиторий целиком. Прогон по +каждой сделанной задаче был бы самой дорогой церемонией процесса, а находок дал +бы почти те же: документы расходятся не с одной задачи, а с десятка. + +Прежде оба звались шагом сессии между спринтами. Спринтов нет, и **момент +пришлось назвать заново** — иначе их не звал бы никто, кроме разовых `adopt` и +`upgrade`, то есть на живом проекте никогда. + +## Обращение к соседним плагинам + +**Копия.** Дом — `shared/plugin-boundary.md` в репозитории плагинов. Правится +дом, а не этот файл. + + + +Плагины `av-dev` ставятся порознь, и ни один не вправе считать, что сосед на +месте. + +**Чужой скилл зовётся полным именем** — `av-dev-docs:canon`, `av-dev-tasks:tasks`, +`av-dev-code:review`. Короткое имя может разрешиться в устаревшую проектную копию +из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. + +**Путь в дерево чужого плагина не пишется никогда.** `$CLAUDE_PLUGIN_ROOT` ведёт +только в свой плагин; вычисленный от него путь к соседу либо не откроется, либо +откроет чужую установку. Нужен чужой справочник — зови владеющий им скилл, он +прочитает его сам. + +**Вызов не разрешился — плагина в проекте нет.** Это исход, а не поломка: назови +строкой доклада, чего теперь не делает никто, и продолжай работу. Молчать нельзя, +пропуск неотличим от сделанного; выдумывать обходной путь нельзя тоже. + +**Присутствие узнаётся вызовом или следом в проекте, но не объявлением.** Перечня +установленных плагинов проект не ведёт — он разошёлся бы с действительностью +молча. Что сосед здесь работал, видно по заведённому им файлу: `docs/.pm.json` — +канон, `<каталог задач>/.tasks.json` — задачи, `openspec/config.yaml` — конвейер. + + + +Здесь сосед один: `av-dev-tasks:tasks`, когда находка тянет на задачу. Его нет — +находки остаются списком в докладе, и это говорится строкой. + +## Пачка — весь канон, и это не расточительство + +Оба агента зовутся **на весь канон разом**, а не на пачку, отобранную работой. + +Когда пачку отбирала работа, без присмотра оставалось ровно то, чего работа не +касалась: правка, отменившая решение, живёт в одном документе, а парный статус +нужен в другом; факт, продублированный год назад, не попадёт ни в один диапазон +диффа. Канон мал — он читается целиком, и цена этого известна заранее. + +## Кого зовёшь и что передаёшь + +| Агент | Что смотрит | Читает | Модель | +| --- | --- | --- | --- | +| `doc-consistency` | смысловой дубль, прямое противоречие между документами, поведение в `architecture.md` вместо спек, ADR без ссылки и парного статуса, число без провенанса, заглушка вместо честной строки | `docs/`, `openspec/` | `opus` | +| `doc-code-drift` | протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки проекта, capability | весь репозиторий | `sonnet` | + +**`doc-code-drift` обязан получить раздел запретов `CLAUDE.md`.** Он гоняет +команды — только читающие, — и без перечня запретов не знает, чего в этом +проекте запускать нельзя. Не передал — он либо остановится, либо тронет то, чего +трогать не следовало. + +**Судит не тот, кто писал.** Ни один из двоих ничего не правит: оба возвращают +готовые формулировки, подставляешь ты. Самопроверка документа слабее всего ровно +там, где формулировка казалась удачной при написании. + +Одного из двух можно позвать отдельно — но **скажи в докладе, кого именно +позвал**. Доклад, умолчавший об этом, читается как «сверено целиком». + +## Разбор урожая + +Находки — обычный материал правки, и разбирать их надо **порциями**, а не одним +заходом: тридцать находок подряд получают «принято» не потому, что верны, а +потому, что разбор затянулся. + +По каждой находке ровно три исхода: + +1. **Строка на замену** — правь документ сразу. Формулировка уже готова, спорить + не с чем, и откладывание превращает её в задачу дороже самой правки. +2. **Работа больше чем на абзац** — задача типа `chore`. Заводит её **не этот + скилл**: вызови Skill `av-dev-tasks:tasks`, у него свой формат, дедупликация + против беклога и кладбища. Плагина нет — отдай списком в докладе и скажи это + строкой. +3. **Не находка** — агент ошибся, документ прав. Скажи это прямо: неразобранная + находка и отклонённая различаются, и вторая экономит время на следующем + прогоне. Класс ошибок, который повторяется, идёт в `docs/review.*`, раздел + настройки, — там дом типовых ложноположительных. + +## Доклад + +- **Кого позвал** — обоих или одного, и почему одного. +- Находки по каждому агенту: сколько, что поправлено сразу, что стало задачей + (со слагами), что отклонено и почему. +- **Границы покрытия**: что смотрели и чего не смотрели. У `doc-code-drift` она + идёт из его собственного отчёта — перечень фактов у него закрытый, и он + называет, какие из них проверить было нечем. +- Канона в проекте нет вовсе — это исход, а не пустой прогон: скажи строкой и + предложи `av-dev-docs:canon`. + +## Чего этот скилл не делает + +- **Не проверяет раскладку, версию и ссылки** — это `canon check`, там машина. +- **Не судит язык** документов: залог, англицизмы, жаргон, термин без дома — это + агент `doc-wording`, и зовут его отдельно, по пачке правленных документов. У + него другой ритм: он нужен там, где текст только что писали, а не там, где он + год лежал. Оркестровать его нечем — он один и работает по названному списку. +- **Не правит документы за агентов** — они возвращают формулировки, решение + подставить принимает человек или ты по его правилу. +- **Не заводит задачи** — этим владеет `av-dev-tasks:tasks`. diff --git a/av-dev-tasks/skills/groom/SKILL.md b/av-dev-tasks/skills/groom/SKILL.md index e471159..bceffcc 100644 --- a/av-dev-tasks/skills/groom/SKILL.md +++ b/av-dev-tasks/skills/groom/SKILL.md @@ -163,8 +163,9 @@ flowchart TD Но повод назвать это здесь есть: беклог и документы протухают от одного и того же — от сделанной работы. Пришёл на груминг и видишь, что с прошлого раза сделан -десяток задач, — скажи строкой, что канон стоит сверить (`av-dev-docs:canon`), и -иди дальше. Плагина в проекте нет — сверять нечем, и это тоже строка. +десяток задач, — скажи строкой, что документы стоит сверить +(`av-dev-docs:healthcheck`), и иди дальше. Плагина в проекте нет — сверять нечем, +и это тоже строка. ## Интерактив diff --git a/shared/plugin-boundary.md b/shared/plugin-boundary.md index 19fbf00..3d2ceb2 100644 --- a/shared/plugin-boundary.md +++ b/shared/plugin-boundary.md @@ -1,8 +1,8 @@ # Граница между плагинами **Это дом.** Правило обращения к соседнему плагину нужно всем, кто зовёт чужой -скилл, — а таких скиллов шесть в двух плагинах, и ни один из двух правилом не -владеет. Поэтому дом стоит снаружи, а плагины везут **копии**, помеченные +скилл, — а таких скиллов больше половины всех, и ни один плагин правилом не +владеет. (Числа здесь нет намеренно: оно уже дважды протухало за один день.) Поэтому дом стоит снаружи, а плагины везут **копии**, помеченные разметкой `copies.py`. Правится **здесь**. Копия, поправленная у себя, — расхождение, а не правка.