Как организовать совместную работу нескольких Claude Code над одним проектом: handoffs, rollup’ы и email-каналы

Запустить один Claude Code и попросить его написать весь проект целиком - верный способ через 20 минут получить либо «контекст переполнен», либо бессвязный код, который агент сам же и сломал. Спасает мультиагентный подход: несколько экземпляров Claude Code работают параллельно, каждый со своей задачей. Но как им обмениваться информацией без общего хранилища состояния? Ответ - три паттерна: handoff, rollup и email-каналы. Разберем их на живых примерах.

Одиночка упирается в потолок

Даже с контекстом в 1 млн токенов, который получил Anthropic Opus 4.6, один агент не способен удерживать всю архитектуру проекта. Он забывает, что сделал вчера, путает названия модулей, а при редактировании одного файла случайно ломает другой. Мы уже обсуждали построение саморазвивающейся мультиагентной системы - но там была централизованная координация. Здесь же каждый агент равноправен, и единственное, что их объединяет, - файловая система и, опционально, почта.

Handoff: передача контекста без потерь

Handoff - это файл (обычно JSON или YAML), который один агент оставляет другому как «пакет» со своим состоянием. По сути, сериализованный мозг. Ключевые поля:

• status - что сделано и что не получилось.
• assigned_to - кому предназначается.
• context_summary - сжатая выжимка решений.
• next_steps - список конкретных задач.

Как не надо делать:

{
  "task": "доделать авторизацию",
  "done": "нет"
}

Это мусор. Агент не поймёт, что уже сделано, а что нет. Правильный handoff похож на мини-лекцию:

{
  "handoff_version": 1,
  "from_agent": "backend-agent",
  "to_agent": ["frontend-agent", "test-agent"],
  "status": {
    "completed": ["POST /login endpoint", "JWT middleware"],
    "pending": ["refresh token rotation", "rate limiting"],
    "failed": ["OAuth2 integration - Facebook returns 403"]
  },
  "context_summary": "Используем mysql2 с prepared statements. JWT-секрет в env.",
  "next_steps": [
    "Frontend: подключить /login с передачей credentials в body",
    "Test: написать сценарий истечения access token"
  ],
  "created_at": "2026-04-23T10:15:00Z"
}

Структуру .handoffs/ лучше положить в корень проекта и заигнорить в .gitignore (если не хотите засорять репозиторий). Имена файлов - {timestamp}-{from}-{to}.json. Удобный способ быстро создать handoff - использовать слэш-команды в Claude Code. Например, /handoff, который сам генерирует шаблон.

Rollup: дайджест из сотен файлов

Когда handoff'ов становится десятки, а агентов несколько, нужен агрегатор. Rollup - это скрипт, который собирает все свежие handoff'ы, объединяет их и создает единый summary. Типичный сценарий: перед началом нового цикла каждый агент запускает rollup, чтобы понять общую картину.

Пример rollup на bash (минимум зависимостей):

#!/bin/bash
HANDOFF_DIR=".handoffs"
ROLLUP_FILE=".rollup/current-summary.md"
mkdir -p ".rollup"

# Собираем все handoff'ы за последние 2 часа
find "$HANDOFF_DIR" -name "*.json" -newer "$ROLLUP_FILE" -type f 2>/dev/null | while read f; do
    echo "### $f" >> "$ROLLUP_FILE.tmp"
    jq '{status, next_steps, context_summary}' "$f" >> "$ROLLUP_FILE.tmp" >> "$ROLLUP_FILE.tmp"
    echo "" >> "$ROLLUP_FILE.tmp"
done

# Если есть новые данные - перезаписываем
if [ -f "$ROLLUP_FILE.tmp" ]; then
    mv "$ROLLUP_FILE.tmp" "$ROLLUP_FILE"
    echo "Rollup обновлен: $ROLLUP_FILE"
else
    echo "Новых handoff'ов нет."
fi

Обратите внимание на jq - он должен быть установлен. Если хотите более детализированный анализ, пишите rollup на Python с парсингом дат и фильтром дубликатов. Но для старта bash - самое то.

Email-каналы: асинхронный обмен для агентов

Handoff-файлы - это однонаправленная передача. А если нужно обсуждение? Для этого поднимаем почтовый канал. Каждый агент имеет свой email-ящик (или один общий с тегами в теме). Агенты отправляют друг другу письма-запросы, и тот, к кому обращаются, отвечает, когда освободится.

Настройка на стороне агента:

# Пример конфигурации .claude/email-config.yml
imap_server: imap.gmail.com
imap_port: 993
email: agent-backend@example.com
password: ${EMAIL_PASSWORD}
check_interval: 60 # секунд

# Паттерны для обработки входящих
subscribe:
  - subject: "[handoff-request]"
    action: parse_and_update_context
  - subject: "[question]"
    action: reply_with_rollup

Claude Code 2.0 умеет подключать внешние инструменты через кастомные bindings. Вы можете написать простой IMAP-клиент на Python и зарегистрировать его как tool. Когда приходит письмо с нужным subject, агент прерывает текущую задачу, читает вопрос и генерирует ответ на основе своего контекста.

Ошибка новичка: не ограничивать частоту проверки почты. Если агент будет дергать IMAP каждые 5 секунд, он просто утонет в соединениях. Ставьте интервал от 30 секунд до 5 минут, в зависимости от задачи.

Собираем рабочую лошадку: пошаговый план

Теперь сложим три кита в один сценарий. Допустим, у нас проект микросервиса с бэкендом (Go), фронтендом (React) и тестами. Мы запускаем три инстанса Claude Code: agent-be, agent-fe, agent-test.

1Создаём структуру .handoffs/

mkdir -p .handoffs
# Добавляем в .gitignore
echo ".handoffs" >> .gitignore
echo ".rollup" >> .gitignore

2Устанавливаем слэш-команду для быстрого handoff

Используем слэш-команды в Warp: создаём алиас /handoff, который запускает скрипт, запрашивающий поля и сохраняющий JSON.

# .claude/slash-commands/handoff.sh
#!/bin/bash
read -p "Кому (agent id): " to
read -p "Статус: " status
read -p "Контекст (1 строка): " context
read -p "Следующие шаги (через запятую): " steps

cat > .handoffs/$(date +%s)-$(whoami)-${to}.json <

3Настраиваем rollup через cron

crontab -e
# Запускать каждые 10 минут
*/10 * * * * /path/to/rollup.sh

4Подключаем email-канал для agent-be

Создаём Python-скрипт, который регистрируется как инструмент Claude Code (подробнее в документации). Скрипт раз в 60 секунд проверяет новые письма с темой [handoff-request] и сохраняет их содержание в специальный файл .inbox/, откуда агент их читает.

5Запускаем цикл

• agent-be пишет код, оставляет handoff после каждого завершённого модуля.
• agent-fe перед началом работы запускает rollup, видит, что бэкенд закончил эндпоинты, и подхватывает их.
• agent-test получает email-уведомление о новых handoff'ах и запускает тесты.
• Если возникает вопрос, agent-fe отправляет письмо с [question], и бэкенд отвечает.

В результате проект движется параллельно, а не последовательно. Мы уже видели подобный подход в кейсе 17 AI-агентов вместо отдела, но там была горизонтальная специализация. Здесь - ролевая коллаборация с динамической передачей.

Типичные грабли и как на них не наступить

1. Race condition в handoff-файлах. Два агента одновременно пишут в один файл. Решение: добавлять в имя файла timestamp и from_agent, а читать только последние по времени. Ещё вариант - использовать файловую блокировку flock, но это усложняет.

2. Бесконечный спам в email-канале. Агенты зацикливаются, отвечая друг другу. Введите правило: на одно письмо - один ответ. После ответа агент должен проверить, не было ли уже ответа на этот запрос (по Message-ID).

3. Rollup слишком длинный. Если не фильтровать по дате, summary раздувается до десятков килобайт. Ограничивайте окно - например, только handoff'ы за последний час. Старый контекст всё равно будет в конкретных handoff'ах, если понадобится.

4. Забыли подключить email-инструмент. Без интеграции агент не может читать почту. Убедитесь, что в конфигурации claude.json прописан custom tool, и он активен. Проверяйте логами.

Почему это работает и когда не сработает

Паттерн handoff+rollup+email эффективен, когда каждый агент работает над своей зоной ответственности и не требует мгновенной синхронизации. Если задачи сильно переплетены (например, рефакторинг общей библиотеки), проще запустить одного агента с большим контекстом или использовать Claude + n8n для сложных DAG-цепей. Email-каналы добавляют latency - для real-time общения лучше подходят WebSocket или MQTT.

Тем не менее, для классической веб-разработки с чёткими интерфейсами (API-контракты) эта связка работает безотказно. Мы внедрили её в трёх коммерческих проектах, и скорость разработки выросла в 2-3 раза за счёт параллелизации. Главное - не забывать про дисциплину: каждый агент обязан писать handoff, даже если «всё просто».

Часто задаваемые вопросы

Что делать, если агент игнорирует handoff?

Включите в промпт каждого агента инструкцию: «Перед началом задачи проверь файл .rollup/current-summary.md. Если там есть handoff для тебя — прочитай и действуй». Это работает в 90% случаев. Остальные 10% - баг контекстного окна, обновляйте версию Claude Code.

Можно ли обойтись без email, используя только handoff?

Да, если ваши агенты запускаются последовательно или по расписанию. Email нужен для асинхронной коммуникации, когда один агент ждёт ответа другого в реальном времени. Если такого сценария нет, handoff + rollup достаточно.

Как защитить email-канал от внешних писем?

Создайте отдельный почтовый ящик, принимающий письма только от известных отправителей (например, с внутреннего домена). В теме используйте токен, который меняется раз в день. Либо вообще не используйте email, а пользуйтесь очередями типа RabbitMQ, но это уже выходит за рамки гайда.

Подписаться на канал