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

URL: https://agentvera.dev/ru/blog/write-documentation-with-ai/ · Опубликовано: 2026-10-27

Как писать документацию с ИИ без ошибок: README, API-документация, docstrings, заметки об архитектуре и changelog из git log с проверкой на выдуманные API.

**Коротко:**

- Агент для программирования пишет хорошую документацию, когда читает настоящий код и запускает настоящие команды; чат-модель, пишущая по памяти, выдумывает флаги, опции и функции.
- Используйте его для README, справочников по API, docstrings и JSDoc, заметок об архитектуре и changelog из git log, и для каждого документа задавайте читателя и источник.
- Обновляйте документацию в том же изменении, что и код, держите в AGENTS.md только правила для агентов и сверяйте каждый описанный API с кодом.

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

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

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

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

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

Все запросы ниже предполагают, что агент работает в репозитории. Если вы ещё не настроили его, помогут статьи [как пользоваться Claude Code](/ru/blog/how-to-use-claude-code/ "Как пользоваться Claude Code") и [как пользоваться Codex CLI](/ru/blog/how-to-use-codex-cli/ "Как пользоваться Codex CLI").

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

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

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

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

## README

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

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

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

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

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

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

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

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

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

## Docstrings и JSDoc

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

```text
Добавь 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 для мягко удалённых пользователей; вызывающий код должен это обработать» — то, что стоит иметь. Скажите это агенту.

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

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

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

Ссылки на файлы — в этом и смысл: по ним проверяющий за секунды выборочно сверит утверждения, и они показывают, какие части устареют, когда эти файлы изменятся. Записывайте, *почему* принимались решения, а не только что существует; короткий журнал решений (в стиле ADR: контекст, решение, последствия) стареет медленнее, чем описание текущего кода. Статья [карта кодовой базы для ИИ-агентов](/ru/blog/codebase-map-for-ai-agents/ "Карта кодовой базы для ИИ-агентов") разбирает родственную задачу: как дать агентам обзор, по которому они смогут ориентироваться.

## Changelog из git log

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

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

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

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

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

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

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

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

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

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

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

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

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

```markdown
# 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](/ru/blog/claude-md-agents-md/ "CLAUDE.md и AGENTS.md") объясняет, что должно быть в этих файлах и как использовать один набор правил для разных агентов.

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

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

- **Ищите каждое имя через grep.** Попросите агента (или второго агента) извлечь все функции, опции, флаги, переменные окружения и эндпоинты, упомянутые в новой документации, и поискать каждое в коде. Всё, что не нашлось, удаляется.

  ```text
  Извлеки из docs/api.md каждый идентификатор, флаг CLI, ключ конфигурации и
  переменную окружения. Для каждого покажи, где он определён в коде, в виде
  file:line, или напиши NOT FOUND. Ничего не правь.
  ```

- **Запускайте каждый пример.** Блоки кода, которые ни разу не выполнялись, — это догадки.
- **Проверяйте значения по умолчанию и лимиты.** Числа (таймауты, размеры, повторные попытки) часто выдуманы; каждое должно прослеживаться до константы в коде.
- **Остерегайтесь «также поддерживает».** Строки вроде «также поддерживает конфигурацию в YAML» или «можно использовать с Redis» — классическая вода. Попросите показать код, который это делает.
- **Привлекайте второго проверяющего.** Отдельный агент, сверяющий документацию с кодом, меньше привязан к ней, чем тот, кто её написал. Как это настроить, рассказывает статья [AI-ревью кода](/ru/blog/ai-code-review/ "AI-ревью кода").

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

[AgentVera](/ru/download/ "Скачать AgentVera") — десктопное приложение для macOS, Windows и Linux, которое запускает Claude Code, Codex, Gemini CLI и других CLI-агентов рядом друг с другом. Несколько его инструментов помогают с документацией:

- **Автор и проверяющий рядом:** запустите одного агента, который пишет документацию, и второго, который сверяет её с кодом, в одном [workspace](/ru/features/workspace/ "Workspace"), или выделите работе над документацией отдельный worktree.
- **[Вкладка Specs](/ru/features/editor-and-terminal/ "Редактор, терминал и спецификации"):** показывает Markdown-файлы репозитория, сначала самые новые, с разбивкой на спецификации, планы и документы, включая незакоммиченные файлы, которые агенты написали в других worktree. Markdown открывается в режиме предпросмотра.
- **[Brain](/ru/features/brain/ "AgentVera Brain"):** читает ваши README, ARCHITECTURE, CHANGELOG, ADR, коммиты и PR, перечисляет решения с их причинами и отмечает те, чьи термины больше не встречаются в коде, — полезный сигнал устаревшей документации.
- **[Обзор проекта](/ru/features/project-tour-and-code-map/ "Обзор проекта и карта кода"):** запуск Claude Code только для чтения, который кратко описывает стек, модули и ключевые файлы репозитория, — хороший черновик для заметок об архитектуре.
- **[Ревью кода](/ru/features/code-review/ "Ревью кода"):** проверяйте изменения агента в документации с выбранной вами моделью Claude; замечания привязаны к файлу и строке.
- **[Панель Git](/ru/features/git-and-github/ "Git и GitHub"):** просматривайте историю, из которой собираете changelog, и пусть Claude Haiku пишет сообщения коммитов в стиле вашего репозитория, — следующий changelog от этого станет проще.

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

ИИ делает написание документации дешёвым, поэтому настоящая работа — точность. Запускайте агента внутри репозитория, говорите ему, кто читатель и где истина, пусть он запускает команды и примеры, а changelog собирает из `git log`, сохраняя хеши. Обновляйте документацию в том же изменении, что и код, держите `AGENTS.md` для агентов, а документацию — для людей, и прогоняйте через grep каждое описанное имя перед публикацией. А если документация вместо этого выявила баг, продолжение — в статье [отладка кода с ИИ](/ru/blog/debug-code-with-ai/ "Отладка кода с ИИ").

## Частые вопросы

**Может ли ИИ писать хорошую документацию?** Да, если он работает с кодом. Агент для программирования, который может открывать файлы, запускать команды и проверять примеры, пишет точные 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 в документации?** Скажите агенту описывать только то, что он находит в коде, указывать файл для каждой функции или опции и запускать каждый пример кода. Затем поищите в коде каждое имя из документации; всё, что не нашлось, — галлюцинация, которую надо убрать.

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

---

**Об AgentVera.** AgentVera — настольное приложение для macOS, Windows и Linux от Solviera Teknoloji. Оно запускает 18 ИИ-агентов для программирования (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) рядом, по проектам, в настоящих терминалах с собственными установками CLI и входами пользователя. В бесплатном тарифе количество агентов не ограничено. Скачать: https://agentvera.dev/ru/download/ · Цены: https://agentvera.dev/ru/pricing/