Три месяца назад я смотрел на пустую страницу документа API, которую нужно было заполнить за неделю. Сорок эндпоинтов, из них половина — без единого коммента в коде. Я уже открыл чат с Клодом, но вместо того чтобы просто попросить «напиши документацию», потратил вечер на эксперименты. Результат — время на доку претью сократилось вдвое, а качество даже выросло. Вот что я понял.
Первое, что я делаю не так, как все
Большинство начинают с «напиши документацию для моего API». И получают generic текст уровня «этот метод принимает параметр и возвращает значение». Бесполезно.
Я вместо этого даю Клоду контекст: кто будет читать этот документ, какую задачу он решает, что ему нужно понять через пять минут. Одна фраза вначале — и результат меняется кардинально.
«Напиши руководство для фронтенд-разработчика, который впервые видит наш бэкенд. Ему нужно за день поднять авторизацию и начать работу с основными сущностями. Никаких подробностей про внутреннее устройство базы — только API-контракты и типичные кейсы использования.»
Видишь разницу? Клод не просто описывает эндпоинты — он выстраивает повествование. Объясняет логику, а не только синтаксис.
Как я генерирую описания эндпоинтов за пять минут
Беру Swagger или OpenAPI спеку — она обычно лежит в репозитории — и кидаю Клоду целиком. Потом говорю что-то вроде: «Для каждого эндпоинта напиши: краткое описание (1 предложение), список параметров с типами и пояснениями, формат ответа, код примера на Python и типичную ошибку, которую допускают новички.»
Это занимает минуту на описание промпта и пять минут на выдачу. То, что раньше я писал вручную два дня.
Иногда спека кривая — параметры без описаний, enum-значения без контекста. Клод в таких случаях честно пишет «недостаточно данных для пояснения этого поля». Я обычно прошу его сделать предположения и отметить их явно — «предполагаю что field_id это UUID, уточни если иначе». Потом сам проверяю. Работает лучше, чем когда ИИ просто выдумывает.
Сценарии — это не то, чем я занимаюсь
Сначала я думал: напишу документацию — и всё. Потом понял, что хорошая техдока — это сценарии, а не список функций.
Клод в этом плане удобный. Я прошу его: «Придумай пять сценариев использования этого API. Для каждого — пошаговый путь: какие вызовы делать, в каком порядке, какой результат ожидать.» И он выдаёт связные цепочки, которые покрывают основные юзкейсы.
Не идеально — иногда пропускает edge cases, иногда предлагает сценарий, который невозможен из-за бизнес-логики. Но как стартовая точка — быстро и неплохо. Я обычно беру три из пяти, дорабатываю, добавляю свои.
Где Клод реально экономит время
Перевод с английского на русский. Не литературный перевод — а адаптация. Я кидаю английскую документацию и прошу: «Переведи, но адаптируй под русскоязычную аудиторию. Убери кальки, замени американизмы на понятные русские термины, добавь пояснения где термин не имеет прямого перевода.» Результат читается как написанное русским человеком, а не как машинный перевод.
Ещё — ревью своей же документации. Я пишу текст, кидаю Клоду и прошу: «Найди места, где непонятно. Где читатель может запутаться. Где терминология скачет без пояснений. Где кодовый пример не соответствует описанию.» Он честно указывает на косяки, которые я пропустил.
Чего я не делаю с Клодом
Не прошу его написать документацию с нуля по одному названию функции. Результат будет бессодержательным. Техническая документация — это контекст. Без него Клод генерирует текст, который выглядит как документация, но не работает как документация.
Не доверяю ему описания бизнес-логики. Если эндпоинт делает что-то неочевидное — я сам пишу, Клод потом только оформляет. Иначе рискуешь получить описание того, что эндпоинт делает по мнению Клода, а не того, что он реально делает.
Не использую его выход как финальный текст. Всегда прогоняю через себя. Текст, который отдаёт Клод — это черновик, который нужно проверить, поправить акценты и убрать местами формальность.
Коротко: что я делаю теперь
Даю Клоду спеку и контекст — получаю черновик описаний. Пишу сценарии сам, Клод помогает оформить. Потом ревью через Клода — и финальная проверка мной.
Раньше один документ занимал два-три дня. Теперь — полтора дня, из которых половина — моя ручная работа, половина — Клод. И доку получается лучше, потому что у меня появляется время на сценарии и структуру, а не только на описание параметров.
Если у тебя есть конкретная задача — кидай спеку, расскажи контекст, попробуем.
