Сижу вечером, дописываю API-референс для нашего внутреннего сервиса. Осталось три эндпоинта — скучные, рутинные, каждый по шаблону. Беру Клода, кидаю ему JSON-схему, прошу: «Сгенерируй секцию для DELETE /users/{id}». Он выдаёт текст за пять секунд. Читаю — вроде нормально, почти готово. Вставляю. И тут замечаю: он написал «Метод возвращает код 200 при успешном удалении».
Звучит логично, да? Вот только наш эндпоинт возвращает 204. Мелкая деталь, но в документации такие мелочи превращаются в ловушки для тех, кто будет по этой документации работать.
На этом моменте я обычно и начинаю объяснять, почему Клод для документации — штука полезная, но с нюансами.
Где Клод реально помогает
Сначала про хорошее, потому что хорошего всё-таки больше.
Каркас — это первое и главное. Если у меня есть сырые данные: схема, код, swagger-файл, простыня из комментариев в коде — Клод превращает это в читаемый текст за минуты. Я даю ему три эндпоинта и прошу описать параметры, формат запроса, коды ошибок. Он выдаёт структуру, я её правию. Это не магия — это ускорение рутины процентов на 40, может больше.
Ещё он хорошо работает с черновиками, где важен стиль. Иногда нужно объяснить не-техническому человеку, что делает сервис. Клод умеет переключаться с «технического» на «человеческий». Кидаю ему описание, прошу переписать для менеджеров проекта — и это обычно приемлемо с первого раза.
Перевод — отдельная история. У нас часть команды на английском, часть на русском. Клод переводит документацию между языками вполне сносно. Не идеально, но для черновика под ревью — достаточного качества.
Ну и обработка старой документации. Был у нас один файл, написанный лет восемь назад человеком, который любил канцелярит и обобщения. «Система предоставляет возможность осуществлять мониторинг состояния сущностей». Клод это переводит в нормальный русский без танцев с бубном. Не всегда идеально, но сносно.
Где я обжёгся
Теперь больное.
Ситуация с кодами ошибок, описанная выше — не единичный случай. Клод уверенно генерирует технические детали, которые не проверяет. Он может придумать параметр, которого нет. Или сказать, что метод принимает JSON, хотя на самом деле он принимает form-data. Или назвать несуществующий код ошибки. Особенно это заметно, когда он «додумывает» то, что ему не дали в контексте.
Правило, которое я для себя вывел: Клод генерирует текст, я проверяю факты. Он хорошо формулирует, я отвечаю за содержание. Если я ему не показал схему — он может напридумывать. Если показал — обычно не врёт, но может неправильно интерпретировать.
Второй косяк — повторяемость структуры. Когда прошу описать пять эндпоинтов, Клод выдаёт пять очень похожих текстов. Консистентность — это хорошо. Но читать такую документацию скучно. Живой автор обычно варьирует подачу, добавляет контекст, уточняет. Клод — нет. Он держит формат.
Третье — он не знает контекста проекта. Не знает, что «у нас это называется „карточка", а не „сущность"». Что у нас есть особенность с авторизацией, которую все знают, поэтому никто не документирует. Клод не умеет догадываться о том, что не написано в его контексте. Это приходится добавлять руками.
Как я сейчас работаю
Выработал для себя несколько приёмов.
Первый: всегда давать Клоду источник истины. Swagger-файл, схему, код — что-то конкретное. Не «напиши документацию для эндпоинта», а «вот схема, вот код, опиши на основе этого».
Второй: просить его сгенерировать факты отдельным списком, а текст — отдельно. Сначала пусть выдаст параметры и коды — я проверю, не напридумывал ли. Потом уже текст.
Третий: давать примеры того, как должен звучать текст. «Вот так пишет наш техписатель: [пример]. Сделай так же». Это реально работает — он ловит стиль.
Четвёртый: не просить сразу всё. Разбиваю на куски по три-пять эндпоинтов. Между итерациями перечитываю, правлю и даю фидбек — «тут слишком формально», «добавь про edge case», «параметр X опционален, подчеркни это».
Пятый: для нетривиальных вещей — сначала спрашиваю его как эксперта. «У меня есть сервис, который делает X. Как лучше всего это описать? Какие подводные камни упомянуть?» Он выдаёт структуру и вопросы, которые стоит осветить. Потом уже пишу на основе этого.
Стоит ли оно того
Для рутинной документации — однозначно да. Для типовых эндпоинтов, для обработки старых текстов, для переводов между языками — Клод экономит время. Не вдвое, но ощутимо.
Для документации, где важна точность и есть риск напридумывать, — использую как черновик, но не как источник истины.
Для документации, где важен голос и стиль, — можно взять за основу, но придётся править. Сильно править.
И главное: если выкладываете документацию вовне, проверяйте всё. Дважды. Клод — как стажёр, который много чего знает, но иногда уверенно несёт чушь. Полезный, но требующий контроля.
Напишите, если есть вопросы или свой опыт — интересно, как вы используете языковые модели для документации.
