Месяц назад у меня накопилась задолженность: три внутренних API без единой строчки документации, README на полстраницы и коллега, который через день спрашивал «а как вот это вообще работает». Я сел писать — и через час понял, что ненавижу писать техдок. Не потому что сложно. Потому что скучно. Ты уже знаешь про этот код всё, и объяснять очевидное самому себе, только в текстовом редакторе — от этого хочется переключиться на что угодно.
Попробовал скинуть задачу Claude. Получилось не идеально, но лучше, чем я ожидал. Рассказываю что и как.
Что реально работает: скидываешь код — получаешь структуру
Самое полезное — это не «напиши документацию за меня», а «прочитай код и скажи, что здесь вообще происходит».
Берёшь функцию или класс, кидаешь в Claude с запросом: «Объясни что делает этот код, какие у него входные параметры, что может пойти не так, и какой пример использования выглядел бы естественно». Смотришь на ответ. Обычно 70% — это то, что ты сам бы написал, только быстрее. Остальные 30% — либо мелкие неточности, либо что-то, что Claude вытащил из контекста и вытащил правильно, но ты бы сам об этом не подумал.
Однажды он заметил edge case, который я забыл задокументировать: что происходит, если передать пустой список. Я посмотрел в код — а там действительно стоял if not items: return {}, и нигде в README этого не было. Не открытие, но приятно.
Где я облажался в первый раз
Первая попытка выглядела так: «Напиши полную документацию для этого модуля». Я скинул 400 строк кода и стал ждать.
Результат был технически правильным. И совершенно мёртвым. Текст без интонации, описания вида «данная функция выполняет обработку входящих данных», примеры, скопированные прямо из кода без малейшего контекста. Читать это было примерно как читать ГОСТ.
Дело в том, что когда просишь «напиши документацию» — Claude пишет её в том виде, в каком чаще всего видел. А видел он её в основном в корпоративных репозиториях, где документация — это формальность. Нужно было уточнить аудиторию, стиль, уровень детализации.
Переспросил иначе: «Напиши это для джуна, который первый день работает с этим API. Покажи не только что делают методы, но и в каком порядке их разумно вызывать». Вышло живее.
Как я строю запрос сейчас
За месяц выработался шаблон, который работает для меня. Не универсальный, но точку отсчёта даёт.
В запросе я указываю три вещи: кто будет читать (джун, опытный разработчик, человек из другой команды), что он хочет сделать (разобраться с нуля, найти конкретный метод, понять почему что-то не работает), в каком формате нужен результат (Markdown с заголовками, docstring, просто текст).
Плюс всегда прошу добавить раздел «частые ошибки». Это обычно самое полезное место в любом техдоке — и обычно его никто не пишет, потому что лень.
Ещё один приём: если документируешь целую систему, а не один файл — сначала попроси Claude описать архитектуру своими словами, опираясь на то, что ты ему дал. Если описание расходится с реальностью, значит контекста не хватило. Лучше выяснить это на этапе «расскажи что понял», чем получить документацию, которая описывает несуществующую систему.
Что Claude не умеет делать за тебя
Он не знает, почему был принят тот или иной архитектурный выбор. Код показывает что, но не почему. Раздел «почему мы сделали именно так» всегда придётся писать самому. Claude может угадать причину из контекста, иногда угадывает верно — но полагаться на это не стоит.
С запутанным легаси тоже плохо работает. Если код писался пятью разными людьми за три года, и в нём есть функции, которые делают три разные вещи в зависимости от фазы луны — Claude честно опишет что видит, но документация получится такой же запутанной, как сам код. Это не его проблема. Ожидать, что документация «причешет» плохую архитектуру, не стоит.
Финальный шаг, который я долго пропускал
Долгое время я использовал Claude как генератор и сразу коммитил результат. Это была ошибка. Не потому что текст был плохим — просто он был чужим. Я не мог за него отвечать, потому что не писал его.
Сейчас делаю иначе: Claude генерирует черновик, я читаю его медленно, правлю то, что звучит не так, добавляю детали которые знаю только я, убираю то, что очевидно без объяснений. Уходит минут двадцать вместо полутора часов с нуля. И в итоге получается документация, под которой я готов подписаться.
Техдок — это всё равно моя работа. Claude просто убирает самую нудную её часть.
