Документация — это такая штука, которую все ненавидят писать, но все ценят, когда она есть. Я на днях полез в API чужого сервиса и полтора часа убил на разбор того, что можно было понять за 15 минут, если бы кто-то нормально описал авторизацию. После этого решил: надо разобраться, как использовать Claude для написания документации, и заодно рассказать, что из этого реально работает.
Почему Claude вообще имеет смысл для документации
Большинство моих попыток использовать ИИ для документирования раньше разбивались об одно и то же: модель выдавала красивые, но бесполезные тексты. «Система обеспечивает высокую производительность и надёжность» — спасибо, теперь понятно.
Проблема в том, что я просил слишком абстрактно. Стоило научиться формулировать задачу конкретно — и результат изменился радикально.
Возьмём пример. Нужно было задокументировать REST API для небольшого сервиса. Раньше я бы просто написал: «Напиши документацию для этого API». Сейчас делаю иначе — даю описание эндпоинтов, примеры запросов и сразу говорю, для какой аудитории это пишется. Разница огромная.
Что реально делает Claude хорошо
Он отлично генерирует шаблоны и черновики, которые потом можно править. Дал ему кусок кода или описание фичи — он выдаёт структуру раздела: описание, параметры, примеры, возможные ошибки. Это не готовый текст, а каркас, который экономит 40–60% времени.
Он переводит между форматами. Берёшь документацию в Markdown, просишь переделать в OpenAPI-спецификацию или в формат Read the Docs. Справляется лучше, чем я ожидал, хотя иногда теряет нюансы.
Он находит дыры. Берёшь готовый документ и просишь: «Найди места, где пользователю будет непонятно, что делать дальше». Иногда указывает на очевидные вещи, но примерно в трети случаев вылавливает реальные лакуны.
Ещё он держит стиль. Если у тебя есть гайд по стилю, можно сказать: «Пиши в этом тоне, избегай этих слов». Работает не идеально, но значительно лучше, чем потом править весь документ вручную.
Конкретный промпт, который использую
Шаблон, который даёт результат, а не воду:
Напиши раздел документации для [название API/фичи]. Аудитория: [кто будет это читать — разработчики, админы, конечные пользователи]. Что нужно объяснить: [конкретно что делает, какие входные данные, что возвращает]. Формат: [Markdown, с примерами кода и описанием ошибок]. Тон: [технический, но без жаргона / простой для новичков / строгий и точный]. Не включай: [список вещей, которые не нужны].
Поначалу я давал только первую строчку и удивлялся, почему снова «высокопроизводительный». Потом дошло: чем точнее контекст, тем ближе к нужному результату.
Где Claude косячит
Буду честен: есть места, где ему нельзя доверять.
Он выдумывает параметры API, которых нет. Описываешь реальный эндпоинт — а он может добавить поле id или created_at, которого в коде нет, и подать это как факт. Проверяй каждый пример.
Он не знает, как работает твой конкретный сервис. Общую структуру — да. Поведение edge cases, known issues, реальные ограничения — это ты знаешь лучше. Claude может описать идеальное поведение, но реальный продакшен он не видел.
Он генерирует уверенный бред. Особенно в технических деталях. Текст выглядит убедительно, но где-то пропущено условие или перепутаны единицы измерения. Поэтому любую документацию, созданную с его помощью, нужно ревьювить человеку, который реально в теме.
Ещё косяк: он любит добавлять секции, которые ему кажутся логичными, но тебе не нужны. «Безопасность», «Масштабируемость», «Производительность» — вставляет их куда попало. Приходится чистить.
Как выглядит мой рабочий процесс
Сначала пишу минимальный черновик сам — буквально тезисы: что делает фича, какие параметры, какие ошибки. Потом прошу Claude расширить и допилить конкретные разделы. Затем — другую модель (или себя же, но другим промптом) — проверить на противоречия и нестыковки.
Отдельно прошу найти места, где пользователь может застрять. Это оказалось ценнее, чем я думал. Claude часто видит эти места с непривычки, свежим взглядом.
Финальный этап — правка человеком, который знает систему. Без этого никуда.
Сколько времени это экономит
Замерял на одном проекте. Полная документация для API из 15 эндпоинтов раньше занимала два дня. С Claude — примерно полдня, из которых половина — ревью и правки. Не в четыре раза, как обещают маркетологи, но ощутимо. Особенно на первой версии, когда ещё не знаешь, как лучше структурировать.
На втором и третьем проекте стало быстрее: удачные промпты переиспользую, отработанные схемы уже есть.
Коротко
Claude полезен для документации, если не пытаться получить от него готовый текст. Он хороший ассистент — быстро делает черновики, переводит между форматами, находит дыры в логике. Но слепо доверять ему параметры и поведение продакшена нельзя. Реальный опыт использования продукта не заменит ничто.
Если есть конкретная задача по документированию — пишите в комментариях, что за проект, и разберёмся с промптом под вас.
