«Снова docstring в три слова», — сказал я вслух, глядя на сгенерированный код. Проблема была понятна: кодеры не пишут документацию, потому что это скучно и долго. Я тоже так делал, пока не попробовал делегировать это Claude.
Этот пост — не обзор возможностей и не гайд «как правильно». Это история о том, что у меня заработало, где я обжёгся и какой подход я использую сейчас.
С чего я начал: базовый запрос
Сначала было просто. Берём код, кидаем в чат, просим: «Напиши документацию». Работает? Работает. Но ровно до того момента, пока задача не станет чуть сложнее одной функции.
Проблема базового подхода: Claude генерирует текст, который звучит как документация, но без контекста — зачем это нужно, когда использовать, какие есть подводные камни. Получается описание сигнатуры функции, обёрнутое в маркдаун.
# ПЛОХО — результат наивного запроса
def calculate_discount(price, discount_percent):
"""Calculate the discount amount."""
return price * discount_percent / 100
Documentation? Технически — да. Полезна? Нет.
Что изменилось, когда я добавил контекст
Я начал давать Claude три вещи перед каждой задачей.
Роль и аудиторию. Не «напиши документацию», а «ты — технический писатель, который документирует внутренний API для фронтенд-команды. Пиши кратко, без общих фраз, с примерами кода».
Формат вывода. «Выведи в формате: описание → параметры → возвращаемое значение → примеры → known issues».
Референсы. Если уже есть документация по похожей функции — дать ссылку на неё и попросить придерживаться того же стиля.
Дельта — ощутимая. Когда я даю Claude существующий файл docs/auth.md и прошу написать docs/payments.md в том же стиле — результат в разы лучше, чем изолированная генерация.
Три сценария, где Claude реально помогает
1. API-документация
Я взял эндпоинты своего микросервиса (swagger JSON), скормил Claude и попросил сгенерировать документацию для каждого роута. Выдал описания параметров, коды ошибок, примеры запросов в curl и Python.
Потом прошёлся руками — поправил формулировки, убрал неточности в описании бизнес-логики. Claude сэкономил мне час механической работы.
2. Внутренние воркфлоу и runbook'и
Вот где Claude подкупает. Написать «как задеплоить релиз» — скучно, но нужно. Я даю Claude схему: шаг 1 → шаг 2 → шаг 3, указываю где что лежит, прошу описать каждый шаг. Потом дополняю секцией «если что-то пошло не так».
Важно: я никогда не про
