вычитка ревью: пережитки трёх плагинов и язык слияния
Восемнадцать веток «плагина нет» описывали недостижимое: скиллы и агенты теперь в одном плагине и разрешаются всегда. Где предмет всё же может отсутствовать — ветка переписана на след в проекте (нет docs/, нет каталога задач, нет openspec/); где отсутствовать нечему — снята. Туда же анонсы, обещавшие ветку, которой в разделе больше нет. Правило копий и его применение разъезжались в одном коммите: правило называло два законных случая, а absence.md разослан семью копиями по SKILL.md. Назван третий случай, и разрез проверяемый — файл, который модель получает целиком, против файла, за которым она идёт отдельным чтением. Заодно сняты объявления копий там, где копию сменила ссылка, и довод у карты домов в doc-consistency: он ссылался на отсутствие плагина, хотя устав едет вместе с плагином. Описания скиллов во фронтматтерах звали снятые короткие имена — по ним скилл не находится. task-track перестал обещать повышение: версию двигает doc-canon. Язык: сняты кросс-вызов, опцион и деградация, конверсия и «читатель» в config.py, charter'ы против уставов, замер против подсчёта, страдательный залог в журнале. Строка «настройки av-dev» в таблице отсутствия — слово «раскладка» называло и целое, и его часть. Мелкое: тема 52 в README была 64, транслит в task-wording машина не проверяет, мёртвая ветка REQUIRED в addresses.py, ссылки на язык в закрытом журнале.
This commit is contained in:
+9
-6
@@ -3928,7 +3928,7 @@ change по нему не будет никогда, — и такое реше
|
||||
верно, но **посылка под ним не проверялась**: за всё время подмножество не
|
||||
понадобилось ни разу, а платился раскол постоянно.
|
||||
|
||||
Цена измерена, а не оценена: шестьдесят с лишним кросс-вызовов при цикле
|
||||
Цена измерена, а не оценена: шестьдесят с лишним вызовов между скиллами при цикле
|
||||
зависимостей `docs → code → docs`, язык проектных текстов четырьмя помеченными
|
||||
копиями по 213 строк, словарь сопровождения двумя, правило границы семью,
|
||||
дюжина веток «плагина нет» — и `copies.py`, заведённый ровно затем, чтобы это
|
||||
@@ -3959,9 +3959,10 @@ change по нему не будет никогда, — и такое реше
|
||||
читаться из него самого, а не из документации плагина. Отсюда правило записи:
|
||||
скрипт правит строку, а не переписывает файл.
|
||||
|
||||
**Опцион не потерян.** Понадобится инфраструктурный плагин — расколоть обратно
|
||||
будет переименованием пространства имён, а не переделкой: граница по-прежнему
|
||||
держится на следе в проекте. Платить за этот опцион копиями сегодня незачем.
|
||||
**Возможность расколоть обратно не потеряна.** Понадобится инфраструктурный
|
||||
плагин — раскол будет переименованием пространства имён, а не переделкой:
|
||||
граница по-прежнему держится на следе в проекте. Платить за эту возможность
|
||||
копиями сегодня незачем.
|
||||
|
||||
### Что из этого следует
|
||||
|
||||
@@ -3975,8 +3976,10 @@ change по нему не будет никогда, — и такое реше
|
||||
слиянии или расколе.
|
||||
220. **Копия дословного текста — плата за неразрешимый путь, а не за важность
|
||||
правила.** Путь разрешился — копия становится вторым домом без причины.
|
||||
Остаётся она там, где текст обязан лежать внутри промпта: устав агента и
|
||||
скелет, уезжающий в проект.
|
||||
Остаётся она там, где текст обязан лежать **внутри промпта**: устав агента,
|
||||
`SKILL.md` скилла и скелет, уезжающий в проект. Разрез проверяемый: файл,
|
||||
который модель получает целиком, против файла, за которым она идёт
|
||||
отдельным чтением.
|
||||
221. **Формат служебного файла выбирается по тому, кто его читает.** Читает
|
||||
человек в чужом репозитории через полгода — значит комментарии, значит
|
||||
TOML, значит построчная правка вместо перезаписи.
|
||||
|
||||
@@ -9,10 +9,10 @@
|
||||
|
||||
## Плагины
|
||||
|
||||
Плагина два: **av-dev** — весь процесс, и **av-dev-git** — сообщения коммитов,
|
||||
работающие в любом репозитории. До 13 августа 2026 процесс жил тремя плагинами
|
||||
Плагина два: **av-dev** — весь процесс, и **av-dev-git** — сообщения коммитов.
|
||||
Второй работает в любом репозитории, в том числе не приведённом к канону. До 13 августа 2026 процесс жил тремя плагинами
|
||||
(`av-dev-docs`, `av-dev-tasks`, `av-dev-code`); раскол делался под раздельную
|
||||
установку, она не понадобилась ни разу, и плагины слились — тема 52
|
||||
установку, она не понадобилась ни разу, и плагины слились — тема 64
|
||||
[DECISIONS.md](DECISIONS.md).
|
||||
|
||||
Имя **скилла** несёт префикс прежнего плагина: `doc-`, `task-`, `code-`. Вызов
|
||||
@@ -148,8 +148,8 @@ flowchart TB
|
||||
путь бы разрешился, но короткое имя разрешается в устаревшую проектную копию из
|
||||
`.claude/skills/` — молча и без признаков подмены.
|
||||
|
||||
**Отсутствовать может не плагин, а часть раскладки проекта**: `docs/`, каталог
|
||||
задач, `openspec/`. Тогда вызывающий называет строкой, чего теперь не делает
|
||||
**Отсутствовать может не плагин, а часть раскладки проекта**: `.av-dev.toml`,
|
||||
`docs/`, каталог задач, `openspec/`. Тогда вызывающий называет строкой, чего теперь не делает
|
||||
никто, и работу не останавливает. Правило целиком —
|
||||
[shared/absence.md](av-dev/shared/absence.md): оно нужно почти каждому скиллу, и
|
||||
ни один им не владеет. Там же, в `shared/`, живут язык проектных текстов и
|
||||
@@ -186,8 +186,8 @@ flowchart TB
|
||||
версий](av-dev/skills/doc-canon/references/changelog.md).
|
||||
|
||||
**Версия одна, и живёт она в `.av-dev.toml` в корне репозитория** — вместе с
|
||||
настройками: `[docs] migrations` и секция `[tasks]`, где лежит каталог задач и
|
||||
как названы его части. Версий было две, пока плагинов было три и проект мог
|
||||
настройками: `[docs] migrations` и секция `[tasks]`, которая говорит, где лежит
|
||||
каталог задач и как названы его части. Версий было две, пока плагинов было три и проект мог
|
||||
взять учёт работ без канона документов; теперь плагин один, и второе число
|
||||
означало бы только вопрос, по какому журналу повышать. Прежние
|
||||
`docs/.docs.json` и `<каталог задач>/.tasks.json` не читаются: увидев их,
|
||||
@@ -375,7 +375,7 @@ python3 scripts/frontmatter.py # 0 в порядке, 1 расхождени
|
||||
а не «имя не то»;
|
||||
- **цвет charter'а, не отвечающий его модели.** Цвет кодирует модель, а не роль
|
||||
прохода — раскладка живёт в
|
||||
[review/SKILL.md](av-dev/skills/code-review/SKILL.md),
|
||||
[code-review/SKILL.md](av-dev/skills/code-review/SKILL.md),
|
||||
разделе «Модель по проходу», здесь только её механизация. Держаться вниманием
|
||||
правило не может: цвет ставится один раз при заведении charter'а, а модель
|
||||
потом меняется калибровкой;
|
||||
@@ -419,9 +419,11 @@ python3 scripts/copies.py # 0 сошлось, 1 расхождение, 2 р
|
||||
|
||||
**Копия при этом делается не всегда.** Пока плагинов было три, копия была
|
||||
единственным способом: путь в дерево соседа не разрешался. Внутри одного дерева
|
||||
скилл читает дом **по ссылке**, и дословная копия остаётся там, где текст обязан
|
||||
лежать внутри самого промпта, — в уставах вычитки, где он и есть критерий
|
||||
суждения, — и в скелетах, уезжающих в репозиторий проекта.
|
||||
справочник читается **по ссылке**, и дословная копия остаётся ровно там, где
|
||||
текст обязан лежать **внутри самого промпта**: в уставе агента, где правило и
|
||||
есть критерий суждения; в `SKILL.md`, который целиком и есть промпт скилла, — за
|
||||
ссылкой скилл пошёл бы отдельным чтением, а правило нужно ему в тот момент,
|
||||
когда он решает; и в скелетах, уезжающих в репозиторий проекта.
|
||||
|
||||
**Дом ставится в `shared/` только тогда, когда владельца нет.** У адресов
|
||||
владелец есть: раскладку `docs/` держит `doc-canon`, каталог задач —
|
||||
|
||||
+1
-1
@@ -84,7 +84,7 @@ check` сверяет версию, но не то, что миграционн
|
||||
смотрели» обязательна в докладе `check`, `adopt`, интейка, штурма и всех пяти
|
||||
агентов канона и задач (`doc-consistency`, `doc-code-drift`, `doc-wording`,
|
||||
`task-form`, `task-wording`) — девять мест, и проверить её исполнение некому:
|
||||
приёмщик и исполнитель одно лицо (`groom/SKILL.md`, «Стимулы»). Выродившаяся
|
||||
приёмщик и исполнитель одно лицо (`task-groom/SKILL.md`, «Стимулы»). Выродившаяся
|
||||
строка **хуже отсутствия**: доклад выглядит проверенным.
|
||||
|
||||
Приём не правится: это гипотеза об износе, а не находка, и менять работающее по
|
||||
|
||||
@@ -16,8 +16,9 @@ color: yellow
|
||||
|
||||
Карта домов, по которой ты судишь о правиле 1, — дословная копия канона; дом её
|
||||
`av-dev/skills/doc-canon/references/canon.md`, раздел «Правило единственного
|
||||
дома», и правится она там. Здесь она стоит потому, что ты работаешь в
|
||||
репозитории проекта, где плагина может не быть вовсе.
|
||||
дома», и правится она там. Здесь она стоит потому, что устав — это твой промпт
|
||||
целиком: за ссылкой ты пошёл бы отдельным чтением, а карта нужна тебе в тот
|
||||
момент, когда ты судишь.
|
||||
|
||||
<!-- копия: карта-домов из av-dev/skills/doc-canon/references/canon.md -->
|
||||
| Факт | Дом |
|
||||
@@ -47,7 +48,7 @@ color: yellow
|
||||
|
||||
Корень проекта. Твоё чтение — `docs/**`, `CLAUDE.md`, `openspec/specs/**` и
|
||||
`openspec/config.yaml`. **Каталог задач не твой** — он лежит в `tasks/` (или в
|
||||
`docs/tasks/` на непереехавшем проекте), принадлежит другому плагину и ведётся
|
||||
`docs/tasks/` на непереехавшем проекте), принадлежит другому скиллу и ведётся
|
||||
своим скриптом; не открывай его ни в той форме, ни в другой. Плюс
|
||||
`openspec/changes/archive/`, когда проверяешь ADR: там лежат `design.md`, из
|
||||
которых записи промоутятся. **Источник у ADR бывает и второй — записка
|
||||
|
||||
@@ -31,7 +31,7 @@ color: green
|
||||
|
||||
## Правила
|
||||
|
||||
Дом — `shared/language.md` в репозитории плагинов, и там же объяснено, зачем
|
||||
Дом — `shared/language.md` в репозитории плагина, и там же объяснено, зачем
|
||||
стиль вообще нужен. Здесь только то, что нужно тебе для работы.
|
||||
|
||||
<!-- копия: язык-правила из av-dev/shared/language.md -->
|
||||
|
||||
@@ -39,7 +39,7 @@ color: green
|
||||
|
||||
## Правила
|
||||
|
||||
Дом — `shared/language.md` в репозитории плагинов, и там же объяснено, зачем
|
||||
Дом — `shared/language.md` в репозитории плагина, и там же объяснено, зачем
|
||||
стиль вообще нужен. Здесь только то, что нужно тебе для работы.
|
||||
|
||||
<!-- копия: язык-правила из av-dev/shared/language.md -->
|
||||
@@ -175,7 +175,7 @@ color: green
|
||||
отдельной задачи — самый дешёвый способ сделать беклог нечитаемым тому, кто
|
||||
вернётся к нему через квартал.
|
||||
|
||||
**Правило 9, имя файла.** Кириллицу в слаге и не-kebab-case ловит `tasks.py` —
|
||||
**Правило 9, имя файла.** Кириллицу в слаге и не-kebab-case ловит `tasks.py check` —
|
||||
про них молчи. Твоё — **транслит**, потому что машина проверяет его эвристикой и
|
||||
ловит не всё: `sostoyanie-partii` проходит мимо неё. Находка — готовый
|
||||
английский слаг на замену плюс напоминание, что переименование это перенос
|
||||
|
||||
@@ -15,9 +15,9 @@
|
||||
узнавалась она следом на диске, а не перечнем плагинов. Перечень того, чего
|
||||
может не быть, стал короче на три имени — механика не изменилась вовсе.
|
||||
|
||||
Заведено правило по замеру: к первому расколу оно стояло в пяти местах в пяти
|
||||
Правило завели по подсчёту: к первому расколу оно стояло в пяти местах в пяти
|
||||
редакциях, и три из пяти молчали о том, ради чего написано, — что делать, когда
|
||||
недостающее обнаружено.
|
||||
недостающее нашлось.
|
||||
|
||||
<!-- дом: отсутствие -->
|
||||
|
||||
@@ -26,7 +26,7 @@
|
||||
|
||||
| Чего нет | Как видно | Чего теперь не делает никто |
|
||||
| --- | --- | --- |
|
||||
| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
|
||||
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
|
||||
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Служебный файл проекта `.av-dev.toml`: чтение, запись, конверсия старого.
|
||||
"""Служебный файл проекта `.av-dev.toml`: чтение, запись, узнавание прежних.
|
||||
|
||||
**Это дом.** Файл один на весь плагин, поэтому и читатель у него один: `docs.py`
|
||||
и `tasks.py` берут настройки отсюда, а не каждый своим разбором. Два разбора
|
||||
одного формата — это два дома для одной схемы, и расходятся они молча: первым
|
||||
**Это дом.** Файл один на весь плагин, поэтому и разбор у него один: `docs.py`
|
||||
и `tasks.py` берут настройки отсюда, а не каждый своим кодом. Два разбора одного
|
||||
формата — это два дома для одной схемы, и расходятся они молча: первым
|
||||
разъезжается не значение ключа, а то, что скрипт делает, ключа не увидев.
|
||||
|
||||
Формат TOML выбран ради **комментариев**: файл лежит в чужом репозитории, и
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
канона, для задач и для решений ADR, и хранить его внутри одного из них значило
|
||||
бы отдать общее правило во владение части. Скиллы читают **этот файл** по
|
||||
ссылке; дословные **копии**, помеченные разметкой `copies.py`, уезжают только в
|
||||
charter'ы вычитки — там текст обязан лежать внутри самого промпта, потому что
|
||||
уставы вычитки — там текст обязан лежать внутри самого промпта, потому что
|
||||
именно он и есть критерий суждения. Расхождение ловит гейт коммита, а не
|
||||
внимание.
|
||||
|
||||
|
||||
@@ -7,11 +7,12 @@ description: "Завести и настроить OpenSpec в проекте
|
||||
|
||||
Каталог `openspec/` — **предпосылка конвейера**, а не канона документов. Без него
|
||||
не работают ни `opsx:propose`, ни ревью дизайна, ни `review-specs`: у требований
|
||||
не остаётся дома. Поэтому заводит и настраивает его этот плагин — тот, кто по
|
||||
не остаётся дома. Поэтому заводит и настраивает его этот скилл — тот, кто по
|
||||
OpenSpec и работает.
|
||||
|
||||
Канон документов о файле не высказывается вовсе: `docs.py` его не открывает и об
|
||||
его отсутствии молчит. Проект без конвейера живёт без OpenSpec законно, и
|
||||
его отсутствии молчит. Проект, не ведущий задачи циклом SDD, живёт без OpenSpec
|
||||
законно, и
|
||||
проверять там нечего. За каноном остаётся одно — **единственный дом**: не
|
||||
пересказан ли в `context` документ, у которого есть свой файл. Это суждение, а не
|
||||
форма, и смотрит его агент.
|
||||
@@ -134,7 +135,7 @@ python3 $os form # слепок формы против жив
|
||||
|
||||
| Чего нет | Как видно | Чего теперь не делает никто |
|
||||
| --- | --- | --- |
|
||||
| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
|
||||
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
|
||||
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
|
||||
|
||||
@@ -61,7 +61,7 @@ description: "Взять одну задачу и довести её до за
|
||||
|
||||
| Чего нет | Как видно | Чего теперь не делает никто |
|
||||
| --- | --- | --- |
|
||||
| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
|
||||
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
|
||||
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
|
||||
@@ -87,9 +87,9 @@ description: "Взять одну задачу и довести её до за
|
||||
|
||||
<!-- /копия: отсутствие -->
|
||||
|
||||
Скилл зовёт `av-dev:code-review`, `av-dev:doc-sync` и
|
||||
`av-dev:task-track`. Чем оборачивается отсутствие каждого — на самих шагах и в
|
||||
разделе «Границы».
|
||||
Скилл зовёт `av-dev:code-review`, `av-dev:doc-sync` и `av-dev:task-track` —
|
||||
все трое в этом же плагине и разрешаются всегда. Чем оборачивается отсутствие
|
||||
части раскладки, под которую они работают, сказано на самих шагах сценариев.
|
||||
|
||||
Перед стартом прочитай `CLAUDE.md` проекта и то, на что он ссылается, если ещё
|
||||
не в контексте. Проектные факты, нужные ревью — инварианты, семантика гейта,
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
|
||||
Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел
|
||||
«Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его
|
||||
ход; общее для всех трёх сценариев — вход, обращение к соседним плагинам, правило
|
||||
ход; общее для всех трёх сценариев — вход, чего может не быть, правило
|
||||
записанного вопроса, правило необратимого — живёт в SKILL.md и тут не
|
||||
пересказывается.
|
||||
|
||||
@@ -351,8 +351,8 @@ Change ты не передаёшь — его нет.
|
||||
оставило бы задачу закрытой без следа работы, если шаг 6 упадёт.
|
||||
|
||||
**Закрытие тоже коммитится — вторым коммитом, тут же**, сообщением про учёт:
|
||||
`закрыта задача <slug>`. Плагина нет — ничего не выдумывай: скажи, что учёт
|
||||
остаётся за владельцем, и назови исход.
|
||||
`закрыта задача <slug>`. Каталога задач в проекте нет — ничего не выдумывай:
|
||||
скажи, что учёт остаётся за владельцем, и назови исход.
|
||||
|
||||
## Границы: чего обслуживание не делает
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел
|
||||
«Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его
|
||||
ход; общее для обоих сценариев — вход, обращение к соседним плагинам, правило
|
||||
ход; общее для всех трёх сценариев — вход, чего может не быть, правило
|
||||
необратимого, доклад — живёт в SKILL.md и тут не пересказывается.
|
||||
|
||||
**Разведка кончается своим исходом, а не переходом к коду.** Выбранный способ
|
||||
@@ -20,7 +20,7 @@
|
||||
**OpenSpec этому сценарию не нужен**, и это единственное место скилла, где он не
|
||||
предпосылка. Разведка не заводит change и не пишет дельта-спеки: её артефакты —
|
||||
документы канона и записи каталога задач. Скилл `opsx:explore` полезен и зовётся,
|
||||
когда плагин в проекте есть; не разрешился — разведка идёт чтением документов,
|
||||
когда внешний плагин установлен; не разрешился — разведка идёт чтением документов,
|
||||
кода и внешних источников, и это говорится строкой доклада, а не отменяет
|
||||
работу.
|
||||
|
||||
@@ -28,7 +28,7 @@
|
||||
|
||||
`av-dev:doc-sync` (ответ уезжает в документы канона), `av-dev:task-track`
|
||||
(задачи заводятся и уточняются), `av-dev-git:commit`. Правило обращения к соседям
|
||||
и ветка «вызов не разрешился» — общие, они в [SKILL.md](../SKILL.md).
|
||||
и правило «чего может не быть» — общие, они в [SKILL.md](../SKILL.md).
|
||||
|
||||
**Отсутствие канона бьёт по разведке сильнее, чем по решению**, и сказать об этом
|
||||
строкой мало: без документов у ответа нет дома, и знание осядет в переписке.
|
||||
@@ -37,7 +37,8 @@
|
||||
|
||||
## Что этот сценарий требует от входа
|
||||
|
||||
Вход общий у обоих сценариев (SKILL.md, раздел «Вход»); своего здесь три условия.
|
||||
Вход общий у всех трёх сценариев (SKILL.md, раздел «Вход»); своего здесь три
|
||||
условия.
|
||||
|
||||
**Паспорт читается раньше кода.** Граница домена и «чем проект **не** является»
|
||||
отсекают половину вариантов до того, как их начнут сравнивать, — а сравнение
|
||||
@@ -288,8 +289,8 @@ git и читается диффом, а второй стоп на каждой
|
||||
способ надуть беклог: она порождает идеи быстрее, чем кто-либо успевает их
|
||||
оценивать, а заведённая задача живёт, пока её кто-то не выкинет руками.
|
||||
|
||||
Плагина нет — задачи остаются **списком формулировок в докладе**, и это говорится
|
||||
строкой: учёт работ остаётся за владельцем.
|
||||
Каталога задач в проекте нет — задачи остаются **списком формулировок в
|
||||
докладе**, и это говорится строкой: учёт работ остаётся за владельцем.
|
||||
|
||||
### 6. Вычитка написанного — до гейта, не после
|
||||
|
||||
@@ -322,8 +323,9 @@ git и читается диффом, а второй стоп на каждой
|
||||
Ни один проход ничего не правит: они возвращают готовые формулировки,
|
||||
подставляешь их ты — и уже с подставленными идёшь на гейт.
|
||||
|
||||
Плагина нет — вызов не разрешится: скажи строкой, что написанное не вычитывал
|
||||
никто, и обходного пути не выдумывай.
|
||||
Проходы вычитки — агенты этого же плагина, и разрешаются они всегда. Не
|
||||
разрешились — это поломка установки, а не раскладки проекта: скажи строкой, что
|
||||
написанное не вычитывал никто, и обходного пути не выдумывай.
|
||||
|
||||
### 7. Гейт и коммит
|
||||
|
||||
@@ -361,8 +363,8 @@ git и читается диффом, а второй стоп на каждой
|
||||
учёт, а не про работу: `закрыта задача <slug>`. Правило «одна разведка — один
|
||||
коммит» про работу, а учёт — не работа.
|
||||
|
||||
Плагина в проекте нет — **ничего не выдумывай**: скажи в докладе, что учёт задач
|
||||
остаётся за владельцем, и назови исход.
|
||||
Каталога задач в проекте нет — **ничего не выдумывай**: скажи в докладе, что
|
||||
учёт задач остаётся за владельцем, и назови исход.
|
||||
|
||||
## Доклад разведки
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
Сценарий выбирается развилкой на входе скилла ([SKILL.md](../SKILL.md), раздел
|
||||
«Развилка: какой сценарий») и называется вслух первой репликой. Здесь только его
|
||||
ход; общее для обоих сценариев — вход, обращение к соседним плагинам, правило
|
||||
ход; общее для всех трёх сценариев — вход, чего может не быть, правило
|
||||
записанного вопроса, правило необратимого — живёт в SKILL.md и тут не
|
||||
пересказывается.
|
||||
|
||||
@@ -364,8 +364,8 @@ flowchart TD
|
||||
работу: `закрыта задача <slug>`. Это второй коммит осознанно: правило «одна задача
|
||||
— один осмысленный коммит» про работу, а учёт — не работа.
|
||||
|
||||
Плагина в проекте нет — вызов не разрешится. Тогда **ничего не выдумывай**: скажи
|
||||
в докладе, что учёт задач остаётся за владельцем, и назови исход.
|
||||
Каталога задач в проекте нет — **ничего не выдумывай**: скажи в докладе, что
|
||||
учёт задач остаётся за владельцем, и назови исход.
|
||||
|
||||
## Доклад решения
|
||||
|
||||
@@ -394,8 +394,8 @@ flowchart TD
|
||||
расхождение с одобренным — отдельным пунктом доклада.
|
||||
- **Заведение задач из урожая ревью — не твоя работа.** Отложенные находки
|
||||
отдаются **списком**; превращает их в задачи `av-dev:task-track`, у него на
|
||||
этот вход отдельный сценарий «задачи из ревью и аудита». Плагина нет — урожай
|
||||
остаётся списком в докладе, и это говорится строкой.
|
||||
этот вход отдельный сценарий «задачи из ревью и аудита». Каталога задач в
|
||||
проекте нет — урожай остаётся списком в докладе, и это говорится строкой.
|
||||
- **Способ решения ты не выбираешь.** Он приходит известным: из постановки, из
|
||||
разведки, от человека. Выбор между двумя подходами с разной ценой делается в
|
||||
разведке, у своего чекпоинта, — не по ходу этого сценария.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: code-review
|
||||
description: "Конвейер ревью изменения, устроенный по темам: документ проекта либо заводит тему ревью, либо питает чужую тему источником, либо процессный и в ревью не читается вовсе. Ядро тем — requirements, autotests, conventions, architecture, security, operations; список тем открытый, свои темы проект заводит документом. Разметка задачи идёт один раз, после propose: агент review-scope выводит размер и сложность, из их максимума — метка, и раздаёт темы проходам обеих стадий. Метка правит и ревью дизайна (small — только specs; medium — плюс rubric; large — плюс architecture), и ревью кода (small — гейт, спеки, код, триаж; medium — плюс приёмник тем; large — плюс доказательство: враждебные постановки, эксплуатационный постмортем, архитектурный проход на широком входе). Триаж обязателен всегда. Порядок прогона — граф зависимостей: гейт открывает проходы с мнением, проходы с пометкой «держит машину» идут цепочкой, триаж — единственный сток. Проектная специфика приходит из документов канона проекта. Вызывается из скилла resolve — двумя стадиями: ревью дизайна до кода и ревью кода после apply. Третий вызов идёт от сценария обслуживания: без change и без метки, фиксированным планом (autotests, operations, плюс conventions, если тронут код), разметчик при этом не запускается."
|
||||
description: "Конвейер ревью изменения, устроенный по темам: документ проекта либо заводит тему ревью, либо питает чужую тему источником, либо процессный и в ревью не читается вовсе. Ядро тем — requirements, autotests, conventions, architecture, security, operations; список тем открытый, свои темы проект заводит документом. Разметка задачи идёт один раз, после propose: агент review-scope выводит размер и сложность, из их максимума — метка, и раздаёт темы проходам обеих стадий. Метка правит и ревью дизайна (small — только specs; medium — плюс rubric; large — плюс architecture), и ревью кода (small — гейт, спеки, код, триаж; medium — плюс приёмник тем; large — плюс доказательство: враждебные постановки, эксплуатационный постмортем, архитектурный проход на широком входе). Триаж обязателен всегда. Порядок прогона — граф зависимостей: гейт открывает проходы с мнением, проходы с пометкой «держит машину» идут цепочкой, триаж — единственный сток. Проектная специфика приходит из документов канона проекта. Вызывается из скилла av-dev:code-resolve — двумя стадиями: ревью дизайна до кода и ревью кода после apply. Третий вызов идёт от сценария обслуживания: без change и без метки, фиксированным планом (autotests, operations, плюс conventions, если тронут код), разметчик при этом не запускается."
|
||||
---
|
||||
|
||||
# Конвейер ревью
|
||||
@@ -78,7 +78,7 @@ description: "Конвейер ревью изменения, устроенны
|
||||
|
||||
| Чего нет | Как видно | Чего теперь не делает никто |
|
||||
| --- | --- | --- |
|
||||
| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
|
||||
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
|
||||
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
|
||||
@@ -1002,8 +1002,8 @@ flowchart TD
|
||||
какой change). Заведение задач принадлежит `av-dev:task-track` — зови его со
|
||||
списком урожая, у него на этот вход отдельный сценарий «задачи из ревью и
|
||||
аудита»: свой формат, кластеризация по причине, дедуп против беклога и
|
||||
кладбища. Плагина нет — урожай остаётся списком в отчёте, и это говорится
|
||||
строкой доклада: задачи из него не заведёт никто. Мелочь класса `nit`
|
||||
кладбища. Каталога задач в проекте нет — урожай остаётся списком в отчёте, и
|
||||
это говорится строкой доклада: задачи из него не заведёт никто. Мелочь класса `nit`
|
||||
идёт в урожай одной пачкой, а не записью на находку.
|
||||
- `Promote candidates` — по процедуре [references/promote.md](references/promote.md):
|
||||
находка → конвенция → правило линтера → **удаление формулировки из конвенций**.
|
||||
|
||||
@@ -55,7 +55,7 @@ stateDiagram-v2
|
||||
поведения библиотеки и драйвера**, — и находка, воспроизведённая числом, отменила
|
||||
решение, принятое по ощущению.
|
||||
|
||||
## Состав проходов принадлежит плагину, а не проекту
|
||||
## Состав проходов принадлежит скиллу, а не проекту
|
||||
|
||||
Проходы общие. Проект не может удалить проход — он может **не звать** его, и
|
||||
тогда это идёт строкой «не запускался» в границы покрытия, как любой другой
|
||||
@@ -67,7 +67,7 @@ stateDiagram-v2
|
||||
- **правка charter'а — правка для всех проектов.** Прежде чем сужать
|
||||
формулировку под свою боль, проверь, не место ли ей в документах проекта: предмет проверки
|
||||
живёт там, метод — в charter'е;
|
||||
- **удаление прохода из плагина требует замера на двух проектах**, а не на одном:
|
||||
- **удаление прохода из конвейера требует замера на двух проектах**, а не на одном:
|
||||
класс, не всплывший здесь, мог быть единственным работающим там.
|
||||
|
||||
## Пробы дефектов по проходам
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: doc-canon
|
||||
description: Привести проект к канону документов av-dev и держать его в соответствии — три операции одной машиной сравнения. check — что разошлось с текущей версией канона; adopt — перевод проекта из любой прежней раскладки (docs/specs, drafts, backlog, BRIEF.md, review-brief) в канон с переносом файлов; upgrade — повышение проекта с версии канона N до текущей по журналу версий. Использовать, когда просят проверить документацию проекта, перевести проект на канон, обновить его под новую версию канона или когда пришли в старый проект и надо понять, что в нём не так. Заведение нового проекта с нуля — скилл init.
|
||||
description: Привести проект к канону документов av-dev и держать его в соответствии — три операции одной машиной сравнения. check — что разошлось с текущей версией канона; adopt — перевод проекта из любой прежней раскладки (docs/specs, drafts, backlog, BRIEF.md, review-brief) в канон с переносом файлов; upgrade — повышение проекта с версии канона N до текущей по журналу версий. Использовать, когда просят проверить документацию проекта, перевести проект на канон, обновить его под новую версию канона или когда пришли в старый проект и надо понять, что в нём не так. Заведение нового проекта с нуля — скилл av-dev:doc-init.
|
||||
---
|
||||
|
||||
# Приведение проекта к канону
|
||||
@@ -48,7 +48,8 @@ description: Привести проект к канону документов
|
||||
ds="$CLAUDE_PLUGIN_ROOT/skills/doc-canon/scripts/docs.py"
|
||||
|
||||
python3 $ds check --dir <корень> [--base <rev>] # раскладка, ссылки, версия, сверки
|
||||
python3 $ds version --dir <корень> # версия канона скрипта и проекта
|
||||
python3 $ds version --dir <корень> # версия раскладки: скрипта и проекта
|
||||
python3 $ds bump --dir <корень> # поднять версию проекта до версии скрипта
|
||||
```
|
||||
|
||||
**Формы `openspec/config.yaml` здесь больше нет.** Каталог принадлежит конвейеру,
|
||||
@@ -103,7 +104,7 @@ capability: незаполненный канон это переходное с
|
||||
|
||||
| Чего нет | Как видно | Чего теперь не делает никто |
|
||||
| --- | --- | --- |
|
||||
| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
|
||||
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
|
||||
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
|
||||
@@ -141,7 +142,7 @@ capability: незаполненный канон это переходное с
|
||||
форма», `doc-healthcheck` — на «не разошлись ли утверждения».
|
||||
3. Доклад: вывод скрипта строкой исхода и **граница покрытия** — что смотрели и
|
||||
чего не смотрели. Если суждение здесь нужно, скажи это строкой и предложи
|
||||
`healthcheck`, а не зови агентов сам.
|
||||
`doc-healthcheck`, а не зови агентов сам.
|
||||
|
||||
Дрейф раскладки чинится переносом; смысловые находки — это либо правка
|
||||
документа, либо задача, если работы больше чем на абзац.
|
||||
@@ -192,8 +193,9 @@ capability), `openspec/config.yaml`.
|
||||
Skill `av-dev:code-openspec`**. Каталог принадлежит конвейеру, и команда
|
||||
заведения с формой файла живут там. Пересказ инвариантов, конвенций и правил
|
||||
ревью из `context` вычисти ссылкой на дом — на переводимом проекте он там
|
||||
почти наверняка есть. Вызов не разрешился — `docs.py` о каталоге тогда тоже
|
||||
молчит, и форму `config.yaml` не проверяет никто; скажи это строкой;
|
||||
почти наверняка есть. Проект решил жить без OpenSpec — `docs.py` о каталоге
|
||||
тогда тоже молчит, и форму `config.yaml` не проверяет никто; скажи это
|
||||
строкой;
|
||||
4. переносы содержимого;
|
||||
5. каталог задач — **вызови скилл `av-dev:task-track`**, сценарий адаптации: он
|
||||
владеет форматом задач. Он же переименует транслитные слаги в английские и
|
||||
@@ -274,8 +276,9 @@ capability), `openspec/config.yaml`.
|
||||
3. Иначе иди по [changelog.md](references/changelog.md) снизу вверх от версии
|
||||
проекта до текущей и делай названное в каждой записи. Записи независимы и
|
||||
применяются по порядку.
|
||||
4. Подними `version` в `.av-dev.toml` до текущей — правь **строку**, а не
|
||||
переписывай файл: комментарии в нём принадлежат проекту.
|
||||
4. Подними версию — `docs.py bump`. Он правит **строку**, а не переписывает
|
||||
файл: комментарии в нём принадлежат проекту. Последним шагом, потому что
|
||||
число объявляет пройденными записи журнала.
|
||||
5. `docs.py check`.
|
||||
6. **Позови судей** — Skill `av-dev:doc-healthcheck`.
|
||||
7. **Позови вычитку** — агент `doc-wording`, но **только по тем документам,
|
||||
@@ -295,7 +298,7 @@ capability), `openspec/config.yaml`.
|
||||
|
||||
**Шаг 6 обязателен, и вот почему.** `check` сверяет **число** в `.av-dev.toml`
|
||||
с версией скрипта — и только его. Применена ли запись журнала **по существу**,
|
||||
он не знает: проект несёт `version = 6` и может не иметь того, чего требовала любая
|
||||
он не знает: проект несёт `version` текущей версии и может не иметь того, чего требовала любая
|
||||
из пройденных версий. Записи применяются руками (переименовать секцию, проставить
|
||||
типы, дописать раздел каждому `fix`), а ручной проход по нескольким записям
|
||||
подряд — ровно то место, где половина шага делается и забывается. Судьи и есть
|
||||
|
||||
@@ -347,10 +347,10 @@ kebab-case.** Причина не эстетическая: имя файла с
|
||||
**Каталог задач канону не принадлежит.** Его ведёт скилл `task-track` — своим
|
||||
скриптом и своими проверками; где каталог лежит и как названы его части, говорит
|
||||
секция `[tasks]` в `.av-dev.toml`. Версия там одна на всю раскладку: канон и
|
||||
каталог задач двигаются вместе, потому что двигает их один плагин.
|
||||
каталог задач двигаются вместе, потому что ведёт их один плагин.
|
||||
Канон **резервирует место** в `docs/` и внутрь не смотрит:
|
||||
`docs.py` каталог не открывает, его отсутствия не считает дрейфом и согласованность
|
||||
задач не проверяет. Проект, поставивший только канон документов, задач не ведёт
|
||||
задач не проверяет. Проект, не заведший каталог задач, их не ведёт
|
||||
вовсе, и отказом это быть не может.
|
||||
|
||||
Раскладку, форму записи и команды держит скилл `av-dev:task-track`. Ниже — то,
|
||||
@@ -379,9 +379,8 @@ kebab-case.** Причина не эстетическая: имя файла с
|
||||
|
||||
**Схемы записи здесь нет намеренно.** Какие разделы тип требует, нужна ли ему
|
||||
цель и берётся ли он в работу — скилл `av-dev:task-track`, раздел «Тип
|
||||
записи», подробно — по файлу на тип в его `references/task-<тип>.md`. Ссылки в
|
||||
дерево того плагина здесь нет намеренно: он ставится отдельно, и путь наружу
|
||||
разрешился бы не всегда. Канон фиксирует **словарь**, потому что
|
||||
записи», подробно — по файлу на тип в его `references/task-<тип>.md`. Канон
|
||||
фиксирует **словарь**, потому что
|
||||
от него зависит, читается ли проект как продукт; схема — механика ведения задач,
|
||||
и второй её экземпляр разошёлся бы с первым (он и разошёлся: канон успел
|
||||
объявить цель у `fix` запрещённой, хотя она там необязательна).
|
||||
@@ -525,7 +524,7 @@ kebab-case.** Причина не эстетическая: имя файла с
|
||||
разрез, что между `task-form` и `task-wording`.
|
||||
|
||||
**Зовутся оба одинаково и одним скиллом — `av-dev:doc-healthcheck`, на весь
|
||||
канон разом; шагом `adopt` и шагом `upgrade` его зовёт `canon`.** Не на синке
|
||||
канон разом; шагом `adopt` и шагом `upgrade` его зовёт `doc-canon`.** Не на синке
|
||||
документации: `doc-consistency` на
|
||||
`opus` по каждой сделанной задаче не окупается, а расхождение между двумя документами по
|
||||
определению требует двух, и на большинстве задач синк правит один. Пачка,
|
||||
|
||||
@@ -646,7 +646,7 @@ ADR объясняет прошлое решение, а не предъявля
|
||||
5. **Заголовки секций — с прописной, после заголовка пустая строка**, во всех
|
||||
индексах. Написание канонических секций и отбивку правит `check --fix`; он
|
||||
же сводит написание секции в мете файла с заголовком индекса.
|
||||
6. **Язык проектных текстов** — [language.md](language.md), общий дом для
|
||||
6. **Язык проектных текстов** — [language.md](../../../shared/language.md), общий дом для
|
||||
документов канона, задач, решений ADR и записок разведки: информационный
|
||||
стиль (глагол вместо отглагольного существительного, активный залог, факт
|
||||
вместо оценки, стоп-слова, параллельность), таблицы англицизмов и жаргона и
|
||||
@@ -711,7 +711,7 @@ ADR объясняет прошлое решение, а не предъявля
|
||||
11. Переписать заголовки задач в форму действия — по мере того, как задача
|
||||
попадает в работу, а не «заодно»: `check` печатает их число, а `task-form`
|
||||
предложит формулировки на замену пачкой.
|
||||
12. Прочитать [language.md](language.md) — и **ничего не переписывать задним
|
||||
12. Прочитать [language.md](../../../shared/language.md) — и **ничего не переписывать задним
|
||||
числом**. Правила языка применяются к тому, что пишется и правится сейчас;
|
||||
сплошная вычитка старых документов стоит дороже, чем даёт.
|
||||
13. `docs/.pm.json`: `"canon": 3`.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Журнал версий формата задач до слияния плагинов
|
||||
|
||||
**Журнал закрыт.** У каталога задач была своя версия, пока плагином его ведал
|
||||
`av-dev-tasks` и ставился он отдельно. Версия теперь одна на всю раскладку —
|
||||
**Журнал закрыт.** У каталога задач была своя версия, пока его вёл отдельный
|
||||
плагин `av-dev-tasks`. Версия теперь одна на всю раскладку —
|
||||
действующий журнал [changelog.md](changelog.md), и переезд числа описан его
|
||||
записью 1.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Журнал версий раскладки
|
||||
|
||||
Одна запись на версию. Проект знает свою версию из ключа `version` в
|
||||
`.av-dev.toml`; `canon upgrade` идёт по записям снизу вверх от версии проекта до
|
||||
текущей и делает то, что в них названо.
|
||||
`.av-dev.toml`; операция `upgrade` скилла `av-dev:doc-canon` идёт по записям
|
||||
снизу вверх от версии проекта до текущей и делает то, что в них названо.
|
||||
|
||||
Правило записи: **что добавилось, что переехало, что удалено, что сделать
|
||||
проекту**. Без последнего пункта запись бесполезна — по ней и работает
|
||||
@@ -26,9 +26,9 @@
|
||||
|
||||
Три плагина — `av-dev-docs`, `av-dev-tasks` и `av-dev-code` — слились в один,
|
||||
`av-dev`. Раскол делался под раздельную установку: проект мог взять учёт работ
|
||||
без документов канона или конвейер без обоих. Практикой посылка не подтвердилась
|
||||
— подмножество не понадобилось ни разу, — а платился раскол помеченными копиями
|
||||
общих правил и ветками деградации на каждый вызов соседа.
|
||||
без документов канона или конвейер без обоих. Практика посылку не подтвердила —
|
||||
подмножество не понадобилось ни разу, — а платился раскол помеченными копиями
|
||||
общих правил и веткой «плагина нет» на каждый вызов соседа.
|
||||
|
||||
**Что переехало в проекте.** Служебных файла было два, стал один:
|
||||
|
||||
@@ -74,7 +74,9 @@
|
||||
6. **Поправить свои вызовы скиллов** — в `CLAUDE.md`, в `Taskfile`, в записях
|
||||
задач: короткое имя разрешится в проектную копию, а прежнее полное не
|
||||
разрешится вовсе.
|
||||
7. `docs.py check` и `tasks.py check --dir <каталог задач>` — до отсутствия
|
||||
7. **Поднять версию** — `docs.py bump`. Последним шагом: число объявляет
|
||||
пройденными шаги журнала, и раньше времени поднятое врёт.
|
||||
8. `docs.py check` и `tasks.py check --dir <каталог задач>` — до отсутствия
|
||||
дрейфа.
|
||||
|
||||
**Чего делать не надо.** Переписывать прошлые записи журналов под новые имена.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Скелеты документов канона
|
||||
|
||||
Что кладут `init` и `canon adopt` в незаполненный слот. Правило одно:
|
||||
Что кладут `init` и `doc-canon adopt` в незаполненный слот. Правило одно:
|
||||
**честная информативная строка вместо заглушки**. Проход читает строку как факт;
|
||||
`<!-- заполнить: … -->` он читает как пробел, и `docs.py check` о таком
|
||||
плейсхолдере напоминает.
|
||||
@@ -428,9 +428,10 @@ severity стоит здесь, а не выводится каждым прох
|
||||
|
||||
## `openspec/config.yaml`
|
||||
|
||||
**Образец переехал.** Файл заводит и заполняет конвейер — скилл
|
||||
**Образец переехал.** Файл заводит и заполняет скилл
|
||||
`av-dev:code-openspec`, — потому что по OpenSpec работает он, а не канон
|
||||
документов. Проект без конвейера каталога `openspec/` не имеет вовсе, и образец
|
||||
документов. Проект, не ведущий задачи циклом SDD, каталога `openspec/` не имеет
|
||||
вовсе, и образец
|
||||
файла, которого у него нет, в скелетах канона лежал бы мёртвым грузом.
|
||||
|
||||
**Форму не проверяет и `docs.py`** — с канона 10 он о файле молчит вовсе.
|
||||
@@ -455,7 +456,7 @@ dir = "tasks"
|
||||
```
|
||||
|
||||
`<текущая версия>` подставляет `init` или `adopt`, целым числом; берётся она из
|
||||
`docs.py version` (строка «раскладка скрипта»), а не из памяти. Литерал здесь
|
||||
`docs.py version` (строка «версия раскладки, скрипт»), а не из памяти. Литерал здесь
|
||||
протухает при каждом повышении, поэтому его тут и нет: незамещённый плейсхолдер
|
||||
ломает разбор TOML громко, а отставшее число дало бы дрейф молча.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: doc-healthcheck
|
||||
description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без провенанса) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию канона проверяет скилл canon, язык документов — агент doc-wording."
|
||||
description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без провенанса) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:doc-canon, язык документов — агент doc-wording."
|
||||
---
|
||||
|
||||
# Здоровье документации
|
||||
@@ -47,7 +47,7 @@ check` и его скрипт; здесь начинается там, где к
|
||||
|
||||
| Чего нет | Как видно | Чего теперь не делает никто |
|
||||
| --- | --- | --- |
|
||||
| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
|
||||
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
|
||||
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
|
||||
@@ -116,8 +116,8 @@ check` и его скрипт; здесь начинается там, где к
|
||||
не с чем, и откладывание превращает её в задачу дороже самой правки.
|
||||
2. **Работа больше чем на абзац** — задача типа `chore`. Заводит её **не этот
|
||||
скилл**: вызови Skill `av-dev:task-track`, у него свой формат, дедупликация
|
||||
против беклога и кладбища. Плагина нет — отдай списком в докладе и скажи это
|
||||
строкой.
|
||||
против беклога и кладбища. Каталога задач в проекте нет — отдай списком в
|
||||
докладе и скажи это строкой.
|
||||
3. **Не находка** — агент ошибся, документ прав. Скажи это прямо: неразобранная
|
||||
находка и отклонённая различаются, и вторая экономит время на следующем
|
||||
прогоне. Класс ошибок, который повторяется, идёт в `docs/review.*`, раздел
|
||||
@@ -136,11 +136,11 @@ check` и его скрипт; здесь начинается там, где к
|
||||
|
||||
## Чего этот скилл не делает
|
||||
|
||||
- **Не проверяет раскладку, версию и ссылки** — это `canon check`, там машина.
|
||||
- **Не проверяет раскладку, версию и ссылки** — это `doc-canon check`, там машина.
|
||||
- **Не судит язык** документов: залог, англицизмы, жаргон, термин без дома — это
|
||||
агент `doc-wording`, и зовут его отдельно, по пачке правленных документов.
|
||||
Звонящие у него названные — последний шаг синка в `av-dev:doc-sync`, шаг 9
|
||||
`av-dev:doc-init` и шаг вычитки в обоих режимах `canon`, — просто ни один из
|
||||
`av-dev:doc-init` и шаг вычитки в обоих режимах `doc-canon`, — просто ни один из
|
||||
них не здесь. У него другой ритм: он нужен там, где текст только что писали, а
|
||||
не там, где он год лежал. Оркестровать его нечем — он один и работает по
|
||||
названному списку.
|
||||
|
||||
@@ -34,8 +34,9 @@ description: "Завести новый проект — сессия вопро
|
||||
|
||||
**`tasks/ROADMAP.md` в таблице нет намеренно.** Первые цели `init` собирает
|
||||
интервью (блок 6), но записывает их не он: каталогом задач и формой целей владеет
|
||||
`av-dev:task-track`, и это шаг 7. Плагина нет — цели остаются списком в докладе,
|
||||
роадмапа в проекте не появляется, и это говорится строкой.
|
||||
`av-dev:task-track`, и это шаг 7. Человек от каталога задач отказался — цели
|
||||
остаются списком в докладе, роадмапа в проекте не появляется, и это говорится
|
||||
строкой.
|
||||
|
||||
## Порядок интервью — зависимость, а не удобство
|
||||
|
||||
@@ -84,7 +85,7 @@ description: "Завести новый проект — сессия вопро
|
||||
|
||||
| Чего нет | Как видно | Чего теперь не делает никто |
|
||||
| --- | --- | --- |
|
||||
| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
|
||||
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
|
||||
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
|
||||
@@ -110,8 +111,9 @@ description: "Завести новый проект — сессия вопро
|
||||
|
||||
<!-- /копия: отсутствие -->
|
||||
|
||||
Чем оборачивается отсутствие каждого — на самих шагах 3 и 7. Заведение проекта
|
||||
из-за этого не останавливается: проект без конвейера и без учёта задач законен.
|
||||
Оба скилла в этом же плагине и разрешаются всегда; чем оборачивается отказ от
|
||||
того, что они заводят, — на самих шагах 3 и 7. Заведение проекта из-за этого не
|
||||
останавливается: проект без OpenSpec и без учёта задач законен.
|
||||
|
||||
## Порядок работы
|
||||
|
||||
@@ -123,8 +125,9 @@ description: "Завести новый проект — сессия вопро
|
||||
ни сверка требований. Каталог принадлежит конвейеру, а не канону, поэтому
|
||||
здесь только вызов — ни команды, ни формы файла `init` не знает.
|
||||
|
||||
**Вызов не разрешился** — проект без конвейера живёт без OpenSpec законно:
|
||||
строка доклада, и дальше; `docs.py check` о каталоге тоже промолчит.
|
||||
**Человек от OpenSpec отказался** — проект живёт без него законно: строка
|
||||
доклада, и дальше; `docs.py check` о каталоге тоже промолчит. Цикл SDD в
|
||||
таком проекте не запускается, и это надо назвать, а не обойти.
|
||||
4. Заведи `.av-dev.toml` в корне с текущей версией раскладки — число берётся из
|
||||
`docs.py version`, а не из памяти.
|
||||
5. Напиши заполняемые документы. **Бриф переезжает в `passport.md`** и
|
||||
@@ -149,7 +152,7 @@ description: "Завести новый проект — сессия вопро
|
||||
## Что дальше
|
||||
|
||||
- Содержимое канона по ходу разработки ведёт скилл `doc-sync`.
|
||||
- Раскладку проверяет `canon check`.
|
||||
- Раскладку проверяет `doc-canon check`.
|
||||
- Первую задачу берёт конвейер проекта; `architecture.md` и `conventions/`
|
||||
наполняются его шагом синка, а не заранее.
|
||||
|
||||
@@ -157,6 +160,6 @@ description: "Завести новый проект — сессия вопро
|
||||
|
||||
- **Не проектирует систему.** Архитектура выводится из кода, а не наоборот.
|
||||
- **Не пишет код** и не заводит сборку.
|
||||
- **Не переводит существующий проект** — это `canon adopt`. Признак: в
|
||||
- **Не переводит существующий проект** — это `doc-canon adopt`. Признак: в
|
||||
репозитории уже есть документация или беклог в какой-то раскладке.
|
||||
- **Не решает за человека**, что важно: цель, границы и периметр — его ответы.
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: doc-sync
|
||||
description: Вести содержимое документов канона по ходу разработки — синк после сделанной задачи с построчным отчётом по каждому документу, заведение ADR промоутом из архивного design.md или из записки разведки, запись наблюдения в research, запись дефекта и настройки конвейера в review.md, чистка architecture.md от поведения с маркерами долга. Использовать, когда задача сделана и надо обновить документацию, когда просят завести ADR или записать решение, занести находку о внешних данных, записать проскочивший дефект, разгрузить разросшуюся архитектуру. Раскладку и соответствие канону проверяет скилл canon.
|
||||
description: Вести содержимое документов канона по ходу разработки — синк после сделанной задачи с построчным отчётом по каждому документу, заведение ADR промоутом из архивного design.md или из записки разведки, запись наблюдения в research, запись дефекта и настройки конвейера в review.md, чистка architecture.md от поведения с маркерами долга. Использовать, когда задача сделана и надо обновить документацию, когда просят завести ADR или записать решение, занести находку о внешних данных, записать проскочивший дефект, разгрузить разросшуюся архитектуру. Раскладку и соответствие канону проверяет скилл av-dev:doc-canon.
|
||||
---
|
||||
|
||||
# Ведение содержимого канона
|
||||
|
||||
Скилл владеет **содержимым** документов канона; раскладкой владеет `canon`.
|
||||
Скилл владеет **содержимым** документов канона; раскладкой владеет `doc-canon`.
|
||||
Определение канона и роли документов — [канон](../doc-canon/references/canon.md),
|
||||
здесь не пересказывается.
|
||||
|
||||
@@ -158,7 +158,7 @@ description: Вести содержимое документов канона
|
||||
|
||||
| Чего нет | Как видно | Чего теперь не делает никто |
|
||||
| --- | --- | --- |
|
||||
| раскладка av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
|
||||
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
|
||||
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
|
||||
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |
|
||||
@@ -184,8 +184,8 @@ description: Вести содержимое документов канона
|
||||
|
||||
<!-- /копия: отсутствие -->
|
||||
|
||||
Чем оборачивается отсутствие конвейера — в каждом из двух разделов отдельно: без
|
||||
него работа не отменяется, отменяется только его процедура.
|
||||
Здесь это значит: документов канона может не быть вовсе — тогда синка нет, и
|
||||
это исход, а не повод раскладывать документы по своему усмотрению.
|
||||
|
||||
## Запись в `review.md`
|
||||
|
||||
@@ -217,8 +217,8 @@ av-dev:code-review`, его `references/review-journal.md`.
|
||||
|
||||
## Чего этот скилл не делает
|
||||
|
||||
- **Не проверяет раскладку** — это `canon`.
|
||||
- **Не заводит недостающие документы** — их скелет кладёт `canon adopt` или
|
||||
`init`.
|
||||
- **Не проверяет раскладку** — это `doc-canon`.
|
||||
- **Не заводит недостающие документы** — их скелет кладёт `doc-canon adopt` или
|
||||
`doc-init`.
|
||||
- **Не сочиняет содержание.** Нечего записать — так и пишется, честной строкой.
|
||||
- **Не переоформляет документы «заодно»**: правится то, чего коснулась работа.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: task-groom
|
||||
description: "Груминг беклога — интерактивный разбор, отвечающий на два вопроса: что сейчас самое важное и что перестало быть важным. Ответ записывается порядком строк в беклоге: первая строка — то, что делают следующим. Разбирает накопившиеся вопросы, переоценивает задачи порциями по 5–8 (сделано попутно, отменено решением, слилось с соседней, подешевело, разрослось, стало сырьём), закрывает отжившее с причиной и расставляет очередь. Использовать, когда просят разобрать беклог, расставить приоритеты, решить «что делать дальше», провести груминг или переоценку, а также когда вернулись к проекту после перерыва и надо понять, где остановились. Формат и содержимое записей — скилл tasks; выполнение задачи — конвейер проекта."
|
||||
description: "Груминг беклога — интерактивный разбор, отвечающий на два вопроса: что сейчас самое важное и что перестало быть важным. Ответ записывается порядком строк в беклоге: первая строка — то, что делают следующим. Разбирает накопившиеся вопросы, переоценивает задачи порциями по 5–8 (сделано попутно, отменено решением, слилось с соседней, подешевело, разрослось, стало сырьём), закрывает отжившее с причиной и расставляет очередь. Использовать, когда просят разобрать беклог, расставить приоритеты, решить «что делать дальше», провести груминг или переоценку, а также когда вернулись к проекту после перерыва и надо понять, где остановились. Формат и содержимое записей — скилл av-dev:task-track; выполнение задачи — конвейер проекта."
|
||||
---
|
||||
|
||||
# Груминг: что важно, что перестало
|
||||
@@ -29,7 +29,7 @@ description: "Груминг беклога — интерактивный ра
|
||||
1. **Порядок назначает человек, машина его не выводит.** Ни давность, ни тип, ни
|
||||
число задач под целью приоритетом не являются. Единственное место в очереди,
|
||||
назначенное не человеком, — конец секции у сырья, и оно из очереди изъято
|
||||
(`tasks`, правило 4).
|
||||
(`task-track`, правило 4).
|
||||
2. **Порция важнее охвата.** Тридцать задач за заход — это усталость и
|
||||
штамповка: последние десять получат «оставить» не потому, что живы, а потому,
|
||||
что разбор затянулся. Лучше две честные порции, чем один полный проход.
|
||||
@@ -164,8 +164,8 @@ flowchart TD
|
||||
Но повод назвать это здесь есть: беклог и документы протухают от одного и того
|
||||
же — от сделанной работы. Пришёл на груминг и видишь, что с прошлого раза сделан
|
||||
десяток задач, — скажи строкой, что документы стоит сверить
|
||||
(`av-dev:doc-healthcheck`), и иди дальше. Плагина в проекте нет — сверять нечем,
|
||||
и это тоже строка.
|
||||
(`av-dev:doc-healthcheck`), и иди дальше. Документов канона в проекте нет —
|
||||
сверять нечем, и это тоже строка.
|
||||
|
||||
## Интерактив
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: task-track
|
||||
description: Ведение задач и целей как каталога markdown-файлов (одна запись = один файл в items/ + строка в одном из индексов). У каждой записи есть тип (goal, feature, fix, chore, research), и тип решает, каких разделов она требует и что с ней можно делать. Заведение записи из диалога, разбор находок аудита/ревью, декомпозиция на независимо полезные части, штурм сырья, гигиена полей и проверка согласованности индексов. Использовать, когда просят добавить задачу/идею/цель, превратить находки ревью в задачи, разбить задачу, проработать идею, поправить формат или проверить беклог. Он же повышает каталог до текущей версии формата по своему журналу версий, когда tasks.py check говорит, что каталог отстал. Расстановка приоритетов и разбор накопившегося — скилл groom. Не реализует задачи — этим занимается скилл решения задачи.
|
||||
description: Ведение задач и целей как каталога markdown-файлов (одна запись = один файл в items/ + строка в одном из индексов). У каждой записи есть тип (goal, feature, fix, chore, research), и тип решает, каких разделов она требует и что с ней можно делать. Заведение записи из диалога, разбор находок аудита/ревью, декомпозиция на независимо полезные части, штурм сырья, гигиена полей и проверка согласованности индексов. Использовать, когда просят добавить задачу/идею/цель, превратить находки ревью в задачи, разбить задачу, проработать идею, поправить формат или проверить беклог. Каталог отстал от версии раскладки — это скажет tasks.py check, а повышает проект скилл av-dev:doc-canon по общему журналу версий. Расстановка приоритетов и разбор накопившегося — скилл av-dev:task-groom. Не реализует задачи — этим занимается скилл решения задачи.
|
||||
---
|
||||
|
||||
# Задачи
|
||||
@@ -223,11 +223,10 @@ stateDiagram-v2
|
||||
|
||||
**Сопровождение и эксплуатация — целое и часть**, а не синонимы, и та же тема
|
||||
живёт ещё в двух местах: разделе «Эксплуатация» в `architecture.md` и теме ревью
|
||||
`operations`. Словарь у всех трёх общий, дом у него один — `shared/operations.md`
|
||||
в репозитории плагинов, — а здесь лежит дословная копия:
|
||||
[shared/operations.md](../../shared/operations.md). Пересказывать его своими
|
||||
словами нельзя: три перечня «чем держат проект» уже разъезжались на «метриках и
|
||||
логах» против «мониторинга».
|
||||
`operations`. Словарь у всех трёх общий, и дом у него один:
|
||||
[shared/operations.md](../../shared/operations.md) — читается по ссылке.
|
||||
Пересказывать его своими словами нельзя: три перечня «чем держат проект» уже
|
||||
разъезжались на «метриках и логах» против «мониторинга».
|
||||
|
||||
Секция выбирается так: очередь значима и обоснована прозой — `Запланировано`;
|
||||
тянется долго и очереди не имеет — `Направления`; не про приложение, а про то,
|
||||
@@ -354,11 +353,10 @@ stateDiagram-v2
|
||||
**Предметно, но без усложнения.** Текст задачи читает человек, который решает,
|
||||
брать её или нет, и делает это по строке индекса и одному экрану тела.
|
||||
|
||||
Язык — общий для всех проектных текстов, и дом у него один,
|
||||
`shared/language.md` в репозитории плагинов; здесь лежит дословная копия:
|
||||
[shared/language.md](../../shared/language.md) (информационный стиль,
|
||||
Язык — общий для всех проектных текстов, и дом у него один:
|
||||
[shared/language.md](../../shared/language.md) — информационный стиль,
|
||||
применённый к задачам и документам канона; там же таблицы англицизмов и жаргона
|
||||
и то, что из стиля отброшено намеренно). Задаче он даёт четыре требования,
|
||||
и то, что из стиля отброшено намеренно. Задаче он даёт четыре требования,
|
||||
которые нарушаются чаще прочих:
|
||||
|
||||
- **глагол вместо отглагольного существительного**: «обработчик не проверяет
|
||||
@@ -701,9 +699,9 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
|
||||
> («закрой задачу `<слаг>`, реализована»). Скилл разрешает свой
|
||||
> `$CLAUDE_PLUGIN_ROOT` сам. Путь наружу не выносится вовсе.
|
||||
|
||||
Плагина в проекте нет — вызов не разрешится, и вызывающий **не выдумывает путь и
|
||||
не правит индекс руками**, а сообщает в докладе, что учёт задач остаётся за
|
||||
владельцем.
|
||||
Каталога задач в проекте нет — вызывающий **не выдумывает путь и не правит
|
||||
индекс руками**, а сообщает в докладе, что учёт остаётся за владельцем. Скилл
|
||||
при этом разрешится: он в том же плагине, что и вызывающий.
|
||||
|
||||
## Слоты проекта
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
**Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл
|
||||
`av-dev:doc-canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что
|
||||
форматом задач владеет `tasks`, а не `canon`. Отдельно сценарий вызывается,
|
||||
форматом задач владеет `task-track`, а не `doc-canon`. Отдельно сценарий вызывается,
|
||||
когда переводить надо **только** задачи.
|
||||
|
||||
Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`,
|
||||
|
||||
@@ -66,8 +66,8 @@
|
||||
у работы, не меняющей поведения, дельта-спек нет по построению. Тип записи там
|
||||
только **предлагает** сценарий, а подтверждает его отсутствие дельт: разошлись —
|
||||
работа останавливается, и это тот самый случай, когда тип, оставшийся от первой
|
||||
формулировки, врёт. Плагина нет — задача решается как проект привык, а этот скилл
|
||||
её только заводит и закрывает.
|
||||
формулировки, врёт. Задачу ведут не этим процессом — она решается как проект
|
||||
привык, а этот скилл её только заводит и закрывает.
|
||||
|
||||
## Что видит машина, а что человек
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Сверка чужих адресов в прозе плагинов с перечнем их владельца.
|
||||
"""Сверка чужих адресов в прозе скиллов с перечнем их владельца.
|
||||
|
||||
Судится **упразднённое, а не незнакомое**, и это следует из канона, а не из
|
||||
осторожности: список тем открытый — всё, что проект кладёт в `docs/` сверх
|
||||
@@ -9,9 +9,9 @@
|
||||
единственная догадка — имя, **почти** совпавшее с каноническим: это опечатка с
|
||||
куда большей вероятностью, чем новая тема.
|
||||
|
||||
Адрес документа принадлежит одному плагину, а называют его все: `docs/*` стоит
|
||||
примерно в сорока местах `av-dev-code`, `tasks/ROADMAP.md` — в четырёх местах
|
||||
`av-dev-docs`. Переименование в каноне до этих мест не доходит.
|
||||
Адрес документа принадлежит одному скиллу, а называют его все: `docs/*` стоит
|
||||
примерно в сорока местах конвейера, `tasks/ROADMAP.md` — в четырёх местах
|
||||
канона. Переименование в каноне до этих мест не доходит.
|
||||
|
||||
**Почему тут нужна машина, а не аккуратность.** Прогон ревью умеет честно
|
||||
деградировать: дома темы нет — в границах покрытия появляется строка «документа в
|
||||
@@ -123,8 +123,9 @@ def vocabularies(root: Path) -> tuple[dict[str, set[str]], dict[str, str]]:
|
||||
docs_names = {stem(n) for n in docs.DOCS}
|
||||
docs_names |= {stem(n) for n in docs.CONDITIONAL_DOCS}
|
||||
docs_names |= {stem(n) for n in docs.NOT_DOCS}
|
||||
# `docs/.docs.json` объявлен обязательным файлом вне раскладки.
|
||||
docs_names |= {stem(Path(p).name) for p in docs.REQUIRED if p.startswith("docs/")}
|
||||
# Обязательные файлы канона живут вне `docs/` (`CLAUDE.md`, `.av-dev.toml`),
|
||||
# и в перечень имён внутри каталога не идут вовсе. Ветка осталась бы мёртвой
|
||||
# молча, поэтому её тут нет: имя служебного файла добавляется ниже поимённо.
|
||||
|
||||
tasks_names = {stem(tasks.DEFAULTS[k]) for k in tasks.PATH_KEYS}
|
||||
tasks_names |= {stem(tasks.CONFIG_NAME)}
|
||||
|
||||
+1
-1
@@ -3,7 +3,7 @@
|
||||
|
||||
Диаграммы заведены там, где структура — граф или автомат: порядок проходов
|
||||
ревью, жизненный цикл записи по индексам, исходы задачи в спринте, храповик
|
||||
промоута, счётчик калибровки, граф вызовов между плагинами.
|
||||
промоута, счётчик калибровки, граф вызовов между скиллами.
|
||||
|
||||
Проверка нужна по одной причине: **синтаксическая ошибка в блоке не видна при
|
||||
чтении**. Текст диаграммы выглядит правдоподобно, `git diff` показывает разумную
|
||||
|
||||
Reference in New Issue
Block a user