Агентная система Claude Code: от субагентов до Teams
Содержание
- 1. Архитектура агентной системы
- 2. Subagents — встроенные агенты
- 3. Teams — координация агентов
- 4. Custom Agents — свои агенты
- 5. Skills — навыки как команды
- 6. Hooks — автоматизация на событиях
- 7. Agent SDK — программный интерфейс
- 8. Headless Mode — Claude без UI
- 9. Комбинированные паттерны
- 10. Сводная таблица
Главная идея
Claude Code — это не просто чат в терминале. Это оркестратор агентов: субагенты, команды, кастомные агенты, навыки, хуки и SDK. Один терминал может порождать десятки параллельных воркеров, каждый со своими инструментами и контекстом.
1 Архитектура агентной системы
Claude Code прошёл эволюцию от CLI-ассистента до полноценной мультиагентной платформы. Понимание всех уровней системы — ключ к максимальной продуктивности. Давайте разберём каждый компонент.
Полная карта
┌─────────────────────────────────────────────────────────────┐ │ Claude Code (основной) │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │ │ Subagents│ │ Teams │ │ Custom │ │ Headless │ │ │ │ (встр.) │ │ (экспер.)│ │ Agents │ │ Mode (-p) │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │ │ │ │ │ │ │ │ ┌────┴─────────────┴─────────────┴────────────────┴───────┐ │ │ │ Agent Tool │ │ │ │ subagent_type: Explore | Plan | general-purpose │ │ │ │ isolation: worktree | (none) │ │ │ │ run_in_background: true | false │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │ │ │ Skills │ │ Hooks │ │ MCP Servers │ │ │ │ (.claude/│ │ (14 evt) │ │ (stdio / HTTP) │ │ │ │ skills/) │ │ │ │ │ │ │ └──────────┘ └──────────┘ └──────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ Agent SDK (Python / TypeScript) │ │ │ │ Внешние программы, CI/CD, собственные оркестраторы │ │ │ └───────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘
7 уровней агентности
| Уровень | Что это | Сложность | Статус |
|---|---|---|---|
| Subagents | Встроенные агенты (Explore, Plan) | Нулевая | Stable |
| Skills | Markdown-промпты как команды | Низкая | Stable |
| Hooks | Shell-команды на события | Низкая | Stable |
| Custom Agents | Агенты с ограниченными tool sets | Средняя | Stable |
| Headless Mode | Claude без UI (-p флаг) | Средняя | Stable |
| Teams | Координация нескольких агентов | Высокая | Experimental |
| Agent SDK | Python/TS SDK для автоматизации | Высокая | Stable |
2 Subagents — встроенные агенты
Субагенты — это дочерние процессы Claude, которые основной агент порождает через Agent tool.
Каждый работает в своём контексте, не загрязняя основное окно. Результат возвращается как одно сообщение.
┌──────────────────────────────────────┐ │ Основной контекст (Claude) │ │ │ │ "Изучи этот файл" ──┐ │ │ ▼ │ │ ┌──────────────┐ │ │ │ Explore │ │ │ │ subagent │ │ │ │ (read-only) │ │ │ └──────┬───────┘ │ │ │ │ │ Результат: ◀─────┘ │ │ "В файле 3 класса..." │ └──────────────────────────────────────┘
3 типа субагентов
Explore (read-only)
Быстрый поиск по кодовой базе. Не может редактировать файлы.
Инструменты: Glob, Grep, Read, Bash (read-only), WebFetch, WebSearch
Когда: поиск файлов, понимание структуры, чтение документации
Plan (read-only)
Архитектор — анализирует код и создаёт план реализации. Не может писать код.
Инструменты: все, кроме Edit, Write, NotebookEdit, Agent
Когда: нужен пошаговый план, trade-off анализ, обзор архитектуры
general-purpose (полный доступ)
Полноценный агент — может читать, писать, запускать команды, порождать других агентов.
Инструменты: все (включая Agent — может порождать суб-субагентов)
Когда: реализация фич, рефакторинг, сложные задачи с изменениями
Ключевые параметры Agent tool
# Быстрый поиск (foreground)
Agent(subagent_type="Explore", prompt="Найди все API endpoints")
# Изолированная работа в git worktree
Agent(subagent_type="general-purpose",
isolation="worktree",
prompt="Реализуй фичу X")
# Фоновая задача (не блокирует)
Agent(run_in_background=True,
prompt="Создай GitHub issue")
# Возобновление предыдущего агента
Agent(resume="agent-id-xxx")
Паттерн: Fan-out (параллельный запуск)
Пользователь: "Разберись с этим проектом"
┌──── Agent 1 (Explore): структура и стек
│
Main ├──── Agent 2 (Explore): git log, активность
│
└──── Agent 3 (Explore): API и интеграции
Результат: 3 параллельных исследования → синтез
Все 3 агента запускаются одновременно в одном сообщении. Каждый работает независимо. Основной контекст ждёт результаты и синтезирует.
Паттерн: Pipeline (последовательное делегирование)
Пользователь: "Найди и пофикси баг в авторизации"
Agent 1 (Explore) → описание проблемы
│
▼
Agent 2 (Plan) → пошаговый план исправления
│
▼
Agent 3 (general) → реализация фикса
│
▼
Agent 4 (Explore) → проверка результата
Выход одного агента — вход следующего. Каждый специализируется на своей задаче. Основной контекст передаёт результаты и координирует.
Ключевое правило: Правило трёх tool calls
Если подзадача требует более трёх вызовов инструментов — делегируй субагенту. Это сохраняет контекстное окно основного агента и повышает качество: каждый субагент работает с чистым, узкоспециализированным контекстом.
# Плохо: основной контекст делает всё сам
# Read file 1, Read file 2, Grep patterns, Analyze...
# → контекст засоряется деталями реализации
# Хорошо: делегируй агенту
Agent(Explore, "Проанализируй структуру auth модуля")
# → один вызов, результат — краткое summary
Изоляция: worktree vs none
По умолчанию субагент работает в том же рабочем каталоге. С isolation="worktree" — в отдельном git worktree:
Без изоляции
Быстро, но рискованно при параллельной работе — два агента могут редактировать один файл одновременно.
Когда использовать: последовательные задачи, read-only операции
worktree изоляция
Каждый агент в своей копии репо. Нет конфликтов. Merge в конце.
Когда использовать: параллельная разработка фич, рефакторинг
3 Teams — координация агентов
Experimental
Teams — экспериментальная фича. Включение: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Чем Teams отличаются от Subagents
| Критерий | Subagents | Teams |
|---|---|---|
| Коммуникация | Результат → родитель | DM между участниками |
| Жизненный цикл | Задача → результат → конец | Живут, пока team-lead не закроет |
| Общая память | Нет | Shared task list |
| Координация | Через родителя | Прямая (peer-to-peer) |
| Сложность | Простая | Высокая |
Как работает Team
┌──────────────────────────────────────────────┐
│ Team Lead (вы) │
│ │
│ TeamCreate("my-project") │
│ │ │
│ ├── TaskCreate("Implement auth") │
│ ├── TaskCreate("Write tests") │
│ ├── TaskCreate("Update docs") │
│ │ │
│ ├── Agent(name="backend") ──────────┐ │
│ ├── Agent(name="tester") ──────────┤ │
│ └── Agent(name="docs") ──────────┤ │
│ │ │
│ ┌────────────────────────────────────────┤ │
│ │ Shared Task List │ │
│ │ ~/.claude/tasks/my-project/ │ │
│ │ │ │
│ │ #1 Implement auth [backend] ✓ │ │
│ │ #2 Write tests [tester] ... │ │
│ │ #3 Update docs [docs] pending │ │
│ └────────────────────────────────────────┘ │
│ │
│ SendMessage(to="backend", "auth done?") │
│ SendMessage(to="*", "stop all work!") │
└──────────────────────────────────────────────┘
Lifecycle команды
TeamCreate — создаёт team + task list в ~/.claude/teams/
TaskCreate — добавляет задачу в shared list
Agent(name="X", team_name="Y") — порождает участника команды
TaskUpdate(owner="X") — назначает задачу участнику
SendMessage — общение между участниками
SendMessage(type: shutdown_request) — завершение работы участника
TeamDelete — удаление team + tasks
Кейс: рефакторинг проекта 3 агентами
Реальный пример использования Teams для большого рефакторинга:
# Team Lead создаёт команду
TeamCreate("refactor-auth")
# Создаём задачи
TaskCreate("Migrate auth to JWT", id="1")
TaskCreate("Update all API tests", id="2")
TaskCreate("Update documentation", id="3")
# Запускаем агентов
Agent(name="backend", team_name="refactor-auth")
Agent(name="tester", team_name="refactor-auth")
Agent(name="docs-agent", team_name="refactor-auth")
# Агенты сами берут задачи из списка
# и обмениваются сообщениями через SendMessage
Каждый агент получает свой экземпляр системного промпта с ролью в команде. backend реализует, tester пишет тесты когда backend сообщает о готовности, docs-agent обновляет документацию после финализации API.
Важно: Teams — экспериментальная фича
Включение: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. API может меняться. Для большинства задач достаточно Subagents — начните с них.
4 Custom Agents — свои агенты
Custom Agents — это markdown-файлы в .claude/agents/, которые описывают специализированных агентов с ограниченным набором инструментов.
Claude автоматически обнаруживает их и может использовать через subagent_type.
# Файл: .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality and security
tools:
- Read
- Grep
- Glob
- Bash
model: sonnet
---
You are a senior code reviewer. Focus on:
1. Security vulnerabilities (OWASP Top 10)
2. Performance issues
3. Code style consistency
Output findings as structured list with severity.
Зачем ограничивать инструменты?
Безопасность: reviewer не должен менять код. Давайте ему только Read/Grep/Glob.
Фокус: без лишних инструментов агент не отвлекается на ненужные действия.
Стоимость: можно задать model: haiku для простых агентов.
Переиспользование: один файл = агент для всего проекта. Commit в git.
Примеры Custom Agents
security-auditor
Tools: Read, Grep, Glob, Bash
Ищет SQL injection, XSS, secrets
test-runner
Tools: Bash, Read
Запускает тесты, анализирует ошибки
docs-writer
Tools: Read, Write, Glob
Пишет документацию на основе кода
deployer
Tools: Bash, Read, MCP(ssh)
Деплоит на сервер через SSH MCP
Полный пример: reviewer с системным промптом
# .claude/agents/senior-reviewer.md
---
name: senior-reviewer
description: Senior code reviewer for Python/FastAPI
tools:
- Read
- Grep
- Glob
- Bash
model: claude-opus-4-6
permissions:
allow: []
deny: ["Edit", "Write", "Bash(rm|drop|delete)"]
---
You are a senior Python developer reviewing FastAPI code.
Focus on:
1. Security: SQL injection, auth bypass, secret exposure
2. Performance: N+1 queries, missing indexes, slow endpoints
3. Patterns: consistency with existing codebase
Output format:
**Critical**: [blocking issues]
**Important**: [should fix]
**Suggestions**: [nice to have]
Агент Opus с запретом на редактирование файлов. Может только читать и давать рекомендации.
--agent флаг: main session как custom agent
Можно запустить Claude Code так, чтобы вся сессия работала как конкретный кастомный агент:
# Запуск как security-auditor агент
claude --agent security-auditor
# Теперь вся сессия работает с ограниченными инструментами
# и системным промптом аудитора
# Постоянный агент по умолчанию (settings.json):
{ "agent": "senior-reviewer" }
Это мощная возможность: разные проекты могут использовать разные агентные конфигурации. Положите в .claude/settings.json нужного агента — и каждый разработчик в команде автоматически работает в правильном режиме.
5 Skills — навыки как команды
Skills — это markdown-файлы в .claude/skills/, которые становятся slash-командами.
Написали code-review.md — получили /code-review. Hot reload — сохранили файл, команда обновилась.
┌──────────────────────────────────────────────┐ │ .claude/skills/ │ │ │ │ code-review.md → /code-review │ │ tdd.md → /tdd │ │ security-audit.md → /security-audit │ │ deploy.md → /deploy │ │ │ │ Каждый skill: │ │ ┌────────────────────────────────┐ │ │ │ --- │ │ │ │ name: code-review │ │ │ │ description: Multi-agent review│ │ │ │ --- │ │ │ │ │ │ │ │ # Instructions │ │ │ │ Review the code for... │ │ │ │ Output structured findings... │ │ │ └────────────────────────────────┘ │ └──────────────────────────────────────────────┘
Skills vs Custom Agents vs CLAUDE.md
| Критерий | CLAUDE.md | Skills | Custom Agents |
|---|---|---|---|
| Когда активен | Всегда | При вызове /skill | При запуске агента |
| Контекст | Основной | Изолированный | Изолированный |
| Инструменты | Все | Все | Ограниченные |
| Модель | Текущая | Текущая | Настраиваемая |
| Назначение | Правила проекта | Повторяемые процессы | Специализированные роли |
Когда что использовать:
CLAUDE.md — постоянные правила, стек, архитектура. Skills — повторяемые процессы (/review, /deploy, /test). Custom Agents — специализированные роли с ограниченными правами (reviewer, tester).
Реальные примеры skills из продуктивной практики
Вот 13 skills, которые используются в реальных проектах. Это не теория — это рабочий инструментарий соло-разработчика:
/code-review
Запускает тяжёлый агент для проверки качества кода. Security + performance + style. Обязателен перед коммитом.
/tdd
Принудительный TDD: сначала falling tests, потом реализация. Предотвращает написание кода без тестов.
/security-audit
OWASP Top 10, проверка secrets в коде, SQL injection, уязвимые зависимости. Обязателен перед деплоем.
/quality-gate
Финальная проверка перед закрытием задачи: все AC выполнены, тесты проходят, нет scope creep.
/systematic-debugging
Структурированная диагностика: reproduce → isolate → hypothesize → test. Не лечить симптомы.
/api-completeness
Проверка покрытия API: все endpoints, error handling, rate limits, документация. Для интеграций с маркетплейсами.
/findings-to-issues
Конвертирует результаты аудитов в GitHub issues с правильными лейблами автоматически.
/perf-review
Анализ производительности: N+1, медленные запросы, узкие места, профилирование.
Skills хранятся в .claude/skills/ и автоматически доступны в любой сессии проекта. Можно делать глобальные (~/.claude/skills/) и проектные.
Автоматические vs ручные триггеры
| Тип | Когда активируется | Примеры |
|---|---|---|
| Автоматический | При определённом событии без явного вызова | После Edit → /code-review, перед деплоем → /security-audit |
| Ручной | Только при явном /skill-name | /tdd при начале задачи, /quality-gate перед закрытием |
Тяжёлые skills запускаются через Agent (context:fork) — результат в виде краткого summary, без переполнения основного контекста. Лёгкие — inline.
6 Hooks — автоматизация на событиях
Hooks — это shell-команды, которые автоматически выполняются при определённых событиях Claude Code.
Настраиваются в .claude/settings.json (проект) или ~/.claude/settings.json (глобально).
┌──────────────────────────────────────────────┐ │ Жизненный цикл сессии + хуки │ │ │ │ SessionStart ─────────────────┐ │ │ │ │ hook: init │ │ ▼ │ │ │ UserPromptSubmit ─────────────┤ │ │ │ │ hook: validate│ │ ▼ │ │ │ PreToolUse ───────────────────┤ │ │ │ │ hook: guard │ │ ▼ │ │ │ [Tool executes] │ │ │ │ │ │ │ PostToolUse ──────────────────┤ │ │ │ │ hook: log │ │ ▼ │ │ │ Notification ─────────────────┤ │ │ │ │ hook: notify │ │ ▼ │ │ │ Stop ─────────────────────────┘ │ │ hook: cleanup│ └──────────────────────────────────────────────┘
Основные события
| Событие | Когда | Пример использования |
|---|---|---|
| SessionStart | Начало сессии | Загрузить контекст, проверить env |
| PreToolUse | Перед вызовом инструмента | Блокировать опасные команды |
| PostToolUse | После вызова инструмента | Автоформатирование, lint |
| Notification | Ожидание ввода | Уведомление в Telegram/Slack |
| Stop | Завершение сессии | Session log, cleanup |
| UserPromptSubmit | После отправки промпта | Валидация, добавление контекста |
Пример: автоформат после Write
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "prettier --write $TOOL_INPUT_FILE_PATH"
}
],
"PreToolUse": [
{
"matcher": "Bash",
"command": "echo $TOOL_INPUT_COMMAND | grep -qE 'rm -rf|drop table' && exit 1 || exit 0"
}
]
}
}
Hook с exit code 1 блокирует действие и показывает stderr как feedback Claude.
Практические hooks из реальных проектов
SessionStart: загрузка контекста
// При старте сессии — проверяем git статус и env
"SessionStart": [{
"command": "cat HANDOFF.md 2>/dev/null || echo 'No handoff'"
}, {
"command": "git log --oneline -5"
}]
Stop: сохранение session log
// При завершении — сохраняем историю сессии
"Stop": [{
"command": "git add SESSION-LOG.md && git commit -m 'chore: session log'"
}]
Notification: Telegram алёрт
// Когда Claude ждёт ввода — уведомление в Telegram
"Notification": [{
"command": "scripts/notify_telegram.sh '$NOTIFICATION_MESSAGE'"
}]
PreToolUse: защита от опасных команд
// Блокируем потенциально разрушительные команды
"PreToolUse": [{
"matcher": "Bash",
"command": "echo \"$TOOL_INPUT_COMMAND\" | grep -qE 'DROP TABLE|rm -rf /' && exit 1 || exit 0"
}]
Env vars доступные в hooks
| Переменная | Содержит |
|---|---|
| $TOOL_NAME | Имя вызванного инструмента (Edit, Bash, ...) |
| $TOOL_INPUT_FILE_PATH | Путь к файлу (для Edit, Write, Read) |
| $TOOL_INPUT_COMMAND | Shell-команда (для Bash) |
| $NOTIFICATION_MESSAGE | Текст уведомления (для Notification) |
| $CLAUDE_SESSION_ID | ID текущей сессии |
7 Agent SDK — программный интерфейс
Agent SDK (Python и TypeScript) позволяет вызывать Claude Code из собственных программ. Это основа для CI/CD интеграций, Slack-ботов, cron-задач и любой автоматизации.
┌──────────────────────────────────────────────┐ │ Ваш Python/TS код │ │ │ │ sdk = ClaudeAgent(model="sonnet") │ │ result = sdk.run( │ │ prompt="Fix the bug in auth.py", │ │ cwd="/path/to/project", │ │ permissions=["Edit", "Bash"], │ │ ) │ │ │ │ │ │ │ ▼ │ │ ┌──────────────────────┐ │ │ │ Claude Code Process │ │ │ │ (subprocess) │ │ │ │ - Reads files │ │ │ │ - Edits code │ │ │ │ - Runs tests │ │ │ │ - Returns result │ │ │ └──────────────────────┘ │ └──────────────────────────────────────────────┘
Python SDK
# pip install claude-agent-sdk
from claude_agent_sdk import Agent
agent = Agent(
model="claude-sonnet-4-6",
allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"],
)
# Синхронный запуск
result = agent.run(
prompt="Найди и исправь все TODO в проекте",
cwd="/path/to/project",
)
# Стриминг
for event in agent.stream("Рефакторинг auth модуля"):
if event.type == "text":
print(event.content)
elif event.type == "tool_use":
print(f"Tool: {event.tool_name}")
Headless Mode (-p) — альтернатива SDK
# Одна задача без UI
claude -p "Fix the failing test in auth.py" \
--allowedTools Edit,Bash \
--output-format json
# В скрипте с pipe
echo "Explain this error: $(cat error.log)" | claude -p
# CI/CD pipeline
claude -p "Run tests and fix any failures" \
--allowedTools Edit,Bash,Read \
--max-turns 20
SDK vs Headless — когда что
| Критерий | Headless (-p) | Agent SDK |
|---|---|---|
| Сложность | Одна строка bash | Python/TS код |
| Стриминг | stdout | Event API |
| Управление | Fire-and-forget | Полный контроль |
| CI/CD | Идеально | Для сложных пайплайнов |
| Multi-agent | Нет (один процесс) | Да (оркестрация) |
TypeScript SDK
// npm install @anthropic-ai/claude-agent-sdk
import {"{"} ClaudeAgent {"}"} from '@anthropic-ai/claude-agent-sdk';
const agent = new ClaudeAgent({"{"}
model: 'claude-sonnet-4-6',
allowedTools: ['Read', 'Edit', 'Bash', 'Glob'],
{"}"});
// Стриминг с обработкой событий
for await (const event of agent.stream("Fix all TypeScript errors")) {"{"}
if (event.type === 'tool_use') {"{"}
console.log(`Using: ${"{"}event.toolName{"}"} on ${"{"}event.input?.file_path{"}"}`)
{"}"}
{"}"}
Реальный кейс: CI/CD автоматический code review
Полный pipeline с Agent SDK и GitHub Actions:
# review_pr.py — запускается в GitHub Actions
import subprocess, json, sys
from claude_agent_sdk import Agent
diff = subprocess.run(['git', 'diff', 'origin/main...HEAD'],
capture_output=True, text=True).stdout
agent = Agent(model="claude-sonnet-4-6",
allowed_tools=["Read", "Grep", "Glob"])
result = agent.run(f"""
Review this PR diff for:
1. Security issues (OWASP Top 10)
2. Logic bugs
3. Breaking changes
Diff: {"{"}diff{"}"}
Output as JSON: {"{"}has_issues: bool, severity: critical|major|minor, findings: []{"}"}
""")
review = json.loads(result.output)
if review['has_issues'] and review['severity'] == 'critical':
sys.exit(1) # блокируем merge
8 Headless Mode — Claude без UI
Флаг -p (или --prompt) запускает Claude без интерактивного UI.
Принимает задачу, выполняет, возвращает результат в stdout. Идеально для скриптов и CI/CD.
Флаги headless режима
| Флаг | Описание |
|---|---|
| -p "задача" | Основной флаг: запустить без UI |
| --output-format json | Вывод в JSON для парсинга скриптами |
| --output-format stream-json | Потоковый JSON (ndjson), обновления в реальном времени |
| --allowedTools | Список разрешённых инструментов (через запятую) |
| --max-turns N | Максимум итераций агента (default: 10) |
| --continue | Продолжить предыдущую сессию |
| --resume SESSION_ID | Продолжить конкретную сессию по ID |
| --model | Выбор модели (haiku/sonnet/opus) |
5 паттернов использования
1. GitHub Actions — автофикс тестов
# .github/workflows/autofix.yml
- name: Fix failing tests
run: |
claude -p "Run pytest, analyze failures, fix the code" \
--allowedTools Bash,Edit,Read \
--max-turns 30
2. Git hook — pre-commit review
# .git/hooks/pre-commit
DIFF=$(git diff --cached)
echo "$DIFF" | claude -p "Review this diff for bugs" \
--output-format json | jq '.has_issues'
3. Cron — ночной аудит
# crontab
0 3 * * * cd /project && claude -p "Security audit" \
--allowedTools Read,Grep,Glob \
--output-format json > /tmp/audit.json
4. Pipeline — цепочка задач
claude -p "Generate API types from schema.json" | \
claude -p "Write tests for these types" | \
claude -p "Review the generated tests"
5. Slack-бот — ответ на вопросы по коду
# В обработчике Slack event
ANSWER=$(cd /project && claude -p "$USER_QUESTION" \
--allowedTools Read,Grep,Glob)
curl -X POST "$SLACK_WEBHOOK" -d "{\"text\": \"$ANSWER\"}"
9 Комбинированные паттерны для соло-оркестратора
Настоящая мощь агентной системы раскрывается в комбинациях. Вот как соло-разработчик или предприниматель может использовать все компоненты вместе:
Паттерн 1: Баг-фикс pipeline
/systematic-debugging
│
▼ диагноз найден
/tdd → failing test написан
│
▼ тест падает
Agent(general-purpose) → fix кода
│
▼ тест проходит
/code-review → финальная проверка
│
▼ PASS
git commit + push
Каждый шаг — отдельный skill или агент. Основной контекст оркестрирует, не делает работу сам.
Паттерн 2: Feature implementation
Agent(Plan) → архитектурный план
│
▼
/tdd → тесты по AC (failing)
│
▼
Agent(general-purpose, worktree) → реализация
│
├── /code-review ──────┐
├── /security-audit ───┤ параллельно
│ │
▼ ▼
/quality-gate → PASS / FAIL
│
▼
deploy
Паттерн 3: Multi-repo management
Соло-оркестратор (1 человек, N репозиториев)
Terminal 1: claude (frontend repo)
Terminal 2: claude (backend repo)
Terminal 3: claude (infra repo)
│ │ │
└─────┬─────┘ │
▼ │
Remote Control │
с телефона │
│ │
└─────────────────┘
Управление всеми тремя через
мобильное приложение
Каждый терминал — отдельная сессия со своим CLAUDE.md и контекстом. Remote Control позволяет переключаться между ними с телефона.
Паттерн 4: Ночной автопилот
tmux session "nightly"
│
├── claude -p "scan-all + process-pending"
│ (headless, cron at 03:00)
│
├── Hook: PostToolUse
│ → prettier/eslint auto-fix
│
├── Hook: Notification
│ → Telegram bot alert
│
└── Hook: Stop
→ session log to git
Полностью автономный рабочий процесс. Вы задаёте задачу вечером, Hooks автоматизируют вспомогательные операции, результат ждёт вас утром.
Паттерн 5: Content generation pipeline
Контент-пайплайн для YouTube-транскрипций с 5 специализированными агентами:
Agent 1 (Explore): поиск видео по теме
│
▼
Agent 2 (general): скачивание субтитров
│
▼
Agent 3 (general): очистка и сегментация
│ (worktree, изолировано)
├── Agent 4a: генерация embedding
└── Agent 4b: создание workbook
│
▼
Agent 5 (general): публикация на сайт
Агенты 4a и 4b работают параллельно (fan-out). Каждый — в своём контексте. Основной агент оркестрирует и не переполняется деталями каждого шага.
Паттерн 6: Progressive autonomy (постепенная автономия)
Начните с высокого уровня вовлечённости, снижайте по мере роста доверия:
| Уровень | Что одобряете | Что автоматически |
|---|---|---|
| Начальный | Каждое действие | Только read operations |
| Средний | Изменения в основном коде | Тесты, документация, форматирование |
| Продвинутый | Только деплой и критические изменения | Весь код, тесты, PR creation |
| Полная автономия | Только финальный ревью | Весь workflow от задачи до деплоя |
Ключ — начинать с простых задач и наращивать автономию по мере понимания поведения агентов в вашем конкретном проекте.
10 Сводная таблица: всё в одном месте
| Компонент | Файл | Запуск | Контекст | Применение |
|---|---|---|---|---|
| Subagents | Встроенные | Agent tool | Fork | Поиск, планирование, реализация |
| Teams | ~/.claude/teams/ | TeamCreate | Shared tasks | Координация нескольких агентов |
| Custom Agents | .claude/agents/ | subagent_type | Fork + ограничения | Специализированные роли |
| Skills | .claude/skills/ | /skill-name | Inline | Повторяемые процессы |
| Hooks | settings.json | Авто (события) | Shell | Автоформат, guard, уведомления |
| Agent SDK | Ваш код | Python/TS import | Subprocess | CI/CD, боты, оркестрация |
| Headless (-p) | CLI | claude -p "..." | Single-shot | Скрипты, cron, pipes |
Правило трёх вызовов:
Если подзадача требует больше 3 tool calls — делегируй Agent. Основной контекст = оркестратор, не исполнитель. Это экономит контекстное окно и повышает качество работы.
+ С чего начать: пошаговый путь
Рекомендуемый порядок освоения
Неделя 1: Subagents
Начните использовать Explore агентов для исследования кода. Это работает из коробки, не требует конфигурации. Привыкните к паттерну «делегируй агенту, не делай сам».
# Пример первого дня
Agent(subagent_type="Explore", "Изучи структуру этого проекта")
Неделя 2: Skills
Создайте 2-3 skill для повторяющихся задач. Начните с /code-review и /deploy — это принесёт сразу ощутимую пользу. Попробуйте автоматические триггеры.
# Создайте первый skill
mkdir -p .claude/skills
echo "---\nname: quick-review\n---\nReview for critical bugs only." > .claude/skills/quick-review.md
Неделя 3: Hooks
Добавьте SessionStart hook для загрузки контекста и Notification hook для Telegram-уведомлений. Настройте автоформатирование через PostToolUse.
Месяц 2: Headless + Custom Agents
Настройте первый CI/CD pipeline с Headless Mode. Создайте специализированных Custom Agents для вашего проекта (reviewer, tester, deployer).
Месяц 3+: Teams и Agent SDK
Экспериментируйте с Teams для больших задач. Интегрируйте Agent SDK в собственные инструменты, ботов, автоматизации.
Типичные ошибки новичков
Ошибка: Делать всё в основном контексте
Признак: сессия зависает, контекст переполняется, Claude начинает «забывать» ранние детали.
Решение: правило 3 tool calls — всё сложное в Agent.
Ошибка: Дать агенту слишком широкую задачу без CLAUDE.md
Признак: агент делает «не то», меняет архитектуру, создаёт лишние файлы.
Решение: детальный CLAUDE.md + конкретные задачи с явными constraints.
Ошибка: Использовать Teams там где хватает Subagents
Признак: сложная координация, много overhead, агенты застревают.
Решение: для большинства задач Subagents достаточно. Teams — для действительно крупных проектов.
Ошибка: Не изолировать параллельных агентов
Признак: два агента редактируют один файл одновременно, конфликты при merge.
Решение: isolation="worktree" для всех агентов, которые пишут код параллельно.
Ключевые метрики: как понять, что вы используете систему правильно
Хорошо
- Основной контекст не переполняется
- Задачи идут параллельно
- Каждый агент делает одно дело
- Повторяющиеся задачи — через skills
Плохо
- Сессия постоянно компактируется
- Всё последовательно, нет параллелизма
- Один агент делает 10 разных вещей
- Повторяете одни и те же инструкции каждый раз
Принципы эффективной агентной архитектуры
Правила оркестратора
- ✓ Основной контекст = оркестратор, не исполнитель
- ✓ >3 tool calls → делегируй агенту
- ✓ Параллелизм везде, где возможно
- ✓ Skills для повторяющихся задач
- ✓ worktree изоляция при параллельных изменениях
Начать с самого простого
- 1. Explore subagents для исследования
- 2. 2-3 skills для review/deploy
- 3. SessionStart + Notification hooks
- 4. Custom agents для специализации
- 5. Teams и SDK — для масштаба
Итог
Агентная система Claude Code — это семь уровней автоматизации, от простых субагентов до полноценных мультиагентных команд. Каждый уровень решает свою задачу: Explore ищет, Plan проектирует, general-purpose реализует, Skills формализуют процессы, Hooks автоматизируют события, Teams координируют команды, SDK интегрирует с внешним миром.
Для соло-разработчика главная ценность — оркестрация без найма. Один человек с правильно настроенными агентами выдаёт результаты, которые раньше требовали команды из 5-10 специалистов. Ключ — в CLAUDE.md (правила проекта) + Skills (повторяемые процессы) + Subagents (параллельное исполнение).
Начните с субагентов (работают из коробки, нулевая настройка), добавьте 2-3 skill для повторяющихся задач, настройте hooks для автоформатирования и уведомлений. Это уже выведет вас на другой уровень эффективности — без сложной конфигурации и без изучения Teams API.
Teams, Custom Agents и Agent SDK — для тех, кто хочет пойти дальше. Но даже без них, просто с правильным использованием Subagents и Skills, вы получите агентную систему, которая реально ускоряет разработку в 3-5 раз.