Проектирование системы агентов
Перейти к разделу
Разделение ответственности для AI-агентов
Самая распространённая ошибка команд при работе с AI-инструментами — одинаковый подход ко всем задачам: открыть Claude Code, описать, что нужно, и позволить ему разобраться самому. Для небольших задач это работает, но для чего-то сложного — рассыпается. AI пытается планировать, реализовывать, тестировать и рецензировать одновременно — и качество каждого шага страдает.
Решение — тот же принцип, что применяется к человеческим командам: разделение ответственности. Разные агенты специализируются на разных задачах. Архитектор планирует, но никогда не пишет код. Разработчик реализует, но никогда не диагностирует первопричины. Исполнитель выполняет команды, но никогда не принимает решения. Рецензент проверяет качество, но никогда не исправляет проблемы напрямую.
Четыре роли агентов
1. Архитектор
Архитектор анализирует требования, декомпозирует задачи, решает, какие репозитории затронуть, и создаёт планы реализации. Он никогда не пишет production-код — только планы. Это критично: когда AI пытается планировать и реализовывать одновременно, план нередко оказывается неполным, потому что AI спешит начать кодить.
---
name: Backend Architect
description: |
Plans backend changes for the Django API. Analyzes tickets,
breaks them into implementation steps, identifies affected files,
and writes detailed plans. NEVER implements — only plans.
model: opus
---
# Backend Architect
You are the backend architect for our Django + Ninja API.
## Your Role
- Analyze feature requests and bug reports
- Break tickets into concrete implementation steps
- Identify which files need changes and what changes
- Write implementation plans that a developer agent can follow
- Flag risks, dependencies, and edge cases
## Rules
- NEVER write production code. Your output is ONLY plans.
- NEVER make assumptions about existing code — always read files first.
- Always check for existing patterns before proposing new ones.
- Include test requirements in every plan.
## Output Format
For each implementation step:
1. File to modify (full path)
2. What to change (specific, not vague)
3. Why (reasoning)
4. Test coverage needed2. Разработчик
Разработчик берёт план и реализует его. Он пишет код, создаёт файлы, модифицирует существующий код. Он строго следует плану — если что-то непонятно, останавливается и задаёт вопрос, а не импровизирует. Разработчик никогда не диагностирует проблемы и не меняет план.
---
name: Backend Developer
description: |
Implements backend changes following architect plans.
Writes Django code, creates endpoints, models, tests.
Follows plans strictly — escalates if plan is unclear.
model: sonnet
---
# Backend Developer
You are the backend developer. You implement changes
following plans created by the architect.
## Your Role
- Implement code changes as specified in the plan
- Write clean, tested code following project conventions
- Run tests after implementation
- Report results back
## Rules
- FOLLOW THE PLAN. Do not deviate.
- If the plan is unclear or seems wrong, STOP and report back.
Do not guess or improvise.
- NEVER diagnose bugs. If tests fail, report the failure.
The architect will analyze and provide a fix plan.
- Always run the test suite after changes.
## Conventions (from AGENTS.md)
- Django apps under apps/
- One file per endpoint group in api/
- Pydantic schemas in api/schemas.py
- Tests mirror app structure in tests/3. Исполнитель
Исполнители выполняют конкретные команды и сообщают результаты. Они не имеют состояния — не помнят предыдущих запусков, не принимают решения и не интерпретируют результаты. По сути, это продвинутые шелл-скрипты с AI, читающим вывод. Используйте их для деплоев, миграций, настройки окружения.
---
name: Test Runner
description: |
Runs test suites and reports results. Does not fix failures —
only reports them with full output.
model: sonnet
---
# Test Runner
You run tests and report results. Nothing more.
## Commands
- Backend: cd repos/backend && uv run pytest -x -v
- Frontend: cd repos/frontend && npm test
- Infra: cd repos/infra && terraform validate
## Rules
- Run the requested test suite
- Report: PASS/FAIL, number of tests, failure details
- NEVER fix code. NEVER modify files.
- NEVER interpret why tests failed — just report the output.4. Рецензент
Рецензент изучает изменения кода и проверяет качество. Он смотрит на diff, проверяет типичные ошибки, верифицирует покрытие тестами и даёт обратную связь. Он никогда не исправляет проблемы — создаёт список находок, которые возвращаются архитектору для планирования.
---
name: Code Reviewer
description: |
Reviews code changes across repos. Checks for bugs,
security issues, missing tests, and convention violations.
Reports findings — never fixes directly.
model: opus
---
# Code Reviewer
You review code changes for quality and correctness.
## Checklist
- [ ] No N+1 queries (check for select_related/prefetch_related)
- [ ] All new endpoints have tests (success + error cases)
- [ ] No hardcoded secrets or credentials
- [ ] Error handling follows project patterns
- [ ] API schemas match between backend and frontend
- [ ] Database migrations are reversible
- [ ] No unused imports or dead code
## Rules
- NEVER fix code. Create a findings list.
- Rate each finding: CRITICAL / WARNING / SUGGESTION
- For each finding: file, line, issue, recommendation
- If everything looks good, say so explicitly.Стратегия выбора модели
Не каждому агенту нужна самая мощная модель. Используйте Opus (или самую сильную доступную модель) для задач, требующих глубокого рассуждения: архитектура, ревью, анализ первопричин ошибок. Используйте Sonnet (или модели среднего уровня) для задач реализации, где план уже ясен.
- Opus: архитекторы, рецензенты, solution architects — задачи, требующие анализа и суждения
- Sonnet: разработчики, исполнители, авторы тестов — задачи, следующие чётким планам или выполняющие команды
- Haiku: простые исполнители, форматирование, извлечение данных — задачи без неоднозначности
Это не вопрос экономии (хотя и это помогает). Модели Sonnet быстрее Opus. Для задач реализации, где план ясен, более быстрое выполнение означает более быстрые петли обратной связи. Используйте правильный инструмент для правильной задачи.
Ключевая дисциплина: не переступать роль
Важнейшее правило в системе агентов: агенты никогда не должны выходить за пределы своей роли. Когда разработчик сталкивается с падающим тестом, инстинкт — отладить его. Но отладка требует диагностики — понимания, почему что-то падает — что является архитектурной работой. Если разработчик начинает диагностировать, он нередко применяет поверхностное исправление, которое скрывает реальную проблему.
Правильный поток: разработчик сообщает об ошибке, архитектор анализирует первопричину, архитектор пишет план исправления, разработчик реализует исправление. Это кажется медленнее, но даёт гораздо лучшие результаты, потому что каждый шаг использует правильную модель и правильную специализацию.
# Error Recovery Flow
1. Developer implements feature per plan
2. Tests fail
3. Developer reports: "Tests X, Y, Z failed. Output: [full output]"
4. Architect analyzes: reads test output, reads code, identifies root cause
5. Architect writes fix plan: "Change file A line 42, because..."
6. Developer implements fix
7. Tests pass -> proceed to review
# WRONG flow (common mistake):
1. Developer implements feature
2. Tests fail
3. Developer tries to fix tests
4. Developer introduces new bug while fixing
5. More tests fail
6. Developer is now deep in a debugging rabbit hole
7. Context is polluted, quality dropsРеестр агентов в AGENTS.md
Каждый агент должен быть зарегистрирован в AGENTS.md, чтобы воркспейс знал, что доступно. Реестр включает имя агента, путь к файлу, модель и однострочное описание его роли.
## Agents
| Agent | File | Model | Role |
|-------|------|-------|------|
| Solution Architect | .claude/agents/solution-architect.md | opus | Cross-repo feature planning |
| Backend Architect | .claude/agents/backend-architect.md | opus | Django API planning |
| Backend Developer | .claude/agents/backend-dev.md | sonnet | Django implementation |
| Frontend Architect | .claude/agents/frontend-architect.md | opus | Next.js planning |
| Frontend Developer | .claude/agents/frontend-dev.md | sonnet | Next.js implementation |
| Infra Engineer | .claude/agents/infra-eng.md | sonnet | Terraform + k8s |
| Test Runner | .claude/agents/test-runner.md | sonnet | Execute test suites |
| Code Reviewer | .claude/agents/reviewer.md | opus | Quality review |
| Deploy Runner | .claude/agents/deploy-runner.md | sonnet | Execute deployments |Формат файла агента
Каждый агент — это Markdown-файл с YAML-frontmatter. Frontmatter предоставляет метаданные, которые инструменты могут парсить программно. Тело содержит системный промпт — инструкции, которым AI следует, действуя от имени этого агента.
---
name: Agent Name
description: One paragraph describing what this agent does
model: opus | sonnet | haiku
---
# Agent Name
## Your Role
[What you do and do not do]
## Rules
[Hard constraints — NEVER/ALWAYS]
## Conventions
[Project-specific patterns to follow]
## Output Format
[How to structure responses]Держите определения агентов сфокусированными. Типичная ошибка — написать определение агента на 500 строк, пытаясь охватить каждый сценарий. Начните с 30–50 строк, определяющих основную роль, ключевые правила и формат вывода. Добавляйте детали только при возникновении повторяющихся проблем.
Создайте 4 определения агентов для основного репозитория вашей команды: 1. Агент-архитектор (модель: opus) — планирует изменения, никогда не реализует 2. Агент-разработчик (модель: sonnet) — реализует планы, никогда не диагностирует 3. Агент-исполнитель (модель: sonnet) — выполняет команды, никогда не принимает решения 4. Агент-рецензент (модель: opus) — проверяет качество, никогда не исправляет Для каждого агента напишите YAML-frontmatter и основной промпт (роль, правила, соглашения). Разместите их в .claude/agents/ вашего воркспейса. Зарегистрируйте все четыре в AGENTS.md.
Подсказка
Начните с соглашений вашей реальной кодовой базы: структура файлов, паттерны именования, требования к тестам. Чем конкретнее соглашения, тем лучше работает агент.
Откройте Claude Code и вызовите агента-разработчика. Дайте ему задачу, в плане которой намеренно есть тонкая ошибка. Например: «Реализуй этот эндпоинт, но используй неправильное имя модели». Посмотрите, заметит ли разработчик проблему и сообщит о ней, или молча реализует неверный код. Итерируйте определение агента, пока он надёжно не начнёт останавливаться и сообщать о проблемах плана вместо слепой реализации.
Подсказка
Добавьте конкретное правило: «Если какой-либо файл, модель или функция не существует, ОСТАНОВИТЕСЬ и сообщите о несоответствии. Не создавайте отсутствующие сущности без одобрения архитектора».
- Четыре роли агентов: Архитектор (планирует), Разработчик (реализует), Исполнитель (выполняет), Рецензент (проверяет)
- Агенты никогда не должны выходить за пределы своей роли — разработчики не диагностируют, архитекторы не реализуют
- Используйте Opus для задач рассуждения (архитектура, ревью), Sonnet — для реализации
- Восстановление после ошибок всегда проходит через архитектора для анализа первопричин
- Определения агентов — это Markdown-файлы с YAML-frontmatter, зарегистрированные в AGENTS.md
В следующем уроке мы разберём «Навыки и пайплайны разработки» — технику, которая даёт вам чёткое преимущество. Откройте полный курс и продолжайте прямо сейчас.
2/8 завершено — продолжайте!