Третий раз за месяц тимлид прислал в чат: «Документацию на API обновили?». Третий раз я не обновил. Не потому что лень — а потому что это скучно. Писать код интересно, писать документацию — как делать уборку: знаешь, что надо, но каждый раз откладываешь.
А потом попробовал использовать Claude для этой задачи и понял, что проблема была не во мне. Проблема была в процессе.
Почему документация — это большая проблема
Когда я начинал писать код, мне казалось: ну вот, функции работают, пусть разработчики сами разбираются. Потом сам же наткнулся на свой же API через полгода, два часа вспоминал, как там авторизация устроена, и осознал масштаб.
Документация — это не побочный продукт разработки. Это часть интерфейса. Если её нет — вы заставляете пользователей (часто коллег) заниматься археологией через исходники.
Но писать её вручную — удовольствие ниже среднего. Особенно когда ты уже три часа фиксил баг, а тебе говорят: «опиши, как работает новый эндпоинт». И сидишь и думаешь: ну что писать, ну принимает он JSON, ну возвращает JSON, ну и что.
Что умеет Claude в контексте документации
Самое полезное — он умеет читать твой код и описывать его. Не идеально, но достаточно близко к тому, что нужно, чтобы потом допилить.
Первый подход: кидаешь ему код и просишь описать. Выглядит это так:
«У меня есть Python-функция, которая делает X. Напиши секцию в стиле docstring, которая объясняет параметры, возвращаемое значение и возможные ошибки».
Он выдаёт текст. Не идеальный — иногда путает порядок аргументов, иногда добавляет то, чего нет. Но основа получается разумная, и допилить её быстрее, чем писать с нуля.
Второй подход, который оказался даже полезнее — генерация changelog-записей. Берёшь diff или список коммитов за спринт, кидаешь в Claude и просишь: «Сделай из этого changelog для пользователей, не для разработчиков». И вот это у него выходит хорошо. Потому что changelog — это по сути перевод технического в человеческое, а это ровно то, в чём языковые модели сейчас сильны.
Как я строю воркфлоу
Сначала делал глупо: просил Claude написать всю документацию целиком. Результат — красиво звучащий, но бесполезный текст, где всё «эффективно», «надёжно» и «высокопроизводительно» без внятных деталей.
Потом дошло: контекст решает всё.
Сейчас работаю так. Сначала пишу в Клод файл с описанием контекста — что за проект, для кого документация, какие есть ограничения. Что-то вроде:
«Это REST API для управления заказами. Документация для внешних клиентов, не для внутренней команды. Используем стандарт OpenAPI. Ответы всегда в формате JSON. Ошибки возвращаются по RFC 7807».
После этого уже кидаю код и прошу конкретный кусок. Один эндпоинт за раз. Получается в разы лучше, чем если попросить «опиши весь сервис».
Ещё одна штука, которая зашла — генерация примеров. Просишь: «Дай curl-запрос, Python requests, JavaScript fetch для этого эндпоинта». И он выдаёт рабочий код. Иногда с косяками — не ту версию API укажет, или не тот формат даты, — но в 80% случаев примеры можно брать и не переписывать.
Где Claude реально помогает, а где нет
Помогает в трёх вещах. Первая — первая черновая версия. Не финальная, а чтобы было от чего отталкиваться. Вторая — перевод с технического на человеческое. Объяснить не-разработчику, что делает функция, описать ограничения API доступным языком. Третья — поддержание консистентности. Попросить «проверь, что все эндпоинты описаны в одинаковом стиле» — это реально работает.
Не помогает в двух случаях. Первое — он не знает, чего не знает. Если в коде нет комментариев, а логика неочевидная, он либо угадает, либо напишет красивое, но неправильное описание. Второе — он не знает ваш контекст. Почему вы приняли именно такое архитектурное решение, какие есть known issues, что скоро поменяется. Это нужно добавлять руками.
Что я понял за месяц
Документация, написанная только Клодом, — это мусор. Документация, написанная только человеком, — это роскошь, которую мало кто может себе позволить. А вот совместная работа — когда ИИ генерирует черновик, а человек правит и дополняет контекстом — это рабочая схема.
У меня ушёл примерно час на то, чтобы с нуля описать шесть эндпоинтов, которые я поленился документировать три месяца. Черновики от Клода сократили это время раза в четыре. Может, это и не идеальная документация — но она хотя бы есть. А «есть, но не идеально» всегда лучше, чем «нет, потому что лень».
Тимлиду я отправил обновлённую документацию через два дня. Он не прислал напоминание в третий раз. Что характерно.
