# Documentation Implementation Consistency Review

> Проверка соответствия реализации нормативной документации проекта с анализом подтверждающих тестов и записью расхождений в `.review/documentation-consistency.md`. Использовать для полного или ограниченного аудита требований, контрактов и реализованного поведения без изменения кода или документации. Не использовать для проектирования документации, восстановления требований из кода или непосредственного исправления замечаний.

- Skill: `nemagu/documentation-implementation-consistency-review` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nemagu/documentation-implementation-consistency-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/documentation-implementation-consistency-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Nemagu (https://skillmd.com/u/nemagu)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/nemagu/documentation-implementation-consistency-review

---


# Проверка согласованности документации и реализации

Сопоставлять нормативные требования с кодом и подтверждающими тестами как
независимый аудитор. Не исправлять ни одну сторону расхождения. Создавать и
обновлять только файл замечаний.

Перед созданием отчёта полностью прочитать
[report-template.md](references/report-template.md) и использовать заданные там
структуру, значения полей и правила обновления.

## Рабочий процесс

1. Прочитать действующие инструкции репозитория.
2. Определить режим и область проверки по тем же правилам, что и пользовательский
   запрос: конкретный компонент означает ограниченную проверку, весь сервис —
   полную.
3. Определить источники требований в порядке приоритета:
   - явно указанные пользователем документы;
   - нормативная документация проекта, обычно в `docs/`;
   - контрактные артефакты OpenAPI, AsyncAPI, схем сообщений и конфигурационные
     спецификации;
   - README только при однозначном описании поведения или контракта.
4. Не считать источником требований код, тесты, комментарии, docstring, историю
   Git, сообщения коммитов и merge request, а также documentation-writing скилы.
   Использовать код и тесты только как доказательства реализации.
5. Отличать нормативное требование от обзора, примера, предложения, черновика и
   открытого вопроса. Не проверять реализацию против ненормативного текста.
6. Перед содержательным анализом и командами вывести в чат стартовую сводку:
   режим, область и её основание, документацию, реализацию, тесты, планируемые
   проверки, исключения и путь `.review/documentation-consistency.md`. После
   однозначной сводки не ждать подтверждения.
7. Если область нужно расширить, сначала сообщить отдельную обновлённую сводку.
8. Для каждого однозначного требования найти реализацию и подтверждающие тесты.
   Проверять наблюдаемое поведение, входы, результаты, ошибки, порядок действий,
   границы согласованности и внешние контракты только в заявленной области.
9. Проверять обратное направление: находить реализованное публичное или системно
   значимое поведение, которое противоречит нормативной документации либо должно
   быть в ней закреплено по установленным правилам проекта.
10. Найти заданные репозиторием профильные lint, type-check и test-команды.
    Выполнять сначала узкие безопасные проверки; полный обязательный набор — при
    полном аудите, если он доступен без нового разрешения.
11. Не запускать автоисправление, обновление snapshots/golden-файлов, установку
    зависимостей, внешнюю инфраструктуру или сетевые сервисы без разрешения.
12. Создавать замечание только при доказанном расхождении. Для отсутствующей
    реализации проверить ожидаемую и альтернативные области и описать границы
    поиска. Для теста формулировать `подтверждающий тест не найден`, если полный
    поиск нельзя гарантировать.
13. При конфликте нормативных документов создавать одно замечание со статусом
    `Требует согласования`, типом `Требование` и приоритетом по влиянию. Не
    выбирать самостоятельно удобный для кода вариант.
14. Подозрения, недоступные источники и непроверяемое внешнее поведение записывать
    в ограничения, а не в замечания.
15. Обновить отчёт по правилам шаблона. При ограниченной проверке не изменять
    замечания вне области.
16. Проверить корневой `.gitignore`. Если отдельной строки `.review/` нет,
    предложить пользователю добавить её. Не изменять `.gitignore` без согласия и
    не использовать `.git/info/exclude` вместо проектного правила.
17. Проверить `git status` и убедиться, что отчёт не добавлен в index.
18. Завершить краткой сводкой: новые и обновлённые замечания, количества по
    статусам и приоритетам, высокоприоритетные замечания, вопросы согласования,
    выполненные проверки, ограничения и ссылка на отчёт. Не начинать исправления.

## Классификация расхождений

Проверять следующие классы без добавления отдельного обязательного поля:

- требование не реализовано;
- реализация противоречит требованию;
- реализовано противоречащее или требующее нормативного закрепления поведение;
- требование не подтверждено найденным тестом;
- нормативные документы противоречат друг другу;
- соответствие невозможно проверить.

Последний класс помещать в ограничения, если само расхождение не доказано.

## Работа с источниками

- Явно указанную пользователем область документации ставить выше автоматически
  обнаруженной.
- Ссылаться на точный файл, раздел или контракт.
- При конфликте перечислять все источники и конкретные несовместимые варианты.
- Не считать открытый вопрос `Требованием` или `Рекомендацией`.
- Считать явно необязательное предпочтение `Рекомендацией`; его нарушение всегда
  имеет приоритет `Низкий`.
- Для требования определять приоритет по наблюдаемому влиянию.

## Границы изменений

Разрешено изменять `.review/documentation-consistency.md` и создавать каталог
`.review/` для него. Строку `.review/` разрешено добавлять в корневой `.gitignore`
только после согласия пользователя. Не исправлять код, тесты или документацию и
не менять `.git/info/exclude`.