Туториал: агент ревью GitHub PR

Проблема: Команда открывает PR быстрее, чем вы успеваете их ревьюить. PR висят днями в ожидании взгляда. Джуниоры мёрджат баги, потому что никто не нашёл время проверить. Утро начинается с просмотра диффов вместо продуктивной работы.

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

Что вы построите:

┌───────────────────────────────────────────────────────────────────┐
│                                                                   │
│   Cron Timer  ──▶  Hermes Agent  ──▶  GitHub API  ──▶  Review     │
│   (каждые 2ч)      + gh CLI           (PR diffs)       delivery   │
│                    + навык                             (Telegram, │
│                    + память                            Discord,   │
│                                                        local)     │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

В этом руководстве используются cron-задачи для опроса PR по расписанию — сервер и публичный эндпоинт не нужны. Работает за NAT и файрволами.

---

Требования

• Hermes Agent установлен — см. руководство по установке
• Запущенный шлюз для cron-задач:

  hermes gateway install   # Установить как сервис
  # или
  hermes gateway           # Запустить в foreground

• GitHub CLI (gh) установлен и аутентифицирован:

  # Установка
  brew install gh        # macOS
  sudo apt install gh    # Ubuntu/Debian
  
  # Аутентификация
  gh auth login

• Мессенджер настроен (опционально) — Telegram или Discord

---

Шаг 1: Проверьте настройку

Убедитесь, что Hermes может обращаться к GitHub. Запустите чат:

hermes

Проверьте простой командой:

Run: gh pr list --repo NousResearch/hermes-agent --state open --limit 3

Вы должны увидеть список открытых PR. Если работает — можно продолжать.

---

Шаг 2: Попробуйте ручное ревью

Всё ещё в чате, попросите Hermes проверить реальный PR:

Review this pull request. Read the diff, check for bugs, security issues,
and code quality. Be specific about line numbers and quote problematic code.

Run: gh pr diff 3888 --repo NousResearch/hermes-agent

Hermes:

1. Выполнит gh pr diff, чтобы получить изменения
2. Прочитает весь дифф
3. Подготовит структурированное ревью с конкретными находками

Если качество устраивает — время автоматизировать.

---

Шаг 3: Создайте навык ревью

Навык даёт Hermes стабильные правила ревью, которые сохраняются между сессиями и cron-запусками. Без него качество ревью будет плавать.

mkdir -p ~/.hermes/skills/code-review

Создайте ~/.hermes/skills/code-review/SKILL.md:

---
name: code-review
description: Review pull requests for bugs, security issues, and code quality
---

# Code Review Guidelines

When reviewing a pull request:

## What to Check
1. **Bugs** — Logic errors, off-by-one, null/undefined handling
2. **Security** — Injection, auth bypass, secrets in code, SSRF
3. **Performance** — N+1 queries, unbounded loops, memory leaks
4. **Style** — Naming conventions, dead code, missing error handling
5. **Tests** — Are changes tested? Do tests cover edge cases?

## Output Format
For each finding:
- **File:Line** — exact location
- **Severity** — Critical / Warning / Suggestion
- **What's wrong** — one sentence
- **Fix** — how to fix it

## Rules
- Be specific. Quote the problematic code.
- Don't flag style nitpicks unless they affect readability.
- If the PR looks good, say so. Don't invent problems.
- End with: APPROVE / REQUEST_CHANGES / COMMENT

Проверьте, что навык загружен — запустите hermes и увидите code-review в списке навыков при старте.

---

Шаг 4: Обучите агента вашим стандартам

Именно это делает ревьюера по-настоящему полезным. Запустите сессию и расскажите Hermes о стандартах команды:

Remember: In our backend repo, we use Python with FastAPI.
All endpoints must have type annotations and Pydantic models.
We don't allow raw SQL — only SQLAlchemy ORM.
Test files go in tests/ and must use pytest fixtures.

Remember: In our frontend repo, we use TypeScript with React.
No `any` types allowed. All components must have props interfaces.
We use React Query for data fetching, never useEffect for API calls.

Эти воспоминания сохраняются навсегда — ревьюер будет соблюдать ваши соглашения без дополнительных напоминаний.

---

Шаг 5: Создайте автоматическую cron-задачу

Теперь соберём всё вместе. Создайте cron-задачу, которая запускается каждые 2 часа:

hermes cron create "0 */2 * * *" \
  "Check for new open PRs and review them.

Repos to monitor:
- myorg/backend-api
- myorg/frontend-app

Steps:
1. Run: gh pr list --repo REPO --state open --limit 5 --json number,title,author,createdAt
2. For each PR created or updated in the last 4 hours:
   - Run: gh pr diff NUMBER --repo REPO
   - Review the diff using the code-review guidelines
3. Format output as:

## PR Reviews — today

### [repo] #[number]: [title]
**Author:** [name] | **Verdict:** APPROVE/REQUEST_CHANGES/COMMENT
[findings]

If no new PRs found, say: No new PRs to review." \
  --name "pr-review" \
  --deliver telegram \
  --skill code-review

Убедитесь, что задача добавлена:

hermes cron list

Другие полезные расписания

Расписание	Когда
0 */2 * * *	Каждые 2 часа
0 9,13,17 * * 1-5	Три раза в день, только в будни
0 9 * * 1	Еженедельная сводка в понедельник утром
30m	Каждые 30 минут (для репозиториев с высокой активностью)

---

Шаг 6: Запустите вручную

Не хотите ждать расписания? Запустите задачу прямо сейчас:

hermes cron run pr-review

Или из чат-сессии:

/cron run pr-review

---

Идём дальше

Постить ревью напрямую в GitHub

Вместо доставки в Telegram можно попросить агента комментировать сам PR:

Добавьте в промпт cron-задачи:

After reviewing, post your review:
- For issues: gh pr review NUMBER --repo REPO --comment --body "YOUR_REVIEW"
- For critical issues: gh pr review NUMBER --repo REPO --request-changes --body "YOUR_REVIEW"
- For clean PRs: gh pr review NUMBER --repo REPO --approve --body "Looks good"

Еженедельный дашборд PR

Создайте понедельничную сводку по всем репозиториям:

hermes cron create "0 9 * * 1" \
  "Generate a weekly PR dashboard:
- myorg/backend-api
- myorg/frontend-app
- myorg/infra

For each repo show:
1. Open PR count and oldest PR age
2. PRs merged this week
3. Stale PRs (older than 5 days)
4. PRs with no reviewer assigned

Format as a clean summary." \
  --name "weekly-dashboard" \
  --deliver telegram

Мониторинг нескольких репозиториев

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

---

Решение проблем

«gh: command not found»

Шлюз запускается в минимальном окружении. Убедитесь, что gh есть в системном PATH, и перезапустите шлюз.

Ревью слишком общие

1. Добавьте навык code-review (Шаг 3)
2. Передайте Hermes соглашения команды через память (Шаг 4)
3. Чем больше контекста о вашем стеке, тем лучше ревью

Cron-задача не запускается

hermes gateway status    # Шлюз запущен?
hermes cron list         # Задача активна?

Лимиты запросов

GitHub разрешает 5 000 API-запросов в час для аутентифицированных пользователей. Одно ревью PR расходует ~3–5 запросов (list + diff + опциональные комментарии). Даже 100 ревью в день укладываются в лимит с большим запасом.

---

Что дальше?

• Ревью PR через вебхуки — мгновенные ревью при открытии PR (требуется публичный эндпоинт)
• Daily Briefing Bot — совместите ревью PR с утренним дайджестом новостей
• Создайте плагин — оберните логику ревью в переиспользуемый плагин
• Профили — запустите выделенный профиль ревьюера с собственной памятью и конфигурацией
• Резервные провайдеры — ревью будут работать, даже если один из провайдеров недоступен