Сижу перед пустым документом. Надо написать раздел API Reference на 2000 слов. Сроки горят, документация никогда не бывает интересной, и делать её хочется меньше всего на свете. Знакомо?
У меня такая история повторяется регулярно. Примерно полгода назад я перестал с этим бороться и просто начал использовать Claude как черновик-машину. Не как замену думанию — а как инструмент для нудной работы, которую раньше откладывал до последнего.
Результат: скорость выросла примерно втрое. Но появились и грабли, о которых раньше не думал. Расскажу что работает, а что нет.
Что Claude делает хорошо
Структура. Это скучная задача, но она отнимает уйму времени, когда сидишь и думаешь «а правильно ли я разбил главы?». Кидаю Клоду кусок кода или описание фичи и прошу: «Предложи структуру документа. Вот что пользователь должен понять на выходе». Он выдаёт логичную иерархию за десять секунд.
Черновики описаний для эндпоинтов, функций, параметров. Особенно когда у меня уже есть комментарии в коде или сигнатура функции. Клод превращает это в читаемый текст. Не идеальный, но достаточный, чтобы потом отредактировать за двадцать минут вместо двух часов.
Примеры кода. Тут у меня отношение двойственное. С одной стороны, Клод пишет примеры быстро и они обычно синтаксически верные. С другой — он любит добавлять «идеальный» код, который в продакшене не работает. Про это отдельно скажу.
Перевод с английского на русский. Не идеальный машинный перевод, а адаптацию. Когда есть английская документация и нужен русский вариант — Клод справляется лучше любого переводчика, потому что понимает контекст.
Простая схема, которая у меня прижилась
Сначала пишу сам. Краткое описание фичи, список параметров, пара примеров. Это «скелет». Без красоты, без объяснений — просто факты.
Потом кидаю это Клоду с инструкцией: «Напиши документацию для этого API-эндпоинта. Используй такой-то стиль. Вот примеры наших существующих документов для ориентира». Он генерирует текст.
Дальше — правлю. Убираю канцелярит, добавляю детали, которых Клод не знает, потому что они есть только у меня в голове. Проверяю каждый факт.
Последний этап — вычитка на живом пользователе. Обычно это кто-то из команды, кто видит продукт с другой стороны. Клод не знает, что пользователи постоянно путают эти два поля. Он не знает, что баг в пятом эндпоинте ещё не пофиксили. Это ложится на мою ответственность.
Галлюцинации — главная проблема
Клод иногда уверенно пишет вещи, которых нет. Параметр, которого нет в API. Формат ответа, который не существует. Версию, которая ещё не вышла. Это не враньё в человеческом смысле — он просто генерирует правдоподобный текст.
Как я с этим справляюсь. Никогда не публикую сгенерированный текст без сверки с кодом. Если Клод написал, что параметр timeout принимает значение в миллисекундах, а в коде он в секундах — это моя ошибка, не его. Для каждого эндпоинта у меня есть контрольный список: параметры, типы, формат ответа, коды ошибок. Сверяю каждую строчку.
И ещё: не генерирую документацию по памяти. Всегда работаю с актуальным кодом, OpenAPI-спецификацией или описанием задачи. Если дать Клоду устаревшую информацию, он добросовестно превратит её в красивый документ с ошибками.
Три приёма, которые реально помогают
System prompt с примером, а не с инструкцией. Не «пиши в деловом стиле», а «вот три страницы нашей существующей документации, которая тебе нравится. Пиши так же». Качество скачет вверх разительно.
Итерации. Первый черновик почти всегда сырой. Кидаю обратно с правками: «короче», «добавь больше про обработку ошибок», «убери канцелярит». На второй-третьей итерации получается прилично.
Разделение задач. Для одного и того же документа прошу Клода отдельно сгенерировать описание, отдельно примеры кода, отдельно раздел про ошибки. Потом собираю сам. Когда прошу всё сразу — получается хуже.
Что Клод не заменит
Контекст продукта. Клод не знает, что документацию читают люди, которые уже работали с нашим API и знают базовые вещи. Что у нас своя терминология. Что один раздел ссылается на другой. Это моё.
Редактуру последнего круга. Механическая проверка фактов — это я. Проверка на понятность — тоже я, потому что я знаю свою аудиторию.
Ответственность. Если в документации ошибка — это моя ответственность. Клод не виноват, даже если сгенерировал полную чушь.
Итого
Клод для технической документации — это мощный ускоритель для нудной работы. Скелет, черновик, первый проход — всё это он делает быстро и приемлемо. Но доверять ему слепо нельзя. Факты, типы данных, версии — это надо проверять руками.
Главное, что я для себя понял: Клод не делает меня хуже как техписа. Он делает быстрее рутину. Мой мозг остаётся для того, что требует контекста и ответственности. И это, как ни странно, честное разделение.
