Agent Dev 101

Модуль 11 · Урок 11.1

Урок 11.1. Когда несколько агентов действительно нужны

На этой странице
  1. Зачем это нужно
  2. Основная идея
  3. Ключевые термины
  4. Базовый single-agent loop
  5. Что multi-agent добавляет
  6. Parallelism vs Coordination Cost
  7. Когда multi-agent обычно не нужен
  8. Когда multi-agent может быть нужен
  9. Prompt Complexity И Tool Overload
  10. Prerequisites for Multi-Agent
  11. Task DAG как основа multi-agent
  12. Схема: от single-agent к multi-agent
  13. Parallel-ready task
  14. Признаки, что задачу нельзя параллелить
  15. Coordination cost
  16. Critical path
  17. Context synchronization
  18. Handoff artifacts
  19. Permissions by maturity
  20. Multi-agent и independent review
  21. Multi-agent и worktrees
  22. Multi-agent и checkpoints
  23. Multi-agent и tests
  24. Когда multi-agent нужен ради разных навыков
  25. Когда multi-agent нужен ради независимости
  26. Decision Framework
  27. Decision Matrix
  28. Cost Model
  29. Пример 1. Password Reset feature
  30. Пример 2. Single-agent лучше
  31. Пример 3. Independent reviewer нужен
  32. Пример 4. Multi-agent преждевременен
  33. Пример 5. Tests expansion across modules
  34. Anti-pattern: multi-agent как компенсация плохого prompt
  35. Anti-pattern: все агенты имеют одинаковые permissions
  36. Anti-pattern: reviewer видит reasoning implementer'а
  37. Anti-pattern: integration как afterthought
  38. Minimal viable multi-agent setup
  39. Decision Checklist
  40. Prompt: решить, нужен ли multi-agent
  41. Prompt: отметить parallel-ready branches
  42. Практика 1. Нужен ли multi-agent?
  43. Практика 2. Password Reset
  44. Практика 3. Permission bug
  45. Практика 4. Unclear architecture task
  46. Практика 5. Составить decision report
  47. Типичные ошибки
  48. Критерии готовности
  49. Краткое резюме
  50. Вопросы для самопроверки
  51. Что дальше

Зачем это нужно

Multi-agent development звучит как естественный следующий шаг:

text
Если один агент ускоряет разработку,
то несколько агентов ускорят ее еще сильнее.

Иногда это правда. Но только иногда.

Несколько агентов не делают систему автоматически умнее, надежнее или быстрее. Они добавляют parallelism, но вместе с ним добавляют:

  • coordination cost;
  • merge conflicts;
  • context synchronization;
  • duplicated work;
  • inconsistent decisions;
  • больше tool calls;
  • больше token consumption;
  • больше точек, где нужно verification evidence;
  • больше handoff artifacts;
  • больше риска, что "почти готовые" части не работают вместе.

Поэтому multi-agent должен появляться не в начале курса, а после safety foundation:

text
Specification
-> Task decomposition
-> Good Agent Task
-> Development loop
-> Tests
-> Git
-> Worktrees
-> Checkpoints
-> Multi-agent

Главная мысль урока:

text
Multi-agent полезен не тогда, когда задача большая.
Multi-agent полезен тогда, когда задача уже разделена на независимые проверяемые ветви.

Основная идея

Начинать нужно с устойчивого single-agent процесса:

text
Human
 ↓
Single Agent
 ↓
Tests
 ↓
Diff Review
 ↓
Commit

Только после этого имеет смысл переходить к нескольким агентам:

text
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:

flowchart TD A[Human gives scoped task] --> B[Single Agent reads context] B --> C[Plan] C --> D[Test or eval] D --> E[Implement] E --> F[Run verification] F --> G[Review diff] G --> H[Commit or PR]

Этот loop должен быть не теорией, а привычкой.

Minimum baseline:

text
[ ] 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:

text
Task -> Agent -> Diff -> Tests -> Review

Multi-agent:

text
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:

text
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 еще не стабилен.

Пример:

text
Task:
Напиши лекцию lesson_11_01_when_multi_agent_is_needed.md.

Это один docs artifact. Multi-agent может дать мало пользы. Один агент с хорошим outline, skill и verification справится лучше.

Другой пример:

text
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 нужен не из-за параллельности, а из-за перегруженности одного агента.

Два частых сигнала:

  1. Prompt complexity - один agent prompt содержит слишком много conditional branches.
  2. Tool overload - у агента много похожих tools, и он регулярно выбирает не тот.

Пример prompt complexity:

text
Если 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:

text
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.

Критерий:

text
Multi-agent оправдан, если разделение ролей уменьшает ambiguity
сильнее, чем увеличивает coordination cost.

Prerequisites for Multi-Agent

Перед multi-agent проверьте foundation.

text
[ ] 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.

Плохо:

text
Запусти 4 агентов на password reset.

Хорошо:

text
Построй 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

flowchart TD A[Specification] --> B[Task DAG] B --> C{Parallel-ready tasks?} C -- no --> D[Single Agent executes safe order] C -- yes --> E[Coordinator assigns branches] E --> F[Backend Agent<br/>worktree A] E --> G[Frontend Agent<br/>worktree B] E --> H[Test Agent<br/>worktree C] F --> I[Branch evidence] G --> I H --> I I --> J[Integration] J --> K[Verifier] K --> L[Independent Reviewer] L --> M[PR / Merge]

Multi-agent появляется только после decision point:

text
Есть ли parallel-ready tasks?

Если нет, выбираем single-agent execution по safe topological order.

Parallel-ready task

Task parallel-ready, если ее можно выполнить без постоянного ожидания другой task.

Checklist:

text
[ ] Task имеет один verifiable outcome
[ ] Dependencies уже выполнены или stable
[ ] Shared contract согласован
[ ] Expected files не пересекаются с другими tasks
[ ] Verification можно запустить отдельно
[ ] Result можно review как отдельный diff
[ ] Integration point известен
[ ] Stop conditions определены

Пример parallel-ready:

text
API contract approved.
Backend agent implements endpoint.
Frontend agent builds form against documented contract.
Test agent prepares E2E scenario.

Пример not parallel-ready:

text
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" для каждой ветви.

В такой ситуации лучше:

text
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 зависят друг от друга последовательно:

text
Spec -> Data model -> Repository -> Service -> API -> UI -> E2E

то десять агентов не ускорят core path. Они могут помочь с review, docs или tests, но не смогут обойти зависимости.

Если graph имеет независимые ветви:

text
             -> Backend endpoint
API contract -> Frontend form
             -> Docs
             -> E2E skeleton

parallelism может помочь.

Вопрос:

text
Что находится на 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:

text
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:

text
Backend is done, UI can use it.

Хороший handoff:

text
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:

text
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:

text
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:

text
One worktree per task branch.
One agent writes in one worktree.

Multi-agent без worktrees часто приводит к mixed diff.

Good:

text
../app-auth-api
  Backend Agent

../app-auth-ui
  Frontend Agent

../app-auth-tests
  Test Agent

Bad:

text
repo/
  Agent A, B, C all editing same working tree

Worktrees не решают coordination автоматически, но дают физическую изоляцию для branches и diffs.

Multi-agent и checkpoints

Checkpoints полезны внутри каждой agent session.

Но checkpoint не является shared artifact.

Плохо:

text
Agent A передал Agent B "checkpoint 7".

Хорошо:

text
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 состоит из двух уровней:

text
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.

Пример:

text
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.

Плохо:

text
Reviewer, посмотри нормально ли.

Лучше:

text
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

Перед запуском нескольких агентов задайте вопросы.

text
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

Простой способ оценить:

text
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 нужен, если:

text
benefit > cost

На маленьких задачах cost почти всегда больше.

На больших независимых graphs benefit может быть значительным.

Пример 1. Password Reset feature

Feature:

text
Implement Password Reset.

Плохой multi-agent prompt:

text
Agents, implement password reset.

Хороший подход:

  1. Specification.
  2. Architecture/design.
  3. Task DAG.
  4. Отметить parallel-ready branches.
  5. Worktree plan.
  6. Run agents.
  7. Integration.
  8. Independent review.

Task DAG:

text
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:

text
Fix typo in final evidence template.

Potential multi-agent plan:

text
Planner decides typo location.
Implementer fixes typo.
Verifier checks spelling.
Reviewer reviews diff.
Coordinator merges.

Это слишком много process для tiny change.

Лучше:

text
Single agent:
- edit one file;
- review diff;
- run docs check if available;
- commit.

Multi-agent должен решать реальную проблему, а не демонстрировать архитектурную сложность.

Пример 3. Independent reviewer нужен

Task:

text
Change permission logic for project settings.

Risk:

  • access control;
  • user data exposure;
  • negative tests required;
  • implementation agent wrote tests and code.

Multi-agent setup:

text
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:

text
Redesign notification architecture.

Current state:

  • no ADR;
  • no event model;
  • no owner boundaries;
  • no acceptance criteria;
  • no tests;
  • unclear product requirements.

Запуск нескольких implementers приведет к конфликтующим designs.

Правильный порядок:

text
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:

text
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:

text
eval name
input prompt
expected output contract
tool trace assertions
failure mode

Если schema не согласована, сначала schema task.

Anti-pattern: multi-agent как компенсация плохого prompt

Плохой подход:

text
Один агент не справился с 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.

Лучше:

text
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'а.

Плохо:

text
Reviewer receives full implementer chat and final answer.

Risk:

  • reviewer inherits assumptions;
  • reviewer follows narrative;
  • reviewer misses mismatch with spec.

Лучше:

text
Reviewer receives:
- spec;
- acceptance criteria;
- diff;
- relevant code;
- test evidence;
- known risks.

Свежий context будет темой урока 11.3.

Anti-pattern: integration как afterthought

Плохо:

text
Agents finish branches.
Someone merges all.
Hope CI passes.

Хорошо:

text
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.

Минимальная схема:

text
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 заполните:

text
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

text
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

text
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:

text
Написать один урок курса в одном Markdown файле.

Заполните:

Question Answer
Есть ли independent branches?
Есть ли need for specialization?
Есть ли high-risk review need?
Coordination cost
Recommendation

Возможный ответ:

text
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:

text
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:

text
Project settings endpoint allows read-only users to update settings.

Risk:

  • access control;
  • security-sensitive;
  • small code change;
  • high review need.

Выберите:

text
[ ] single implementer only
[ ] implementer + independent reviewer/verifier
[ ] full backend/frontend/test multi-agent split

Объясните:

  • почему;
  • какие roles нужны;
  • какие tests/evidence обязательны;
  • почему parallelism может быть не главным.

Практика 4. Unclear architecture task

Scenario:

text
Redesign notification system for multiple channels.
No ADR, no requirements, no event model.

Решите:

  • можно ли запускать implementer agents;
  • какой первый agent task нужен;
  • какие artifacts должны появиться до multi-agent implementation;
  • когда можно будет отметить parallel-ready branches.

Возможный ответ:

text
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 из своего проекта и заполните:

text
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.

Базовый порядок:

text
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 стартует не с фразы "запусти несколько агентов", а с вопроса:

text
Какие ветви task graph действительно parallel-ready?

Если таких ветвей нет, лучше использовать одного агента и безопасный sequential order.

Если ветви есть, каждому агенту нужны clear role, bounded context, permissions, worktree/branch, verification target и handoff artifact.

Вопросы для самопроверки

  1. Почему multi-agent может ухудшить плохой single-agent процесс?
  2. Какие prerequisites должны быть готовы до запуска нескольких агентов?
  3. Чем parallel-ready task отличается от task в другой папке?
  4. Почему integration task должна быть частью DAG?
  5. В каких случаях multi-agent нужен не ради скорости, а ради независимого review?

Что дальше

В следующем уроке мы разберем роли агентов: Planner, Implementer, Reviewer и Verifier. Важно, что разные роли не обязательно означают разные модели. Главное - разные contexts, permissions, responsibilities и handoff artifacts. Именно role separation превращает несколько агентов из хаотичной параллельности в управляемый engineering workflow.

Обновлено 03.10.2026