Сижу писать документацию к API, которую уже полгода откладывал. Дедлайн в понедельник, страниц на сорок, половину сам уже не помню зачем делал. Беру чай, открываю файл — и зависаю на первом предложении. «Данный эндпоинт предоставляет возможность...» — нет. «Сервис позволяет...» — тоже нет. Стираю, снова набираю. На третьей попытке ловлю себя на мысли: а может, пусть Клод напишет черновик, а я потом причешу?
Так я начал разбираться, где Claude реально помогает, а где превращается в генератор бессмысленных фраз про «ключевые преимущества» и «интуитивно понятный интерфейс».
Что реально получается хорошо
Первое — превратить хаос из issues, коммитов и устных объяснений в связный текст. Берёшь десяток коммитов, описываешь что делал, и просишь: «Напиши раздел про аутентификацию. Пользователь должен понять, как это работает, не читая код». Клод выдаёт черновик, где есть логика, последовательность шагов и хоть какая-то драма — «сначала так, потом эдак, иначе сломается».
Второе — примеры кода. Тут он реально хорош. Даёшь сигнатуру функции и просишь: «Три примера — базовый, с обработкой ошибок, edge case с пустым входом». Минута работы, полчаса экономии.
Третье — структура. «Организуй документацию: overview → getting started → API reference → troubleshooting». Он выдаёт скелет, который остаётся только заполнить. Скучная работа, и отдать её роботу — правильное решение.
Где всё ломается
Но вот что я понял после пары десятков страниц: Клод не понимает, для кого пишешь. Генерирует текст, который звучит как документация, но не работает как документация.
Типичная проблема — он пишет «система поддерживает аутентификацию OAuth 2.0» вместо «чтобы авторизоваться, передай токен в заголовке Authorization: Bearer
Ещё хуже с описанием ошибок. Клод любит писать «в случае ошибки система вернёт соответствующий код», а не «если забыл передать user_id, получишь 400 с телом {"error": "user_id is required"}». Конкретику приходится добавлять руками.
Третий косяк — голос. Клод пишет «для начала работы необходимо выполнить следующие шаги», а не «сначала создайте проект. Без проекта ничего не выйдет — всё упадёт с 401». Живой язык исчезает на второй странице, и текст начинает читаться как инструкция к микроволновке.
Как я теперь работаю
Схема простая. Сначала прошу Клода сгенерировать черновик — быстро, даёт скелет. Потом беру текст и делаю три вещи.
Вырезаю всё, что звучит как бюрократия: «следует отметить», «необходимо подчеркнуть», «важно учитывать». Этот мусор лезет автоматически, я вычищаю на раз.
Заменяю абстракции на конкретику. Каждое «система делает X» превращается в «GET /users вернёт массив объектов, где каждый содержит id, name, email». Нет id, name, email — это не документация, а мнение.
Добавляю то, чего Клод не знает. Историю решений: почему сделали так, а не иначе. Граничные случаи, обнаруженные в продакшене, а не в документации. Предупреждения, которые спасут кому-то час отладки.
Пример промпта, который сработал
Вот промпт, от которого я получил приличный черновик раздела про rate limiting:
Напиши раздел документации про rate limiting.
Аудитория — разработчики, которые интегрируют наше API.
Формат: проблема → как работает → как обрабатывать.
Упомяни: лимиты по умолчанию (100 req/min), что возвращает API при превышении (429 + Retry-After), как отличить глобальный лимит от per-endpoint.
Тон: деловой, без воды. Примеры — в curl.
«Тон: деловой, без воды» и конкретные пункты — ключевое. Чем точнее промпт, тем меньше правок потом.
Что в итоге
Клод — отличный первый черновик. Не устаёт, не ворчит, не болеет. Но документация — это не только текст. Это модель того, как пользователь будет думать о твоей системе. И эту модель Клод не выстроит: он не знает, какой вопрос задаст разработчик в три часа ночи, когда всё сломалось. Не знает, что человек перепробовал три варианта, прежде чем открыть документацию.
Теперь воспринимаю Клода как продвинутый автозаполнитель. С ним быстрее. Но последнее слово — моё. Иначе получается текст, который выглядит как документация, а читается как рекламный буклет.
