Может ли ИИ писать хорошую документацию?

Да, если он работает с кодом. Агент для программирования, который может открывать файлы, запускать команды и проверять примеры, пишет точные README, API-документацию и docstrings. Модель, пишущая по памяти без репозитория, склонна выдумывать опции и имена функций, которые выглядят правдоподобно, но не существуют.

Как сгенерировать changelog из git log с помощью ИИ?

Дайте агенту диапазон с последнего релиза, например git log v1.4.0..HEAD --no-merges, и попросите сгруппировать заметные пользователю изменения под заголовками вроде Added, Changed, Fixed и Removed, пропуская рефакторинг и рутинные задачи. Затем сверьте каждую запись с её коммитом.

Чем AGENTS.md отличается от документации проекта?

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

Как не дать ИИ выдумывать API в документации?

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

Как поддерживать документацию в соответствии с кодом?

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

Документация с ИИ: от README до changelog

Чтобы писать документацию с ИИ, дайте агенту для программирования прочитать код и запустить команды, которые он описывает, задайте для каждого документа понятного читателя и сверьте каждую упомянутую функцию, флаг и пример с репозиторием. Агенты вроде Claude Code и Codex хорошо справляются с утомительной частью документации: превратить кодовую базу в README, заполнить docstrings, кратко описать релиз по истории git. Их слабое место — уверенность: они опишут опцию, которая звучит правдоподобно, но так и не была реализована.

В этом руководстве — что документировать с помощью агента, работающие запросы для каждого вида документов, генерация changelog из git log, поддержание документации в актуальном состоянии, место AGENTS.md и проверка написанной ИИ документации на выдуманные API.

Агент, а не окно чата

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

открыть файлы, которые вызывает код, а не только тот, что вы вставили;
запустить --help, набор тестов или пример, который он только что написал;
найти все места, где используется функция;
прочитать существующую документацию и подстроиться под её стиль.

Все запросы ниже предполагают, что агент работает в репозитории. Если вы ещё не настроили его, помогут статьи как пользоваться Claude Code и как пользоваться Codex CLI.

Сначала определите читателя

«Напиши документацию для этого проекта» даёт шаблонную страницу. У каждого вида документа свой читатель и свой источник истины:

Документ	Читатель	Источник истины
README	Новый пользователь или контрибьютор	Манифест пакета, скрипты, точки входа
Справочник по API	Разработчик, вызывающий ваш код	Сигнатуры функций, типы, определения маршрутов
Docstrings / JSDoc	Тот, кто читает или вызывает одну функцию	Тело функции и места её вызова
Заметки об архитектуре	Инженер, который меняет систему	Структура модулей, потоки данных, решения
Changelog	Пользователи, которые обновляются	Коммиты и pull request с последнего релиза
AGENTS.md / CLAUDE.md	Агенты для программирования	Правила и команды вашей команды

Укажите читателя и источник в запросе. Это влияет на результат сильнее любых указаний по стилю.

README

Хороший README быстро отвечает на четыре вопроса: что это, как это установить, как этим пользоваться и как внести вклад. Попросите агента проверять всё по ходу работы:

Напиши README.md для этого репозитория. Читатель: разработчик, который видит его
впервые. Разделы: что он делает (2-3 предложения), требования,
установка, быстрый старт, настройка, запуск тестов, структура проекта.

Правила:
- Бери команды из скриптов package.json и workflow CI; запусти каждую
  команду установки и быстрого старта и исправь README, если какая-то упадёт.
- Перечисляй только те переменные окружения, которые действительно читаются в коде;
  для каждой укажи файл.
- Без бейджей, без маркетинговых формулировок, без функций, которых нет в коде.

«Запусти каждую команду» — вот что превращает правдоподобный README в правильный. Если агент не может что-то запустить (например, нужны учётные данные), попросите его пометить этот шаг как непроверенный, чтобы вы проверили его вручную.

Справочник по API

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

Для HTTP API попросите агента собрать справочник прямо по определениям маршрутов:

Опиши каждый HTTP-эндпоинт в src/routes. Для каждого: метод, путь,
требования к аутентификации, тело запроса и параметры запроса с типами,
структура ответа, коды ошибок. Читай обработчик и
схему валидации; не делай выводов по именам. Добавь по одному примеру curl на
эндпоинт и запусти его на локальном dev-сервере.

Если в проекте уже есть OpenAPI, пусть агент обновляет файл спецификации, а не пишет отдельный справочник в Markdown, и пусть её отображают ваши существующие инструменты. Один источник истины проще держать честным, чем два.

Docstrings и JSDoc

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

Добавь JSDoc ко всем экспортируемым функциям в src/billing/. Для каждой:
однострочное описание, @param с типом и смыслом, @returns и @throws
для каждой ошибки, которую функция действительно может выбросить (прочитай тело и
функции, которые она вызывает). Добавляй @example, только если запустил его.
Не меняй код.

Две недорогие проверки делают docstrings надёжными:

TypeScript в JS-проектах: с // @ts-check в начале файла или checkJs в tsconfig.json TypeScript проверяет типы из JSDoc, так что неверный тип в @param превращается в ошибку.
Python: примеры в формате doctest (строки с >>>) можно запустить через python -m doctest module.py -v, так что пример, разошедшийся с кодом, упадёт.

Полезное правило: docstring должен объяснять, почему и зачем, а не повторять сигнатуру. «Возвращает пользователя» у getUser(id): User — шум; «Возвращает null для мягко удалённых пользователей; вызывающий код должен это обработать» — то, что стоит иметь. Скажите это агенту.

Заметки об архитектуре

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

Напиши docs/architecture.md для инженеров, которые впервые видят кодовую базу.
Опиши: основные модули и за что отвечает каждый, как запрос проходит от
HTTP-слоя до базы данных, фоновые задачи и внешние сервисы.
Для каждого утверждения укажи файл (и функцию), откуда оно взято.
Добавь диаграмму Mermaid для прохождения запроса.
Помечай всё, в чём не уверен, как "TODO: verify".

Ссылки на файлы — в этом и смысл: по ним проверяющий за секунды выборочно сверит утверждения, и они показывают, какие части устареют, когда эти файлы изменятся. Записывайте, почему принимались решения, а не только что существует; короткий журнал решений (в стиле ADR: контекст, решение, последствия) стареет медленнее, чем описание текущего кода. Статья карта кодовой базы для ИИ-агентов разбирает родственную задачу: как дать агентам обзор, по которому они смогут ориентироваться.

Changelog из git log

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

git describe --tags --abbrev=0
git log v1.4.0..HEAD --no-merges --pretty=format:'%h %s%n%b'

Затем запрос:

Напиши запись CHANGELOG.md для следующего релиза по
git log v1.4.0..HEAD --no-merges. Читатель: пользователи, которые обновляются.
Используй заголовки Keep a Changelog (Added, Changed, Deprecated,
Removed, Fixed, Security). Пропускай рефакторинг, тесты, CI и рутину.
Перепиши каждую запись понятным пользователю языком, ломающие изменения ставь первыми с
шагами обновления и оставляй короткий хеш рядом с каждой записью.

Если ваша команда пишет Conventional Commits (feat:, fix:, feat!: для ломающих изменений), упомяните это: агент сможет надёжно сортировать по типу. Если сообщения коммитов скупые, пусть агент для важных записей читает diff (git show <hash>) или связанный pull request. Хеш рядом с каждой строкой ускоряет проверку: вы проверяете запись, открыв её коммит.

Как поддерживать документацию в актуальном состоянии

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

То же изменение, тот же агент. Добавьте в правила агента одну строку: «Когда меняешь поведение, флаги, переменные окружения или публичные API, обнови связанную документацию в том же коммите».

Просите проверку документации в конце каждой задачи:

Перечисли все документы, разделы README, docstrings и примеры, которые упоминают
изменённый тобой код. Обнови те, что теперь неверны.

Проверяйте ветку перед слиянием: дайте агенту diff (git diff main...HEAD) и папку с документацией и спросите, какие утверждения в документации этот diff делает ложными.
Запускайте примеры как тесты. Doctest, скрипт, запускающий фрагменты из README, или JSDoc с проверкой типов превращают устаревшую документацию в падающую сборку.
Генерируйте, что можно. Справка CLI, спецификации OpenAPI и справочники по типам, сгенерированные из исходников, не могут разойтись с кодом.

AGENTS.md — это не ваша документация

AGENTS.md (его читают Codex и многие другие агенты) и CLAUDE.md (его читает Claude Code) — файлы инструкций для агентов. Они загружаются в каждую сессию, поэтому должны быть короткими: команды сборки и тестов, соглашения, папки, которые трогать не надо. Команда /init в Claude Code или Codex создаёт первую версию.

У документации для людей другая задача, и она может быть такой длинной, как нужно. Если их смешивать, возникают две проблемы: длинный AGENTS.md тратит контекст агента в каждой задаче, а README, полный правил для агентов, сбивает людей с толку. Держите их раздельно и ссылайтесь друг на друга:

# AGENTS.md
## Commands
- Test: pnpm test
## Docs
- Architecture overview: docs/architecture.md (read before changing modules)
- When you change public APIs, update docs/api.md in the same commit.

Статья CLAUDE.md и AGENTS.md объясняет, что должно быть в этих файлах и как использовать один набор правил для разных агентов.

Проверяйте написанную ИИ документацию на выдуманные API

Самая вредная ошибка в документации — API, которого не существует: опция конфигурации, флаг CLI или метод, который модель придумала, потому что такой есть в похожих проектах. Читатели доверяют документации, поэтому теряют время, прежде чем заподозрят, что она неверна. Проверяйте это целенаправленно:

Ищите каждое имя через grep. Попросите агента (или второго агента) извлечь все функции, опции, флаги, переменные окружения и эндпоинты, упомянутые в новой документации, и поискать каждое в коде. Всё, что не нашлось, удаляется.
```
Извлеки из docs/api.md каждый идентификатор, флаг CLI, ключ конфигурации и
переменную окружения. Для каждого покажи, где он определён в коде, в виде
file:line, или напиши NOT FOUND. Ничего не правь.
```
Запускайте каждый пример. Блоки кода, которые ни разу не выполнялись, — это догадки.
Проверяйте значения по умолчанию и лимиты. Числа (таймауты, размеры, повторные попытки) часто выдуманы; каждое должно прослеживаться до константы в коде.
Остерегайтесь «также поддерживает». Строки вроде «также поддерживает конфигурацию в YAML» или «можно использовать с Redis» — классическая вода. Попросите показать код, который это делает.
Привлекайте второго проверяющего. Отдельный агент, сверяющий документацию с кодом, меньше привязан к ней, чем тот, кто её написал. Как это настроить, рассказывает статья AI-ревью кода.

Документация с AgentVera

AgentVera — десктопное приложение для macOS, Windows и Linux, которое запускает Claude Code, Codex, Gemini CLI и других CLI-агентов рядом друг с другом. Несколько его инструментов помогают с документацией:

Автор и проверяющий рядом: запустите одного агента, который пишет документацию, и второго, который сверяет её с кодом, в одном workspace, или выделите работе над документацией отдельный worktree.
Вкладка Specs: показывает Markdown-файлы репозитория, сначала самые новые, с разбивкой на спецификации, планы и документы, включая незакоммиченные файлы, которые агенты написали в других worktree. Markdown открывается в режиме предпросмотра.
Brain: читает ваши README, ARCHITECTURE, CHANGELOG, ADR, коммиты и PR, перечисляет решения с их причинами и отмечает те, чьи термины больше не встречаются в коде, — полезный сигнал устаревшей документации.
Обзор проекта: запуск Claude Code только для чтения, который кратко описывает стек, модули и ключевые файлы репозитория, — хороший черновик для заметок об архитектуре.
Ревью кода: проверяйте изменения агента в документации с выбранной вами моделью Claude; замечания привязаны к файлу и строке.
Панель Git: просматривайте историю, из которой собираете changelog, и пусть Claude Haiku пишет сообщения коммитов в стиле вашего репозитория, — следующий changelog от этого станет проще.

Подведём итог

ИИ делает написание документации дешёвым, поэтому настоящая работа — точность. Запускайте агента внутри репозитория, говорите ему, кто читатель и где истина, пусть он запускает команды и примеры, а changelog собирает из git log, сохраняя хеши. Обновляйте документацию в том же изменении, что и код, держите AGENTS.md для агентов, а документацию — для людей, и прогоняйте через grep каждое описанное имя перед публикацией. А если документация вместо этого выявила баг, продолжение — в статье отладка кода с ИИ.