Documentation Implementation Consistency Review

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

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

Перед созданием отчёта полностью прочитать 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.