dev-skills/av-dev/skills/doc-sync/SKILL.md

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

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

Скилл владеет **содержимым** документов канона; раскладкой владеет `canon`.
Определение канона и роли документов — [канон](../canon/references/canon.md),
здесь не пересказывается.

Главный вызывающий — **шаг синка документации в конвейере задачи**: скилл
`av-dev:code-resolve` зовёт этот по имени. Задачу ведут не конвейером —
документация ведётся тем же скиллом вручную.

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

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

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

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

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

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

| Документ | Обновляется, когда | Проверка |
| --- | --- | --- |
| `openspec/specs/` | всегда при изменении поведения | вливает `opsx:archive` |
| `database.md` | тронуты миграции | `docs.py check --base` |
| `architecture.md` | новый компонент, граница, внешняя зависимость, изменилось окружение | `docs.py`: capability без упоминания |
| `adr/` | сработал триггер канона (перечень — [canon.md](../canon/references/canon.md#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:doc-healthcheck`

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

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

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

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

**Язык правленого вычитывается тем же прогоном, который его написал, и зовёшь
агента `doc-wording` ты.** Довод обратный доводу про судей: он читает **только
названную пачку**, стоит дёшево и ищет ровно то, что портится в момент письма, —
залог, оценку без факта, жаргон, термин без ввода. Ждать `doc-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-resolve`, сценарий разведки: решение, принятое разведкой (намеренный отказ, выбор
подхода, «проверили и не делаем»), `design.md` не имеет по построению — change по
нему не будет никогда. Промоут при этом тот же: цитата и ссылка, но на записку.
Перечень источников закрыт и живёт в [каноне](../canon/references/canon.md),
раздел `adr/`.

**Триггер заведения, форма имени и правило замены — в
[каноне](../canon/references/canon.md), раздел `adr/`.** Здесь они не
повторяются: копия правила расходится с оригиналом на первой же смене версии
канона, а расходится незаметно.

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

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

## Чистка `architecture.md`

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

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

## Запись в `research/`

Наблюдение о внешнем мире: что реально шлёт источник, чем документация формата
расходится с практикой. **Требование происхождения и правило про расходящееся
число — в [каноне](../canon/references/canon.md), раздел `research/`.**

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

## Чего может не быть

Два раздела ниже — запись в `review.md` и промоут в конвенции — берут форму у
конвейера ревью: она принадлежит ему, а не канону. Берут **вызовом скилла**, а не
чтением файла по пути.

**Копия.** Дом правила — `shared/absence.md` в репозитории плагина.
Правится дом, а не этот файл.

<!-- копия: отсутствие из av-dev/shared/absence.md -->

**Скилл не вправе считать раскладку проекта полной.** Части заводятся порознь и
живут порознь; каждая узнаётся своим следом:

| Чего нет | Как видно | Чего теперь не делает никто |
| --- | --- | --- |
| настройки av-dev | нет `.av-dev.toml` в корне | проект под процесс не заводился; версии нет, настроек нет |
| документы канона | нет `docs/` | проектную конкретику брать неоткуда — темы, инварианты, прецеденты |
| учёт работ | нет каталога задач | запись остаётся владельцу: назови её текстом в докладе |
| источник требований | нет `openspec/config.yaml` | цикл SDD не запускается: спеки не с чем сверять |

**Свой скилл зовётся полным именем** — `av-dev:canon`, `av-dev:task-track`,
`av-dev:code-review`. Короткое имя может разрешиться в устаревшую проектную
копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в
поведении.

**Внешний плагин может не стоять.** Их два: `opsx:*` — цикл SDD, и
`av-dev-git:commit` — сообщения коммитов. Путь в дерево чужого плагина не
пишется никогда: `$CLAUDE_PLUGIN_ROOT` ведёт только в своё дерево, а
вычисленный от него путь к соседу либо не откроется, либо откроет чужую
установку. Нужен чужой справочник — зови владеющий им скилл, он прочитает его
сам.

**Отсутствие — исход, а не поломка.** Назови строкой доклада, чего теперь не
делает никто, и продолжай работу. Молчать нельзя: пропуск неотличим от
сделанного. Выдумывать обходной путь нельзя тоже.

**Присутствие узнаётся следом в проекте, а не объявлением.** Перечня того, что
здесь заведено, проект не ведёт — он разошёлся бы с действительностью молча.

<!-- /копия: отсутствие -->

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

## Запись в `review.md`

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

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

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

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

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

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

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