Сижу над README для внутреннего инструмента — и понимаю, что написал уже три версии, ни одна не нравится. В первой слишком академично, во второй слишком коротко, третья вышла какой-то «для галочки». Решил попробовать Claude не как замену себе, а как собеседника, которому можно объяснить задачу и посмотреть что получится.
Получилось интереснее, чем я ожидал. Но не без граблей.
Первый барьер — объяснить контекст
Самая частая ошибка, которую я делал поначалу: кидать Claude голый запрос без контекста. «Напиши документацию для API авторизации» — и получаешь что-то максимально общее, что не подходит ни под один реальный проект.
Пришлось переучиться. Теперь я начинаю с мини-брифа: кто читатель (разработчик, который уже знает REST, но впервые видит нашу систему), какой формат нужен (короткий справочник, не туториал), что уже есть (схема эндпоинтов, пара примеров запросов). Когда есть этот минимум — качество сразу другое.
Ещё хорошо работает приём «покажи, не рассказывай». Я скидываю кусок кода или существующий раздел документации и говорю: «Продолжи в том же стиле, вот пример». Claude довольно точно держит тон, не начинает выдумывать от себя — по крайней мере, если пример достаточно конкретный.
Где он реально экономит время
Есть задачи, с которыми Claude справляется быстро и без вопросов. Структура — первая из них. Когда есть большой бесформенный кусок технического описания, я прошу разбить его на разделы с логикой «от общего к частному» или «от установки к использованию». Получаю скелет, который потом заполняю сам. Не всегда соглашаюсь с предложенным порядком, но он даёт точку отсчёта вместо чистого листа.
Вторая задача — расшифровка «птичьего языка». У меня в команде есть разработчик, который пишет комментарии к коду в стиле «инициализация дескриптора пространства имён объекта конфигурации». Я скидываю это Claude с просьбой объяснить проще, он справляется. Иногда теряется технический нюанс, и я его возвращаю руками — но 80% работы сделано.
Третья — примеры использования. Писать их вручную скучно и долго. Я описываю сценарий («разработчик хочет получить список пользователей с фильтром по роли»), и Claude генерирует блок с curl-запросом, Python-примером и ответом. Потом обязательно проверяю что это реально работает — иногда он придумывает несуществующие параметры.
Где он стабильно ошибается
С Claude нельзя расслабляться. Есть несколько мест, где я почти гарантированно нахожу ошибки при проверке.
Числа и версии. Он уверенно пишет, что «функция доступна с версии 3.2», хотя в реальности это 4.0. Или указывает дефолтный порт, правильный для PostgreSQL, но не для нашего сервиса. Мелочи — но разработчик найдёт такое за 10 минут и потеряет доверие к документации целиком.
Дальше — специфика продукта. Claude не знает ваш конкретный инструмент, если вы ему не объяснили. Когда я описываю архитектуру достаточно подробно — он держится в рамках. Когда забываю уточнить — начинает фантазировать про «типичное поведение», которое с реальностью расходится.
На практике ещё один больной момент — тон для смешанной аудитории. Попросить написать «для разработчиков и менеджеров одновременно» почти гарантированно означает получить текст, который не подойдёт ни тем, ни другим. Лучше сразу делать два варианта и потом выбирать нужный.
Мой рабочий процесс
После нескольких месяцев экспериментов сложился примерно такой алгоритм. Сначала я сам пишу грубый черновик или список тезисов — не пытаюсь сделать красиво, просто фиксирую что должно быть. Потом отдаю это Claude с конкретным заданием: «структурируй», «перепиши понятнее», «добавь примеры к каждому эндпоинту».
Готовый текст я всегда читаю сам. Не по диагонали, а именно читаю — проверяю технические детали, убираю места где чувствуется шаблонность, добавляю что-то от себя. Это занимает время, но меньше, чем писать с нуля.
Конкретный пример: в феврале делал документацию для вебхуков. Написал список событий и их payload в виде таблицы, попросил Claude превратить это в нормальное описание с примерами. За 20 минут получил рабочий черновик на 4 страницы. Потом ещё 40 минут редактировал. Итого час вместо трёх — это реальная разница.
Несколько настроек, которые помогают
Есть вещи, которые я добавил в свои промпты после того как набил шишки.
Всегда указываю целевого читателя явно. Не «для разработчиков», а «для backend-разработчика на Python, который знает HTTP, но не знает нашу систему». Разница ощутимая.
Прошу избегать пассивного залога. Документация в стиле «запрос отправляется системой» хуже, чем «система отправляет запрос» — а Claude по умолчанию тяготеет к пассивному, если не напомнить.
Когда нужна конкретная структура — показываю её, не описываю словами. Даю шаблон: «вот как выглядит раздел для одного метода, сделай остальные так же». Это убирает половину недопониманий сразу.
Документация с Claude получается быстрее. Не лучше автоматически — но быстрее, и это уже что-то. Главное не пытаться убрать себя из процесса полностью: Claude хорошо работает как первый черновик или как редактор, но не как замена человеку, который понимает продукт.
