Handoff pattern: агент A → агент B

Тебе нужен явный handoff от {{agent_a}} к {{agent_b}}. Самая болезненная вещь в multi-agent системах — потеря контекста на стыке. Решается не «передачей всего», а дистилляцией.

1. Handoff vs «общий чат»

«Общий чат» иногда работает на 1-2 шагах, но разваливается как только цепочка длиннее или ветвится.

2. Структура payload (минимум)

handoff_id: hf_2026-05-17_001
from: agent_a
to: agent_b
timestamp: 2026-05-17T10:30:00Z
goal: |
  Одно предложение: чего достичь после твоей работы.

summary: |
  3-7 строк: что произошло у меня (A) до этого момента.
  Только то, что нужно для решения, без истории попыток.

decisions:
  - id: d1
    text: "Используем библиотеку X, не Y"
    reason: "Y не поддерживает feature Z"
    locked: true   # B не может пересмотреть без эскалации
  - id: d2
    text: "База — Postgres"
    locked: true

open_items:
  - id: o1
    text: "Не решён вопрос: использовать ли cron или event-bus"
    impact: "влияет на latency и стоимость"
    suggestion: "склоняемся к event-bus, но нужна проверка"
  - id: o2
    text: "Нужна авторизация для endpoint /admin/*"

artifacts:
  - path: docs/plan.md
    sha256: ...
    purpose: "полный план"
  - path: schemas/user.json
    sha256: ...
    purpose: "схема пользователя"

constraints:
  - "Не трогай app/legacy/**"
  - "Уложись в N токенов / M минут"

success_criteria:
  - "Все endpoints возвращают 200 на happy path"
  - "Тесты в tests/api/ зелёные"

return_schema:
  status: "ok" | "partial" | "failed"
  output: <по схеме B>
  evidence: [...]
  open_questions: [...]
  confidence: 0-100

Каждый блок — обязательный. Пропустишь decisions — B пересмотрит то что A уже зафиксировал. Пропустишь success_criteria — B сдаст «что-то».

3. Где живёт state

Три места, разные роли:

Правило: handoff payload — это сжатая выжимка артефактов в репо. Если payload — единственный источник истины, ты потеряешь его при сбое.

4. Алгоритм отправителя (агент A)

1. Закончить свою работу
2. Запушить артефакты в репо (план / схемы / решения)
3. Сгенерировать handoff payload по схеме
4. Прогнать self-check (см. §6)
5. Передать payload в B вместе со ссылками на артефакты
6. Не уходить пока B не подтвердил «принял»

5. Алгоритм приёмника (агент B)

1. Прочитать только payload (не всю историю A)
2. Если payload не соответствует схеме → отбить с указанием полей
3. Если поняли цель — подтвердить: «принял, начинаю с X»
4. Если есть open_questions с impact: high — задать уточняющий вопрос до старта, не на середине
5. По завершении — вернуть по return_schema

6. Self-check отправителя (без него не отправлять)

• Goal — одно предложение, без «и»
• Summary помещается в 7 строк
• Каждое decision имеет reason
• Все open_items имеют impact и suggestion (или явно «нет идей»)
• Все ссылки на artifacts проверены (sha256)
• Constraints — не пустые (если их нет — пиши «нет»)
• Success criteria — измеримые
• Размер payload ≤ 2k токенов (иначе сжимай или дроби задачу)

7. Типичные ошибки потери контекста

8. Когда нужен round-trip handoff

B может вернуть промежуточный handoff к A, если:

• Найдено новое существенное ограничение, неучтённое в decisions
• Open_question оказался блокирующим
• Готов partial result, нужна валидация перед продолжением

Формат — тот же, но to: agent_a и блок why_back с конкретикой. Не путай round-trip с loop: round-trip — целевое прерывание; loop — когда они пинают друг друга бесконечно. Считай round-trips в метриках, ≥ 3 на handoff — сигнал плохой декомпозиции.

9. Метрики качества handoff

• payload_size_tokens (target ≤ 2k)
• rejection_rate (B отверг payload по схеме — должно быть < 5%)
• clarification_questions_before_start (≤ 1 норма, ≥ 2 — payload неполный)
• round_trip_count (см. выше)
• rework_rate — % случаев когда B переделал то что A зафиксировал (≥ 10% = decisions не уважаются)

10. Анти-паттерны

• ❌ Передавать «весь чат A» вместо payload — токены и шум
• ❌ Свободный текст вместо схемы — B не сможет валидировать
• ❌ Decisions без reason — B пересмотрит при первой возможности
• ❌ Goal с «и»: «реализуй фичу И почини баг» — две задачи, два handoff
• ❌ Артефакты «в чате», не в репо — потеряешь при перезапуске
• ❌ Implicit context («ну ты же знаешь как мы делаем») — B не знает
• ❌ Нет success_criteria — нет способа понять что готово
• ❌ A не дожидается подтверждения B — payload может уйти в пустоту
• ❌ B читает историю A в обход payload — рушит дисциплину
• ❌ Один payload на двух разных B одновременно — race на open_items
• ❌ Payload без handoff_id — нельзя проследить инцидент
• ❌ B молча игнорирует decisions A — нарушение контракта

На выходе

• Схема payload (YAML / JSON) с примером
• Self-check список отправителя
• Алгоритмы A и B (по 5-7 шагов)
• 5 метрик handoff с порогами
• Документ «как мы делаем handoff» (один на проект)