AI-assisted documentation

1. Почему документация — именно сейчас

Раньше писать документацию было нечем. Сейчас есть: CODEBASE_INVENTORY.md, API_MAP.md, привычка проверять утверждения по коду, доказательства из терминала и логов, короткие выжимки по широким расследованиям. Документ теперь собирается из подтвержденных артефактов, а не из памяти и красивого пересказа.

Документация — это перевод с языка проекта на язык человека. Код знает, что делает RefundService, конфиг — на каком порту поднимается backend, тест — какой сценарий корректен. Документация собирает это в форму, понятную другому разработчику, новому участнику команды или вам через две недели. Память тут подводит: вам кажется «я потом разберусь». Обычно нет.

В Commerce OS это видно на возвратах, оплатах, dashboard-метриках, AI-подсказках поддержки. Пока код свежий, логика кажется очевидной. Но как только нужно объяснить, где начинается поток возврата, какой эндпоинт его запускает, когда включается ручная проверка и что происходит локально без webhook, «ну это где-то в сервисе» перестает быть документацией.

2. Документы, которые усиливают Claude Code

«AI помогает писать документацию» в голове часто превращается в один огромный README.md, куда сваливают запуск, архитектуру, troubleshooting, обзор API и историю компании. На практике полезнее набор небольших документов с конкретным читателем и конкретной задачей.

Карта того, с чем Claude Code реально помогает в Commerce OS:

Правило: один документ — одна задача. «Задокументируй модуль возвратов» работает так же, как «сделай красиво». А «собери onboarding-документ для локального запуска backend и frontend» или «сделай черновик объяснения потока возврата для ревью» дает результат заметно лучше.

Claude силен в первом каркасе: быстро предложит разделы, подзаголовки, черновые формулировки, вынесет assumptions и ограничения. Это много. Но это каркас, не окончательная правда.

3. Claude пишет черновик, не истину

Здесь главная ловушка. Claude пишет документацию убедительно — иногда слишком. Он опишет модуль, которого в проекте нет, придумает правдоподобную команду запуска, упомянет интеграцию, которая «логично должна существовать». Логично — не значит подтверждено.

Сравните формулировки:

AI-документация без проверки — это вежливая галлюцинация. Выглядит как текст опытного инженера, а стоит на двух прочитанных файлах и воображении.

Правило урока: все, что сгенерировал Claude, — черновик, пока вы не сверили текст с кодом, конфигами, командами и тестами. Не сверили — это заготовка документации, не документация.

4. Даем Claude правильный материал

Качество документации начинается не с формулировки запроса, а с источников. Дали абстрактный вопрос и ноль доказательств — получите абстрактный текст. Дали API_MAP.md, конкретные классы, тесты и конфиги — Claude уже не так легко уплывает в художественную литературу.

Хороший запрос для документа о потоке возврата в Commerce OS:

Составь черновик файла `docs/refund-flow.md` для Commerce OS.

Опирайся только на следующие источники:
- `API_MAP.md`
- `src/orders/OrderController.java`
- `src/refunds/RefundService.java`
- `src/test/java/.../RefundServiceTest.java`
- `src/main/resources/application.yml`

Отделяй подтвержденные факты от предположений.
Если чего-то не хватает, добавь раздел «Открытые вопросы».
Не придумывай новые классы, интеграции и очереди.

Этот запрос хорош не магией, а границами: где правда, что запрещено выдумывать, как обращаться с неопределенностью. Взрослая работа с AI — задавать рамки, а не ждать чудо-промпт.

Если модуль большой и читать все в основной сессии не хочется, сначала через subagent или изолированную investigation-сессию соберите доказательства, потом просите черновик:

Исследуй только модуль возвратов в Commerce OS.
Верни:
- список файлов, которые формируют поток возврата,
- связанные тесты,
- конфиги,
- открытые вопросы.
Не пиши документацию, только собери источники.

В основную сессию попадает не сырой поиск, а короткая проверяемая выжимка. Claude пишет из подготовленного набора источников, а не «с головы».

5. Превращаем API_MAP.md в живую документацию

API_MAP.md — один из самых полезных артефактов уровня. Но сам по себе он остается картой: компактной, технической, сухой. Документация делает следующий шаг — превращает карту в маршрут. Не «вот эндпоинт», а «вот как через него проходит сценарий и на что смотреть».

Из карты API можно собрать такой фрагмент:

# Поток возврата средств

Запрос на возврат создается через `POST /api/orders/{id}/refund`.
Обработчик находится в `OrderController.java`, после чего управление
передается в `RefundService#createRequest`.

Если сумма возврата превышает лимит ручного одобрения, заявка не
исполняется сразу и получает статус `PENDING_REFUND_REVIEW`.

## Что проверено
- `API_MAP.md`
- `src/orders/OrderController.java`
- `src/refunds/RefundService.java`
- `src/test/java/.../RefundServiceTest.java`

Это уже не список эндпоинтов, а документ, отвечающий на конкретный вопрос: «Как устроен возврат средств?» Раздел «Что проверено» — не украшение, он показывает, на чем текст стоит. Поменяли поведение RefundService — сразу видно, какой документ обновлять. Reviewer читает docs/refund-flow.md и может не верить на слово, а открыть исходники.

6. README и команды запуска: самое частое вранье

Документация по запуску устаревает первой: команды меняются быстрее README. Поэтому setup-разделы звучат правдоподобно и подводят на первом же шаге.

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

Текст предлагает npm run start, а package.json знает только npm run dev — это не спор о стиле, а ошибка в документации. Для черновика хватит: Claude соберет структуру раздела «Локальный запуск» и список кандидатов на команды. Статус «это работает» текст получает только после проверки по build.gradle, package.json, application.yml и реальному запуску.

7. Документация в коде и архитектурные заметки

Кроме README.md есть короткие комментарии рядом с кодом и небольшие архитектурные заметки. Их читают в момент работы, а не «когда-нибудь потом». И они особенно легко скатываются в вранье — кажутся маленькими и безобидными.

Нормальная докстрока для метода в модуле возвратов:

/**
 * Создает заявку на возврат и переводит ее в ручную проверку,
 * если сумма превышает лимит одобрения.
 *
 * @param orderId идентификатор заказа
 * @param amount сумма возврата
 * @return созданная заявка на возврат
 */
public RefundRequest createRequest(Long orderId, BigDecimal amount) {

Она описывает наблюдаемое поведение и не обещает лишнего — никаких мифов про «гибкий интеллектуальный движок возвратов нового поколения».

С архитектурными заметками осторожнее: они звучат солидно и потому легко становятся слишком смелыми. Не уверены — напишите это прямо:

## Предположения
Мобильный клиент, вероятно, использует тот же endpoint возврата, но это
не подтверждено кодом текущего репозитория.

## Ограничения
Локальная среда не получает реальные webhook-события от платежного
провайдера, поэтому этот этап проверяется отдельно.

Такая честность делает текст сильнее. Документация не обязана изображать всеведение — ее задача передавать проверенное знание и явно отмечать границы.

8. Честный фрагмент документации для Commerce OS

Соберем все вместе в один короткий, но взрослый пример. Вы закончили исследование потока возврата и хотите положить в репозиторий документ, который через месяц можно открыть без слез:

# Возвраты в Commerce OS

Запрос на возврат создается через `POST /api/orders/{id}/refund`.
HTTP-запрос принимает `OrderController`, после чего управление
передается в `RefundService`.

Если сумма возврата превышает лимит ручного одобрения, заявка
не исполняется сразу и получает статус `PENDING_REFUND_REVIEW`.

Для локальной проверки используйте `RefundServiceTest` и запуск backend
через `./gradlew bootRun`.

## Источники
- `API_MAP.md`
- `src/orders/OrderController.java`
- `src/refunds/RefundService.java`
- `src/test/java/.../RefundServiceTest.java`

## Ограничения
Webhook от платежного провайдера в локальной среде не приходит автоматически.

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