Открытый фреймворк Agency Agents: полное руководство

Руководство для разработчиков, продуктовых команд и руководителей автоматизации, которые хотят использовать Agency Agents как набор ролевых конфигураций для AI Agent команды. Мы разбираем установку, выбор ролей, последовательную и параллельную работу, требования к доступам и условия перехода к удалённой среде.

Последнее обновление: 13 августа 2026 года. Данные сверены с официальным сайтом Agency Agents, репозиторием на GitHub, инструкциями по установке и документацией поддерживаемых инструментов.

Подходит: если нужно быстро добавить в Claude Code, Cursor или другой кодовый инструмент специализированные роли с собственными правилами работы.

Не подходит: если ожидается готовая корпоративная платформа, которая сама управляет агентами, доступами, очередями, журналами и безопасной изоляцией.

Agency Agents — это набор ролевых конфигураций для AI Agent команды, а не самостоятельная среда исполнения. Роль задаёт специализацию, стиль рассуждения, рабочий процесс, ожидаемые артефакты и критерии проверки. Однако планирование задач, запуск нескольких процессов, разграничение прав, контроль изменений и ручное принятие результата остаются на стороне команды и выбранного инструмента.

Эта статья предназначена для трёх групп:

• индивидуальных разработчиков, которым нужны роли для проектирования, реализации, тестирования или маркетинга;
• продуктовых и инженерных команд, оценивающих многоролевой рабочий процесс;
• руководителей автоматизации, которым предстоит запускать такие задачи в постоянно работающей удалённой среде.

Что именно устанавливает Agency Agents

Главная ошибка при оценке проекта — считать каждую роль отдельной моделью или автономным цифровым сотрудником. На практике файл агента — это текстовая конфигурация, которую читает выбранный кодовый инструмент. В ней обычно описываются:

• идентичность и область ответственности;
• предпочтительный стиль коммуникации;
• последовательность действий;
• форматы результата;
• критерии качества;
• ограничения и типовые ошибки.

Иными словами, роль не получает автоматически отдельную память, собственный сервер, очередь задач или независимый канал доступа к репозиторию. Она влияет на инструкции и контекст текущего сеанса.

Официальный сайт сейчас показывает 146 ролевых персон, а README репозитория использует формулировку «230+ специализированных агентов». Это расхождение само по себе важно: количество карточек нельзя считать стабильной характеристикой платформы. Перед внедрением следует проверить текущий каталог и конкретные файлы в репозитории, а не принимать рекламное число за фиксированную спецификацию. (agencyagents.dev)

В роли обычно есть четыре слоя:

1. Квалификация. Например, архитектор серверной части, инженер безопасности или специалист по тестированию.
2. Метод работы. Агент может сначала задавать уточняющие вопросы, строить карту рисков или требовать доказательства.
3. Формат поставки. Это может быть план, патч, список дефектов, тестовый отчёт или документ решения.
4. Критерий остановки. Хорошая роль должна объяснять, когда задача считается завершённой и что делать при нехватке данных.

Поэтому Agency Agents правильнее воспринимать как библиотеку специализаций. Само наличие ролей не превращает Claude Code или Cursor в полноценный оркестратор.

Поддержка нескольких инструментов достигается через разные форматы интеграции. Для Claude Code используются файлы агентов, для Cursor — правила проекта, для других инструментов репозиторий предоставляет скрипты конвертации и установки. Документация Cursor по правилам проекта подтверждает, что правила хранятся в .cursor/rules и добавляются в контекст модели как постоянные инструкции. (docs.cursor.com)

Как начать одному разработчику без потери контроля

Индивидуальному разработчику не стоит устанавливать весь каталог сразу. Большая коллекция ролей быстро создаёт три проблемы.

Во-первых, становится непонятно, какая инструкция сработала. Во-вторых, роли начинают дублировать друг друга: несколько «экспертов» дают похожие рекомендации разными словами. В-третьих, растёт объём контекста и количество ручных переключений.

Мы рекомендуем начать с трёх ролей:

• планировщик — формирует границы задачи, допущения и план изменений;
• исполнитель — пишет код или создаёт необходимый артефакт;
• проверяющий — ищет дефекты, несоответствия и недоказанные утверждения.

Для небольшого проекта этого достаточно, чтобы проверить сам принцип. Если задача связана с безопасностью, добавляется отдельный проверяющий безопасности. Если речь идёт о продукте или контенте — исследователь и редактор.

Установка для Claude Code в репозитории описана двумя способами. Можно воспользоваться установочным скриптом:

git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents
./scripts/install.sh --tool claude-code

Для точечного варианта лучше скопировать только нужную группу:

cp engineering/backend-architect.md ~/.claude/agents/
cp testing/reality-checker.md ~/.claude/agents/

Названия файлов и каталоги необходимо сверить с актуальной структурой репозитория перед выполнением команды. Официальный README также описывает ручное копирование агентов в ~/.claude/agents/ и запуск через текстовую команду в сессии. (github.com)

Claude Code необходимо установить и авторизовать отдельно. В официальной инструкции указаны поддерживаемые операционные системы, необходимость сетевого доступа и базовый способ установки. Agency Agents не заменяет сам Claude Code и не предоставляет модель или учётную запись. (docs.anthropic.com)

Для Cursor логика другая: роли могут преобразовываться в правила проекта и размещаться в .cursor/rules. Это удобнее для командной работы, потому что правила можно хранить вместе с кодом и просматривать в истории изменений.

Важно: перед установкой проверьте содержимое каждого файла. Роль — это исполняемая инструкция в контексте кодового инструмента, а не сертифицированный модуль безопасности.

Как выбрать роли для продукта, контента и маркетинга

В продуктовой или контентной группе роли должны соединяться не по названиям, а по входам и выходам. Если просто запустить исследователя, автора и редактора без контракта, каждый агент начнёт заново пересказывать исходный запрос.

Рабочая цепочка выглядит так:

1. Исследователь потребностей получает сегмент пользователей, проблему и ограничения.
2. Продуктовый аналитик превращает наблюдения в гипотезы и критерии приоритета.
3. Проектировщик решения описывает структуру, сценарии и спорные места.
4. Создатель контента работает только с утверждённым брифом.
5. Проверяющий сверяет факты, полноту и соответствие исходной цели.

Для каждой передачи следует зафиксировать минимум пять полей:

• источник данных;
• задача следующего агента;
• допустимый формат;
• критерий достаточности;
• список неизвестных вопросов.

Например, исследователь не должен передавать дизайнеру длинный свободный текст. Лучше передать таблицу с проблемой, доказательством, частотой сигнала, риском и рекомендуемым следующим действием.

Для команды разработки принцип тот же. «Архитектор» выдаёт решение и список затронутых компонентов. «Исполнитель» принимает этот документ и изменяет код. «Тестировщик» получает описание ожидаемого поведения и проверяет его. «Ревьюер» оценивает уже конкретный diff, а не повторяет проектирование.

Такой подход отвечает на вопрос, как выбирать роли в Agency Agents: начинать нужно не с привлекательного названия, а с отсутствующего результата в рабочем процессе.

Поддерживает ли Agency Agents Claude Code, Cursor и другие инструменты

Да, проект рассчитан на несколько кодовых инструментов, но уровень интеграции различается. Официальный сайт указывает Claude Code, Cursor, Windsurf, Aider, Qwen Code и GitHub Copilot. README репозитория дополнительно описывает скрипты для генерации файлов под ряд других сред. Список и структура могут меняться, поэтому перед внедрением следует проверять раздел интеграций в репозитории. (agencyagents.dev)

Практическое различие выглядит так:

• в Claude Code ролевой файл подключается как агент;
• в Cursor роль чаще представляется правилом или набором правил;
• в GitHub Copilot используются профили пользовательских, проектных или организационных агентов;
• в остальных инструментах могут потребоваться конвертация и отдельная проверка формата.

GitHub описывает пользовательские агенты как Markdown-профили, где задаются специализация, инструменты и инструкции. Для проекта такие файлы могут храниться в .github/agents, а область действия определяется уровнем размещения. (docs.github.com)

Из этого следует важное ограничение: одинаковое имя роли не гарантирует одинаковое поведение во всех инструментах. Различаются:

• механизм загрузки инструкций;
• доступные команды;
• формат конфигурации;
• поддержка подагентов;
• политика подтверждения опасных действий;
• область действия правил.

Перед переносом роли необходимо выполнить один и тот же контрольный запрос в каждой среде и сравнить не стиль ответа, а результат: какие файлы изменены, какие команды запущены, какие проверки выполнены и какие ограничения соблюдены.

Когда несколько ролей работают последовательно, а когда параллельно

Последовательная схема подходит, если каждый этап зависит от результата предыдущего. Типичный пример:

1. планировщик определяет архитектуру;
2. исполнитель реализует изменение;
3. тестировщик проверяет поведение;
4. ревьюер анализирует diff;
5. человек принимает решение о слиянии.

Параллельная схема полезна, когда задачи независимы. Например, один агент проверяет безопасность API, второй анализирует производительность запроса, третий готовит тесты. Их результаты затем собирает общий проверяющий.

Параллельность нельзя оценивать по числу ролей. Решение зависит от зависимости данных и пересечения файлов.

Можно запускать параллельно, если:

• агенты работают с разными файлами или только читают код;
• каждый получает отдельную формулировку результата;
• итог можно сравнить без автоматического перезаписывания;
• есть единый ответственный за сборку результата.

Нужно выполнять последовательно, если:

• второй этап требует артефакт первого;
• несколько задач меняют один и тот же файл;
• общий интерфейс ещё не согласован;
• ошибка на раннем этапе делает последующие проверки бессмысленными.

Для изменений в одном репозитории необходимы отдельные ветки или git worktree. Иначе параллельные процессы будут видеть незавершённые изменения друг друга. Даже если конфликта Git не возникнет, логика проекта может оказаться смешанной.

Опыт: параллельный запуск ускоряет независимые проверки, но не устраняет очередь согласований. Без единого владельца merge gate команда получает несколько правдоподобных, но несовместимых вариантов.

Как организовать роли в инженерной команде

Для программного проекта удобно разделить роли на пять уровней:

• планирование — требования, архитектура, критерии готовности;
• реализация — код, миграции, конфигурация;
• тестирование — модульные, интеграционные и сценарные проверки;
• безопасность — угрозы, секреты, права доступа, внешние входы;
• документация — инструкции запуска, решения и ограничения.

Роль архитектора не должна одновременно писать код и самостоятельно принимать его. Иначе команда теряет независимую проверку. Тестировщик не должен ограничиваться сообщением «всё работает» — ему нужен список выполненных команд, покрытые сценарии и явно обозначенные непроверенные участки.

Для каждого агентского задания мы советуем использовать короткий шаблон:

Цель:
Входные файлы:
Разрешённые изменения:
Запрещённые изменения:
Ожидаемый результат:
Проверки:
Формат отчёта:
Условие остановки:

Такой шаблон снижает риск расползания задачи и облегчает повторный запуск после ошибки.

Для параллельной работы следует добавить:

Ветка или worktree:
Владелец результата:
Зависимости:
Файлы, которые нельзя менять:
Порядок слияния:

Если в задаче есть внешние документы, письма, веб-страницы или пользовательский ввод, нужен отдельный контроль prompt injection. В репозитории Agency Agents эта угроза прямо рассматривается в описании специализированной инженерной роли: внешний текст может попытаться подменить исходные инструкции агента. (github.com)

Что нужно добавить для корпоративного использования

Agency Agents может использоваться в корпоративном проекте, но только как слой ролевых инструкций. Полный контур корпоративного контроля нужно строить отдельно.

Минимальный набор защитных функций включает:

1. Права доступа. Разделите чтение, изменение кода, запуск команд, доступ к инфраструктуре и публикацию результата.
2. Секреты. Ключи API не должны попадать в Markdown-файлы ролей, логи терминала или общий контекст.
3. Журналы. Записывайте инициатора, задачу, использованную роль, изменённые файлы, команды и итог проверки.
4. Хранение данных. Определите, какие фрагменты кода, логи и документы можно передавать внешней модели и как долго их хранить.
5. Ручное одобрение. Слияние в защищённую ветку, изменение схемы базы, публикация и работа с production должны требовать отдельного подтверждения.
6. Изоляция. Для рискованных задач используйте отдельную рабочую среду, ограниченные токены и запрет доступа к ненужным каталогам.

Сам файл агента не создаёт IAM, аудит, контейнеризацию или сетевую сегментацию. Даже если в роли написано «не удаляй данные», это остаётся инструкцией, а не техническим запретом.

В этом смысле Agency Agents отвечает на вопрос «как должен рассуждать и оформлять результат специалист», но не на вопрос «какие системные действия ему разрешены». Для второго нужны настройки самого инструмента, операционной системы и инфраструктуры исполнения.

Как выбрать среду запуска для команды разного размера

Маленькой команде достаточно локального запуска, если задачи короткие, репозиторий помещается на рабочей машине, а ручной контроль сохраняется. Это хороший режим для первоначальной проверки трёх ролей.

Временная удалённая среда подходит, если нужно:

• быстро проверить новый набор ролей;
• не устанавливать зависимости на основной компьютер;
• дать доступ нескольким участникам;
• провести короткий эксперимент с отдельной веткой.

Постоянная удалённая среда нужна, когда задачи выполняются регулярно и должны быть воспроизводимыми. Решение о расширении инфраструктуры следует принимать не по количеству ролей, а по четырём факторам:

• сколько задач действительно выполняется одновременно;
• насколько долго живёт один рабочий процесс;
• сколько зависимостей нужно устанавливать;
• требуется ли постоянный доступ к репозиторию и тестовым сервисам.

Если агентам нужно работать с macOS-инструментами, Xcode или специфичными сборочными цепочками, можно рассмотреть удалённую аренду Mac в облаке. Для распределённых команд полезно заранее сравнить варианты аренды Mac в Сингапуре, учитывая задержку, регион доступа к сервисам и требования проекта.

Сравнение Agency Agents с полноценной платформой

Выбор схемы внедрения

Оценка готовности к применению

Мы используем простую шкалу от 0 до 2:

• 0 — процесс не определён;
• 1 — процесс есть, но проверяется вручную и нестабильно;
• 2 — процесс повторяемый, результат можно принять по заранее заданным критериям.

Если хотя бы две области получают 0 баллов, расширять число ролей рано. Сначала нужно исправить процесс.

Пошаговое внедрение в реальный проект

1. Выберите один повторяемый сценарий. Например, подготовка API-изменения, написание тестов или ревью pull request.
2. Определите три результата. План, изменение и проверочный отчёт должны быть отдельными артефактами.
3. Подберите три роли. Планировщик, исполнитель и проверяющий покрывают базовый цикл.
4. Установите только нужные файлы. Не копируйте весь каталог без причины.
5. Зафиксируйте права. Укажите, какие команды и каталоги разрешены каждой роли.
6. Запустите задачу в отдельной ветке или worktree.
7. Сохраните входной запрос и итоговые артефакты. Это позволит повторить эксперимент.
8. Проверьте возможность повторного запуска. Уберите случайные ручные действия и уточните недостающие входы.
9. Попросите человека принять результат по чек-листу.
10. Только после этого добавляйте четвёртую роль или параллельный процесс.

Чек-лист перед расширением AI Agent команды

• [ ] Каждая роль имеет одну основную ответственность.
• [ ] Для каждой передачи определены входной и выходной форматы.
• [ ] Понятно, какие задачи можно выполнять параллельно.
• [ ] Изменения в общих файлах проходят через ветки или worktree.
• [ ] Ошибку можно классифицировать и повторить с исправленным входом.
• [ ] Секреты не находятся в инструкциях и логах.
• [ ] Есть человек, отвечающий за финальное принятие.
• [ ] Проверяющий получает фактический diff, а не только описание работы.
• [ ] Контекст из одного проекта не переносится в другой без разрешения.
• [ ] Результат можно проверить тестом, документом или конкретным артефактом.

Итоговая рекомендация для внедрения

Agency Agents полезен, когда нужно быстро превратить общую команду «сделай задачу» в несколько специализированных режимов работы. Он помогает формализовать ожидания к архитектору, разработчику, тестировщику, редактору или специалисту по безопасности. Но он не решает автоматически вопросы координации, IAM, аудита, хранения данных и изоляции.

Для индивидуального проекта достаточно начать с трёх ролей. Продуктовой группе нужны контракты между исследованием, проектированием, производством и проверкой. Инженерной команде необходимы ветки, worktree и единый merge gate. Бизнесу — отдельный контур доступа, журналирование и ручное одобрение.

Слабое место локального запуска — зависимость от личного компьютера, прерывания сессии и отсутствие стабильной среды для долгих задач. Общий удалённый сервер добавляет другой риск: конкуренцию за файлы, смешивание секретов и сложность изоляции. Поэтому для временной проверки лучше не строить тяжёлую инфраструктуру, а для регулярных параллельных задач — не полагаться на один локальный терминал.

Мы бы начали с одного настоящего проекта: один планировщик, один исполнитель и один проверяющий. Если результаты взаимно дополняют друг друга, ошибки можно повторно обрабатывать, а человек успевает принимать изменения, тогда имеет смысл переносить процесс в постоянную удалённую среду. Если нужны длительные или параллельные сессии с macOS-зависимостями, следующим шагом будет оценка удалённой среды для Claude Code и других инструментов, а не установка десятков новых ролей без контроля.