Зачем это нужно
Multi-agent development звучит как естественный следующий шаг:
Если один агент ускоряет разработку,
то несколько агентов ускорят ее еще сильнее.
Иногда это правда. Но только иногда.
Несколько агентов не делают систему автоматически умнее, надежнее или быстрее. Они добавляют parallelism, но вместе с ним добавляют:
- coordination cost;
- merge conflicts;
- context synchronization;
- duplicated work;
- inconsistent decisions;
- больше tool calls;
- больше token consumption;
- больше точек, где нужно verification evidence;
- больше handoff artifacts;
- больше риска, что "почти готовые" части не работают вместе.
Поэтому multi-agent должен появляться не в начале курса, а после safety foundation:
Specification
-> Task decomposition
-> Good Agent Task
-> Development loop
-> Tests
-> Git
-> Worktrees
-> Checkpoints
-> Multi-agent
Главная мысль урока:
Multi-agent полезен не тогда, когда задача большая.
Multi-agent полезен тогда, когда задача уже разделена на независимые проверяемые ветви.
Основная идея
Начинать нужно с устойчивого single-agent процесса:
Human
↓
Single Agent
↓
Tests
↓
Diff Review
↓
Commit
Только после этого имеет смысл переходить к нескольким агентам:
Coordinator
├─ Backend Agent
├─ Frontend Agent
├─ Test Agent
└─ Reviewer Agent
Почему?
Потому что multi-agent не исправляет плохой процесс. Он масштабирует его.
Если один агент:
- получает неясные задачи;
- пишет без tests;
- делает большой diff;
- не умеет останавливаться;
- меняет unrelated files;
- не сообщает evidence;
то несколько агентов будут делать то же самое параллельно. Быстрее, шумнее и дороже.
Multi-agent полезен, когда уже есть:
- specification;
- task graph;
- independent branches of work;
- clear role boundaries;
- test/eval evidence;
- Git workflow;
- worktrees;
- integration step;
- independent review.
Ключевые термины
| Термин | Значение |
|---|---|
| Multi-agent development | Workflow, где несколько агентных ролей или экземпляров работают над задачей координированно. |
| Single-agent baseline | Стабильный процесс, где один агент проходит task через plan, edit, verify, review. |
| Coordinator | Роль или процесс, который распределяет задачи, следит за dependencies и integration. |
| Parallelism | Возможность выполнять независимые задачи одновременно. |
| Coordination cost | Стоимость синхронизации агентов: handoffs, conflicts, review, integration, context sharing. |
| Task DAG | Directed acyclic graph задач и зависимостей. |
| Parallel-ready task | Task, которую можно выполнять независимо, с понятным contract и verification. |
| Handoff | Передача artifact между агентами: spec, plan, diff, test evidence, findings. |
| Context synchronization | Поддержание общего понимания между агентами без смешивания их внутренних reasoning traces. |
| Integration point | Узел, где результаты нескольких branches собираются и проверяются вместе. |
| Role separation | Разделение агентов по responsibilities, contexts и permissions. |
Базовый single-agent loop
Перед multi-agent должен стабильно работать такой loop:
Этот loop должен быть не теорией, а привычкой.
Minimum baseline:
[ ] Agent получает маленькую task
[ ] Agent читает relevant context
[ ] Agent пишет или обновляет tests/evals, когда practical
[ ] Agent запускает verification
[ ] Agent показывает changed files
[ ] Agent показывает commands/results
[ ] Diff review проходит до commit
[ ] One task не смешивается с unrelated changes
[ ] Git branch/commit/rollback понятны
Если это не работает с одним агентом, multi-agent будет преждевременным.
Что multi-agent добавляет
Multi-agent добавляет не только "больше рук". Он добавляет новый слой системы.
Single-agent:
Task -> Agent -> Diff -> Tests -> Review
Multi-agent:
Task DAG
-> Coordinator
-> Multiple agents
-> Handoffs
-> Parallel diffs
-> Integration
-> Reviewer
-> Verification
Новые вопросы:
- кто делит feature на tasks;
- кто решает dependencies;
- кто владеет shared contract;
- кто выбирает merge order;
- кто видит full picture;
- кто проверяет, что agents не делают одно и то же;
- кто отвечает за integration;
- кто решает conflicts;
- кто имеет write permissions;
- кто может approve;
- где хранится evidence.
Если на эти вопросы нет ответов, multi-agent будет выглядеть мощно, но работать непредсказуемо.
Parallelism vs Coordination Cost
Главный trade-off:
Gain = useful parallel work - coordination overhead
Если task нельзя реально распараллелить, multi-agent только увеличит overhead.
| Factor | Single agent | Multi-agent |
|---|---|---|
| Setup cost | Низкий | Выше: roles, worktrees, handoffs |
| Context consistency | Проще | Нужно синхронизировать artifacts |
| Diff ownership | Один diff | Несколько diffs |
| Merge conflicts | Меньше | Больше |
| Review complexity | Ниже | Нужен review отдельных частей и integration |
| Speed | Последовательная | Может быть выше при independent tasks |
| Token cost | Ниже | Выше |
| Verification | Один loop | Per-agent + integration |
| Failure debugging | Проще | Нужно понять, какая branch/role сломала |
Multi-agent имеет смысл, когда выигрыш от parallelism больше coordination cost.
Когда multi-agent обычно не нужен
Не нужен для:
- маленькой isolated task;
- docs update в одном файле;
- one-line bug fix;
- task без ясной specification;
- feature без task decomposition;
- area без tests;
- dirty repository без Git hygiene;
- refactor shared module;
- migration, которая блокирует все ветви;
- product decision, который еще не принят;
- project, где single-agent loop еще не стабилен.
Пример:
Task:
Напиши лекцию lesson_11_01_when_multi_agent_is_needed.md.
Это один docs artifact. Multi-agent может дать мало пользы. Один агент с хорошим outline, skill и verification справится лучше.
Другой пример:
Task:
Fix typo in API error message.
Multi-agent здесь будет почти комичным overhead: coordinator, implementer, reviewer, verifier потратят больше времени, чем сама правка.
Когда multi-agent может быть нужен
Multi-agent становится полезен, когда есть независимые ветви работы.
Хорошие признаки:
- feature уже разложена в task DAG;
- есть stable architecture/design contract;
- есть несколько independent workstreams;
- tasks не меняют одни и те же файлы;
- у каждой ветви свой verification target;
- можно запускать agents в отдельных worktrees;
- integration step понятен;
- reviewer получает clean diffs;
- CI или evals могут проверить результат;
- human coordination cost оправдан.
Примеры:
| Scenario | Почему multi-agent может помочь |
|---|---|
| Backend + UI + E2E после согласованного API contract | Ветви частично независимы. |
| Large test coverage expansion across modules | Tasks можно разделить по owned areas. |
| Migration planning + docs + compatibility tests | Read-only/planning ветви могут идти параллельно. |
| Agent workflow development | Один агент пишет policy, другой evals, reviewer проверяет independence. |
| Independent review | Reviewer должен быть свежим context, лучше отдельная роль. |
| Alternative solution spike | Несколько approaches можно исследовать в отдельных worktrees. |
Важно: "большая задача" не равна "multi-agent". Сначала большая задача должна стать graph.
Prompt Complexity И Tool Overload
Иногда multi-agent нужен не из-за параллельности, а из-за перегруженности одного агента.
Два частых сигнала:
- Prompt complexity - один agent prompt содержит слишком много conditional branches.
- Tool overload - у агента много похожих tools, и он регулярно выбирает не тот.
Пример prompt complexity:
Если task про billing - делай A.
Если task про auth - делай B.
Если task про security exception - делай C.
Если task про enterprise tenant - делай D.
Если task про migration - делай E.
Но если это legacy customer, сначала делай F...
Такой prompt становится маленькой программой без type checker. Агент начинает путать ветви, пропускать условия и применять правила не к тому домену.
Пример tool overload:
update_customer_record
patch_customer_profile
modify_customer_account
set_customer_status
sync_customer_to_crm
Если tools пересекаются по смыслу, агент может ошибаться даже при небольшом количестве tools. Иногда 6 похожих tools хуже, чем 15 хорошо разделенных.
Что делать до multi-agent:
- улучшить names и descriptions tools;
- сузить input schemas;
- убрать дублирующие tools;
- добавить examples and negative examples;
- разделить skills по workflows;
- добавить tool trace evals.
Когда это не помогает, можно разделить систему на роли:
| Симптом | Возможное разделение |
|---|---|
| Слишком много domain-specific branches | Domain agents: billing, auth, support, platform. |
| Похожие write tools путаются | Один специализированный agent владеет конкретным tool set. |
| Один prompt стал длиннее самой задачи | Несколько smaller role prompts + handoff contract. |
| Review и implementation смешаны | Separate implementer and reviewer. |
Критерий:
Multi-agent оправдан, если разделение ролей уменьшает ambiguity
сильнее, чем увеличивает coordination cost.
Prerequisites for Multi-Agent
Перед multi-agent проверьте foundation.
[ ] Specification exists
[ ] Acceptance criteria are explicit
[ ] Task DAG exists
[ ] Parallel-ready tasks marked
[ ] Integration tasks defined
[ ] Single-agent loop works
[ ] Tests/evals exist or can be added
[ ] Git workflow is clean
[ ] Worktrees or isolated branches are available
[ ] Handoff artifacts are defined
[ ] Reviewer role is independent
[ ] Permissions by role are clear
[ ] Cost/token budget is acceptable
Если нет specification, multi-agent agents будут спорить с пустотой.
Если нет tests, agents будут приносить summaries вместо evidence.
Если нет Git isolation, diffs смешаются.
Если нет integration step, части могут работать отдельно, но не вместе.
Task DAG как основа multi-agent
Multi-agent должен начинаться не с agents, а с graph.
Плохо:
Запусти 4 агентов на password reset.
Хорошо:
Построй task DAG для password reset.
Отметь parallel-ready ветви.
Назначь агента только на независимые tasks.
Task DAG показывает:
- nodes: tasks;
- edges: dependencies;
- integration points;
- critical path;
- parallel-ready branches;
- conflict risks.
Без DAG multi-agent превращается в параллельный one-shot.
Схема: от single-agent к multi-agent
Multi-agent появляется только после decision point:
Есть ли parallel-ready tasks?
Если нет, выбираем single-agent execution по safe topological order.
Parallel-ready task
Task parallel-ready, если ее можно выполнить без постоянного ожидания другой task.
Checklist:
[ ] Task имеет один verifiable outcome
[ ] Dependencies уже выполнены или stable
[ ] Shared contract согласован
[ ] Expected files не пересекаются с другими tasks
[ ] Verification можно запустить отдельно
[ ] Result можно review как отдельный diff
[ ] Integration point известен
[ ] Stop conditions определены
Пример parallel-ready:
API contract approved.
Backend agent implements endpoint.
Frontend agent builds form against documented contract.
Test agent prepares E2E scenario.
Пример not parallel-ready:
API contract still changing.
Frontend agent guesses response shape.
Backend agent changes it again.
E2E agent writes tests for third version.
Это не parallelism. Это sync debt.
Признаки, что задачу нельзя параллелить
Task не готова к multi-agent, если:
- несколько agents должны менять один файл;
- contract еще не утвержден;
- один agent должен постоянно читать недописанный diff другого;
- output format не согласован;
- ownership unclear;
- tests зависят от unstable branch;
- migration меняет shared schema;
- dependency update затрагивает всех;
- feature flags не описаны;
- integration order неизвестен;
- нет reviewer context;
- нет clear "done" для каждой ветви.
В такой ситуации лучше:
1. выполнить missing design/spec task;
2. зафиксировать shared contract;
3. разделить tasks;
4. затем запускать agents.
Coordination cost
Coordination cost состоит из нескольких видов расходов.
| Cost | Пример |
|---|---|
| Planning cost | Нужно построить DAG и boundaries. |
| Context cost | Каждому агенту нужен свой relevant context. |
| Handoff cost | Нужны artifacts между roles. |
| Merge cost | Branches нужно объединить. |
| Conflict cost | Agents могут менять shared files. |
| Verification cost | Нужны per-branch и integration tests. |
| Review cost | Reviewer должен смотреть несколько diffs. |
| Token cost | Каждый агент потребляет context и reasoning budget. |
| Latency cost | Ожидание slowest branch или failed integration. |
Multi-agent оправдан, когда parallel work сокращает critical path больше, чем добавляет coordination.
Critical path
Critical path - самая длинная зависимая цепочка задач.
Если tasks зависят друг от друга последовательно:
Spec -> Data model -> Repository -> Service -> API -> UI -> E2E
то десять агентов не ускорят core path. Они могут помочь с review, docs или tests, но не смогут обойти зависимости.
Если graph имеет независимые ветви:
-> Backend endpoint
API contract -> Frontend form
-> Docs
-> E2E skeleton
parallelism может помочь.
Вопрос:
Что находится на critical path, а что можно делать рядом?
Context synchronization
Каждый агент видит свой context. Это полезно для role separation, но создает risk:
- backend agent обновил API error code;
- frontend agent все еще использует старый error code;
- test agent пишет assertion на третью версию contract;
- reviewer видит только final diff и не понимает, где contract changed.
Решение:
- shared artifacts вместо устных assumptions;
- spec/design as source of truth;
- explicit handoff documents;
- contract tests;
- integration step;
- no hidden decisions inside agent chat.
Хороший shared artifact:
API contract:
POST /reset-password
Request: token, newPassword
Responses:
- 200 RESET_OK
- 400 TOKEN_EXPIRED
- 400 TOKEN_ALREADY_USED
- 400 PASSWORD_POLICY_FAILED
Агенты должны читать contract, а не guesses друг друга.
Handoff artifacts
Handoff - это не "агент сказал агенту". Это передача проверяемого artifact.
Примеры:
| From | To | Artifact |
|---|---|---|
| Planner | Implementer | Task spec, scope, AC, expected files |
| Implementer | Verifier | Diff, test names, commands run |
| Implementer | Reviewer | Spec, diff, final evidence |
| Verifier | Reviewer | Test results, failed checks, residual risks |
| Backend Agent | Frontend Agent | API contract, generated client, examples |
| Test Agent | Integration | E2E scenarios, fixtures, assumptions |
Плохой handoff:
Backend is done, UI can use it.
Хороший handoff:
Backend branch:
feature/auth-reset-api
Contract:
POST /reset-password
Request/response schema in docs/api/auth.md
Verification:
- API integration tests passed
Known risks:
- browser E2E not run
Permissions by maturity
На раннем этапе multi-agent лучше ограничить permissions.
| Role | Early-stage permissions |
|---|---|
| Planner | Read files, write plan, no code edits |
| Implementer | Edit scoped files, run tests, no merge |
| Test Agent | Edit tests/evals, run tests, no production code unless approved |
| Verifier | Run commands, inspect logs, no code edits |
| Reviewer | Read spec/diff/code, write findings, no edits by default |
| Coordinator | Assign tasks, manage handoffs, no silent conflict resolution |
Почему так строго? Потому что multi-agent bugs часто появляются от role mixing:
Reviewer сам чинит код.
Verifier меняет tests.
Implementer меняет spec.
Planner делает implementation.
Следующий урок будет про роли подробно. Сейчас важно понять: multi-agent value появляется не от количества agents, а от separation of responsibilities.
Multi-agent и independent review
Один из самых полезных случаев multi-agent - независимый reviewer.
Даже если implementation делает один agent, review лучше делать свежим context:
Implementer Agent:
reads broad context, makes changes
Reviewer Agent:
receives spec + diff + relevant code + test evidence
does not inherit implementer assumptions
Это не обязательно parallelism. Это quality separation.
Multi-agent может быть нужен не для скорости, а для независимости проверки.
Multi-agent и worktrees
Из модуля 10:
One worktree per task branch.
One agent writes in one worktree.
Multi-agent без worktrees часто приводит к mixed diff.
Good:
../app-auth-api
Backend Agent
../app-auth-ui
Frontend Agent
../app-auth-tests
Test Agent
Bad:
repo/
Agent A, B, C all editing same working tree
Worktrees не решают coordination автоматически, но дают физическую изоляцию для branches и diffs.
Multi-agent и checkpoints
Checkpoints полезны внутри каждой agent session.
Но checkpoint не является shared artifact.
Плохо:
Agent A передал Agent B "checkpoint 7".
Хорошо:
Agent A передал:
- branch name;
- commit or diff;
- test evidence;
- API contract;
- known risks.
Checkpoint помогает agent recover locally. Multi-agent coordination должна идти через Git artifacts, specs, tests и handoffs.
Multi-agent и tests
Каждый agent должен приносить evidence.
Multi-agent verification состоит из двух уровней:
Per-agent verification
Integration verification
Per-agent:
- backend tests for backend branch;
- component tests for UI branch;
- evals for agent workflow branch;
- docs checks for docs branch.
Integration:
- API + UI together;
- E2E flow;
- contract tests;
- migration apply;
- full relevant regression;
- reviewer checks final diff.
Если каждая ветвь green отдельно, feature все равно может быть broken together.
Пример:
Backend returns TOKEN_ALREADY_USED.
Frontend expects INVALID_TOKEN.
Both branches pass local tests.
Integration fails.
Поэтому integration task обязательна.
Когда multi-agent нужен ради разных навыков
Иногда parallelism не главное. Полезна specialization.
Пример:
| Need | Agent role |
|---|---|
| Разбить feature на DAG | Planner |
| Написать backend code | Backend Implementer |
| Написать UI | Frontend Implementer |
| Написать tests/evals | Test Agent |
| Найти bugs in diff | Reviewer |
| Запустить checks и собрать evidence | Verifier |
Но specialization должна иметь output contracts.
Плохо:
Reviewer, посмотри нормально ли.
Лучше:
Reviewer, проверь diff against AUTH-RESET-04.
Find correctness bugs, missing tests, scope creep and security risks.
Do not suggest style changes unless they hide a bug.
Когда multi-agent нужен ради независимости
Независимость важна для review, verification и security checks.
Один и тот же agent context может защищать собственное решение:
- помнить свои assumptions;
- объяснять away failures;
- не замечать scope creep;
- доверять своим tests;
- видеть code through implementation plan.
Fresh reviewer context снижает этот риск.
Multi-agent нужен, если:
- change high-risk;
- security-sensitive;
- payments/auth/data migration;
- user-facing behavior;
- large diff;
- agent touched shared module;
- tests were created by same agent that wrote code;
- final approval должен быть независимым.
Это будет тема урока 11.3, но уже сейчас важно: multi-agent не всегда про parallel speed. Иногда он про independent judgment.
Decision Framework
Перед запуском нескольких агентов задайте вопросы.
1. Есть ли стабильный single-agent workflow?
2. Есть ли specification and acceptance criteria?
3. Есть ли task DAG?
4. Есть ли parallel-ready tasks?
5. Есть ли stable shared contracts?
6. Можно ли изолировать branches/worktrees?
7. Есть ли tests/evals for each branch?
8. Есть ли integration step?
9. Есть ли independent reviewer?
10. Coordination cost ниже ожидаемого выигрыша?
Если ответы в основном "нет", multi-agent преждевременен.
Decision Matrix
| Scenario | Multi-agent? | Почему |
|---|---|---|
| Исправить один small bug с regression test | Usually no | Один agent быстрее, меньше overhead. |
| Написать один Markdown урок | Usually no | Один artifact, один context. |
| Feature с backend, UI и E2E после stable API contract | Yes | Ветви можно разделить. |
| Refactor shared auth module | Usually no | Высокий conflict и integration risk. |
| Reviewer для high-risk diff | Yes | Независимость review полезна. |
| Добавить tests across 5 independent modules | Yes | Work can be partitioned by module. |
| Product behavior unclear | No | Сначала specification. |
| No tests and no Git hygiene | No | Сначала safety foundation. |
| Compare two architecture approaches | Maybe | Worktrees/spikes, then choose one. |
| Migration + API + UI with unstable schema | Not yet | Сначала schema/design contract. |
Cost Model
Простой способ оценить:
Expected benefit:
- saved time on critical path
- independent review quality
- parallel test coverage
- faster exploration
Expected cost:
- planning
- context preparation
- handoff writing
- worktree setup
- merge conflicts
- integration tests
- reviewer time
- token/tool cost
Multi-agent нужен, если:
benefit > cost
На маленьких задачах cost почти всегда больше.
На больших независимых graphs benefit может быть значительным.
Пример 1. Password Reset feature
Feature:
Implement Password Reset.
Плохой multi-agent prompt:
Agents, implement password reset.
Хороший подход:
- Specification.
- Architecture/design.
- Task DAG.
- Отметить parallel-ready branches.
- Worktree plan.
- Run agents.
- Integration.
- Independent review.
Task DAG:
AUTH-010 Reset token model
-> AUTH-012 Request reset endpoint
-> AUTH-013 Reset password endpoint
-> AUTH-020 API integration tests
AUTH-016 Reset password UI form
depends on API contract
AUTH-021 Docs for reset token states
depends on error semantics
AUTH-030 E2E reset flow
depends on API + UI
Parallel candidates after API contract is stable:
| Branch | Agent | Task |
|---|---|---|
feature/auth-reset-api |
Backend Agent | Endpoints and service tests |
feature/auth-reset-ui |
Frontend Agent | Reset form against contract |
docs/auth-reset-contract |
Docs Agent | Contract docs |
test/auth-reset-e2e |
Test Agent | E2E skeleton or final flow after integration |
Not parallel yet:
- data model decision;
- API error semantics;
- migrations;
- integration E2E before API/UI exist.
Пример 2. Single-agent лучше
Task:
Fix typo in final evidence template.
Potential multi-agent plan:
Planner decides typo location.
Implementer fixes typo.
Verifier checks spelling.
Reviewer reviews diff.
Coordinator merges.
Это слишком много process для tiny change.
Лучше:
Single agent:
- edit one file;
- review diff;
- run docs check if available;
- commit.
Multi-agent должен решать реальную проблему, а не демонстрировать архитектурную сложность.
Пример 3. Independent reviewer нужен
Task:
Change permission logic for project settings.
Risk:
- access control;
- user data exposure;
- negative tests required;
- implementation agent wrote tests and code.
Multi-agent setup:
Implementer Agent:
- adds regression tests;
- fixes permission check;
- runs targeted tests.
Verifier Agent:
- reruns permission tests;
- checks denied/allowed roles.
Reviewer Agent:
- fresh context;
- receives spec, diff, test evidence;
- looks for privilege escalation and scope creep.
Здесь multi-agent оправдан даже если работа не сильно параллельная. Главная ценность - независимость проверки.
Пример 4. Multi-agent преждевременен
Task:
Redesign notification architecture.
Current state:
- no ADR;
- no event model;
- no owner boundaries;
- no acceptance criteria;
- no tests;
- unclear product requirements.
Запуск нескольких implementers приведет к конфликтующим designs.
Правильный порядок:
1. Planner/discovery task.
2. ADR.
3. Specification.
4. Task DAG.
5. Identify parallel-ready branches.
6. Only then consider implementer agents.
На этом этапе multi-agent может быть полезен только для research/review, но не для implementation.
Пример 5. Tests expansion across modules
Task:
Increase coverage for output contracts across 5 agent workflows.
Modules independent:
- Plan Mode output;
- Bug Fix Flow output;
- Skill Discovery output;
- RAG citation output;
- Final Evidence output.
Multi-agent может помочь:
| Agent | Scope |
|---|---|
| Agent A | Plan Mode evals |
| Agent B | Bug Fix Flow evals |
| Agent C | Skill Discovery evals |
| Agent D | RAG citation evals |
| Reviewer | Check eval consistency |
Но нужен shared eval schema:
eval name
input prompt
expected output contract
tool trace assertions
failure mode
Если schema не согласована, сначала schema task.
Anti-pattern: multi-agent как компенсация плохого prompt
Плохой подход:
Один агент не справился с vague task.
Давайте запустим пять.
Это обычно ухудшает ситуацию.
Если task vague, нужно не больше agents, а лучше:
- specification;
- constraints;
- examples;
- acceptance criteria;
- tests;
- task decomposition;
- stop conditions.
Multi-agent масштабирует clarity. Он не создает clarity из пустоты.
Anti-pattern: все агенты имеют одинаковые permissions
Если каждый agent может:
- менять любой файл;
- запускать любые tools;
- менять spec;
- менять tests;
- approve merge;
- resolve conflicts;
то role separation фактически отсутствует.
Даже если agents называются "Planner", "Reviewer" и "Verifier", это один большой write-capable swarm.
Лучше:
Planner: read/write plan only
Implementer: scoped edits
Verifier: run checks, no edits by default
Reviewer: read diff, write findings
Coordinator: assign/merge with explicit gates
Anti-pattern: reviewer видит reasoning implementer'а
Reviewer должен проверять результат, а не убеждаться reasoning implementer'а.
Плохо:
Reviewer receives full implementer chat and final answer.
Risk:
- reviewer inherits assumptions;
- reviewer follows narrative;
- reviewer misses mismatch with spec.
Лучше:
Reviewer receives:
- spec;
- acceptance criteria;
- diff;
- relevant code;
- test evidence;
- known risks.
Свежий context будет темой урока 11.3.
Anti-pattern: integration как afterthought
Плохо:
Agents finish branches.
Someone merges all.
Hope CI passes.
Хорошо:
Integration is a task:
- merge order;
- conflict risk;
- contract checks;
- full relevant tests;
- reviewer gate;
- rollback plan.
Integration task должна быть в DAG заранее.
Minimal viable multi-agent setup
Для курса не нужен production multi-agent runtime.
Минимальная схема:
Human Coordinator
-> Planner Agent creates task DAG
-> Implementer Agent works one branch
-> Test/Verifier Agent checks evidence
-> Reviewer Agent reviews diff independently
-> Human decides merge
Даже это уже multi-agent, если roles имеют:
- разные contexts;
- разные responsibilities;
- разные permissions;
- explicit handoff artifacts.
Не обязательно использовать разные модели. Важнее разные роли.
Decision Checklist
Перед запуском multi-agent заполните:
Feature:
Goal:
Single-agent baseline:
[ ] works
[ ] does not work
Specification:
[ ] ready
[ ] missing
Task DAG:
[ ] ready
[ ] missing
Parallel-ready branches:
- ...
Shared contracts:
- ...
Agent roles needed:
- ...
Worktree/branch plan:
- ...
Verification per branch:
- ...
Integration verification:
- ...
Reviewer independence:
[ ] yes
[ ] no
Coordination risks:
- ...
Decision:
[ ] use single-agent
[ ] use multi-agent
[ ] not ready, do planning first
Prompt: решить, нужен ли multi-agent
Evaluate whether this task should use multi-agent development.
Input:
<feature/task description>
Analyze:
- current specification quality;
- task DAG readiness;
- parallel-ready branches;
- shared contracts;
- expected file conflicts;
- verification availability;
- coordination cost;
- token/tool overhead;
- need for independent review.
Output:
- recommendation: single-agent / multi-agent / planning first;
- rationale;
- candidate roles, if multi-agent;
- tasks that must remain sequential;
- integration plan;
- risks and stop conditions.
Prompt: отметить parallel-ready branches
Given this task DAG, mark branches as:
- sequential;
- parallel-ready;
- integration-only;
- not ready.
For each parallel-ready branch, provide:
- reason it can run independently;
- required shared contract;
- expected files;
- verification command;
- conflict risks;
- suggested worktree branch name.
Практика 1. Нужен ли multi-agent?
Scenario:
Написать один урок курса в одном Markdown файле.
Заполните:
| Question | Answer |
|---|---|
| Есть ли independent branches? | |
| Есть ли need for specialization? | |
| Есть ли high-risk review need? | |
| Coordination cost | |
| Recommendation |
Возможный ответ:
Recommendation:
single-agent.
Reason:
One content artifact, one file, no parallel branches.
Review can be separate later, but implementation itself does not need multi-agent.
Практика 2. Password Reset
Scenario:
Implement Password Reset with API, UI, tests and docs.
Specification and API contract are ready.
Заполните:
| Branch | Agent | Parallel-ready? | Dependencies | Verification |
|---|---|---|---|---|
| Backend API | ||||
| UI form | ||||
| E2E tests | ||||
| Docs | ||||
| Integration |
Ответьте:
- какие branches можно запустить параллельно;
- какая task должна быть sequential first;
- кто владеет API contract;
- какой merge order;
- где нужен independent reviewer.
Практика 3. Permission bug
Scenario:
Project settings endpoint allows read-only users to update settings.
Risk:
- access control;
- security-sensitive;
- small code change;
- high review need.
Выберите:
[ ] single implementer only
[ ] implementer + independent reviewer/verifier
[ ] full backend/frontend/test multi-agent split
Объясните:
- почему;
- какие roles нужны;
- какие tests/evidence обязательны;
- почему parallelism может быть не главным.
Практика 4. Unclear architecture task
Scenario:
Redesign notification system for multiple channels.
No ADR, no requirements, no event model.
Решите:
- можно ли запускать implementer agents;
- какой первый agent task нужен;
- какие artifacts должны появиться до multi-agent implementation;
- когда можно будет отметить parallel-ready branches.
Возможный ответ:
Implementation multi-agent is premature.
First task: planner/discovery + ADR + specification.
After event model and channel contracts are approved, split into provider adapters, API, tests and docs.
Практика 5. Составить decision report
Выберите feature из своего проекта и заполните:
Feature:
Why not single-agent:
Prerequisites ready:
- spec:
- task DAG:
- tests:
- Git/worktrees:
- shared contracts:
Parallel-ready tasks:
1.
2.
3.
Sequential tasks:
1.
2.
Roles:
- Planner:
- Implementer:
- Test/Verifier:
- Reviewer:
Integration plan:
Coordination risks:
Recommendation:
Типичные ошибки
| Ошибка | Симптом | Исправление |
|---|---|---|
| Начинать с multi-agent | Много активности, мало evidence | Сначала single-agent baseline. |
| Нет task DAG | Agents работают в разных направлениях | Build DAG and mark dependencies. |
| Параллелить dependent tasks | UI и tests расходятся с backend | Freeze contract first. |
| Все агенты пишут в одну working tree | Mixed diff and lost changes | Use worktrees/branches. |
| Нет integration task | Parts pass separately, feature broken together | Add integration node. |
| Reviewer не независим | Self-review repeats assumptions | Fresh reviewer context. |
| Все roles имеют write permission | Role boundaries meaningless | Limit permissions by role. |
| No handoff artifacts | Agents rely on chat summaries | Pass spec, diff, tests, contracts. |
| Coordination cost ignored | Multi-agent медленнее single-agent | Use decision matrix. |
| Token cost ignored | Budget burns on duplicated context | Scope contexts and artifacts. |
| Multi-agent для tiny task | Process heavier than work | Use single-agent. |
| Multi-agent для unclear spec | Agents produce conflicting solutions | Planning/spec first. |
Критерии готовности
После урока студент должен уметь:
- объяснить, почему multi-agent не является автоматическим улучшением;
- назвать prerequisites for multi-agent;
- отличить parallel-ready task от dependent task;
- оценить parallelism vs coordination cost;
- объяснить role of task DAG;
- назвать новые риски: merge conflicts, context synchronization, token cost;
- решить, когда single-agent лучше;
- решить, когда independent reviewer нужен даже без parallelism;
- составить decision checklist;
- подготовиться к разделению ролей в следующем уроке.
Краткое резюме
Multi-agent development полезен только после стабильного single-agent foundation.
Базовый порядок:
Single-agent loop
-> Tests/evals
-> Git safety
-> Worktrees
-> Task DAG
-> Multi-agent
Multi-agent добавляет parallelism, specialization и independent review. Но он также добавляет coordination cost, conflicts, context synchronization и token overhead.
Хороший multi-agent стартует не с фразы "запусти несколько агентов", а с вопроса:
Какие ветви task graph действительно parallel-ready?
Если таких ветвей нет, лучше использовать одного агента и безопасный sequential order.
Если ветви есть, каждому агенту нужны clear role, bounded context, permissions, worktree/branch, verification target и handoff artifact.
Вопросы для самопроверки
- Почему multi-agent может ухудшить плохой single-agent процесс?
- Какие prerequisites должны быть готовы до запуска нескольких агентов?
- Чем parallel-ready task отличается от task в другой папке?
- Почему integration task должна быть частью DAG?
- В каких случаях multi-agent нужен не ради скорости, а ради независимого review?
Что дальше
В следующем уроке мы разберем роли агентов: Planner, Implementer, Reviewer и Verifier. Важно, что разные роли не обязательно означают разные модели. Главное - разные contexts, permissions, responsibilities и handoff artifacts. Именно role separation превращает несколько агентов из хаотичной параллельности в управляемый engineering workflow.