Agent pipeline: артефакти між етапами

1. Pipeline починається з артефактів, а не з агентів

Коли ви вперше чуєте фразу agent pipeline, дуже легко уявити собі ланцюжок розумних істот: одна досліджує, друга планує, третя пише код, четверта тестує. Майже стартап-презентація на кофеїні. Ось тільки цінність pipeline не в тому, хто працює на етапі, а в тому, що залишається після етапу.

Уявіть естафету. Якщо бігуни кричать одне одному з доріжки «я майже добіг, лови ідею» — спорт закінчиться травмпунктом. Естафета працює тому, що є паличка. У pipeline така паличка — артефакт. Він переживає автора, сесію, перезапуск, зміну контексту і ваш стан після другої чашки кави.

Подивіться, у чому різниця на практиці. Researcher написав у чат «проблема десь у розрахунку суми, глянь там у checkout» — planner отримав не вхід, а натяк. Researcher повернув evidence_map.md з точними файлами, спостереженнями й неясностями — planner працює з фактами. Ось межа між розмовою і pipeline.

Нижче — проста схема того, як виглядає pipeline, коли між етапами справді передаються результати, а не враження:

flowchart TD
    T["TASK_SPEC.md"] --> E["evidence_map.md"]
    E --> P["plan.md"]
    P --> D["diff + changed_files.md"]
    D --> T2["test_output.md"]
    T2 --> R["risk_list.md"]
    R --> H["parallel-session-log.md"]

Щоб ці файли не виглядали як розсип однакових markdown-артефактів, корисно тримати перед очима коротку карту ролей:

• Workflow Kit зберігає шаблони, що можна перевикористати, і правила, наприклад AGENT_HANDOFF_CONTRACT.md.
• Поруч із конкретним проєктом або треком живуть контрольні файли: контракт треку, parallel-session-log.md, іноді metrics.md.
• Всередині самого треку етапи повертають свої артефакти: evidence_map.md, plan.md, changed_files.md, test_output.md, risk_list.md.
• Якщо треків кілька, зверху зʼявляється roll-up-зведення — але це верхній шар спостережуваності, а не обовʼязковий файл на кожен крок.

І важлива межа: один трек може включати кілька handoff підряд. Окремий worktree потрібен для незалежного паралельного треку, а не для кожного етапу pipeline.

Зверніть увагу на важливу річ: у цій схемі ніде не сказано, хто робить крок: subagent, окрема сесія, людина, reviewer-agent або ви самі. Pipeline визначає не набір акторів, а домовленість про вхід і вихід кожного етапу.

Ще один приємний бік такого підходу в тому, що він прибирає магію. «У нас pipeline researcher → planner → implementer» — це ще театр. «Після дослідження завжди є evidence_map.md, після планування — plan.md, після реалізації — diff і список змінених файлів, а рішення фіксується в parallel-session-log.md» — це вже інженерія. І з інженерією Claude Code дружить куди краще, ніж із гарними словами.

2. Ознаки хорошого handoff-артефакту

Тепер давайте розберемося, що взагалі вважати хорошим артефактом. Формально і записка «все ок» — теж артефакт. Тільки марний. Хороший handoff достатньо короткий, щоб його читали, і достатньо повний, щоб наступний етап не починав розслідування заново.

Найзручніший спосіб перевірити артефакт — поставити до нього пʼять запитань. Відповідає на них — годиться далі.

Мінімальний handoff-файл виглядає так:

# handoff.md

Етап: дослідження
Вхід: TASK_SPEC.md, лог падіння checkout
Вихід: evidence_map.md
Невизначеності: порядок округлення для multi-currency
Наступний крок: planner готує plan.md

Такий файл маленький, але вже корисний: звідки інформація, що на виході, де автор не впевнений. Саме невизначеності особливо важливі. Не зафіксуєте — вони не зникнуть, а тихо переїдуть у наступний етап і спливуть зламаним тестом або дивним diff.

Корисно також порівняти поганий і хороший handoff. У команді це часто спрацьовує краще, ніж довгі пояснення:

Секрет тут простий: наступний етап отримує не переказ вашої роботи, а її компактний зліпок. Не емоцію, а матеріал.

3. Pipeline на задачі Commerce OS

Щоб усе це не залишалося гарною теорією, візьму знайомий контекст із Commerce OS. У checkout баг: після промокоду й ПДВ підсумкова сума в деяких multi-currency замовленнях округляється неправильно. Задача неприємна — розрахунки люблять мститися вночі й у production.

Тут pipeline особливо корисний: у кожного етапу зрозумілий шмат роботи. Workflow Kit дає шаблони, Commerce OS — реальну задачу, на якій їх перевіряють.

Ось як такий pipeline можна описати на рівні етапів і артефактів:

evidence_map.md

evidence_map.md

plan.md

plan.md

changed_files.md

test_output.md

risk_list.md

parallel-session-log.md

Подивімося на ці файли в міні-форматі.

Дослідницький етап не повинен повертати роман про архітектуру — йому достатньо зафіксувати факти:

# evidence_map.md

Проблемна зона:
- src/checkout/CartTotal.java
- src/promo/PromoEngine.java
- src/tax/TaxRules.java
Невизначеність: порядок знижки й ПДВ у multi-currency

Далі planner уже не блукає проєктом заново, а будує план поверх знайденої карти:

# plan.md

Мета: виправити розрахунок суми без зміни публічного API
Крок 1: додати regression test на rounding
Крок 2: виправити порядок викликів у CartTotal
Поза scope: UI промокодів і payments

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

# changed_files.md

Змінено:
- src/checkout/CartTotal.java
- src/test/checkout/CheckoutVatTest.java
Не змінювалися: payments, orders, promotions UI

Потім tester повертає не настрій, а результат перевірки. Перевірка впала — це теж хороший output, чесний і корисний:

# test_output.md

Команда: ./gradlew test --tests "*Checkout*"
Результат: fail
Зламався тест: CheckoutVatTest.roundsHalfUp
Вивід: потрібно уточнити правило округлення

А reviewer уже дивиться на зміни як на пакет ризиків, а не як на абстрактний код:

# risk_list.md

Високий ризик: multi-currency checkout
Середній ризик: старий promo flow
Потрібна ручна перевірка: замовлення з купоном і ПДВ
Diff читабельний: так

Зверніть увагу, наскільки спокійнішою стає робота, коли кожен етап залишає після себе щось відчутне. Tester не перечитує весь діалог реалізації. Reviewer не вгадує, які тести «точно мали запускати». Людина з рішенням відкриває пакет артефактів і бачить шлях від дослідження до зміни.

Саме в цей момент pipeline перестає бути красивою схемою в голові й стає виробничою лінією. Не завод, але вже й не чат «на авось».

4. Шаблон AGENT_HANDOFF_CONTRACT.md

Коли один і той самий тип задач повторюється кілька разів, команді швидко набридає щоразу заново пояснювати, що поверне tester, що робить reviewer і де зупиниться implementer. У Workflow Kit такі речі краще зафіксувати один раз. Для цього і потрібен AGENT_HANDOFF_CONTRACT.md — не звіт по задачі, а командний контракт на передачу результату.

Важливо розрізняти два рівні. AGENT_HANDOFF_CONTRACT.md живе в Workflow Kit і задає форму handoff. А файли на кшталт evidence_map.md, plan.md, test_output.md і запис рішення в parallel-session-log.md живуть поруч із workstream і містять зміст handoff. Шаблон і екземпляр — не одне й те саме.

Ось мінімальний фрагмент такого командного контракту:

# AGENT_HANDOFF_CONTRACT.md

Роль: tester
Бере: plan.md, changed_files.md
Повертає: test_output.md
Стоп-умова: є команда перевірки та її підсумок
Заборонено: змінювати production-код

Цей шаблон корисний одразу з двох боків. Він робить ролі нудними — а в інженерії це комплімент: tester не «думає як тестувальник», а бере визначений вхід, повертає визначений вихід і зупиняється в визначеній точці. І він захищає від scope creep: корис tester у production-код — це не «ну він же хотів допомогти», а порушення контракту.

Такий самий шаблон можна зробити для planner, reviewer або documenter. І тут є важливий нюанс: етап не обовʼязково має збігатися з окремим агентом. Одна людина зіграє planner і reviewer, один subagent виконає дослідження, свіжа сесія виступить як reviewer з новим контекстом. Handoff-contract корисний незалежно від виконавця, бо задає формат входу й виходу.

Коли команда тримає такі контракти в Workflow Kit, повторювані pipeline збираються значно швидше. Ви не сперечаєтесь щоразу, що вважати хорошим тестовим handoff, — відкриваєте домовленість і перевіряєте, чи виконано її.

5. Артефакти роблять pipeline перевірюваним

Одна з найсильніших сторін artifact-driven pipeline у тому, що його можна зупинити, оглянути і продовжити без колективного гіпнозу. Етап упав — не треба проходити весь шлях заново. Повертаєтесь до останнього хорошого артефакту і йдете далі від нього. Це recoverability — здатність процесу відновлюватися.

Уявіть, що tester повернув провал. Без артефактів починається археологія: що змінювали, який був план, звідки взагалі взялася гіпотеза про rounding? Із plan.md, changed_files.md і test_output.md місце поломки видно майже одразу.

Навіть короткий status-файл уже рятує пів години життя:

етап: tester
вхід: plan.md@v2
команда: ./gradlew test --tests "*Checkout*"
результат: fail
наступний_крок: повернутися до planning
причина: незрозуміле правило округлення

З таким файлом planner отримує не «щось там упало», а структуроване повернення: дослідження можна не повторювати (карта проблемної зони вже є), зламалася конкретна гіпотеза про округлення, наступний крок відомий.

Перевірюваність працює схожим чином. Коли reviewer або людина дивиться на pipeline, їй не потрібно читати 200 повідомлень сесії — вона читає робочий набір результатів. Величезна економія уваги. Для новачка це критично: довгі transcripts виглядають переконливо, але в них важко зрозуміти, де факт, де припущення, а де втома автора.

У цьому сенсі артефакт — не лише handoff, а й фільтр шуму. Він виносить назовні суть етапу і залишає за кадром усе проміжне. Наступний учасник не тоне в контексті й не тягне розумове сміття попереднього кроку.

6. Pipeline без паперового заводу

Після всіх цих розмов у вас може виникнути природна реакція: «Ага, тепер на кожен чх десять markdown-файлів». Ні. Так ви побудуєте не pipeline, а філію бюрократичного пекла з розширенням .md. Хороший pipeline мінімальний — рівно стільки артефактів, щоб етапи були зрозумілі й передавані.

Корисно мислити так: не кожен крок заслуговує файла, але кожен ризиковий перехід відповідальності заслуговує на handoff. Змінюєте один очевидний файл — вистачить короткої нотатки і diff. Multi-file change, кілька ролей, окремі tester і reviewer — без явних артефактів усе розповзеться.

Ось проста орієнтовна таблиця:

Ще один хороший принцип: не дублюйте одне й те саме в трьох місцях. Ризик уже в risk_list.md — не переказуйте його абзацом у секції Decision всередині parallel-session-log.md, покличтеся на ризик-пакет і зафіксуйте рішення. Список файлів уже в changed_files.md — не копіюйте його в test-output. Нехай кожен артефакт відповідає за свій шматок правди.

І нарешті, памʼятайте головне: pipeline потрібен не для того, щоб вразити складністю. Він потрібен, щоб наступний етап чесно сказав: «Розумію, що отримав, можу це перевірити і знаю, що робити далі». Поверніться до образу естафети з початку лекції: поки між етапами передають враження, будь-який збій валить усю дистанцію. Щойно між ними лягає паличка-артефакт — evidence_map.md, plan.md, diff, test_output.md — впалий етап не відкидає вас на початок: берете останній надійний артефакт і біжите далі від нього. Не хто працює на етапі, а що залишається після нього — ось що перетворює ланцюжок агентів на pipeline.