В прошлом месяце мне поручили написать документацию к API, который достался в наследство от предыдущей команды. Триста эндпоинтов, сорок страниц спек, половина примеров кода уже устарела. До Claude я бы засел на неделю. Сел на три дня — и это уже победа.
Не потому что ИИ написал всё за меня. А потому что он заменил ту часть работы, которая съедает больше всего времени: скучный рефакторинг, первичную сборку структуры и перевод с языка «я понимаю как это работает» на язык «это можно прочитать и понять».
Расскажу, что я делаю конкретно.
Первая проблема: начать
С холодным стартом всегда туго. Есть модуль, есть код — с чего начинать писать? Могу час смотреть в экран и страдать.
С Claude я делаю так: даю ему код и прошу описать, что делает функция, какие у неё входные данные, какие побочные эффекты, какие граничные случаи. Он выдаёт черновик, я его правию. Результат — не идеальный текст, а отправная точка. Намного проще поправить чужой текст, чем начать свой с нуля.
Пример запроса:
Прочитай этот код и напиши секцию документации: что делает функция,
какие аргументы принимает, какие ошибки может вернуть,
какие ограничения есть. Пиши сухо, без маркетингового языка.
Не прошу «написать документацию» в целом. Прошу описать конкретный кусок. Иначе получится текст уровня README с водой.
Структура: он предлагает, я решаю
Одна из ошибок — просить сразу целый документ. Тридцать страниц за один разворот — это мусор. Claude хорошо делает куски: одну секцию, один эндпоинт, одно описание потока данных.
Мой рабочий процесс выглядит так. Сначала прошу архитектуру: «Есть сервис X. Напиши план документации: какие секции должны быть, в каком порядке, что в каждой секции должно быть». Получаю скелет. Правишь план — это пять минут. Переписывать тридцать страниц — два часа.
Потом по секциям. Каждую секцию отдельно. Сначала черновик, потом вычитка, потом дополнение примерами.
Примеры кода — это большая проблема
Тут у меня был конкретный затык. Claude генерирует примеры кода, но они часто содержат ошибки и неточности. Не потому что плохой — просто не знает контекст проекта, версии библиотек, принятые соглашения.
Что я делаю. Сначала прошу пример без привязки к проекту — просто показать логику. Проверяю по коду. Потом уже адаптирую под конкретный проект сам или прошу переписать с учётом стиля проекта.
Сгенерируй пример использования этого метода.
Код должен работать с Python 3.11 и библиотекой requests 2.x.
Не используй async/await — это синхронный клиент.
Чем точнее запрос, тем меньше потом править. Разница — в три раза по времени.
Спецификации и таблицы
Мне нравится просить Claude преобразовать сырые данные в таблицы и спецификации. Например, даю ему JSON-схему ответа API и прошу: «Выпиши все поля, их типы, обязательные они или нет, и какие ошибки могут возникнуть при каждом поле». За пять секунд получаю таблицу, которую мучительно делать вручную.
Потом форматирую в Markdown. Тоже можно попросить: «Выведи это таблицей в Markdown».
Редактура: слепое пятно на своей писанине
Второй день работаешь с текстом — перестаёшь видеть косяки. Сел, перечитал, вроде нормально — а коллега открывает и не понимает.
Пользуюсь приёмом: даю готовый текст и прошу найти места, где непонятно. Claude умеет это делать, если попросить.
Вот секция документации. Прочитай её глазами человека,
который впервые видит этот сервис. Укажи места,
где может запутаться, где не хватает контекста,
где непонятно что делать дальше. Будь конкретным.
Обычно находит три-четыре места, которые я пропустил. Иногда его замечание спасает от бага в документации — описание противоречит реальному поведению API, и он это замечает.
Чего Claude не умеет
Буду честным. С некоторыми вещами он справляется плохо.
Первое — знание продукта. Он не знает, почему архитектор принял именно такое решение, какие баги известны, что скоро поменяется. Это нужно добавлять вручную, иначе документ будет технически правильным, но бесполезным.
Второе — актуальность. Если библиотека обновилась, а документация в интернете ещё нет, он может подсказать устаревший подход. Всегда проверяю кодом.
Третье — тон. Сгенерированный текст часто звучит ровно и безлико. «Данный метод выполняет чтение данных из источника». Мне приходится переписывать на человеческий: «Метод читает данные из базы и возвращает их в виде списка». Мелочь, но из таких мелочей складывается читаемость.
Итого
Claude не заменил мою работу. Он забрал монотонную часть — первичные черновики, преобразование данных в таблицы, переписывание спецификаций в читаемый текст. Моя работа — понимать продукт, проверять точность, делать документ живым.
До него один эндпоинт занимал полчаса на документацию. Сейчас — пятнадцать минут. Качество при этом не просело, местами даже лучше стало — потому что меньше устаёшь и меньше пропускаешь.
Для меня это рабочий инструмент, как редактор или IDE. Не волшебная палочка, но серьёзно ускоряет. Рекомендую попробовать — хотя бы на своих внутренних API, где ошибки не так критичны.
