Граф агентов для выполнения задач разработки

Как построить оркестратор, который не теряет контекст, допускает безопасное возобновление и доказывает результат независимо от памяти одной агентной сессии.
Зачем превращать выполнение задачи в граф
Одиночная сессия агента удобна для прототипа, но плохо подходит для длительной разработки. Контекст может быть усечён, агент может завершиться с ошибкой, а итоговое сообщение не всегда показывает, какие проверки действительно выполнялись.
Надёжнее представить задачу как граф выполнения: набор этапов с явными входами, выходами и условиями перехода. Каждый этап оставляет артефакт на диске. Следующий агент читает артефакт, а не полагается на пересказ предыдущей сессии.
Цель такой схемы — не заставить агентов работать строго последовательно. Цель — сделать каждое важное решение наблюдаемым и проверяемым:
- требования зафиксированы отдельно от кода;
- план и изменения имеют собственные доказательства;
- проверки запускаются в отдельном этапе;
- ревьюер не является тем же агентом, который писал результат;
- переход дальше возможен только при выполнении формального условия.
Минимальная архитектура
Для большинства задач достаточно шести узлов. Это не универсальный стандарт, а практический шаблон, который можно адаптировать под репозиторий.
intake
│
▼
spec ──► plan ──► implement ──► verify ──► review
│ │
└────────────── retry / blocked ◄──────┘
1. Intake
Агент приёма нормализует запрос: фиксирует цель, ограничения, критерии готовности и предполагаемые области репозитория. Он не должен сразу менять код.
2. Spec
Агент спецификации превращает исходный запрос в проверяемые требования. Хорошая спецификация отвечает на вопрос: «Как понять, что задача выполнена?» Если ответ нельзя выразить через файл, команду, состояние или наблюдаемое поведение, требование пока слишком расплывчато.
3. Plan
Агент планирования сопоставляет требования с файлами и шагами изменения. План должен содержать границы: что не входит в задачу, какие риски известны и какие проверки обязательны.
4. Implement
Агент реализации работает только после принятого плана. Его результат — не сообщение «готово», а набор изменений и журнал действий.
5. Verify
Агент проверки запускает разрешённые команды и сохраняет их вывод. Он не должен подменять отсутствующую проверку предположением о корректности.
6. Review
Независимый ревьюер читает требования, план, diff и доказательства проверки. Он оценивает не красоту отчёта, а соответствие результата условиям перехода.
Файлы-доказательства как контракт между агентами
Сессии агентов эфемерны. Файлы — устойчивее: их можно прочитать после сбоя, сравнить с предыдущей попыткой и проверить вручную.
Один из возможных layouts рабочего состояния:
.agent/
├── state.json
├── intake.md
├── spec.md
├── plan.md
├── implementation.md
├── verification.md
├── review.md
└── attempts/
├── 001/
└── 002/
Это пример структуры, а не требование конкретного инструмента. Важно другое: каждый файл должен иметь владельца этапа и понятный формат.
Что записывать в доказательство
- Идентификатор задачи и номер попытки.
- Входы: commit, список файлов, версия окружения или ссылка на предыдущий артефакт.
- Действия: какие команды и операции были выполнены.
- Результат: коды возврата, изменённые файлы и важные фрагменты вывода.
- Ограничения: что не проверялось и почему.
- Решение: pass, retry или blocked.
Файл доказательства не обязан содержать полный лог. Для воспроизводимости достаточно сохранить точную команду, код завершения, краткий итог и путь к полному логу, если он существует.
Проверяемые переходы между этапами
Оркестратор не должен переходить к следующему узлу только потому, что предыдущий агент завершил ответ. Переход проверяется по предикату — явному условию, которое можно вычислить из файлов и состояния.
{
"task_id": "example-001",
"stage": "verify",
"attempt": 1,
"artifacts": {
"spec": ".agent/spec.md",
"plan": ".agent/plan.md",
"verification": ".agent/verification.md"
},
"transitions": {
"verify_to_review": {
"requires": [
"verification.exists",
"verification.exit_code == 0",
"verification.scope_complete == true"
]
}
}
}
Формат JSON выше — иллюстративный. В рабочей системе проверка должна быть строгой: отсутствие поля, неоднозначное значение или устаревший commit должны блокировать переход.
Пример правил
intake → spec: заполнены цель, ограничения и критерии готовности.spec → plan: каждое требование имеет способ проверки.plan → implement: указаны файлы или области изменений и риски.implement → verify: diff существует, а журнал реализации указывает изменённые пути.verify → review: обязательные проверки завершились успешно либо явно получили статус «не выполнено» с причиной.review → done: ревьюер подтвердил критерии и не оставил блокирующих замечаний.
Воспроизводимый рабочий процесс
Ниже — безопасный пример последовательности команд для отдельного рабочего каталога. Команды только читают состояние или создают локальную папку; пути нужно заменить на реальные.
# 1. Проверить рабочий каталог
pwd
git status --short
# 2. Создать каталог доказательств в текущем проекте
mkdir -p .agent/attempts/001
# 3. Сохранить список отслеживаемых файлов
git ls-files > .agent/attempts/001/files-before.txt
# 4. После работы агента посмотреть изменения
git diff --stat
git diff --check
# 5. Зафиксировать состояние без публикации
git status --short
Команды git diff --check и git status --short не доказывают корректность бизнес-логики. Они лишь помогают обнаружить часть механических проблем. Набор проверок должен соответствовать проекту и быть объявлен в спецификации.
Возобновление после сбоя
При перезапуске оркестратор читает state.json, сверяет существование артефактов и определяет последний допустимый переход. Он не продолжает «с места в памяти» и не доверяет последнему сообщению агента без проверки файлов.
if state.stage == "implement":
if exists(".agent/implementation.md") and diff_is_present():
next_stage = "verify"
else:
next_stage = "implement"
elif state.stage == "verify":
if verification_is_current():
next_stage = "review"
else:
next_stage = "verify"
Псевдокод показывает принцип, а не готовую библиотеку. Критически важно сравнивать доказательства с актуальным состоянием репозитория: старый успешный лог не должен разрешать переход после новых изменений.
Почему ревьюер должен быть независимым
Агент, который написал код, естественным образом склонен интерпретировать неоднозначности в свою пользу. Независимый ревьюер получает ограниченный, но достаточный набор материалов:
- исходную спецификацию;
- план;
- diff или список изменений;
- отчёт проверки;
- правила приёма.
Ревьюеру не обязательно знать всю историю диалога. Более того, отсутствие доступа к ней повышает качество проверки: решение опирается на опубликованные артефакты, а не на устные обещания.
Формат результата ревью
# Review
status: pass | retry | blocked
## Findings
- severity: blocker | major | minor
- location: path:line
- evidence: какой артефакт подтверждает замечание
- action: что нужно изменить
## Coverage
- requirement-1: pass
- requirement-2: pass
## Decision
Краткое объяснение решения.
Статус retry означает, что этап можно выполнить повторно после исправления. Статус blocked означает отсутствие необходимого входа или разрешения; он не должен маскироваться под успешное выполнение.
Типовые ошибки
«Успех» определяется текстом ответа
Сообщение агента — это полезное резюме, но не доказательство. Исправление: переходы должны читать файлы, diff, коды возврата и версии входов.
Один общий журнал на весь граф
Общий лог быстро превращается в неструктурированную стену текста. Исправление: отдельный артефакт на этап плюс общий индекс состояния.
Ревьюер повторяет работу автора
Если ревьюер получает только фразу «проверено», независимость теряется. Исправление: выдавать ему требования, diff и первичные результаты проверок.
Повторная попытка перезаписывает первую
Так исчезает информация о причине сбоя. Исправление: хранить попытки отдельно и ссылаться на предыдущий артефакт.
Слишком широкие полномочия агента
Агенту реализации не нужны права менять конфигурацию CI или публиковать изменения, если это не часть задачи. Ограничивайте команды, рабочий каталог и доступные секреты.
Устаревшие доказательства
Успешная проверка до последнего изменения не подтверждает текущий код. Исправление: сохранять идентификатор commit или хеш входных файлов и сравнивать его перед переходом.
Ограничения подхода
Граф повышает проверяемость, но не устраняет неопределённость. Он не может доказать корректность требований, если сами требования неверны. Он также не заменяет человеческое решение в областях, где требуется продуктовый, юридический или риск-анализ.
Цена надёжности — дополнительная работа: проектирование форматов артефактов, хранение логов, обработка повторных запусков и поддержка правил перехода. Для маленькой одноразовой правки такая схема может быть избыточной. Практический критерий прост: чем дороже ошибка, длиннее выполнение и выше вероятность прерывания, тем полезнее отдельные этапы и доказательства.
Проверка результата перед завершением
Перед переводом задачи в конечное состояние оркестратор и ревьюер должны независимо проверить:
- все обязательные артефакты существуют;
- артефакты относятся к текущей попытке и текущему состоянию репозитория;
- каждое требование сопоставлено с проверкой;
- команды проверки записаны вместе с результатом;
- не осталось блокирующих замечаний;
- ограничения и пропущенные проверки явно указаны;
- после сбоя можно определить безопасную точку возобновления.
Если хотя бы один пункт не подтверждён, корректный итог — не «готово», а повторная попытка или блокировка с объяснением.
Итог
Граф агентов для выполнения задач разработки становится надёжным не благодаря количеству агентов, а благодаря ясным границам между этапами. У каждого узла есть вход, выход и проверяемое условие перехода. У каждого результата есть файл-доказательство. У финального решения есть независимый ревьюер.
Начните с малого: intake, spec, implement, verify и review. Добавляйте параллельные ветви только тогда, когда их результаты можно объединить формальным правилом. Такая архитектура делает выполнение возобновляемым, снижает зависимость от памяти одной сессии и позволяет восстановить ход работы по артефактам.
Дополнительные практические материалы собраны в разделе гайдов, а определения терминов — в глоссарии.