Документация — та работа, которую откладывают дольше всего и делают формальнее всего. Комментарий // увеличивает счётчик над строкой counter++ пишут не потому, что он кому-то нужен, а потому, что требование «документировать функции» выполнено буквально. README устаревает через месяц после написания. Каталог docs/ наполняется файлами, которые никто не открывает.

Агент способен снять с вас механическую часть этой работы — но ровно так же способен произвести те самые бесполезные комментарии в промышленных количествах, причём быстрее, чем вы успеете их прочитать. Разница определяется постановкой задачи.

После этого урока вы будете уверенно поручать документирование: получать объяснения вместо пересказа сигнатур, поддерживать README в актуальном состоянии и понимать, какая часть знаний о проекте вообще не должна оказываться в документации, потому что для неё есть CLAUDE.md.

Что уже умеем / что добавим

Вы разобрались, где живут инструкции для агента: CLAUDE.md, правила, auto memory, а также практические паттерны вроде REVIEW.md. Теперь посмотрим на документы, адресованные людям. Это другая аудитория и другие критерии качества — и, что важно, другое место хранения, которое легко перепутать с инструкциями для агента.

Что вы узнаете в рамках статьи

• Как ставить задачу на документирование, чтобы получить объяснения, а не пересказ кода
• Как выстроить цикл «найти недокументированное — написать — проверить»
• Чем README, docs/ и CLAUDE.md различаются по аудитории и содержанию
• Почему документация устаревает и что с этим делать средствами агента
• Как проверять сгенерированную документацию на осмысленность

Ключевые термины

• Docstring — блок документации внутри исходного файла: JSDoc в JavaScript, docstring в Python, doc-комментарий в других языках.
• README — точка входа в проект: что это, как запустить, куда идти дальше.
• Каталог docs/ — материалы для людей, не помещающиеся в README: архитектура, регламенты, руководства.
• Дрейф документации — расхождение между тем, что написано, и тем, как код работает сейчас.
• Аудитория документа — тот, для кого он написан; определяет и содержание, и место хранения.

Постановка задачи на документирование

Общий запрос «задокументируй модуль» даёт предсказуемо плохой результат: агент добавит блок над каждой функцией, где перечислит параметры, уже видные в сигнатуре. Формально требование выполнено, ценность нулевая.

Чтобы получить полезное, нужно сказать, что именно объяснять. Ценность документации в том, чего в коде не видно: зачем эта функция существует, какие у неё предпосылки, что произойдёт при нарушении контракта, почему выбран именно такой подход.

Слабо:
добавь JSDoc ко всем функциям в @src/auth

Сильно:
Добавь JSDoc к экспортируемым функциям в @src/auth.
Для каждой опиши: зачем она нужна, при каких условиях бросает
исключение и что происходит при просроченном токене.
Параметры перечисляй только там, где имя не объясняет назначение.
Для приватных вспомогательных функций документацию не добавляй.

Обратите внимание на два ограничения: не документировать приватные помощники и не перечислять очевидные параметры. Они убирают ровно тот шум, из-за которого документацию перестают читать.

Полезно и указать формат, если в проекте он устоялся: JSDoc, docstring в стиле Google, reStructuredText. Иначе агент выберет распространённый вариант, который может не совпасть с принятым у вас.

Цикл: найти, написать, проверить

Документирование удобно вести в три шага, каждый со своим запросом.

Сначала — поиск пробелов:

Найди в @src/auth экспортируемые функции без JSDoc.
Выведи списком с указанием файла и строки.

Затем — написание по найденному списку. Здесь работает всё, что вы знаете о промптах: область, ограничения, формат.

И наконец — проверка. Этот шаг пропускают чаще всего, а он самый показательный:

Проверь, что добавленная документация соответствует
принятому в проекте стилю, и не описывает того,
что и так видно из сигнатуры функции.

Отдельная разновидность проверки — на устаревание. Документация дрейфует от кода незаметно, и вопрос «где написанное расходится с реальностью» стоит задавать периодически:

Сравни описания функций в @src/api с их фактическим поведением.
Покажи расхождения: где документация обещает не то, что делает код.

Это одна из тех задач, где агент выигрывает у человека вчистую: сверка десятков описаний с кодом утомительна и потому обычно не делается вовсе.

README и docs: разные документы для разных читателей

Разделение простое и держится на вопросе «кто это читает».

README — первое, что открывает человек, впервые попавший в репозиторий. Его задача: объяснить, что это за проект, как его запустить и куда идти дальше. Всё, что не отвечает на эти три вопроса, README перегружает.

Обнови README: раздел установки не соответствует текущему
package.json, а команды запуска устарели после перехода на vite.
Проверь по @package.json и @vite.config.ts.
Структуру и тон разделов не меняй, правь только фактические
расхождения.

Ограничение «не меняй структуру» здесь принципиально: без него README нередко переписывается целиком, и вы получаете большой дифф вместо точечной правки.

Каталог docs/ — материалы, не помещающиеся в README: описание архитектуры, регламенты, руководства по конкретным задачам. Читают их выборочно и по необходимости.

Ключевой момент, который стоит удерживать: и README, и docs/ адресованы людям. CLAUDE.md адресован агенту. Это разные документы, и попытка совместить портит оба.

Практическое следствие: если сведения нужны и людям, и агенту, храните их в документации, а из CLAUDE.md ссылайтесь. Дублирование гарантированно приведёт к расхождению — правку внесут в одну копию.

Что не должно попадать в документацию

Есть категория сведений, для которых документация — неподходящее место, и стоит проговорить границу явно.

Не пишите в README и docs/ то, что предназначено для агента: команды, которые он не угадает, правила стиля, отличающиеся от умолчаний, особенности окружения. Всему этому место в CLAUDE.md, откуда оно загружается автоматически. Читатель README ищет не это.

Обратное тоже верно. В CLAUDE.md не стоит держать подробную документацию API — на неё лучше сослаться. Не стоит держать пофайловые описания структуры и всё, что агент выяснит сам чтением кода. И не стоит держать быстро меняющиеся сведения: они устареют и начнут вводить в заблуждение.

Хороший критерий для CLAUDE.md вы уже знаете: «если это убрать, агент начнёт ошибаться?» Для документации критерий другой: «поможет ли это человеку, впервые открывшему проект?» Материал, не проходящий ни один из двух, скорее всего, не нужен вовсе.

Частые ошибки

• Требование задокументировать всё подряд. Общий запрос без ограничений даёт комментарии над приватными помощниками и пересказ сигнатур. Ограничивайте область: только экспортируемое, только публичный API, только сложная логика.
• Пересказ кода вместо объяснения. Документация ценна тем, чего в коде не видно: назначением, предпосылками, поведением в исключительных случаях. Прямо перечисляйте в промпте, что нужно объяснить.
• Полная перезапись README вместо точечной правки. Без ограничения «структуру не меняй» вы получите дифф на весь файл, где реальные исправления смешаны с переформулировками. Всегда фиксируйте, что именно править.
• Смешение документации и инструкций для агента. Команды и правила стиля в README не загружаются в контекст, а описание архитектуры в CLAUDE.md занимает контекст без пользы. Разделяйте по аудитории.

Наиболее частые вопросы

• Стоит ли документировать каждую функцию? — Нет. Разумная граница — экспортируемые функции и нетривиальная логика. Приватные помощники с говорящими именами документации не требуют.
• Как заставить агента писать в принятом у нас формате? — Назовите формат явно и укажите файл-образец: по нему стиль воспроизводится точнее, чем по названию стандарта.
• Что делать с документацией, которая уже устарела? — Попросите сравнить описания с фактическим поведением кода и показать расхождения. Это та задача, где сверка десятков описаний выполняется быстро.
• Куда положить описание архитектуры? — В docs/, а из CLAUDE.md при необходимости сослаться. В самом CLAUDE.md держать его не стоит: объём большой, а нужно оно не в каждой сессии.
• Можно ли поручить агенту весь README целиком? — Первую версию да, особенно по существующему коду. Но проверьте её сами: агент опишет то, что видит в проекте, а не то, что важно знать новичку в первую очередь.

Итоги

Поздравляем — вы закрыли пятую главу, и закрыли её сильной темой. Документация перестала быть формальностью: вы умеете ставить задачу так, чтобы получать объяснения вместо пересказа сигнатур, вести цикл поиска пробелов и проверки написанного, находить расхождения между документацией и кодом и, что важнее всего, разделять материалы по аудитории — README и docs/ для людей, CLAUDE.md для агента.

За главу вы прошли путь от трюков CLAUDE.md через правила с привязкой к путям и auto memory к осознанному выбору механизма и практическим паттернам. Ваш проект теперь может нести инструкции, которые действительно работают. Впереди шестая глава и скиллы — тот самый четвёртый механизм, о котором мы говорили в уроке 5.4. Там вы научитесь упаковывать повторяемые сценарии так, чтобы вызывать их одной командой.