healthcheck: у судей документов появился свой скилл и свой момент

doc-consistency и doc-code-drift звались шагом сессии между спринтами.
Сессия стала грумингом, груминг судит задачи, а не документы, и звать
чужих агентов не вправе — они в av-dev-docs. На живом проекте их не
звал бы никто, кроме разовых adopt и upgrade.

Момент назван у владельца. Разрез с canon check проверяемый: машина
сверяет форму, healthcheck — утверждения.

Почему скилл, а не просто описания агентов: двоим нужна оркестровка —
позвать обоих на весь канон разом, передать doc-code-drift раздел
запретов, разобрать урожай порциями, назвать границы покрытия и кого
именно позвал. Этого агент о себе не знает.

doc-wording внутрь не взят: ему оркестровка не нужна, и ритм другой —
он нужен там, где текст только что писали.

Заодно из shared/plugin-boundary.md и README убран счётчик скиллов: он
протух дважды за день.
This commit is contained in:
av
2026-08-09 16:58:51 +03:00
parent df5af47dc3
commit 4354cc4146
14 changed files with 218 additions and 41 deletions
+1 -1
View File
@@ -8,7 +8,7 @@
{ {
"name": "av-dev-docs", "name": "av-dev-docs",
"source": "./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", "name": "av-dev-tasks",
+40
View File
@@ -3553,3 +3553,43 @@ change нет — берём источником актуальные спек
192. **Версия в прозе, которую не читает машина, протухает молча.** Дом канона 192. **Версия в прозе, которую не читает машина, протухает молча.** Дом канона
назвал себя версией 7 при текущей 11: сверка шла по константе скрипта, а назвал себя версией 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. **Оркестровка — вот что отличает скилл от агента.** Одному исполнителю с
ясным входом скилл не нужен, его находит описание. Скилл заводят там, где
надо решить, кого звать, что передать, в каком объёме и что делать с
результатом.
+8 -5
View File
@@ -15,9 +15,12 @@
- `canon` — привести проект к канону документов: `check` / `adopt` / - `canon` — привести проект к канону документов: `check` / `adopt` /
`upgrade`, плюс скрипт `docs.py`. Там же лежит копия языка проектных `upgrade`, плюс скрипт `docs.py`. Там же лежит копия языка проектных
текстов — информационный стиль, англицизмы, жаргон; дом у него общий, текстов — информационный стиль, англицизмы, жаргон; дом у него общий,
`shared/language.md`. Смысловую часть, которой скрипт не видит, судят три `shared/language.md`;
агента: `doc-consistency` (документы между собой и с openspec), - `healthcheck` — здоровье документации **судом, а не машиной**: не разошлись
`doc-code-drift` (документы против кода) и `doc-wording` (язык документов); ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом —
`doc-consistency` (документы между собой и с openspec) и `doc-code-drift`
(факты против кода) — и разбирает урожай порциями. Дорого, поэтому не на
каждой задаче; язык документов вычитывает отдельный агент `doc-wording`;
- `docs` — содержимое канона по ходу разработки: ADR из архивного - `docs` — содержимое канона по ходу разработки: ADR из архивного
`design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка `design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка
архитектуры. архитектуры.
@@ -93,8 +96,8 @@ flowchart TB
Зависимости **односторонние: `av-dev-code` знает про `av-dev-docs` и Зависимости **односторонние: `av-dev-code` знает про `av-dev-docs` и
`av-dev-tasks`, обратно — нет.** Между собой эти двое тоже не связаны жёстко: `av-dev-tasks`, обратно — нет.** Между собой эти двое тоже не связаны жёстко:
каждый работает без другого. Как именно зовут соседа и что делают, когда вызов не каждый работает без другого. Как именно зовут соседа и что делают, когда вызов не
разрешился, — `shared/plugin-boundary.md`: правило нужно шести скиллам в двух разрешился, — `shared/plugin-boundary.md`: правило нужно большинству скиллов, и
плагинах, и ни один им не владеет. То, что нужно нескольким дословно — граница ни один плагин им не владеет. То, что нужно нескольким дословно — граница
плагинов, язык проектных текстов, словарь сопровождения, — живёт домом в плагинов, язык проектных текстов, словарь сопровождения, — живёт домом в
`shared/` и уезжает в каждый плагин помеченной копией. `shared/` и уезжает в каждый плагин помеченной копией.
-5
View File
@@ -71,11 +71,6 @@
сам разбор. Наблюдение к первому прогону: **не выродился ли шаг 4 в сам разбор. Наблюдение к первому прогону: **не выродился ли шаг 4 в
«оставить как есть»** — признак тот, что доклад не называет ни одного «оставить как есть»** — признак тот, что доклад не называет ни одного
движения с доводом движения с доводом
- [ ] `av-dev-docs:canon` больше не имеет момента для двух своих агентов.
`doc-consistency` и `doc-code-drift` звались шагом сессии раз в спринт;
сессии нет, груминг их звать не вправе (чужой плагин), и на живом проекте
их теперь не зовёт **никто**, кроме `adopt` и `upgrade`. Момент называет
их владелец — решить, какой
## 3. Калибровка — блокирует переезд jellybit ## 3. Калибровка — блокирует переезд jellybit
+1 -1
View File
@@ -153,7 +153,7 @@ description: "Конвейер ревью изменения, устроенны
читал решения, а эксплуатационный и `specs` — числа. Цена решения записана в читал решения, а эксплуатационный и `specs` — числа. Цена решения записана в
каноне и повторяется здесь, потому что платит её конвейер: **расхождение каноне и повторяется здесь, потому что платит её конвейер: **расхождение
изменения с записанным решением прогоном не ловится**, это работа сверки изменения с записанным решением прогоном не ловится**, это работа сверки
документации (`av-dev-docs`, агент `doc-consistency`) на сессии между спринтами. документации — скилл `av-dev-docs:healthcheck`.
Строка об этом обязательна в границах покрытия каждого прогона. Строка об этом обязательна в границах покрытия каждого прогона.
**Своя тема проекта бывает двух происхождений, и обе законны:** документ, который **Своя тема проекта бывает двух происхождений, и обе законны:** документ, который
+1 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "av-dev-docs", "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": { "author": {
"name": "Anton Vakhrushev", "name": "Anton Vakhrushev",
"email": "anwinged@gmail.com" "email": "anwinged@gmail.com"
+1 -1
View File
@@ -1,6 +1,6 @@
--- ---
name: doc-code-drift 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 tools: Read, Grep, Glob, Bash
model: sonnet model: sonnet
color: green color: green
+1 -1
View File
@@ -1,6 +1,6 @@
--- ---
name: doc-consistency 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 tools: Read, Grep, Glob
model: opus model: opus
color: yellow color: yellow
+10 -12
View File
@@ -127,15 +127,13 @@ capability: незаполненный канон это переходное с
## `check` ## `check`
1. `docs.py check`, при наличии базы диффа — с `--base`. 1. `docs.py check`, при наличии базы диффа — с `--base`.
2. **Агентов на каждом `check` не зови.** Оба — `doc-consistency` и 2. **Судей документов на каждом `check` не зови.** Ими владеет отдельный скилл —
`doc-code-drift`зовутся раз в спринт (шаг сессии), а также шагом 6 `adopt` `av-dev-docs:healthcheck`,и там же записано, когда его звать: он дорог, и
и шагом 6 `upgrade`, на весь канон разом. Они дороги: `doc-consistency` — тем, прогон по каждому `check` не окупается. `check` отвечает на «сходится ли
что на `opus` (сличение утверждений это суждение), `doc-code-drift` — тем, что форма», `healthcheck` — на «не разошлись ли утверждения».
читает репозиторий целиком, хотя сам идёт на `sonnet`. Позвал 3. Доклад: вывод скрипта строкой исхода и **граница покрытия** — что смотрели и
`doc-code-drift` — передай ему раздел запретов `CLAUDE.md`. чего не смотрели. Если суждение здесь нужно, скажи это строкой и предложи
3. Доклад: вывод скрипта строкой исхода, находки агентов поимённо, **граница `healthcheck`, а не зови агентов сам.
покрытия** — что смотрели и чего не смотрели, и **кого из двоих позвал**:
доклад, умолчавший об этом, читается как «сверено».
Дрейф раскладки чинится переносом; смысловые находки — это либо правка Дрейф раскладки чинится переносом; смысловые находки — это либо правка
документа, либо задача, если работы больше чем на абзац. документа, либо задача, если работы больше чем на абзац.
@@ -229,8 +227,8 @@ capability), `openspec/config.yaml`.
проекте обычно самый урожайный — правило единственного дома до адаптации никто не проекте обычно самый урожайный — правило единственного дома до адаптации никто не
проверял. проверял.
Зови **`doc-consistency`** (документы между собой и с openspec) и Вызови Skill **`av-dev-docs:healthcheck`** — он зовёт обоих судей на весь канон
**`doc-code-drift`** (факты против кода). Разбирай порциями, а не одним заходом. разом и держит разбор урожая порциями.
**Передай им объявленное переходное состояние из шага 5** — иначе честная строка **Передай им объявленное переходное состояние из шага 5** — иначе честная строка
в незаполненном слоте вернётся находкой, а это не поломка, а объявленный долг. в незаполненном слоте вернётся находкой, а это не поломка, а объявленный долг.
@@ -245,7 +243,7 @@ capability), `openspec/config.yaml`.
применяются по порядку. применяются по порядку.
4. Подними `canon` в `docs/.pm.json` до текущей. 4. Подними `canon` в `docs/.pm.json` до текущей.
5. `docs.py check`. 5. `docs.py check`.
6. **Позови обоих судей**`doc-consistency` и `doc-code-drift`. 6. **Позови судей**Skill `av-dev-docs:healthcheck`.
Записи журнала описывают **что сделать проекту**. Если запись этого не говорит — Записи журнала описывают **что сделать проекту**. Если запись этого не говорит —
это дефект журнала, и о нём надо сказать, а не догадываться. это дефект журнала, и о нём надо сказать, а не догадываться.
+5 -4
View File
@@ -149,8 +149,8 @@ openspec/
Цена этого решения записана, а не подразумевается: **расхождение изменения с Цена этого решения записана, а не подразумевается: **расхождение изменения с
записанным решением прогоном больше не ловится.** Раньше архитектурный проход записанным решением прогоном больше не ловится.** Раньше архитектурный проход
читал `adr/` и мог сказать «здесь отменено решение ADR-2026-03-11, а парного читал `adr/` и мог сказать «здесь отменено решение ADR-2026-03-11, а парного
статуса нет»; теперь это скажет только `doc-consistency` на сессии между статуса нет»; теперь это скажет только `doc-consistency`, а зовёт его скилл
спринтами. Сделка сознательная — ADR объясняет прошлое, а не предъявляет `healthcheck`. Сделка сознательная — ADR объясняет прошлое, а не предъявляет
требование к изменению, и чтение всего каталога решений на каждой задаче требование к изменению, и чтение всего каталога решений на каждой задаче
оплачивалось на каждой, а срабатывало на единицах. оплачивалось на каждой, а срабатывало на единицах.
@@ -521,8 +521,9 @@ kebab-case.** Причина не эстетическая: имя файла с
читающие команды. Слитый агент делал бы одну половину поверхностной; тот же читающие команды. Слитый агент делал бы одну половину поверхностной; тот же
разрез, что между `task-form` и `task-wording`. разрез, что между `task-form` и `task-wording`.
**Зовутся оба одинаково — раз в спринт на сессии, а также после `adopt` и после **Зовутся оба одинаково и одним скиллом — `av-dev-docs:healthcheck`, на весь
`upgrade`, на весь канон разом.** Не на синке документации: `doc-consistency` на канон разом; шагом `adopt` и шагом `upgrade` его зовёт `canon`.** Не на синке
документации: `doc-consistency` на
`opus` по каждой сделанной задаче не окупается, а расхождение между двумя документами по `opus` по каждой сделанной задаче не окупается, а расхождение между двумя документами по
определению требует двух, и на большинстве задач синк правит один. Пачка, определению требует двух, и на большинстве задач синк правит один. Пачка,
отбираемая работой, вдобавок не видит того, чего работа не касалась, — а именно отбираемая работой, вдобавок не видит того, чего работа не касалась, — а именно
+7 -6
View File
@@ -62,12 +62,13 @@ description: Вести содержимое документов канона
`security.md` не знает про новый эндпоинт. Поймать это на своей же правке нельзя, `security.md` не знает про новый эндпоинт. Поймать это на своей же правке нельзя,
и судит это агент `doc-consistency`. и судит это агент `doc-consistency`.
**Но синк его не зовёт.** Оба судьи документов `doc-consistency` и **Но синк его не зовёт.** Обоими судьями документов владеет скилл
`doc-code-drift` — зовутся раз в спринт, шагом сессии, на весь канон разом. `av-dev-docs:healthcheck`, и зовут их на весь канон разом, а не на пачку,
Причина в цене: `doc-consistency` на `opus` по каждой сделанной задаче — самая отобранную работой. Причина в цене: `doc-consistency` на `opus` по каждой
дорогая церемония процесса, а `doc-code-drift` хоть и на `sonnet`, но читает сделанной задаче — самая дорогая церемония процесса, а `doc-code-drift` хоть и на
репозиторий целиком. К тому же расхождение между двумя документами по определению `sonnet`, но читает репозиторий целиком. К тому же расхождение между двумя
требует двух документов, а на большинстве задач синк правит один. документами по определению требует двух документов, а на большинстве задач синк
правит один.
Что теряется: привязка находки к задаче, которая её породила. Что выигрывается, Что теряется: привязка находки к задаче, которая её породила. Что выигрывается,
кроме денег: синк перестаёт отбирать пачку, и в неё попадают документы, кроме денег: синк перестаёт отбирать пачку, и в неё попадают документы,
+138
View File
@@ -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` в репозитории плагинов. Правится
дом, а не этот файл.
<!-- копия: граница-плагинов из 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`.
+3 -2
View File
@@ -163,8 +163,9 @@ flowchart TD
Но повод назвать это здесь есть: беклог и документы протухают от одного и того Но повод назвать это здесь есть: беклог и документы протухают от одного и того
же — от сделанной работы. Пришёл на груминг и видишь, что с прошлого раза сделан же — от сделанной работы. Пришёл на груминг и видишь, что с прошлого раза сделан
десяток задач, — скажи строкой, что канон стоит сверить (`av-dev-docs:canon`), и десяток задач, — скажи строкой, что документы стоит сверить
иди дальше. Плагина в проекте нет — сверять нечем, и это тоже строка. (`av-dev-docs:healthcheck`), и иди дальше. Плагина в проекте нет — сверять нечем,
и это тоже строка.
## Интерактив ## Интерактив
+2 -2
View File
@@ -1,8 +1,8 @@
# Граница между плагинами # Граница между плагинами
**Это дом.** Правило обращения к соседнему плагину нужно всем, кто зовёт чужой **Это дом.** Правило обращения к соседнему плагину нужно всем, кто зовёт чужой
скилл, — а таких скиллов шесть в двух плагинах, и ни один из двух правилом не скилл, — а таких скиллов больше половины всех, и ни один плагин правилом не
владеет. Поэтому дом стоит снаружи, а плагины везут **копии**, помеченные владеет. (Числа здесь нет намеренно: оно уже дважды протухало за один день.) Поэтому дом стоит снаружи, а плагины везут **копии**, помеченные
разметкой `copies.py`. разметкой `copies.py`.
Правится **здесь**. Копия, поправленная у себя, — расхождение, а не правка. Правится **здесь**. Копия, поправленная у себя, — расхождение, а не правка.