AI для документации: генерируем README, changelog и API-документацию

Документация отстаёт от кода — это факт, который не обсуждают, потому что он очевиден. Разработчики пишут фичу, доделывают тесты, мержат PR и закрывают задачу. README обновляется «когда-нибудь», changelog заполняется вручную перед релизом, а API-документация живёт отдельным миром, который все читают и никто не обновляет. AI-агенты изменили эту картину: не заменяют человека, а взяли на себя рутину — превращение диффов в структурированные записи.

В августе 2026 года команда Microsoft .NET Aspire запустила автоматизацию, которая за 30 дней обработала 396 слитых PR и создала 82 документационных pull request со 100%-ным merge rate (github.blog, 08.07.2026). Это не теория — это рабочий pipeline в production-проекте. Ниже — как он устроен, какие инструменты работают для каждой задачи и как повторить это у себя.

Кейс: 396 коммитов → 82 документационных PR

David Pine (Microsoft) и Peli de Halleux (Microsoft Research) построили agentic workflow pr-docs-check, который запускается на каждом слитом PR в репозитории microsoft/aspire (источник):

Метрика	Значение
Обработано PR за 30 дней	396
Создано док-PR	82
Смержено из них	82 (100%)
Целевые ветки	52 → release/13.3, 27 → release/13.4, 3 → main
Медиана от создания до merge	44.8 часов
Мерж в течение 24ч / 7 дней	38% / 96%

396 запусков → 82 PR — это не дефект. Бóльшая часть коммитов (рефакторинг, тесты, зависимости) не требует документации. Агент 314 раз за 30 дней правильно определил, что «документация не нужна». Ключевой момент: агент никогда не мержит сам. Он создаёт draft PR, а SME-ревьюер (тот же инженер, который слил фичу) проверяет содержание.

An agent that says “no docs needed” 300+ times is a feature, not a defect.

«Агент, который 300+ раз отвечает “документация не нужна” — это фича, а не баг.»

— David Pine, github.blog

Как работает pipeline

Workflow разделён на два этапа: детерминированный bash до агента и сам агент после.

Pre-agent bash (без LLM):
1. Извлекает milestone исходного PR (например, «13.4»).
2. Парсит linked issues из тела PR (Fixes/Closes/Resolves #N).
3. Маппит milestone на ветку docs-репозитория: 13.4 → release/13.4 на aspire.dev.
4. Фолбэк: base ref PR, затем main.

Это, по словам авторов, «single highest-leverage choice» (источник) — milestone уже стоят на PR, а ветки docs-репозитория следуют той же нумерации. Агент получает структурированный вход и не угадывает целевую ветку.

AI-агент (GitHub Agentic Workflow):
— Читает diff и linked issues.
— Решает: нужна ли документация (‘user-facing change’ vs internal).
— Если да — генерирует контент в checkout docs-репозитория, следуя voice/MDX/Starlight-конвенциям.
— Создаёт draft PR с label docs-from-code и ревьюером из исходного PR.
— Комментирует в исходный PR со ссылкой на docs-PR.

Что пошло не так при первом запуске

Первая версия была слишком щедрой: агент создавал PR для CI-твиков и рефакторинга логирования. Из 69 PR — 9 закрыты без мержа (≈13%). Исправление: уточнили в промпте определение «user-facing change» и добавили негативные примеры (CI, internal helpers, tests-only). После этого false-positive rate упал до нуля (источник).

Безопасность: safe-outputs contract

Агент работает с двумя GitHub App-токенами, привязанными ровно к двум репозиториям. AGENTS.md, манифесты зависимостей и security-конфиг — в protected-files, агент их не трогает. PR создаётся всегда draft, всегда в main или release/*, fallback — issue в случае ошибки. Это не stylish choice, а требование security-review (источник).

Три типа документации: разные входы, разная стратегия

AI-агенты работают с документацией по-разному в зависимости от типа задачи. Сравнение — на схеме:

README — по исходникам, changelog — по git diff, API-доки — по аннотациям и тестам. Для каждого типа — свой промпт и свой чеклист.

README: агент читает код, человек проверяет факты

README — самая рутинная задача: агент сканирует репозиторий (структуру, докстринги, package.json/pyproject.toml, тесты) и генерирует файл. Проблема не в генерации, а в проверке: команда из README, которой нет в коде, дойдёт до тысяч читателей.

Рабочий промпт:

Изучи исходники проекта (модули, скрипты, примеры, тесты).
Напиши README.md: назначение проекта, установка, быстрый старт,
примеры использования, структура каталогов, лицензия.
Каждую команду установки/запуска проверь по исходникам —
не выдумывай. Не упоминай то, чего нет в репозитории.
Формат: markdown, уровень H2, без H1.

Готовые сервисы для README: DeepWiki от Cognition (автоматическая вики по репозиторию), ReadmeAI (генератор README с настройкой секций). Смежная тема — как писать README для AI-агентов (Habr, декабрь 2025): исследование 2303 контекстных файлов показало, что «контекстный долг» по документации растёт вместе с числом AI-инструментов.

Changelog: новые записи — агенту, историю — не трогать

Changelog — территория, где «навести порядок» означает сломать историческую точность. Агент должен писать только новые записи по диффам и никогда не редактировать старые. Старое имя в changelog за 2024 год — историческая точность, а не ошибка.

Посмотри git diff с момента прошлого тега (git log --oneline v2.1..HEAD).
Добавь записи в CHANGELOG.md по формату Keep a Changelog:
Added / Changed / Deprecated / Removed / Fixed / Security.
Существующие записи НЕ редактируй.
Исторические имена API/CLI не изменяй.

В кейсе Aspire companion workflow milestone-changelog.md запускается каждые два часа, собирает слитые PR за активный milestone и ведёт wiki-страницу «13.x Change Log» с editorial-feedback issue. Источник — публичный в microsoft/aspire.

API-документация: аннотации + тесты = промпт

API-документация — самая требовательная к точности. Агент должен читать аннотации типов (TypeScript interfaces, Python docstrings, Go doc comments) и тесты (как live-примеры вызовов), а не генерировать «по памяти».

Прочитай src/api/ и tests/api/. Обнови docs/api-reference.md:
опиши каждый экспортный метод, его параметры (с типами),
возвращаемое значение и пример из тестов.
Не трогай OpenAPI-спеку напрямую — только markdown-документацию.
Если метод deprecated в коде — пометь в доке.

Ключевое правило: тесты как источник правды. Если агент генерирует пример вызова, он должен взять его из существующего теста, а не выдумать.

Инструменты: Claude Code, Codex, Gemini CLI

Для документационных задач подходят все три терминальных агента, но с разными компромиссами:

Критерий	Claude Code	Codex CLI	Gemini CLI
Модель по умолчанию	Claude Sonnet 5 / Opus 4	codex-mini (o4-mini)	Gemini 2.5 Pro
Headless-режим	`claude -p "..."` + GitHub Actions	Облачные sandbox-задачи	`gemini -p "..."`
Контекстное окно	200K+ токенов	192K токенов	1M токенов
Чтение файлов	да (Bash, Read, Write)	да (+ гоняет тесты)	да (Read, Write, Bash)
CI/CD интеграция	GitHub Actions (документация)	GitHub App (документация)	Gemini CLI Actions (экспериментально)
Стоимость	API: от $3/1M input; подписка: Pro $20/мес	API: $1.50/1M input, $6/1M output (codex-mini)	Бесплатно через AI Studio API
Доступность в РФ	Требует VPN + зарубежную карту	Требует VPN	Доступен через VPN, API-ключ бесплатный

Claude Code: headless + GitHub Actions

Claude Code — единственный из трёх с production-ready интеграцией в GitHub Actions. Быстрая настройка: /install-github-app в интерактивном терминале ставит GitHub App, сохраняет API-ключ как secret и открывает PR с workflow-файлом (документация).

Два режима работы:
— Interactive: агент ждёт @claude в комментарии к issue/PR и отвечает на запрос.
— Automation: workflow содержит prompt, агент запускается по событию (merge, cron, issue open).

Минимальный workflow для документации:

name: Docs on merge
on:
  pull_request:
    types: [closed]
jobs:
  docs:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
        with: { fetch-depth: 1 }
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Посмотри diff этого PR. Если это user-facing изменение,
            обнови README.md и/или CHANGELOG.md.
            Существующие записи не редактируй.
            Создай коммит с префиксом [docs].

Агент получает diff, решает нужна ли дока, правит файлы и коммитит. Безопасность — в CLAUDE.md проекта и --allowedTools в claude_args.

Codex: облачные sandbox-задачи параллельно

Codex (OpenAI) работает иначе: каждая задача — отдельный облачный контейнер с вашим репозиторием (документация). Агент может читать/править файлы, запускать тесты и линтеры. Задача занимает от 1 до 30 минут, результат — коммиты в sandbox или PR в GitHub.

Для документации это удобно: можно назначить пять задач параллельно (README, changelog за спринт, API-доки для нового модуля, обновление CONTRIBUTING.md, проверка ссылок) и получить пять draft PR. Codex-Clause: задачи асинхронные, «подправить» агента во время работы нельзя — только после получения результата.

Рабочий промпт для Codex:

Analyze the changes in the current branch compared to main.
If any changes affect the public API or user-visible behavior,
update CHANGELOG.md with entries in Keep a Changelog format.
Do not modify historical entries. Do not change API names or CLI commands.
Commit your changes with a [docs] prefix.

Gemini CLI: бесплатный вход, лимиты на ответственном

Gemini CLI — бесплатный терминальный агент от Google с доступом к Gemini 2.5 Pro через API-ключ AI Studio (установка). Контекстное окно до 1M токенов — больше, чем у конкурентов. Подходит для генерации черновиков README и первичной документации, где скорость важнее идеальной точности.

Лимит: бесплатный tier имеет rate limits, которые могут не выдержать массовую генерацию документации на большом репозитории. Для production-автоматизации лучше Claude Code или Codex.

Автоматизация через CI/CD: workflow от мержа до док-PR

Полный pipeline документационной автоматизации выглядит так:

Pipeline из кейса Microsoft Aspire: merge PR → GitHub Action → pre-agent bash (milestone → ветка) → AI-агент (diff → решение → draft PR) → SME-ревью. Источник: github.blog, 08.07.2026.

Сценарий 1: README при первом коммите

Триггер: push в main с пустым или отсутствующим README.md.

name: Generate README
on:
  push:
    branches: [main]
    paths: ['src/**']
jobs:
  readme:
    runs-on: ubuntu-latest
    if: "!hashFiles('README.md')"
    steps:
      - uses: actions/checkout@v6
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Репозиторий не имеет README. Проанализируй структуру,
            модули и тесты. Напиши README.md с секциями:
            # Название, ## Описание, ## Установка, ## Быстрый старт,
            ## Лицензия. Команды проверь по коду.
          claude_args: "--max-turns 5"

Сценарий 2: Changelog при релизе

Триггер: создание GitHub Release (тег v*).

name: Update Changelog
on:
  release:
    types: [created]
jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with: { fetch-depth: 0 }
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Проанализируй git log с предыдущего тега.
            Добавь раздел в CHANGELOG.md для версии ${{ github.event.release.tag_name }}.
            Формат: Keep a Changelog (Added/Changed/Fixed/Removed).
            Существующие записи не редактируй.

Сценарий 3: API-документация при добавлении endpoint

Триггер: изменение файлов в src/api/ в PR.

name: API docs check
on:
  pull_request:
    paths: ['src/api/**']
jobs:
  api-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            В этом PR добавлены/изменены endpoint-ы в src/api/.
            Проверь, обновлена ли документация в docs/api/.
            Если нет — создай или обнови markdown-файл
            с описанием новых/изменённых методов, параметров и примеров.
            Примеры бери из tests/api/.
          claude_args: "--max-turns 3"

Советы по CI/CD

Ограничивайте --max-turns: агент без лимита может уйти в цикл правок. Для документации 3–5 ходов достаточно.
Храните CLAUDE.md в корне: агент читает его при каждом запуске. Опишите формат доки, тон, стиль и список «что нельзя трогать».
Draft-only: никогда не мержьте автоматически. AI-документация — черновик, а не финальная версия.
Бюджет: GitHub Actions минуты + API-токены. Для nhỏких проектов — хватит бесплатного tier; для больших — считайте стоимость (один run = ~$0.02–0.10 в зависимости от размера diff и модели).

Промпты для типовых задач

Готовые формулировки, адаптированные под Claude Code / Codex CLI / Gemini CLI:

# README по репозиторию
Изучи исходники и существующую документацию. Напиши README.md:
назначение, установка, быстрый старт, примеры, структура, лицензия.
Каждую команду проверь по коду. Не упоминай того, чего нет в проекте.

# Запись в changelog по диффу
Посмотри git diff с момента прошлого тега (git log --oneline v1.2..HEAD).
Добавь записи в CHANGELOG.md по формату Keep a Changelog: Added / Changed /
Fixed / Deprecated. Существующие записи не редактируй.

# Обновление API-документации
Прочитай src/api/ и tests/api/. Обнови docs/api-reference.md:
опиши каждый экспортный метод, параметры (с типами),
возвращаемое значение и пример из тестов.
Не трогай OpenAPI-спеку напрямую.

# Проверка актуальности доки
Сверь README.md с текущим состоянием кода:
все команды установки/запуска должны работать,
описание модулей — совпадать со структурой,
примеры — быть актуальными. Список расхождений.

# Проверка перед мержем
Сверь, что все ссылки внутри документации ведут на существующие страницы,
все redirect-правила указаны, в changelog нет дублей записей.
Отчёт — списком файлов с проблемами.

Ограничения (честно)

Галлюцинации в документации опаснее, чем в коде. Несуществующая команда установки в README уйдёт к тысячам читателей. Проверять каждое утверждение по исходникам — обязательный шаг, а не «хорошая практика».
Шаблонность. README, сгенерированные AI, выглядят одинаково (исследование, Habr, июль 2026). Если ваш README неотличим от соседнего — редактируйте вручную.
Историческая точность changelog. Агент может «исправить» старую запись, и это будет ошибка. Safe-лист: исторические записи, API-имена, CLI-команды — не трогать.
Big diffs ломают контекст. В кейсе Aspire метаданные PR (linked issues, milestone) извлекаются bash до запуска агента, чтобы тот получал структурированный вход, а не сырую кашу диффов (источник).
Агент не заменяет техрайтера. Он берёт на себя рутину (обновление reference-страниц, запись changelog по диффам, синхронизация README с кодом), но решение о терминологии, структуре доки и нарративе остаётся за человеком.
Стоимость CI/автоматизации. Каждый запуск агента в GitHub Actions потребляет Actions-минуты и API-токены. В Aspire за 30 дней — 396 запусков, что при Claude Sonnet 4.5 обходится примерно в $4–15 в месяц (зависит от размера diff и модели).

Инструменты и российские реалии

Для генерации документации подходят все упомянутые инструменты, но доступность в РФ отличается:

Инструмент	VPN нужен?	Оплата	Альтернатива
Claude Code	Да	Подписка Anthropic (Pro $20/мес) или API-ключ с зарубежной картой. Mir/UnionPay не принимаются. Работает через VPN с Claude Desktop.	OpenCode (бесплатные модели, без VPN)
Codex CLI	Да	API OpenAI ($1.50/1M input для codex-mini). Оплата через зарубежную карту или виртуальный номер.	—
Gemini CLI	Да (нестабильно)	Бесплатно через API-ключ Google AI Studio. Google-сервисы периодически блокируют российские аккаунты.	OpenCode + локальные модели
OpenCode	Нет	Бесплатные модели из коробки (Qwen, DeepSeek через Ollama или облако).	—

Русскоязычные материалы по теме:

«Как писать README-файлы для AI-агентов» (Habr, декабрь 2025) — исследование 2303 контекстных файлов, термин «контекстный долг».
«AI для документации кода: генерируем README и обновляем changelog» — кейс Márcio Florindo: 4 продукта, 695 файлов, 3 дня (smежная статья на нашем сайте).
«Почему README стали шаблонными» (Habr, июль 2026) — data-driven разбор генерации README с ИИ.

Честно о пробеле: автоматизация документации через CI/CD (Claude Code GitHub Actions, Codex в GitHub) — тема свежая и в рунете практически не описана. Статьи на Habr ограничиваются ручной генерацией README через чат-боты; pipeline «merge → AI → docs PR» — это уровень production-проектов, который только начинает появляться в блогах.

Вывод

Автоматизация документации через AI-агентов — это не «генерировать и забыть». Это три конкретных pipeline:

README по исходникам — одноразово или при первом коммите.
Changelog по git diff — при каждом релизе или мерже в release-ветку.
API-документация по аннотациям и тестам — при изменении публичного API.

Кейс Microsoft Aspire показывает зрелую модель: agent делает типовую работу (396 → 82, 100% merge rate), человек проверяет. Начать можно с малого: один claude -p "..." в CI, который обновляет changelog при релизе. Инструменты вырастут из работы — как это было в Aspire.

Насколько публикация полезна?

Нажмите на звезду, чтобы оценить!

Средняя оценка / 5. Количество оценок:

Оценок пока нет. Поставьте оценку первым.

Статьи по теме:

AI-агент пишет тесты: pytest, Playwright и integration-тесты

Huzzah: пишем код через псевдокод — альтернативный подход к ИИ-программированию

Claude Code vs Cursor vs ZCode: что выбрать в августе 2026