dev-skills/av-dev-docs/skills/docs/SKILL.md

name, description

name

description

docs

Вести содержимое документов канона по ходу разработки — синк после сделанной задачи с построчным отчётом по каждому документу, заведение ADR промоутом из архивного design.md или из записки разведки, запись наблюдения в research, запись дефекта и настройки конвейера в review.md, чистка architecture.md от поведения с маркерами долга. Использовать, когда задача сделана и надо обновить документацию, когда просят завести ADR или записать решение, занести находку о внешних данных, записать проскочивший дефект, разгрузить разросшуюся архитектуру. Раскладку и соответствие канону проверяет скилл canon.

Ведение содержимого канона

Скилл владеет содержимым документов канона; раскладкой владеет canon. Определение канона и роли документов — канон, здесь не пересказывается.

Главный вызывающий — шаг синка документации в конвейере задачи. Конвейер живёт в другом плагине и зовёт этот скилл по имени; проект без конвейера ведёт документацию тем же скиллом вручную.

Правило, из которого всё следует

Принуждённое отрицание. Синк обязан назвать каждый документ канона: либо чем он обновлён, либо «не требуется, потому что…». Нетронутые группируются одной строкой с общей причиной.

Причина, по которой правило именно такое, измерена: у ADR был список триггеров прозой — и он дал 6 записей на 43 изменения. Прозаический триггер, который некому проверить, не срабатывает. Отличить «не написал» от «написал, что не требуется» можно только тогда, когда отрицание обязательно.

Это тот же приём, что «границы покрытия» в отчёте ревью и «пустое называется пустым» в каноне.

Чек-лист синка

Идёт сверху вниз; каждая строка попадает в доклад.

Документ	Обновляется, когда	Проверка
openspec/specs/	всегда при изменении поведения	вливает opsx:archive
database.md	тронуты миграции	docs.py check --base
architecture.md	новый компонент, граница, внешняя зависимость, изменилось окружение	docs.py: capability без упоминания
adr/	дорогой откат, намеренный отказ, пересмотр прежнего	нет — только этот чек-лист
research/	узнали новое о внешнем формате или данных	нет
security.md	новый недоверенный вход, токен, путь наружу, сдвиг периметра	нет
conventions/	находка принята и не специфична для одного места	промоут
review.md	дефект воспроизведён; сузили или расширили проверку	нет
passport.md	новый потребитель, сдвиг границы «чем не является»	нет
CLAUDE.md	изменился инвариант, гейт, запрет, необратимое	нет

Пример доклада:

Синк документации:
- architecture.md — добавлен воркер свёртки, ссылка на capability reindex
- database.md — миграция 00006, таблица bucket
- adr/ — заведён ADR-2026-08-03-queue-as-table: отказ от внешней очереди
- research/ — новое о формате не узнано
- passport, security, conventions, review — не требуется: изменение внутреннее

Сверка — не здесь, а в av-dev-docs:healthcheck

Синк правит документы поодиночке, а расходятся они между собой: факт, дописанный в architecture.md, уже живёт в CLAUDE.md; периметр в security.md не знает про новый эндпоинт. Поймать это на своей же правке нельзя, и судит это агент doc-consistency.

Но синк его не зовёт. Обоими судьями документов владеет скилл av-dev-docs:healthcheck, и зовут их на весь канон разом, а не на пачку, отобранную работой. Причина в цене: doc-consistency на opus по каждой сделанной задаче — самая дорогая церемония процесса, а doc-code-drift хоть и на sonnet, но читает репозиторий целиком. К тому же расхождение между двумя документами по определению требует двух документов, а на большинстве задач синк правит один.

Что теряется: привязка находки к задаче, которая её породила. Что выигрывается, кроме денег: синк перестаёт отбирать пачку, и в неё попадают документы, которых работа не касалась, — расхождение, внесённое правкой в одном месте, там и живёт.

Вычитка — наоборот, здесь

Язык правленого вычитывается тем же прогоном, который его написал, и зовёшь агента doc-wording ты. Довод обратный доводу про судей: он читает только названную пачку, стоит дёшево и ищет ровно то, что портится в момент письма, — залог, оценку без факта, жаргон, термин без ввода. Ждать healthcheck здесь нечего: через месяц никто уже не помнит, какую фразу имел в виду автор.

Позови его последним шагом правки, до коммита, отдав список файлов, которых она коснулась, — и назови этот список в промпте: по нему же он судит, известен ли термин. Находки он отдаёт готовыми формулировками, подставляешь их ты.

Условие вызова — правка, а не синк. Синк самый частый вызывающий, но не единственный: разведка (av-dev-code:resolve, сценарий разведки) пишет ответ по одному адресу и синком себя не считает намеренно — вычитка ей нужна ровно та же. Признак один и читается буквально: документы правились — зови, ничего не правил — не зови.

ADR — промоут, а не второе сочинение

Обоснование уже написано: opsx:propose кладёт design.md в каждый change, и после архивации он лежит в openspec/changes/archive/<id>/design.md с разделами Context / Goals / Non-Goals / Decisions / Risks / Trade-offs.

ADR цитирует решение оттуда и ссылается на источник. Не пересказывает и не сочиняет заново.

Второй законный источник — записка разведки, и приходит он от скилла av-dev-code:research: решение, принятое разведкой (намеренный отказ, выбор подхода, «проверили и не делаем»), design.md не имеет по построению — change по нему не будет никогда. Промоут при этом тот же: цитата и ссылка, но на записку. Перечень источников закрыт и живёт в каноне, раздел adr/.

Триггер заведения, форма имени и правило замены — в каноне, раздел adr/. Здесь они не повторяются: копия правила расходится с оригиналом на первой же смене версии канона, а расходится незаметно.

Твоя часть — применить триггер к этой задаче и сказать вслух, сработал он или нет. Строка «adr/ — не требуется: решение рутинное» и есть то, ради чего чек-лист существует; её отсутствие неотличимо от «забыл посмотреть».

Порядок работы: открой источник — архивный design.md change либо записку разведки, — найди в нём решение, проходящее триггер, процитируй его и причину, сошлись на источник, добавь строку в индекс docs/adr/README.md сверху.

Чистка architecture.md

Обзор не держит поведение — его нормативный дом openspec/specs/. Форма маркера долга и правило «гейт от них не краснеет» — в каноне, раздел architecture.md.

Разбирается порциями: раздел вычищает та задача, которая его касается. Содержимое не выбрасывается, а переезжает — требования в дельта-спеку change, обоснование в ADR, обзор остаётся строкой со ссылкой на capability.

Запись в research/

Наблюдение о внешнем мире: что реально шлёт источник, чем документация формата расходится с практикой. Требование провенанса и правило про расходящееся число — в каноне, раздел research/.

Твоя часть — заметить, что по ходу задачи узналось новое о внешних данных, и не дать этому остаться в контексте. Признак: ты правил разбор, опираясь на то, чего нет ни в одном документе.

Обращение к соседним плагинам

Два раздела ниже — запись в review.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/.docs.json — канон, <каталог задач>/.tasks.json — задачи, openspec/config.yaml — конвейер. Имя файла — имя плагина, который его завёл, и держит он в том числе версию своего формата: у канона документов и у каталога задач они свои и двигаются порознь.

Чем оборачивается отсутствие конвейера — в каждом из двух разделов отдельно: без него работа не отменяется, отменяется только его процедура.

Запись в review.md

Файл держит два раздела с разными сроками жизни — журнал дефектов и настройку конвейера. Что в каком и в какой форме — в каноне, раздел review.md; подробности формы записи и выбор адреса, куда она ведёт, — у конвейера ревью проекта (при av-dev-code — Skill av-dev-code:review, его references/review-journal.md). Конвейера в проекте нет — пиши по форме из скелета review.md, которую положил канон, и скажи в докладе, что подробностей формы взять негде.

Твоя часть на синке: дефект пишется сразу, а не «потом, когда починим». Со временем теряется не факт, а то, почему дефект не поймали, — единственное, ради чего журнал есть. И решение сузить проверки (перестали звать проход, понизили метку) обязано попасть в раздел настройки, а не остаться в отчёте ревью.

Промоут в конвенции

Находка → конвенция → правило линтера → удаление из прозы. Процедура целиком принадлежит конвейеру ревью проекта (при av-dev-code — его references/promote.md, читается через Skill av-dev-code:review); роль каталога конвенций — в каноне. Конвейера нет — три шага всё равно твои, просто без его процедуры: сформулируй правило, поищи, чем оно механизируется, и вычеркни прозу, если механизировалось.

Твоя часть — третий шаг, который пропускают чаще всего: правило заработало, а формулировка осталась в прозе, и проход продолжает проверять уже проверенное. На синке это отдельная строка: «conventions/ — правило X механизировано, формулировка удалена» либо «не требуется».

Чего этот скилл не делает

• Не проверяет раскладку — это canon.
• Не заводит недостающие документы — их скелет кладёт canon adopt или init.
• Не сочиняет содержание. Нечего записать — так и пишется, честной строкой.
• Не переоформляет документы «заодно»: правится то, чего коснулась работа.