Я потратил несколько недель на то, чтобы переложить часть работы с документацией на Claude. Не "протестировал" — именно использовал в реальных задачах: README для нескольких проектов, API-справочник, внутренние гайды для команды. Расскажу честно, где это сэкономило время, а где пришлось переделывать.
Зачем вообще трогать то, что и так работает
У меня была стандартная проблема: документация пишется по остаточному принципу. Код готов, фича залита, дедлайн прошёл — и тут кто-то вспоминает, что надо бы описать, как это всё работает. Садишься, смотришь на экран, и вместо текста рождается что-то вроде "Функция processData() обрабатывает данные". Спасибо, очень помогло.
Я решил попробовать Claude не как замену себе, а как напарника, которому можно скинуть сырой материал и получить обратно что-то читаемое. Разница принципиальная: не "напиши мне документацию", а "вот мой черновик и код — помоги привести это в порядок".
Что реально работает
С чего я начал — переработка уже написанных кусков. Берёшь свой кривой черновик, скидываешь Claude вместе с контекстом ("это для разработчиков, которые подключают API впервые") и просишь выправить структуру и убрать двусмысленность. Результат стабильно лучше исходника. Не гениально, но чисто.
Дальше — генерация примеров кода. Я описываю сценарий использования, Claude пишет пример, я проверяю и правлю. Это быстрее, чем придумывать примеры с нуля, особенно когда нужно показать три-четыре разных случая применения одной функции.
Ещё одна вещь, которая меня удивила: Claude хорошо держит терминологию, если ты её один раз задал. В начале сессии я объяснял, как в проекте называются сущности — "у нас это не users, а participants" — и дальше он не путал. Мелочь, а экономит правки.
Где я обжёгся
Самый болезненный момент — точность. Claude уверенно пишет про поведение функций, которых не видел. Один раз я не проверил кусок про обработку ошибок — оказалось, описание было технически правдоподобным, но не соответствовало тому, как оно реально устроено в коде. Хорошо, что это заметил я, а не тот, кто будет читать документацию.
Вывод простой: Claude должен видеть код, про который пишет. Не пересказ, не "у нас есть функция, которая делает X" — а сам код. Тогда галлюцинаций заметно меньше.
Вторая проблема — стиль. Если не задать тон явно, получаешь корпоративный нейтральный текст, который технически верен, но читать его скучно. Я потратил час, пока не понял, что надо прямо писать в промпте: "пиши как опытный разработчик, который объясняет коллеге, без формальщины". После этого стало значительно лучше.
Как я выстроил процесс
Сейчас у меня примерно такой порядок. Сначала я пишу скелет — заголовки разделов и пару фраз о том, что должно быть в каждом. Это занимает 10-15 минут и стоит потраченного времени: иначе структура будет такой, какой её видит Claude, а не такой, какая нужна мне.
Потом скидываю в контекст скелет, релевантный код и коротко — кто будет читать этот документ. Прошу Claude заполнить разделы. Получаю черновик, который обычно процентов на 70 готов к использованию.
Оставшиеся 30% — это правки по точности (сверяю с кодом), правки по тону (убираю канцелярит, который всё равно пролезает) и добавление вещей, которые Claude не знает: внутренний контекст, решения по нетехническим причинам, известные ограничения.
На выходе документация получается быстрее раза в два-три. Не в десять, как иногда обещают, — но два-три уже ощутимо.
Один приём, который я не ожидал найти полезным
Я начал использовать Claude для проверки готовой документации с позиции новичка. Даю ему текст и прошу задать вопросы, которые возникнут у человека, читающего это впервые. Обычно вылезает три-пять вещей, которые я считал очевидными, но нигде не объяснил.
На практике это дешевле, чем просить живого коллегу прочитать черновик, и работает честно — Claude не знает, что "так исторически сложилось", поэтому задаёт именно те вопросы, которые задал бы новый человек в команде.
Документация всё равно остаётся моей ответственностью. Claude не знает, почему конкретная функция работает именно так, не помнит, что мы обсуждали на ретро три месяца назад, и не чувствует, где у читателя возникнет ступор. Но как инструмент для ускорения черновой работы и проверки структуры — вполне. Главное не ждать, что он сделает всё сам.
