Оркестраційні патерни та суміжні поняття

1. Патерн оркестрації — це схема, а не три агенти

Після розмов про agent team легко зачепитися саме за оболонку: team lead, кілька subagent-ів, стрілочки, усе блищить. Але жити потім доводиться не з оболонкою, а зі схемою. Патерн оркестрації — це схема розподілу роботи за ролями, артефактами та перевірюваними межами: хто що робить, що віддає на виході, як наступний розуміє, що йому передали робочий результат, а не фантазію.

Хороший патерн живе довше за конкретну версію Claude Code: сьогодні роль виконується через plan mode, завтра — через вбудований subagent, післязавтра — через свіжу сесію. Схема залишається тією самою. Це й робить workflow стійким, а не прив’язаним до кнопки.

Зручно тримати в голові таку карту:

planner / executor / verifier

PLAN.md

researcher / implementer / reviewer

CODEBASE_NOTE.md

architect / coder / tester

ARCHITECTURE_NOTE.md

hypothesis A / hypothesis B / neutral verifier

HYPOTHESES.md

Зверніть увагу на одну тонку, але важливу річ. Security reviewer, performance reviewer, test reviewer, architecture reviewer — це не нові патерни, а різні фокуси ролі reviewer. Одна й та сама людина в різних окулярах, а не новий оркестр.

І ще один корисний орієнтир. Якщо ви не можете назвати перший артефакт патерну — патерну у вас поки що немає. Є надія, що «ну вони там якось домовляться». Надія в інженерії гріє душу, але погано проходить code review.

2. Базова трійка planner / executor / verifier

Це найуніверсальніший і найприземленіший патерн, і хороший він саме тим, що не намагається виглядати розумнішим, ніж є: хтось продумує хід і ризики, хтось робить зміну, хтось незалежно перевіряє результат за diff та перевірками. Якщо вам потрібен один патерн «за замовчуванням» для більшості нетривіальних задач — це зазвичай він.

Уявімо знайомий контекст Commerce OS. Є issue: в черзі повернень запити на refund ідуть у неправильному порядку. Проблема вже більш-менш зрозуміла: місце болю знайдено, область відома — задача не про дослідження всього проєкту, а про акуратну зміну та верифікацію.

Тоді planner робить не код, а план: його задача — зафіксувати мету, межі, ризики та команди перевірки. Наприклад, так:

# PLAN.md
Мета: виправити сортування refund-запитів в inbox.
Файли: support/RefundInboxService.java, support/RefundInboxServiceTest.java
Ризики: не змінювати API контролера і SLA-логіку.
Перевірка: ./gradlew test --tests "*RefundInbox*"

Зверніть увагу: хороший planner не пише «виправити баг красиво». Він окреслює рамки, щоб наступний не вгадував, що чіпати не можна, — і ви не витрачаєте п’ять ітерацій на «ой, Claude ще поліз і сюди».

Далі приходить executor. Його робота — не думати про весь світ, а реалізувати узгоджений крок. У простому випадку це основна сесія Claude, у формальному — subagent із вузькими правами запису. На виході — не «готово», а конкретний diff і список змінених файлів.

Після цього вступає verifier. І ось тут багато хто ламає схему: їм здається, що це просто ще один синонім слова review. Ні. Verifier перетворює «я щось змінив» на «ця зміна або пройшла agreed checks, або ні» — за планом, межами та перевірками, а не тільки за кодом.

Схему зручно бачити як потік артефактів:

flowchart TD
    A["Планувальник
plan mode"] -->|PLAN.md| B["Виконавець
main session / subagent"]
    B -->|diff + changed files| C["Перевіряльник
fresh session / reviewer"]
    C -->|VERIFY.md| D["Рішення людини"]

Якщо хочете, це майже конвеєр. Не завод, звісно, а радше маленька майстерня. Але принцип той самий: наступний крок починається не після натхнення, а після зрозумілого артефакту.

Результат verifier-а теж має бути конкретним:

# VERIFY.md
Статус: REWORK
Причина: сортування виправлено, але падає тест на archived refunds.
Команда: ./gradlew test --tests "*RefundInbox*"
Diff: тільки support/*

Бачите, як різко падає градус магії? І це добре. Замість «мені здається, стало краще» з’являється інженерна мова: статус, причина, команда, область diff. Саме в цей момент картинка стає робочим механізмом.

3. Researcher / implementer / reviewer

Цей патерн часто недооцінюють, бо він виглядає менш героїчно: перша роль тут не «вирішує», а «розбирається». Здається, ніби нічого не відбувається. Насправді найцінніше — ви не лізете лагодити незнайомий код із обличчям людини, яка вже все зрозуміла.

Припустімо, у Commerce OS надійшов сигнал: дивно поводяться high-value refunds. Домен ви знаєте, але не знаєте точно, де змішалися сортування, SLA та ручне підтвердження. У такій задачі planner / executor / verifier запускати на повному ходу зарано — сам план будувався б на надто слабкому розумінні системи. Тут вигідніше спершу виділити researcher. Його вихід — не diff, а коротка карта фактів.

# CODEBASE_NOTE.md
Маршрут: POST /api/orders/{id}/refund
Ключовий сервіс: RefundApplicationService
Чергу inbox будує: RefundInboxQueryService
Ризик: SLA-логіка змішана з пріоритетом черги

Implementer у цій схемі вже працює значно спокійніше: у нього вхідний артефакт із кодовими опорами, а не лише текст issue. Він може взяти основну сесію Claude, plan mode перед редагуванням або вузький subagent. Але поведінка все одно залишається локальною: не пере-досліджувати половину проєкту, якщо researcher уже це зробив — і не змінювати симптоми, не зрозумівши причину.

А ось reviewer тут особливо корисний у вигляді fresh session. Чому не та сама сесія? Тому що implementer уже заражений своїм контекстом: гіпотези, глухі кути, старі версії рішення, логіка «ну я ж тут трішки поправив, це нормально». У fresh reviewer цього багажу немає. І в цьому вся його сила.

Просити reviewer-а можна коротко і строго:

Погляньте лише на diff і CODEBASE_NOTE.md.
Перевірте, чи не вийшли зміни за узгоджену область.
Поверніть findings із прив’язкою до файлів і ризиків.

Такий reviewer не повинен перетворюватися на другого researcher-а — інакше ви просто подвоїте вартість етапу дослідження. Його задача — свіжо перевірити зміну, а не перепрожити весь шлях implementer-а.

Якщо сформулювати різницю між першим і другим патерном зовсім коротко, вийде так. Planner / executor / verifier потрібен, коли задача вже загалом зрозуміла. Researcher / implementer / reviewer — коли зрозумілість ще треба заробити.

4. Architect / coder / tester: про межі відповідальності

Тепер візьмімо інший тип роботи. Не баг і не локальне fix, а структурну задачу: у Commerce OS ви хочете винести експорт замовлень в окремий модуль, щоб контролер перестав бути «швейцарським ножем на стероїдах» і делегував CSV-логіку нормальному сервісу. Тут проблема вже не в одному if, а в тому, де проходить межа відповідальності.

Саме для таких задач добре працює architect / coder / tester. Тут architect не зобов’язаний бути сивочолою людиною з відділу «я забороняю вам комітити». Це роль, яка фіксує: що розділяємо, що залишається недоторканним, який контракт не можна зламати.

Наприклад, його артефакт може виглядати так:

# ARCHITECTURE_NOTE.md
Новий модуль: orders/export
Межа: controller приймає запит, CSV збирає ExportService
Не чіпаємо: payments/, support/, публічний URL /api/orders/export
Перевірка: ручний експорт і наявна команда збирання

Цей фрагмент може видатися скромним, але саме він захищає coder-а від дуже поширеної хвороби: «раз уже я тут, давайте заодно покращу сусідній пакет». Ні, не давайте: у великих структурних задачах scope creep зростає зі швидкістю грибів після дощу.

Coder тут уже працює в жорсткішому коридорі: він не проєктує межі заново, а реалізує зафіксоване рішення. У цьому патерні особливо добре видно, що роль не дорівнює рівню seniority: одні й ті самі ви, з тим самим Claude, в одній задачі architect, в іншій — coder.

Tester у цій схемі теж не зобов’язаний одразу перетворюватися на окремий департамент якості. Його роль проста: перевірити, що нова межа працює так, як очікувалося — експорт доступний, контракт не зламано, а сусідні частини системи не почали плакати в кутку.

Особливо корисний цей патерн там, де задача звучить як «додамо новий модуль», «виділимо adapter», «винесемо service», «розріжемо відповідальність». Якщо ж ви лікуєте баг на шість рядків — кликати architect-а не потрібно: це вже не orchestration, а засідання комітету з перестановки стільця.

5. Одна й та сама роль не зобов’язана бути агентом

Ієрархію понять ми вже розклали в лекції про agent teams: orchestration pattern — це сама схема ролей і артефактів, а конкретну роль виконує main session, fresh session, subagent або людина. Звідси висновок, важливий саме тут: симетрія «одна роль = один агент» майже ніколи не є обов’язковою.

Тут у студентів часто виникає дуже зрозуміле бажання: раз ми говоримо про ролі, давайте кожній одразу дамо окремого агента. Красиво, симетрично, на діаграмі взагалі диво — але симетрія у workflow не завжди дорівнює здоровому глузду. Іноді planner у plan mode корисніший і дешевший за subagent-а, іноді роль узагалі має закрити людина.

Хороше правило звучить так: реалізацію ролі обирають за ризиком і складністю, а не через любов до архітектурної краси.

planner

researcher

executor

reviewer / verifier

tester

Це означає, наприклад, що робити planner окремим агентом просто «для єдності стилю» — погана економічна ідея: ви платите coordination cost заради естетики. А естетика, звісно, прекрасна, але merge conflict нею не зупинити.

Тут же корисно пам’ятати про підхід курсу, стійкий до зміни версій. У вашій версії Claude Code якісь поверхні називаються інакше, частина можливостей agent team недоступна, інтерфейс agent view відрізняється від скриншота сусіда. Це нормально: важлива не кнопка, а логіка — роль → артефакт → перевірка.

Корисне запитання для самоперевірки звучить так: «Якщо прибрати слово agent, чи залишиться роль змістовною?» Так — ви правильно проєктуєте workflow. Ні — ви, найімовірніше, проєктуєте інтерфейс, а не інженерний процес.

6. Verifier тримає всю схему на землі

Найменш оцінена частина сьогоднішньої теми — termination model, тобто умова зупинки ролі. Поки її немає, патерн виглядає серйозно, але працює як нескінченний месенджер: один щось зробив, другий прокоментував, третій щось відчув, а коли завершувати — невідомо. Особливо критично це для verifier.

Саме verifier найчастіше перетворює розпливчасте «ну, здається, готово» на машинно перевірювану умову. Ця ідея вже знайома за long-running tasks: якщо умова завершення перевіряється машиною, Claude рухається до неї кількома кроками поспіль без ручного babysitting. Тут та сама логіка, тільки на рівні ролі.

Порівняйте погані й хороші stop conditions:

Тобто хороший verifier не каже «я подивився» — він каже: ось команда, ось область diff, ось вердикт. Наприклад, так:

verifier_condition:
  tests: ./gradlew test --tests "*RefundInbox*"
  diff_scope: support/RefundInboxService.java, support/RefundInboxServiceTest.java
  api_contract: unchanged
  result: VERIFIED | REWORK

Бачите, чому verifier — центр усієї схеми? Тому що саме навколо нього формалізується finish line: executor змінює код, доки condition не виконано, а щойно виконано — задача переходить у людське рішення. Без описаної condition ви повертаєтесь до ручної диспетчеризації: «ну що, тепер краще?», «а тепер?», «а ще раз подивись». Втомлює людину, Claude і бюджет токенів. І виглядає, чесно кажучи, як ремонт крана методом розмов.

Окремо корисно пам’ятати про situational pattern hypothesis A / hypothesis B / neutral verifier. Він особливо добрий там, де дві гіпотези причини багу сперечаються між собою: один доводить версію A, другий — версію B, а neutral verifier дивиться на відтворювані ознаки та вирішує, яка гіпотеза витримує перевірку. Без neutral verifier це філософський гурток за інтересами.

7. Agent pipeline diagram — патерн як артефакт

Після вердикту щодо самої паралельності потрібен другий артефакт: схема ролей, handoff-ів і точок перевірки. Поки патерн живе у вашій голові або в домовленості «ну ти спершу досліди, потім я поправлю», він крихкий: один зрозумів так, інший інакше, третій вирішив, що reviewer і verifier — різні всесвіти. Тому його фіксують як agent pipeline diagram: він переводить схему з розмов у підтримуваний артефакт Workflow Kit.

Хороший pipeline diagram не зобов’язаний бути шедевром дизайнерської думки. Він відповідає на три запитання: яка роль іде першою, який артефакт віддає і хто на нього спирається далі. Наприклад, у Workflow Kit це може жити так:

# docs/pipelines/refund-inbox.md
Pattern: planner / executor / verifier
Planner: main session / plan mode -> PLAN.md
Executor: subagent refund-fixer -> diff + changed files
Verifier: fresh reviewer -> VERIFY.md
Human: рішення щодо merge

Якщо потрібно, діаграма може бути й візуальною:

flowchart TD
    A["Планувальник"] -->|PLAN.md| B["Виконавець"]
    B -->|diff + tests| C["Перевіряльник"]
    C -->|VERIFY.md| D["Рішення людини"]

Сенс тут не в красі стрілочок, а в тому, що workflow стає командним артефактом, а не особистою звичкою одного розробника. Ба більше, таку діаграму зручно класти поруч із AGENT_HANDOFF_CONTRACT.md, щоб кожен перехід між ролями був підкріплений формальним handoff: вхід, вихід, перевірка.

У цей момент оркестрація перестає бути «набором розумних чатів» і стає частиною інженерної системи. І перевіряється це просто: візьміть будь-який патерн із сьогоднішньої таблиці та подумки викресліть слово «агент». Залишилися роль, артефакт і перевірка — planner віддає PLAN.md, verifier повертає вердикт за diff — отже, схема переживе і зміну версії Claude Code, і переїзд ролі з plan mode у subagent. Стрілочки на діаграмі другорядні. Первинне те, що кожен перехід підкріплений зрозумілим входом, виходом і способом перевірити, що далі передали робочий результат, а не надію.