Сижу перед пустым файлом README.md. Проект на 40 тысяч строк кода, коммиты с 2019 года, а документации — ноль. Команда просит хотя бы краткое описание API. Открываю Claude, пишу первое, что приходит в голову: «Напиши документацию к моему проекту». На выходе — красивый, уверенный текст. Полностью выдуманный. Класс.
С тех пор прошло несколько проектов, и я понял кое-что важное: Claude отлично пишет техдокументацию, но только если сам знаешь, чего хочешь. Без нормального промпта он генерирует красивые абстракции, которые ничего не значат для тех, кто будет это читать. Поделюсь тем, что у меня наконец заработало.
Сначала — контекст, потом — формат
Главная ошибка, которую я совершал — пытался получить готовый документ одним промптом. Типа: «Напиши docs для REST API». Это не работает. Ну, работает, но на выходе получается текст уровня маркетингового лендинга.
Что реально работает: дать Claude прочитать код или схему данных и попросить описать конкретные эндпойнты, функции, параметры. Без этого он просто фантазирует.
Мой рабочий процесс сейчас выглядит примерно так. Сначала — файл с кодом целиком. Потом промпт: «Вот функция, которая делает X. Напиши для неё docstring в стиле Google. Объясни, какие параметры обязательные, какие опциональные, какие исключения может выбросить». И вот это он делает отлично — потому что видит реальный код и работает с ним.
Для API-спецификаций я скармливаю ему примеры запросов и ответов, которые уже точно работают. Потом прошу сгенерировать документацию по каждому эндпойнту. Получается значительно лучше, чем если бы я диктовал ему «у нас есть эндпойнт /users, он принимает JSON».
Промпты, которые у меня прижились
Несколько шаблонов, которые я копирую из проекта в проект.
Для docstring:
Вот функция на Python [вставляю код]. Напиши docstring в стиле Google. Укажи:
- что функция делает
- какие аргументы и их типы
- что возвращает
- какие исключения может выбросить
- пример использования
Для описания API:
На основе этих примеров запросов и ответов [вставляю curl-команды или JSON] напиши описание каждого эндпойнта в формате:
- метод и путь
- краткое описание
- параметры запроса (имя, тип, обязательность, описание)
- тело запроса (если есть)
- формат ответа
- коды ошибок
Для README:
Проект [вставляю структуру файлов и краткое описание]. Напиши README, который включает:
- что это и зачем
- как установить и запустить
- базовые примеры использования
- структуру проекта
- требования
Не добавляй ничего, чего нет в коде.
Последняя строчка критична. Без неё Claude обязательно добавит описание фич, которых у тебя нет, или сгенерирует команду установки, которая не работает.
Где Claude реально экономит время
Структура и черновики. Я могу час сидеть и думать, как организовать документацию. А можно за 10 минут получить три варианта структуры, выбрать лучший и доработать.
Перевод с английского на русский. Код у меня на английском, комментарии на английском, а документация нужна на русском. Claude переводит описания функций и эндпойнтов заметно лучше, чем Google Translate, — сохраняет контекст и не переводит названия переменных.
Генерация примеров кода. Берёшь описание эндпойнта и просишь: «Дай пример вызова на Python, curl и JavaScript». Получаешь три рабочих примера за минуту. Это экономит уйму времени, если сам не пишешь на всех этих языках.
Форматирование. Попросил — и таблица параметров уже красиво свёрстана в Markdown. Просишь добавить схему, диаграмму последовательности в текстовом виде — справляется. Не идеально, но как отправная точка — норм.
Где я наступил на грабли
Один раз я попросил Claude описать архитектуру проекта, который плохо знал сам. Результат выглядел убедительно и грамотно, но был наполовину выдуман. Я чуть не опубликовал это как официальную документацию. С тех пор правило простое: нельзя документировать то, чего не понимаешь сам, даже если ИИ это красиво описал.
Ещё проблема — устаревание. Claude не знает, что ты изменил в коде. Каждый раз надо подсовывать актуальную версию, иначе документация расходится с реальностью. Никакой магии.
И третья штука — стиль. Первое поколение текста всегда слишком формальное и водянистое. Я обычно прошу: «Перепиши короче, без канцелярита, как будто объясняешь коллеге в чате». После этого текст реально читабельный.
Коротко
Claude не заменит технического автора. Но если нужно быстро получить черновик, сгенерировать docstring по реальному коду, перевести описания или набросать структуру — он очень помогает. Ключевое: давай ему код и факты, а не абстрактные инструкции. И всегда проверяй, потому что он уверенно пишет и про то, чего не знает.
Для меня это теперь стандартный этап в работе. Сначала пишу код, потом кидаю в Claude и прошу сгенерировать черновик документа. Дорабатываю — и готово. Экономит часа два на каждый модуль, не меньше.
