Документация как docs-as-code артефакт

1. Документация — часть delivery, а не приложение

Когда разработчик слышит слово «документация», мозг иногда переводит его как «что-нибудь текстовое, потом допишем». Для delivery это опасный автоперевод. README с неправильной командой ломает запуск не хуже битого shell-скрипта, а runbook с выдуманным шагом портит вечер всей команде поддержки. Просто тише и пассивно-агрессивнее.

Представьте Commerce OS. Команда перевела локальный запуск на docker compose, build зелёный, CI счастлив. А в README осталась старая инструкция: сначала ./gradlew bootRun, потом npm run dev. Новый разработчик идёт по документации, получает половину окружения, странные ошибки подключения к базе и подозревает всё подряд — от Java до ретроградного Меркурия. Формально баг не в коде. Практически он уже в поставке.

Именно поэтому мы говорим о docs-as-code. Документация живёт в репозитории, меняется вместе с кодом, проходит diff и review, принимается только после проверки по источнику истины — не по «воспоминаниям автора», а по коду, командам, конфигам и наблюдаемому поведению.

Полезно увидеть разницу между двумя похожими, но на деле очень разными задачами:

Здесь и происходит главный сдвиг: документация перестаёт быть приложением к фиче и входит в change set.

2. Какие документы Commerce OS вести как код

Если автоматизировать всё подряд, получится не инженерная система, а фабрика очень убедительного шума. Поэтому сначала полезно разделить документы по привязке к реальному поведению: чем сильнее документ связан с запуском, API, конфигом и поддержкой, тем больше смысла проверять его как код.

Для Commerce OS это выглядит примерно так:

README.md

Заметьте важную деталь. Ключевое слово — delivery artifacts: документы, что напрямую участвуют в запуске, проверке, эксплуатации и понимании change. На тексте без привязки к коду автоматизация быстро начинает фантазировать.

Поэтому есть тексты, где Claude — помощник по структуре, но не основной автор: архитектурное решение, ADR, postmortem, объяснение выбранного компромисса. Здесь слишком много ответственности и человеческого суждения. Модель оформит черновик, но финальный смысл — за человеком. Иначе выходит документ, который выглядит серьёзно, но отвечает не на тот вопрос.

Здесь полезно держать простое правило: проверяется механически по коду, командам или логам — в docs-as-code workflow. Описывает reasoning, ответственность и компромиссы — полностью автоматизировать опасно.

3. Сверяйте с кодом, командами и поведением

Когда документация становится частью delivery, главный вопрос звучит очень прозаично: как именно её проверять? Ответ не романтический, зато надёжный — три опоры проверки: код, команды, фактическое поведение. Не совпала хотя бы одна — это не «почти актуальная документация», а обычная ошибка в репозитории.

Возьмём простой пример из Commerce OS. Допустим, в README всё ещё написано так:

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

1. `./gradlew bootRun`
2. `npm run dev`
3. Убедитесь, что PostgreSQL уже запущен локально

Но команда давно перешла на единый сценарий через контейнеры:

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

1. `docker compose up -d`   # поднимает PostgreSQL, backend и frontend
2. `./gradlew test`         # backend-проверки
3. `npm run lint`           # frontend-проверки

Именно здесь Claude полезен как инструмент сравнения, а не как литературный талант. Дайте ему очень ограниченную задачу:

Сравни README раздел «Локальный запуск» с docker compose, Gradle tasks и frontend scripts.
Верни только:
1. несовпадения;
2. команды, которые реально существуют;
3. места, где есть неуверенность.
Файлы не меняй.

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

Точно так же работает сверка API-документации. Возьмём backend-код:

@RestController
@RequestMapping("/api/orders")
public class RefundController {

    @PostMapping("/{id}/refund")
    public RefundResponse requestRefund(@PathVariable UUID id) {
        return refundService.request(id);
    }
}

Значит, документация не имеет права внезапно рассказывать про PUT /api/orders/{id}/refund или про поле amount, которого в коде нет. Корректный фрагмент будет выглядеть скромнее и честнее:

### Запрос на возврат
`POST /api/orders/{id}/refund`

Создаёт запрос на возврат для существующего заказа.
Ответ возвращается в формате `RefundResponse`.

Здесь есть важный практический нюанс: проверки по файлам иногда мало. Команда может существовать в package.json, но не работать на чистом окружении. Endpoint может быть объявлен в controller, но валиться из-за отсутствующего профиля. Поэтому docs-as-code verification почти всегда требует хотя бы одного шага реального выполнения — маленького, но настоящего.

Документация, которую проверили только «по смыслу», остаётся черновиком. Проверенная по командам, route и поведению — часть поставки.

4. Пусть Claude сверяет, а не фантазирует

С документацией у моделей есть любимый фокус: они очень красиво достраивают недостающие детали. Для блога терпимо, для README и runbook — катастрофа. Claude здесь проверяющий редактор, а не автор, который «сам догадается, как у нас устроен проект». Догадывается он слишком смело.

Хорошая роль — найти расхождения, предложить черновик, отметить неуверенность, сослаться на источник. Плохая — придумывать команды, env vars, endpoints и сценарии восстановления, которых он не видел.

Поэтому полезно закрепить это прямо в проектных инструкциях. В CLAUDE.md Commerce OS:

## Правила для документации
- не придумывай endpoints, env vars и команды
- для API-утверждений указывай файл-источник
- если не уверен, пиши "не проверено"
- ADR и postmortem оставляй человеку

Это коротко, но очень практично. Особенно строка про «не проверено»: скучная, пока не спасает от абзаца красивой фантазии. У честной инженерной документации спокойный характер: она не стесняется сказать «этот сценарий я не подтвердил».

Вот полезное сравнение ролей Claude по типам документов:

Иногда очень полезно просить Claude не переписывать документ целиком, а работать по diff — показать только строки, которые стоит изменить. Иначе вместе с одной починенной командой вы внезапно получаете полпереписанного README в новом стиле, с новыми заголовками и неожиданной философией жизни.

Ещё один сильный приём — просить модель разделять подтверждённые факты и предположения:

Проверено:
- backend поднимается через `docker compose up -d`

Не проверено:
- нативный запуск без Docker на Windows

Такой стиль не выглядит глянцево, зато отлично работает в команде. Глянец в runbook редко кому нужен.

5. Документация как diff внутри PR и quality gate

Когда вы начинаете относиться к документации как к коду, следующий шаг очевиден: правка docs входит в тот же PR, что и изменение поведения. Не «потом допишу», не в следующую пятницу, не после комментария тимлида с грустным смайликом. В тот же change set, чтобы reviewer видел причину и следствие рядом.

Удобнее всего закреплять это прямо в шаблоне PR:

## Проверка документации
- [ ] README обновлён, если менялись команды запуска или setup
- [ ] API docs обновлены, если менялись routes или response
- [ ] примеры команд проверены на чистом окружении
- [ ] секреты не попали в примеры и `.env`

Здесь важен не сам формат галочек, а привычка: документация проверяется не «вообще», а по конкретному признаку изменения. Не меняли запуск — README можно не трогать. Меняли response возврата — API note уже обязательная часть diff.

Если базовый QUALITY_GATES.md уже описывает проход PR -> main, docs-правила лучше добавлять туда же отдельной секцией — рядом с кодовыми проверками:

## Документация в PR
- README и runbook обновлены, если менялись команды, env или routes
- команды из docs проверены на чистом окружении
- API-описания сверены с controller и тестами
- секреты не попали в примеры и документацию

Просто теперь видно, что gate относится не только к build и test jobs. Тот же принцип потом понадобится для changelog с release notes: текст проверяется по наблюдаемым изменениям, а не по уверенной интонации.

Заметьте, что здесь уже встречаются и deterministic, и human-driven проверки. Secret scan и наличие changed files в docs автоматизируются надёжно. А честную проверку, что пример запроса соответствует смыслу endpoint, лучше сочетать с review человеком и, при необходимости, AI-assisted сверкой по исходникам.

Очень важно не смешивать документацию с «красивым текстом для клиента». Нас интересуют delivery artifacts: README, setup, API docs, runbook, onboarding. Маркетинговый текст, локализация, customer-facing copy живут по другим правилам и создадут здесь только шум.

Когда документация попадает в gate, она перестаёт быть хвостом кометы. Она становится таким же проверяемым элементом change, как код.

6. Сквозной пример: README и API note без вранья

Теперь соберём всё в один небольшой сценарий, чтобы картина не осталась набором правил. Команда Commerce OS добавила обязательное ручное подтверждение для возвратов дороже 100 долларов. Backend научился возвращать новый признак для support-модуля. Код обновили, тесты прошли, а документация живёт вчерашним днём.

Например, теперь backend отвечает так:

{
  "requestId": "rf_123",
  "status": "PENDING_APPROVAL",
  "approvalRequired": true
}

Если API note всё ещё обещает просто «возврат создан», support-команда не увидит важную ветку поведения. А если runbook молчит про approvalRequired = true, оператор начнёт повторять запросы, хотя нужно ждать ручного решения. То есть ошибка в документации уже бьёт по продукту.

В этом случае разумный workflow выглядит спокойно и без магии. Просите Claude сравнить controller, DTO и существующий markdown с API-описанием. Проверяете реальный response через тест или локальный вызов. Обновляете документацию небольшим diff, а не переписыванием половины раздела.

Например, корректный runbook fragment может стать таким:

### Возвраты дороже 100 $
Если `approvalRequired = true`, оператор не отправляет повторный запрос.
Нужно дождаться ручного подтверждения в панели поддержки.
Статус до подтверждения: `PENDING_APPROVAL`.

А рядом в PR — обновлённый API note и, если нужно, секция README для локальной проверки refund flow. Reviewer видит и код, и docs, и тест. Gate не выпускает наружу change, который меняет поведение, но молчит о нём в сопровождающих артефактах.

И вот здесь документация наконец ведёт себя как инженерный артефакт: не «текст, который надо приложить», а часть рабочей системы. Совпадает с кодом, командами и поведением — помогает двигаться быстрее; не совпадает — такой же дефект поставки, как упавший smoke test. Поэтому документацию в delivery ценят не за красоту, а за проверяемость.

1

Задача

Claude code, 22 уровень, 1 лекция

Недоступна

Добавление runnable docs check в package.json

Добавление runnable docs check в package.json

Открыть

1

Задача

Claude code, 22 уровень, 1 лекция

Недоступна

Привести controller route к API documentation

Привести controller route к API documentation

Открыть