Docs-as-code review rubric: проверка документации через diff, grep и find

1. Документация тоже проходит через diff

Черновик документа ничего не гарантирует. Пока текст не прошёл diff и сверку с проектом, это аккуратно оформленное предположение.

«Документация — это тоже код» звучит как лозунг, но мысль практическая. Плохой метод ломает программу. Плохой README ломает человека, который пытается её запустить. Для команды разница невелика.

Представьте: Claude сгенерировал для Commerce OS новый docs/onboarding.md. Текст красивый и структурный. Там сказано, что проект запускается командами npm start и ./gradlew run, а платежи обрабатывает отдельный модуль уведомлений. Новый разработчик честно делает всё по инструкции — и спотыкается на первой команде. Это не проблема стиля. Документ соврал про систему.

Поэтому документация живёт в репозитории, меняется через diff и проходит review. Даже если вы работаете один без формального pull request, логика та же: любой текст о проекте — проверяемый артефакт, а не заметка «на доверии».

Вот путь документации от черновика до принятого текста:

flowchart TD
    D[AI draft] --> F[Diff в репозитории]
    F --> V[Проверка по коду, конфигам и командам]
    V --> C[Правки]
    C --> A[Документ принят]

Ключевой сдвиг: документ принимается не по уверенности тона и не по тому, как «приятно читается», а по совпадению с кодом, конфигами, командами запуска и реальным поведением системы. Claude ускоряет написание, но право сказать «это правда» — за вами.

Документация принимается не по красоте формулировок, а по совпадению с кодом и поведением проекта.

Для Commerce OS это критично: у нас уже есть источники истины — CODEBASE_INVENTORY.md, API_MAP.md, build-команды, конфиги, тесты. Документация, живущая отдельно от них, превращается в декорацию. А декоративный README работает до первой попытки что-то запустить.

2. Восемь критериев хорошего docs review

Частая ошибка ревью — оценивать «всё сразу». Короткая рубрика не заменяет голову, но не даёт пропустить очевидное — особенно когда текст написал AI и каждая вторая строка звучит подозрительно разумно.

Держите эту rubric рядом при проверке документации Commerce OS.

Тонкий момент: complete enough — это не «написать всё на свете». Хорошая документация не энциклопедия. В onboarding guide важно, чтобы новый разработчик поднял Commerce OS локально и понял, где основные модули; трактат обо всех краях потока возврата ему не нужен. В архитектурной заметке наоборот — там важны связи между модулями и границы интеграций.

Так же и source-anchored не требует академического списка литературы в каждом абзаце. Смысл проще: если документ утверждает что-то нетривиальное, вы должны быстро понять, откуда это взялось — из build.gradle, application.yml, src/payments/StripeClient.java, теста на контроллер, лога запуска. Источник не находится — утверждение не прошло проверку.

Таблица превращает ревью из туманного «ну вроде нормально» в инженерный процесс. Вы проверяете конкретные свойства артефакта, а не «красивость».

3. Проверяем команды, а не верим им на слово

Самая дешёвая и самая полезная проверка — запускать команды из документа руками. Именно на командах вскрываются расхождения между красивым текстом и реальным проектом.

Допустим, Claude сгенерировал для Commerce OS такой фрагмент onboarding guide:

## Запуск проекта

```bash
npm start
./gradlew run
```

На вид прилично. Но вы его не обсуждаете — вы его проверяете:

npm start                     # npm ERR! Missing script: "start"
./gradlew run                 # Task 'run' not found in root project
./gradlew bootRun             # backend запускается на :8080
cd apps/web && npm run dev    # frontend запускается на :3000
docker compose up -d db       # PostgreSQL поднимается в фоне

За тридцать секунд выясняется: документ даёт две неправильные команды подряд. Для нового разработчика это первая точка контакта с проектом. После такого доверие к документации падает до «лучше вообще ничего не читать».

Принцип простой: команда верна только после запуска. Не запускается — либо документ ошибся, либо проект сломан. Обе ситуации полезно обнаружить.

После проверки фрагмент становится пригодным к жизни:

## Локальный запуск Commerce OS

```bash
docker compose up -d db       # PostgreSQL
./gradlew bootRun             # backend, порт 8080
cd apps/web && npm run dev    # frontend, порт 3000
```

Проверено по:
- build.gradle
- apps/web/package.json
- application.yml

Хороший фрагмент конкретнее плохого: он не просто называет команду, а показывает контекст — из какой директории запускать, какой сервис поднимается, на каком порту. Это важно для студентов, неуверенных в терминале: им нужна не «подсказка на запуск», а последовательность действий, которую можно честно повторить.

И ещё: скрытые условия нельзя оставлять «между строк». Нужен .env — пишите. База должна быть поднята заранее — пишите. Иначе документ выглядит корректным, а на практике остаётся ловушкой.

4. Архитектура, API и самые уверенные галлюцинации

С командами честно: запускаются или нет. С архитектурными заметками и описаниями API коварнее. AI пишет такие абзацы с видом разработчика, который лично проектировал все сервисные слои, очереди и обработчики событий. Поэтому architecture notes — самый опасный тип документации.

Представьте, что в черновике по Commerce OS появляется пассаж:

Для SMS-уведомлений о возвратах используется модуль
`src/notifications/SmsGateway.java`, который вызывается из refund flow.

Звучит солидно. Но при правиле evidence-first следующий шаг — не раздумья, а поиск:

find src -name "SmsGateway.java"   # ничего не найдено
grep -R "SmsGateway" src           # совпадений нет

Если вы редко в терминале, запомните две команды. find ищет файл по имени, а grep — текст по содержимому проекта. Простые, но крайне полезные инструменты проверки AI-документации. Иногда одного grep хватает, чтобы за две секунды превратить «уверенное архитектурное утверждение» в галлюцинацию.

Та же логика для API-документации. Если текст называет эндпоинт, проверьте его по API_MAP.md, контроллеру и тестам. На прошлых лекциях вы уже собрали карту API и интеграций Commerce OS — теперь она работает как помощник ревьюера.

Корректный, привязанный к источнику фрагмент про refund flow:

## Refund flow

- `POST /api/orders/{id}/refund`
- handler: `src/orders/OrderController.java`
- service: `src/refunds/RefundService.java`
- payment client: `src/payments/StripeClient.java`
- related tests: `src/test/java/.../RefundServiceTest.java`

Он хорош не длиной, а проверяемостью: reviewer быстро откроет контроллер, увидит вызов клиента, сверится с тестом. А если при рефакторинге какой-то элемент исчезнет, diff покажет, что именно перестало соответствовать коду.

Ещё правило: если API_MAP.md уже содержит проверенные факты про endpoints и интеграции, не пересочиняйте их в каждом документе заново. Опирайтесь на карту как на промежуточный источник и идите от неё к коду. Иначе получится хор из пяти файлов, по-разному рассказывающих одну историю.

5. Assumptions, Limitations и размер diff

Соблазнительно писать документацию как нечто универсальное и завершённое. AI это любит: у него всё «работает», «поддерживается» и «интегрировано». Честная документация показывает не только что есть в проекте, но и что предполагается и где заканчиваются гарантии.

Представьте onboarding guide, который даёт команды запуска — и всё. Формально документ есть. Практически — нет: новый разработчик не понимает, нужна ли локальная база, собран ли .env, работают ли платежи в dev-режиме, воспроизводятся ли webhooks локально. Это нельзя оставлять на телепатию.

Поэтому Assumptions и Limitations — не декоративное приложение, а часть проверки качества:

## Предположения
- локальная база поднята через `docker compose up -d db`
- `.env` собран на основе `.env.example`

## Ограничения
- Stripe работает только с test keys
- webhooks локально не воспроизводятся без внешнего туннеля

Такие секции делают документ честным: показывают не только «что делать», но и «в каких границах это имеет смысл». Новичок меньше винит себя в том, что «не смог поднять проект», когда документ заранее признаёт ограничения среды.

Отдельно — размер diff. AI любит щедрость. Попросили «улучшить документацию» — получите переписанный README, новый onboarding guide, расширенные архитектурные заметки, секцию по API и пару советов про запуск. Выглядит старательно. Ревьюится ужасно.

Хороший docs diff — reviewable: его реально прочитать и проверить за один подход. Переписал Claude сразу всё — reviewer почти неизбежно пропустит ошибку. Большие изменения режьте: отдельно запуск, отдельно refund flow, отдельно архитектурная заметка по payments. Документация любит аккуратную нарезку не меньше кода.

«Слишком много полезного сразу» — это реальная проблема. Полезное, которое не успели проверить, в репозитории превращается в риск.

6. Полный проход по docs diff на примере Commerce OS

Соберём всё в один сценарий. Claude подготовил обновление docs/onboarding.md для Commerce OS: разделы про локальный запуск, краткая архитектурная справка, небольшой блок про payments. Ваша задача — не «оценить впечатление», а провести ревью.

Сначала открываете diff и смотрите ширину. Если в одном изменении переписаны разом запуск, API, архитектура и troubleshooting — просите разбить правки. Иначе проверка превращается в лотерею.

Дальше — самый дешёвый и полезный путь: копируете команды и запускаете. ./gradlew bootRun, npm run dev, docker compose up -d db работают — хороший знак. Нет — правите документ или выясняете, что сломан setup.

Следующий проход — по именованным сущностям. Все классы, пути, контроллеры, конфиги, интеграции должны существовать. Здесь помогают find, grep, поиск в IDE и собранный API_MAP.md. Ссылка на несуществующий SmsGateway.java или выдуманный маршрут — фрагмент удаляется или помечается непроверенной гипотезой и в финал не попадает.

Затем смотрите на целостность глазами читателя. Onboarding guide: запустит ли новый разработчик Commerce OS и не упрётся ли в тупик на первом шаге? Есть ли assumptions? Есть ли limitations? Понятно, что платежи локально тестовые? Не обещает ли текст больше, чем проект умеет?

Только после этих проверок документ можно оставить в репозитории. Исправленный фрагмент скромнее AI-черновика, зато ему можно доверять:

## Локальный запуск Commerce OS

```bash
docker compose up -d db       # PostgreSQL
./gradlew bootRun             # backend, :8080
cd apps/web && npm run dev    # frontend, :3000
```

### Assumptions
- `.env` собран из `.env.example`

### Limitations
- платежи работают только в тестовом режиме

В этот момент вы закрываете не только конкретный diff. У вас собрана полная цепочка: держать проект в чистом Git-состоянии, формулировать задачу, управлять контекстом, строить CODEBASE_INVENTORY.md, собирать API_MAP.md, использовать доказательства из рантайма и принимать документацию по совпадению с системой, а не по красоте текста. Claude по-прежнему помогает быстро, но право сказать «этому документу можно доверять» — за вами. Это не магия, а нормальная инженерная работа.

И здесь видно, какие ручные шаги начинают повторяться: собрать source-anchored evidence, обновить артефакт, проверить команды, принять diff. Когда они стабилизировались вручную, их пора упаковывать в reusable workflow assets и общий Workflow Kit — явные правила, шаблоны и чеклисты, а не сборку с нуля каждый раз.