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 заказах округляется неправильно. Задача неприятная — расчёты любят мстить ночью и в продакшене.

Здесь 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 место поломки видно почти сразу.

Даже короткий статус-файл уже спасает полчаса жизни:

этап: 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.

1

Задача

Claude code, 16 уровень, 1 лекция

Недоступна

Применение subagent-based handoff для research stage

Применение subagent-based handoff для research stage

Открыть

1

Задача

Claude code, 16 уровень, 1 лекция

Недоступна

Починка скрипта для machine-readable handoff

Починка скрипта для machine-readable handoff

Открыть