Агент поддержки документации

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

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

Что делает агент

По еженедельному расписанию (или по требованию через назначение) агент документации:

1. Находит устаревшую документацию — обнаруживает ссылки на старые API, устаревшие флаги или удаленные функции
2. Проверяет наличие сломанных ссылок — ползает внутренние и внешние ссылки; отмечает 404
3. Проверяет примеры — запускает фрагменты кода и проверяет, что они компилируются/выполняются
4. Обновляет changelog — извлекает названия объединенных PR в черновой changelog
5. Открывает PR — консолидирует результаты в один PR с четкими разделами для проверки

Настройка

Предварительные условия

• Рабочая область AACWorkflow с активным агентом
• Репозиторий документации (или папка документации в основном репозитории)
• Среда выполнения агента с установленными bash, Go или Node.js

Шаг 1: Создание агента поддержки документации

1. Перейдите в Settings → Agents и нажмите New Agent
2. Выберите ваш runtime и провайдер
3. Назовите его docs-audit или doc-keeper
4. Добавьте эту системную подсказку:

Role: Documentation auditor
Task: Every week or on-demand:
1. Clone the repository
2. Find all .md and .mdx files
3. Check all links (internal with grep, external with curl)
4. Find code snippets and validate syntax
5. Look for TODOs, deprecated markers, or version mismatch
6. Summarize findings in a changelog-style report
7. Create a GitHub branch "docs/maintenance-<date>"
8. Open a PR with all findings grouped by category
9. Link the PR to workspace as "docs-audit"

Output format:
## Stale References
- api/v1/GetIssue() → moved to /v2/GetIssue
- Example in quickstart.md lines 45–50 uses old syntax

## Broken Links
- Internal: docs/guides/auth.mdx → "see [Setup Guide](/setup)" (guide removed)
- External: 3 links to archived.example.com (404)

## Code Examples
- JavaScript example in index.mdx fails to parse (syntax error line 12)

## Changelog
Merged PRs since last scan:
- feat: add workspace invites
- fix: pagination token bug
- docs: update API docs

Шаг 2: Планирование агента

В AACWorkflow перейдите в Settings → Automations и создайте запланированную задачу:

• Trigger: Еженедельно (например, понедельник в 9:00)
• Task: Назначьте docs-audit агенту
• Template: docs-maintenance

Или используйте cron-задачу в вашей собственной инфраструктуре:

# Запустите аудит документации каждый понедельник в 9:00
0 9 * * 1 curl -X POST https://aacworkflow.com/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent_id": "docs-audit", "title": "Weekly docs audit"}'

Шаг 3: Настройка доступа к репозиторию

Добавьте .aacworkflow/config.yml в ваш репозиторий:

docs_audit:
  paths:
    - "docs/"
    - "README.md"
    - "CHANGELOG.md"
  exclude:
    - "docs/archived/"
    - "node_modules/"
  checks:
    - link-validation
    - code-snippet-syntax
    - version-references
    - deprecated-markers

Пример выходного PR

Title: docs: maintenance audit for 2025-06-22

Body:

## Stale References (3 items)
- Line 87 in docs/agent-setup.md: "Runtime v2" → should be "Runtime v3"
- docs/api/endpoints.md: Old Swagger URL → update to OpenAPI v3.1
- Quickstart: "Deploy to Heroku" section → remove (service EOL)

## Broken Links (7 items)
- docs/guides/docker.mdx: line 23 → /install/docker-compose (moved to /docker)
- External: https://old-api-docs.example.com → 404

## Code Examples (2 updated)
- Python snippet in examples/webhook.md uses old v1 client → fixed
- Go example missing error handling → added

## Changelog Fragment
### Merged since 2025-06-15
- feat(api): add workspace export endpoint
- fix: typo in API error messages
- docs: expand rate limiting guide

---
Review and merge to publish. Auto-close stale branches after merge.

Советы и лучшие практики

• Автоматизация Changelog — извлекайте названия объединенных PR в раздел ## Unreleased, чтобы у вас был фору на примечания к выпуску
• Проверка примера — используйте контейнеры Docker для проверки примеров кода на разных языках без локальной установки всего
• Timeout внешней ссылки — установите 5-секундный timeout для проверок внешних ссылок, чтобы избежать зависаний
• Исключить паттерны — держите архивированную документацию вне аудита (добавьте в .aacworkflow/config.yml)
• Врата утверждения — требуйте хотя бы одного человеческого утверждения перед автоматическим объединением PR документации

Связанные руководства

• Release Notes Agent — конвертируйте объединенные PR в полированные примечания к выпуску
• CI Triage Agent — исправляйте сломанный CI, а не сломанную документацию