Автоматизация кросс-репозиторной документации с помощью GitHub Agentic Workflows: опыт и кейсы

Введение

Когда я начал активно использовать vibe coding — подход, при котором код пишется не вручную, а генерируется AI-агентами на основе описания задачи, — я быстро столкнулся с проблемой: документация перестала успевать за кодом. В одном проекте у нас было пять репозиториев: фронтенд, бэкенд, ML-модели, инфраструктура и тесты. Каждый раз, когда AI-агент вносил изменения в один репозиторий, он не обновлял документацию в других. Через месяц мы получили разрозненные README, устаревшие схемы API и полную путаницу в архитектурных решениях.

Решение пришло неожиданно: GitHub Agentic Workflows. Это не просто CI/CD — это система, где AI-агенты могут самостоятельно анализировать изменения, писать документацию и синхронизировать её между репозиториями. В этой статье я расскажу, как мы настроили автоматизацию кросс-репозиторной документации, какие инструменты использовали и какие результаты получили.

Проблема: документация — узкое горлышко

В традиционной разработке документация часто отстаёт от кода на недели. В мире vibe coding, где AI-агенты генерируют код за минуты, этот разрыв становится критическим. Вот с чем мы столкнулись:

• Изменения в одном репозитории ломали документацию в другом. Например, обновление схемы данных в бэкенде требовало изменений в документации API, которая лежала в отдельном репозитории.
• Ручная синхронизация не работала. Команда тратила 2-3 часа в неделю только на сверку документации между репозиториями.
• AI-агенты не умели учитывать контекст. Они генерировали документацию для одного репозитория, не зная, что уже написано в других.

Как пишет GitHub в официальной документации по Actions (https://docs.github.com/en/actions), workflows позволяют автоматизировать практически любые задачи, включая генерацию документации. Но стандартные триггеры не решали нашу проблему: нам нужна была система, которая отслеживает изменения во всех репозиториях и синхронизирует документацию в реальном времени.

Решение: GitHub Agentic Workflows + AI-агенты

Мы построили архитектуру на трёх компонентах:

1. GitHub Agentic Workflows — как оркестратор. Мы использовали workflow с событиями pull_request и push, но с дополнительным шагом: AI-агент анализирует diff и определяет, какие репозитории затронуты.

2. AI-агент для генерации документации — на базе GPT-4 Turbo, но с кастомными промптами. Агент получает diff, читает существующую документацию из целевого репозитория и генерирует обновления.

3. Кросс-репозиторный триггер — через GitHub API. Когда в одном репозитории появляется PR, workflow отправляет запрос в другие репозитории на обновление документации.

Конкретный пример

Допустим, мы меняем эндпоинт /users в бэкенд-репозитории. Вот как это работает:

1. Разработчик (или AI-агент) создаёт PR в backend-repo.
2. Workflow doc-sync.yml срабатывает на pull_request.
3. AI-агент анализирует diff — видит, что изменён контроллер UsersController.
4. Агент читает docs/api.md из frontend-repo и docs/integration.md из infra-repo.
5. Генерирует обновления: меняет описание эндпоинта, добавляет пример запроса, обновляет схему ошибок.
6. Создаёт PR в каждом целевом репозитории с описанием изменений.

Ключевой момент: агент не просто копирует код в документацию — он понимает контекст. Например, если изменение ломает обратную совместимость, агент добавляет секцию "Breaking changes" и рекомендации по миграции.

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

Мы использовали следующие инструменты:

• GitHub Actions — для триггеров и выполнения workflow. Версия actions/checkout@v4 и actions/github-script@v7.
• GitHub API — для создания PR в других репозиториях. Использовали octokit в JavaScript-скриптах.
• OpenAI API — для генерации текста. Модель gpt-4-turbo-2026-04-09.
• markdownlint — для проверки качества документации после генерации.

Пример части workflow (упрощённо):

name: Cross-repo doc sync
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate docs
        uses: actions/github-script@v7
        with:
          script: |
            const diff = await github.rest.pulls.get({
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: context.issue.number
            });
            // Здесь вызываем AI-агента через OpenAI API
            const docs = await generateDocs(diff.data);
            // Создаём PR в другом репозитории
            await github.rest.pulls.create({
              owner: 'other-org',
              repo: 'other-repo',
              title: 'Update docs from backend change',
              body: docs,
              head: 'doc-sync-bot/main',
              base: 'main'
            });

Результаты

Мы запустили эту систему три месяца назад. Вот что получили:

Самое неожиданное: AI-агенты начали предлагать улучшения, которые мы не просили. Например, при изменении API они автоматически добавляли примеры на Python и JavaScript, хотя в исходной документации были только curl-запросы.

Выводы и рекомендации

1. Не бойтесь AI для документации. Многие думают, что AI-агенты генерируют "воду" — но с правильными промптами и контекстом они выдают отличный результат. Главное — дать им доступ к существующей документации и diff.

2. Кросс-репозиторная синхронизация — это must-have для vibe coding. Если вы используете AI-агентов для генерации кода, без автоматизации документации вы быстро утонете в хаосе.

3. GitHub Agentic Workflows — зрелый инструмент. На июль 2026 года это не экспериментальная фича, а стабильное решение. Документация GitHub Actions подробная (https://docs.github.com/en/actions/using-workflows), а сообщество активно делится шаблонами.

4. Тестируйте качество документации. Мы добавили шаг с markdownlint и автоматическими проверками на соответствие OpenAPI-схемам. Это отсекает большую часть ошибок.

Заключение

Автоматизация кросс-репозиторной документации с GitHub Agentic Workflows — это не про "заменить человека", а про "дать человеку заниматься тем, что важно". В мире, где AI-агенты пишут код быстрее, чем мы успеваем его документировать, такие системы становятся необходимостью.

Мы планируем расширить систему: добавить поддержку диаграмм (Mermaid) и автоматическую генерацию changelog на основе diff. А пока — делюсь опытом и буду рад вопросам в комментариях.

Использованные источники: GitHub Docs (https://docs.github.com/en/actions), OpenAI API documentation (https://platform.openai.com/docs), личный опыт команды из 5 репозиториев.