«Третий раз переписываю раздел API — и каждый раз получается либо слишком формально, либо слишком размыто», — пожаловался я в чат коллеге. Он ответил: «А ты через Клода генерируй, а потом редактируй руками». Звучало как капитуляция. Но я попробовал — и оказалось, что это рабочая схема, если понимать, где Claude реально помогает, а где начинает врать с той же уверенностью, что и хороший разработчик на планёрке.
С тех пор прошло несколько месяцев. Я набил шишек, нашёл приёмы, которые работают, и понял, откуда берутся те ужасные docs, которые все ненавидят читать.
Главное — правильно поставить задачу
Самая частая ошибка: дать Claude короткий промпт и ждать чуда. «Напиши документацию для API» — это не задача, это мечта. Claude сгенерирует текст, который выглядит как документация, но будет напичкан неточностями и обобщениями.
Что работает: контекст плюс ограничения плюс формат.
Я даю Claude не только описание функции, но и контекст — кто будет это читать (новый разработчик в команде? внешний партнёр? сам автор через полгода?), какие решения уже приняты, что НЕ нужно описывать. Например: «Это внутренняя документация для команды, которая уже знает концепцию. Не объясняй базовые вещи. Фокус — на edge cases и известные подводные камни.»
Чем точнее контекст, тем меньше потом переписываешь.
Где Claude реально хорош
Первое — черновики структуры. Я даю Claude кучу сырых заметок, ссылок на код, комментариев из issue tracker и прочего мусора, который накопился за проект. Он умеет вытащить из этого логичную структуру. Не идеальную, но отправную точку — уже неплохо.
Второе — перевод с кода на русский. Когда у меня есть метод с пятью параметрами и описанием в одну строку, я прошу Claude раскрыть: что делает каждый параметр, какие значения принимает, что будет, если передать null. Получается первая версия docstring. Потом я читаю, правлю — но черновик уже есть.
Третье — адаптация тона. У меня бывает документ, где часть написана сухим языком стандарта, а часть — в спешке написанными комментариями в стиле «и тут магия». Прошу Claude привести к единому стилю — и он справляется, если объясню, какой стиль нужен. Без объяснения делает среднее между всем, что хуже обоих вариантов.
Четвёртое — список вопросов. После черновика прошу: «Перечисли 10 вещей, которые непонятны из этого текста человеку, который не участвовал в разработке». Это работает как чеклист для редактора — иногда находишь лакуны, которые сам пропустил.
Где Claude опасен
Документация — это факты. И здесь Claude подводит. Он генерирует текст, который звучит убедительно, но может содержать:
- устаревшие сведения о версиях и зависимостях
- описания поведения, которые не соответствуют реальному коду
- ссылки на несуществующие разделы
- названия параметров, которые ты выдумал, а он подхватил как данность
Проблема в том, что текст выглядит готовым. Короткие предложения, уверенный тон, структурированно — гладенько. Именно так выглядит качественная документация. И именно поэтому так легко пропустить ошибку.
Поэтому я всегда прошу его указать, где он не уверен. Прямо в промпте: «Если ты не уверен в каком-то утверждении — напиши "uncertain" рядом с ним». Не всё работает, но часть таких пометок реально спасает.
Пример рабочего процесса
Покажу на реальном примере — мне нужно было описать систему авторизации для нашего проекта.
Сначала я скормил Claude всё: схему базы данных, swagger-файл, комментарии из кода, несколько старых issue от сапорта, где люди спрашивали «как войти если...». Попросил сгенерировать оглавление.
Он предложил пять разделов. Я поправил порядок, убрал один (был про OAuth в целом — не нужно), добавил другой (про логирование ошибок).
Дальше — по секциям. Каждую секцию писал отдельно. Промпт выглядел примерно так: «Напиши раздел про refresh-токены. Целевая аудитория — разработчики, которые будут интегрировать наш API. Предполагаемый уровень — middle. Опиши только наш конкретный механизм, без общей теории OAuth. Упомяни: время жизни токена, процедуру ротации, что происходит при компрометации. Тон — нейтральный, без шуток, без длинных вводных абзацев.»
Получился текст, где треть — близко к финальному варианту, треть — требовала правки, треть — я просто выкинул и переписал с нуля. Это нормальная пропорция.
Потом попросил пройтись по всему документу и пометить места, где логика прыгает резко. Он нашёл два перехода, где мы объясняли А, потом Б, а потом возвращались к А — я поправил.
Что я понял за это время
Claude — это ускоритель для черновой работы. Не для финального текста. Он хорошо делает первичный набросок, вытаскивает структуру из хаоса, находит дыры в логике. Но итоговый текст должен проходить через человека, который знает контекст.
Второе: документация, сгенерированная целиком, почти всегда хуже, чем документация, где LLM — помощник. Когда я прошу «напиши всю документацию для модуля X», результат формально хорош, но не отвечает на реальные вопросы. Когда прошу «напиши черновик раздела про Y, а потом я буду задавать вопросы и править» — выходит в разы лучше.
Третье: проверяй код и ссылки, которые он упоминает. Это самое скучное, но самое важное. Один раз я пропустил строчку, где Claude описал несуществующий эндпоинт — и через неделю мне пришёл вопрос от разработчика, который потратил два часа, пытаясь его найти.
Вместо вывода
Документация — это не побочный продукт разработки. Это часть интерфейса. И как с любым интерфейсом — с ней либо больно, либо удобно. Claude может помочь писать больше и быстрее. Но быстрее и больше — не значит лучше. Пока что лучше всё равно получается с живым глазом и руками.
Если хочешь, чтобы я разобрал что-то конкретнее — промпты, структуру, отдельные форматы — пиши, разберём.
