Сижу над README.md третий час. Двести строк, половина ссылок битые, коллеги из второго спринта уже просят добавить секцию про безопасность. Мне бы писать, а я думаю: может, за меня напишет кто-то умный и молчаливый.
Кто-то умный и молчаливый — это Claude. За последние полгода я перепробовал разные подходы к работе с ним на документационных задачах. Что-то реально зашло, что-то сожгло миллион токенов впустую. Делюсь тем, что выработал.
С чем Claude справляется на раз
Клод хорош в двух вещах: структурировать хаос и переводить с инженерного на человеческий.
Когда мне дают задачу типа "напиши доку по нашему API для клиентов", у меня обычно есть набор эндпоинтов, описание параметров и каша в голове. Я кидаю Клоду весь JSON или Swagger-спеку и прошу разбить это на логические разделы, предложить структуру. Он выдаёт скелет за пару минут. Я его правлю, добавляю нюансы, граничные случаи, known issues — то, что знаю только я. Это быстрее, чем садиться с чистого листа.
Дальше — объяснения. Берёшь кусок кода или конфига и просишь объяснить так, чтобы понял продукт-менеджер. Клод умеет держать этот уровень. Не идеально, но как отправная точка — норм. Обычно я потом переписываю каждую вторую фразу, зато черновой вариант готов за секунды, а не за час.
И таблицы. Сравнительные таблицы фич, матрицы поддержки браузеров, таблицы совместимости версий. Клод делает это чисто, и в Markdown выглядит прилично. Раньше я рисовал их руками и тратил на это непропорционально много времени.
Где всё ломается
Настоящий косяк начинается, когда просишь Клода написать полную документацию с нуля. Он выдаёт красивый, уверенный текст — и при этом может выдумывать детали, которых нет. Не специально, просто он генерирует правдоподобный контент. Читаешь и думаешь: да, логично, так и есть. Проверяешь — а там другая версия библиотеки, и половина параметров называются иначе.
Я для себя ввёл правило: Клод пишет, я проверяю факты. Числа, названия, версии, ссылки — всё. Клод может придумать название параметра, которое звучит правдоподобно, но не существует. Это не баг, это его природа.
С длинными документами тоже проблема. Когда просишь написать развёрнутый guide на 3000 слов, Клод начинает повторяться. Появляются параграфы, которые по смыслу почти идентичны, просто другие слова. Ближе к концу чувствуется, что автор выдохся и стал накидывать воду. Я заметил, что оптимальный кусок — до 800–1000 слов одним запросом. Потом бьёшь на секции и собираешь.
Как я сейчас работаю
Допустим, задача — документация для нового сервиса аутентификации.
Сначала собираю входные данные. Код, схема API, требования, протоколы. Кидаю всё в один большой промпт и прошу описать структуру документа. Не писать текст, а показать скелет.
Потом правлю этот скелет. Убираю лишнее, добавляю то, что Клод не мог знать — организационные детали, процессы, нюансы развёртывания.
На практике генерация секций по одной работает лучше всего. По каждому разделу — отдельный запрос. Параметры, ошибки, примеры — всё отдельно. Это дольше, чем один большой запрос, но результат чище и меньше галлюцинаций.
Дальше — сборка и редактура. Склеиваю секции, убираю повторы, прохожусь по стилю. Тут обычно замечаю, что Клод любит длинные предложения с кучей уточнений. Упрощаю.
Последний этап — проверка фактов. Код-примеры запускаю. Ссылки открываю. Названия параметров сличаю с исходниками.
На выходе — документ, который я написал на 60%, а Клод — на 40%. И мне не стыдно.
Что стоит попробовать
Если у тебя есть документация на английском и нужна русская версия — проси Клода не переводить, а адаптировать. Скажи: переведи так, чтобы звучало естественно, не как перевод. Результат обычно лучше, чем Google Translate.
Если у тебя мешанина из Confluence, Notion и старых README — попроси Клода нормализовать структуру. Дай ему всё что есть и скажи: это зоопарк, приведи к единому стилю и логичной структуре. Не идеал, но отправная точка.
Коротко
Клод не заменит технического писателя. Он заменит первый час мучительного взгляда в пустой экран. Он хороший помощник для черновиков, структур, объяснений и таблиц. Но факты за ним никто не проверяет, и это не мелочь.
Мой подход: дать ему скелет, поправить скелет, заполнить секции по одной, проверить всё самому. Это не волшебство, просто ускоряет рутину. А рутина с README — не та работа, ради которой стоит сидеть до полуночи.
