Что если организовать работу нескольких AI-агентов в одном проекте — без сторонних фреймворков, без Python-оберток и без единой строчки инфраструктурного кода? Именно это и сделал автор claude-alloy: он собрал полноценную систему мультиагентной оркестрации для Claude Code, используя исключительно конфигурационный каталог .claude/ и файлы CLAUDE.md. Звучит почти как хак — но работает как архитектурное решение.

Что такое claude-alloy и зачем он нужен

claude-alloy — это не библиотека и не SaaS-продукт. Это паттерн организации проекта, при котором несколько специализированных агентов Claude Code взаимодействуют друг с другом через общую систему инструкций, разделённых по ролям.

Проблема, которую он решает, хорошо знакома всем, кто работает с большими кодовыми базами через AI-ассистентов: один агент не справляется эффективно сразу с архитектурой, написанием тестов, ревью кода и документацией. Контекстное окно ограничено, фокус размывается, качество падает.

Стандартный подход — использовать специализированные фреймворки вроде LangGraph, CrewAI или AutoGen. Но у них есть цена: дополнительные зависимости, сложная отладка, необходимость поддерживать инфраструктурный слой.

claude-alloy предлагает другой путь: вся оркестрация живёт в файлах конфигурации, которые Claude Code читает нативно.

ℹ Контекст
Claude Code — это официальный CLI-инструмент от Anthropic для работы с Claude прямо в терминале и IDE. Он поддерживает файлы CLAUDE.md как способ передачи инструкций агенту на уровне проекта или директории.

Архитектура: как устроена система ролей

Ключевая идея claude-alloy — иерархическая структура директорий .claude/ с вложенными файлами CLAUDE.md, каждый из которых описывает конкретного агента.


graph TD
    A[.claude/CLAUDE.md — Оркестратор] --> B[agents/architect/CLAUDE.md]
    A --> C[agents/dev/CLAUDE.md]
    A --> D[agents/reviewer/CLAUDE.md]
    A --> E[agents/docs/CLAUDE.md]
    B --> F[Принимает архитектурные решения]
    C --> G[Пишет и рефакторит код]
    D --> H[Проверяет качество и безопасность]
    E --> I[Генерирует документацию]
    A --> J[commands/]
    J --> K[/orchestrate — запуск цепочки]
    J --> L[/delegate — передача задачи агенту]

На верхнем уровне находится оркестратор — главный CLAUDE.md в корне .claude/. Он знает о существовании всех агентов, умеет делегировать задачи и собирать результаты. Каждый подагент живёт в своей поддиректории и имеет чётко ограниченный скоуп.

Типичная структура проекта выглядит так:

my-project/
├── .claude/
│   ├── CLAUDE.md          # Главный оркестратор
│   ├── commands/
│   │   ├── orchestrate.md # Slash-команда для запуска цепочки
│   │   ├── delegate.md    # Команда делегирования
│   │   └── review.md      # Команда запуска ревью
│   └── agents/
│       ├── architect/
│       │   └── CLAUDE.md  # Системный промпт архитектора
│       ├── dev/
│       │   └── CLAUDE.md  # Системный промпт разработчика
│       └── reviewer/
│           └── CLAUDE.md  # Системный промпт ревьюера
├── CLAUDE.md              # Описание проекта (опционально)
└── src/

Как работают CLAUDE.md-файлы агентов

Каждый файл CLAUDE.md — это по сути системный промпт, написанный на обычном Markdown. Именно в них закодирована вся «умность» системы.

Пример файла для агента-архитектора:

# Agent: Architect

## Role
You are the system architect. Your ONLY job is to make high-level
design decisions. You do NOT write implementation code.

## Responsibilities
- Analyze requirements and propose system design
- Define module boundaries and interfaces
- Choose appropriate patterns (CQRS, Event Sourcing, etc.)
- Output decisions as structured ADRs (Architecture Decision Records)

## Output format
Always respond with:
1. **Decision**: one-sentence summary
2. **Context**: why this decision is needed
3. **Consequences**: trade-offs accepted
4. **Next agent**: which agent should act next (dev/reviewer/docs)

## Constraints
- Never write actual code
- Always reference existing patterns in /docs/architecture/
- Flag any decision that affects public API to the reviewer agent
💡 Почему это работает
Claude Code читает CLAUDE.md как часть системного контекста при каждом вызове. Если запустить агента из нужной поддиректории или явно указать путь к нужному CLAUDE.md, Claude получит ровно те инструкции, которые нужны для конкретной роли.

Оркестратор в главном CLAUDE.md содержит протокол передачи управления:

# Orchestrator Protocol

## Agent Registry
- **architect**: design decisions, ADRs → `.claude/agents/architect/CLAUDE.md`
- **dev**: implementation, refactoring → `.claude/agents/dev/CLAUDE.md`  
- **reviewer**: quality, security, tests → `.claude/agents/reviewer/CLAUDE.md`
- **docs**: documentation generation → `.claude/agents/docs/CLAUDE.md`

## Delegation syntax
When delegating, output:

DELEGATE TO: TASK: CONTEXT: EXPECTED OUTPUT: 


## Chain rules
1. New feature → architect → dev → reviewer → docs
2. Bug fix → dev → reviewer
3. Refactor → architect (if structural) → dev → reviewer

Slash-команды как точки входа в оркестрацию

Мощная часть системы — slash-команды (custom commands в Claude Code). Они хранятся как .md-файлы в .claude/commands/ и позволяют запускать целые сценарии одной командой прямо в чате с Claude.

Команда /orchestrate:

# /orchestrate

## Description
Run the full multi-agent pipeline for a feature or task.

## Usage
/orchestrate <task description>

## Steps
1. Parse the task description
2. Invoke Architect agent to produce design decision
3. Pass ADR to Dev agent for implementation
4. Route output to Reviewer agent for quality check  
5. If approved → invoke Docs agent
6. If rejected → return to Dev with reviewer feedback
7. Summarize all agent outputs in a final report

## Template
When running this command, follow the Orchestrator Protocol
defined in .claude/CLAUDE.md and track state in /tmp/alloy-session.json

Именно slash-команды превращают набор конфигов в настоящий workflow. Пользователь вводит /orchestrate добавить авторизацию через OAuth2 — и цепочка агентов последовательно обрабатывает задачу.

Аспектclaude-alloy (.claude/ конфиги)CrewAI / LangGraph
ЗависимостиНулевыеPython, pip, Docker
ОтладкаЧитаешь MarkdownТрейсинг, логи, дебаггер
ГибкостьСредняяВысокая
Порог входаНизкийВысокий
ВерсионированиеGit (обычные файлы)Git + код
Стоимость поддержкиМинимальнаяЗначительная
МасштабируемостьОграниченаПрактически неограничена
⚠ Ограничения подхода
claude-alloy не поддерживает параллельное выполнение агентов — цепочка всегда последовательная. Для задач, где важна параллельность или сложная логика ветвления с состоянием, стоит рассмотреть полноценные фреймворки.

Практическое применение: от идеи до PR

Разберём реальный сценарий использования claude-alloy на примере добавления новой фичи в существующий проект.

Шаг 1. Запуск оркестратора

# В корне проекта, где лежит .claude/
claude

В чате:

/orchestrate Добавить endpoint POST /api/users/{id}/avatar 
             для загрузки аватара, максимум 5MB, форматы jpg/png/webp

Шаг 2. Работа архитектора

Оркестратор вызывает архитектора. Тот анализирует существующую кодовую базу и выдаёт ADR:

DECISION: Использовать multipart/form-data с валидацией на уровне middleware
CONTEXT: Проект уже использует Express middleware chain, добавление
         нового middleware не нарушит существующие паттерны
CONSEQUENCES: Добавляем зависимость multer или аналог; размер файла
              проверяется до попадания в контроллер
NEXT AGENT: dev

Шаг 3. Разработчик реализует

Dev-агент получает ADR и пишет код с учётом стиля проекта, существующих утилит и тестовых паттернов, которые он видит в кодовой базе.

Шаг 4. Ревьюер проверяет

Reviewer-агент смотрит на реализацию через призму безопасности, качества и тестового покрытия. Если находит проблемы — возвращает Dev-агенту с конкретными замечаниями.

Шаг 5. Документация

Docs-агент генерирует OpenAPI-описание эндпоинта, обновляет README и добавляет примеры в /docs/api/.

Весь этот pipeline происходит в одной сессии Claude Code — без переключения инструментов, без копирования контекста вручную, без внешних зависимостей.

Почему это важнее, чем кажется

claude-alloy — это не просто хитрый трюк с конфигами. Это демонстрация важного принципа: оркестрация агентов не обязана быть сложной.

Большинство реальных задач разработки следуют предсказуемым паттернам: проектирование → реализация → проверка → документирование. Эти паттерны можно закодировать в текстовых файлах. Claude достаточно умён, чтобы следовать сложным инструкциям без внешнего «движка».

Что это означает на практике:

  • Для индивидуальных разработчиков: можно настроить персональную систему агентов под свой стек и стиль прямо в репозитории
  • Для команд: .claude/ коммитится в git, все разработчики работают с одинаковой конфигурацией агентов
  • Для экспериментов: легко добавить нового агента — создал директорию, написал CLAUDE.md, добавил его в реестр оркестратора
📝 Идеи для собственных агентов
Security auditor — проверяет код на OWASP Top 10 перед каждым PR.
Dependency analyst — анализирует новые зависимости на уязвимости и лицензионные конфликты.
Changelog writer — автоматически формирует CHANGELOG.md из диффов и commit messages.
Test strategist — определяет, какие тесты нужны для новой фичи, и генерирует тест-план.

Конечно, у подхода есть потолок: сложные графы зависимостей между агентами, динамическое порождение агентов, параллельные ветки — всё это требует кода. Но для 80% задач, с которыми сталкивается обычный разработчик, claude-alloy-паттерн покрывает потребности с запасом.

Заключение

claude-alloy — элегантное доказательство того, что мультиагентная оркестрация может быть простой. Вместо тяжёлых фреймворков — Markdown-файлы. Вместо Python-кода — чётко написанные инструкции. Вместо внешних сервисов — нативные возможности Claude Code.

Это не значит, что CrewAI или LangGraph стали ненужными — они решают другие задачи и другой масштаб. Но если вы ищете способ организовать работу нескольких AI-агентов в проекте прямо сейчас, без онбординга в новый фреймворк — .claude/-конфиги это честный и рабочий путь.

Попробуйте начать с двух агентов: developer и reviewer. Добавьте slash-команду /review и посмотрите, как изменится качество кода. Дальше — по потребности.