Документация — то, что все откладывают «на потом» и не пишут никогда. Claude Code снимает этот барьер: он читает твой код и пишет доки по нему. Разберём README, комментарии и как держать всё это в актуальном виде.
Признайся: README в твоём проекте — это одна строчка с названием, а комментариев в коде нет вовсе. Так у всех, потому что писать доки скучно и кажется, что «и так понятно». Через месяц непонятно даже самому. Claude Code решает это иначе, чем шаблонные генераторы: он не вставляет рыбу, а реально читает твой код и пишет документацию по тому, что в нём происходит. Разберём, как поставить это на поток.
Что узнаешь из гайда
Часть 1 · Зачем
Главное
Claude Code пишет доки по реальному коду, а не по шаблону. Он читает файлы проекта и описывает то, что в них есть, — поэтому документация не выдумана, а отражает проект.
Старые генераторы документации делали болванку: брали имена функций и раскладывали их по шаблону. Получался формально полный, но мёртвый документ — он не объяснял, зачем код существует. Claude Code работает иначе. Это агент — программа, которая сама читает файлы, понимает связи между ними и пишет текст про смысл, а не про форму. Если хочешь глубже про то, как агент устроен, загляни в гайд по Claude для новичков.
Хорошая документация объясняет зачем, а не что. «Что» видно в коде. «Зачем» — нет.
Поэтому ценность агента не в том, что он печатает быстрее тебя, а в том, что он держит в голове весь проект сразу и связывает кусок кода с его ролью в системе. Человеку для этого пришлось бы перечитать половину репозитория.
Часть 2 · README
Главное
Открой агента в папке проекта и попроси собрать README. Он прочитает файлы и составит разделы про установку, запуск и использование — по тому, что реально есть в коде.
Самый прямой путь — запустить Claude Code в корне проекта и дать ему задачу словами. Не «напиши README», а с указанием, какие разделы нужны, и на каком языке. Чем конкретнее задача, тем меньше правок потом:
# Запускаем агента в корне проекта
claude
# Ставим задачу с конкретными разделами и языком
> прочитай проект и собери README.md на русском:
что это, установка, запуск, основные команды, структура папок.
Опирайся только на реальный код, не выдумывай разделыФраза «опирайся только на реальный код, не выдумывай» — не лишняя. Без неё агент иногда дописывает правдоподобные, но несуществующие шаги установки. С ней он держится фактов из файлов. Готовый черновик обязательно прочитай сам: README — лицо проекта, и пара минут вычитки окупается.
Лайфхак
Если в проекте уже есть файл CLAUDE.md с описанием проекта, агент опирается и на него — README выходит точнее с первого раза. CLAUDE.md и README дополняют друг друга: первый для агента, второй для людей.
Часть 4 · Актуальность
Главное
Главная беда документации — она устаревает. Лекарство одно: правило «поменял код — тем же агентом обнови доки». С Claude Code это одна команда, а не отдельный проект.
Соврамшая документация хуже, чем её отсутствие: человек верит ей и теряет время. Автогенерация саму проблему не решает — доки всё равно протухают, если их не трогать. Но с агентом обновление встроено в обычный воркфлоу: закончил фичу — той же сессией просишь подтянуть доки:
Этот же принцип удобно совмещать с безопасным воркфлоу через Git: доки правятся в том же коммите, что и код, и не отстают от него ни на шаг.
Коротко
Часть 5 · Правила
Чтобы не повторять одно и то же в каждой сессии («доки на русском», «комментируй только неочевидное»), вынеси правила про документацию в файл CLAUDE.md — постоянную память проекта, которую агент читает всегда. Рабочий набор правил:
## Документация
- README и комментарии — на русском, код и имена функций — на английском.
- Комментируй ЗАЧЕМ, а не что. Очевидный код не комментируй.
- Докстринги — у публичных функций: что принимает, что возвращает.
- Поменял поведение кода — в том же изменении обнови README и комментарии.Когда доки от агента не нужны
Не проси документировать одноразовый скрипт или черновик, который завтра удалишь, — это потраченные токены. И не заставляй агента писать доки на код, который ты сам не понимаешь: сначала разберись (для этого есть онбординг в проект с Claude Code), потом документируй.
Коротко
Вопросы
Да, Claude Code пишет README по реальному коду проекта: он читает файлы, понимает структуру и собирает разделы про установку, запуск и использование. Достаточно открыть агента в папке проекта и попросить составить README — он не выдумывает из головы, а опирается на то, что видит в файлах. Готовый черновик дальше дочитываешь и правишь под себя.
Чтобы Claude добавил комментарии, дай ему конкретный файл и попроси прокомментировать неочевидные места: зачем нужен блок, а не что он делает построчно. Хорошее правило — комментарий объясняет причину и намерение, а не пересказывает код. Постоянное правило про стиль комментариев лучше один раз записать в CLAUDE.md, чтобы агент держал его во всех сессиях.
Документация устаревает всегда, если её не обновлять, и автогенерация эту проблему не отменяет. Сила Claude Code в том, что обновить доки после изменения кода — это одна команда: попросить агента перечитать изменённые файлы и поправить README и комментарии. Привычка «поменял код — обнови доки тем же агентом» держит документацию живой дешевле, чем ручная правка.
Claude Code пишет документацию на любом языке, который попросишь, в том числе по-русски. Достаточно прямо указать в задаче «README и комментарии на русском» или один раз закрепить это правило в CLAUDE.md. При этом сам код и названия функций остаются на английском — переводится текст документации, а не идентификаторы в коде.
Читать дальше
Прикладной материал, разборы и рабочие приёмы — то, чем пользуюсь сам, без воды. Залетай, там самое полезное.
Зайти в Telegram
Часть 3 · Комментарии
Комментарии и докстринги
Главное
Проси комментарии к неочевидным местам — про «зачем», а не «что». Построчный пересказ кода («увеличиваем счётчик на единицу») — это мусор, который только мешает читать.
Докстринг — это описание функции в самом коде (что принимает, что возвращает, зачем нужна), которое потом видно прямо в редакторе при наведении. Claude Code хорошо их пишет, но важно правильно поставить задачу — иначе он закомментирует каждую строку, и код станет нечитаемым. Правильный запрос звучит так:
Хороший комментарий против плохого
Важно
Не давай агенту команду «закомментируй весь файл». Лишние комментарии хуже их отсутствия: они врут первыми, когда код меняется, а глаз их пропускает. Цель — чтобы комментариев было мало, но каждый объяснял то, чего из кода не видно.