AGENTS.md — инструкция для ИИ-агента: как я управляю 26 субагентами через один файл

Первый раз я столкнулся с тем, что агент «пошёл не туда», в феврале 2025 года. Агент для обработки входящих лидов решил самостоятельно написать клиенту в Instagram — канал, который я ему не давал. Он просто нашёл контакт, увидел, что задача не решается через Telegram, и сымпровизировал. Технически правильно. Операционно — катастрофа: клиент получил сообщение от «бота», а не от меня, и ушёл.

Тогда у меня было 3 агента и системный промпт в 12 строк. Сейчас 26 субагентов, у каждого AGENTS.md на 50–400 строк плюс общая конституция на 365 строк. За полтора года я понял: агент без чёткого AGENTS.md — это не инструмент, это источник рисков.

Что такое AGENTS.md и откуда взялось это название

AGENTS.md — текстовый файл в корне рабочей директории агента, который содержит его операционные инструкции. Формат popularized в Claude Code (Anthropic): инструмент автоматически загружает этот файл в контекст каждой сессии. Аналог CLAUDE.md для кодового агента, только для любого типа агента.

Название — не стандарт, а конвенция. В разных платформах он называется по-разному: .cursorrules в Cursor, system.md в некоторых фреймворках, AGENT_PROMPT в ранних версиях AutoGPT. В Paperclip (платформа, на которой я строю Solar OS) он называется AGENTS.md и хранится в базе, инжектируется в системный контекст при старте каждого heartbeat-а агента.

Принципиальное отличие от системного промпта: AGENTS.md — постоянный, версионируемый операционный документ. Системный промпт пишется под конкретный диалог. AGENTS.md живёт в Git, меняется со временем, централизованно обновляется скриптом. Это разница между инструкцией на разовую задачу и должностной инструкцией сотрудника.

На практике это означает: когда агент просыпается и получает новую задачу, первое, что он читает — AGENTS.md. Не контекст прошлой сессии (его нет), не историю переписки, а операционный документ с правилами. Именно поэтому правила должны быть конкретными, а не абстрактными.

Из чего состоит AGENTS.md: минимальная структура на 7 блоков

За 18 месяцев работы с мультиагентными системами я выработал минимум из 7 блоков, без которых production-агент работает ненадёжно.

Блок 1. Идентичность и позиция в иерархии. Кто этот агент, как его называть, кому подчиняется, кем управляет. UUID важен: агент должен знать свой идентификатор, чтобы правильно подписывать задачи и логи. Tier определяет объём полномочий — Tier 1 (CEO) может нанимать и удалять агентов, Tier 3 (IC) только выполняет задачи в своей зоне.

Пример из реального AGENTS.md SEO-агента Solar OS:

UUID: be55de85-9bec-4bb5-80ba-ff894a03aab8
Tier: 3 (researcher)
Reports to: Marketing
Company: Solar OS (default Paperclip)

Блок 2. Зона ответственности — что делает агент. Конкретно и без размытости. Не «помогает с маркетингом», а «ведёт SEO для 4bos.ru: keyword research, написание статей, мониторинг Яндекс.Вебмастер, AI-readiness всех страниц». Если зона нечёткая — агент начнёт интерпретировать её в свою пользу.

Блок 3. Явные запреты — чего НЕ делает агент. Самый важный блок. Без него агент «помогает» в соседних зонах, создавая конфликты. В SEO-агенте прямо написано: «НЕ вести SEO для solarpropertybali.com — это другая компания. НЕ публиковать без QA-гейта seo_article.» Запреты формируются из инцидентов — каждый раз, когда агент делает что-то не то, это становится запретом.

Блок 4. Инструменты с ограничениями. Какие инструменты доступны и с какими ограничениями. SSH только на конкретный сервер. БД только read. API только GET. Это не про технические permissions — это про то, что агент должен явно знать границы своих инструментов, чтобы правильно их использовать и не лезть куда не нужно.

Блок 5. Approval-gate — что требует подтверждения человека. В Solar OS: расход ≥ 1.5M IDR, удаление таблиц БД, деплой в прод — всё NEED-APPROVAL. Агент не должен угадывать эту границу. Она написана явно. Без конкретных порогов агент либо спрашивает разрешения на каждые мелкие действия, либо делает крупный расход самостоятельно.

Блок 6. Handoff-протокол — кому передать задачу. Таблица: что пришло → куда. Если агент не знает кому передать задачу — он либо держит её у себя (блокер для всей цепочки), либо дропает (потеря). В SEO-агенте: «Критичная ошибка Яндекс.Вебмастер → CTO для тех.фикса, агент занимается диагностикой причины». Ответственность разделена явно.

Блок 7. KPI — по чему оценивается результат. Агент должен знать, что значит «хорошо». Не абстрактно, а измеримо. «Новых статей ≥ 1 в неделю. AI-readiness Level всех страниц 4bos.ru — 4 (Agent-Integrated). Яндекс.Вебмастер критичные ошибки — 0.» Без KPI агент оптимизирует то, что умеет, а не то, что нужно.

Конституция vs AGENTS.md агента: как разделить общее и частное

Когда у меня было 3 агента, я писал полные инструкции в каждый AGENTS.md отдельно. При 10 агентах это стало проблемой: одно правило («не использовать холодный аутрич») нужно было обновить в 10 файлах. При 26 — вручную невозможно, ошибки неизбежны.

Я разделил AGENTS.md на два слоя.

Конституция — /opt/constitution.md, 365 строк. Содержит правила, одинаковые для всех 26 агентов: иерархия компании, approval-gate, запреты (холодный аутрич, выдуманные цены, публикация без разрешения клиента), anti-slop фильтр на 12 категорий, протоколы безопасности. Конституция инжектируется в начало каждого AGENTS.md автоматически через constitution_distribute.py — cron каждые 15 минут.

Агент-специфичная часть — уникальная для конкретного агента: его UUID, Tier, зона ответственности, инструменты, KPI, heartbeat-задачи. Это 30–100 строк, которые я пишу вручную один раз при создании агента.

Результат: когда 21 мая 2026 я принял решение полностью выключить холодный аутрич после года неудачных экспериментов (0 продаж), я изменил одну строку в constitution.md. Через 15 минут правило появилось во всех 26 AGENTS.md без единого ручного редактирования.

Маркеры в файле позволяют скрипту найти границу:

<!-- CONSTITUTION-START -->
...365 строк общих правил...
<!-- CONSTITUTION-END -->

<!-- AGENT_CONTENT_START -->
...30-100 строк агент-специфичного контента...
<!-- AGENT_CONTENT_END -->

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

Главный архитектурный вывод: общие операционные правила компании живут в конституции. Роль и контекст агента — в его персональном AGENTS.md. Смешивать — создавать долг обслуживания, который растёт с каждым новым агентом.

Иерархия 26 субагентов Solar OS: как это выглядит на практике

В Solar OS (компания 4bos.ru, B2B-автоматизация) работают 26 субагентов в 3 тирах. Каждый знает своё место через AGENTS.md.

Tier 1 — CEO (1 агент): Альтрон. Управляет всем: routing входящих задач, KPI верхнего уровня, NEED-APPROVAL для крупных решений. Единственный канал между Юрием и компанией — через личного ассистента (@spb_claude_bot), который передаёт задачи CEO. CEO-агент не работает с клиентами напрямую.

Tier 2 — Менеджеры (5 агентов): CTO, Marketing, Product, Sales, Finance. Каждый управляет своей областью и набором IC-агентов. Tier 2 может создавать задачи для Tier 3, но не для других Tier 2 напрямую — через CEO. Это предотвращает горизонтальные конфликты полномочий.

Tier 3 — IC-агенты (20 агентов): Исполнители с узкой специализацией. seo-4bos, Telegram-агент (@mr_solar_blog), Instagram, Threads, X, VK, Broadcaster, QA и другие. Каждый знает только свою зону и свои инструменты. IC не создаёт задачи для других IC без согласования с менеджером.

Почему это важно для AGENTS.md: каждый агент в своём файле видит только ту часть иерархии, которая нужна для работы. SEO-агент знает, что он Tier 3, подчиняется Marketing-менеджеру, и что если задача требует правок в структуре сайта — это к CTO через Marketing, не прямой выход на CTO. Прописано в AGENTS.md явно.

Без явной иерархии в AGENTS.md агенты начинают «прыгать» через уровни. Агент-исполнитель пишет напрямую CEO с предложением реструктуризации. CEO перегружается нерелевантными задачами. Система теряет управляемость при росте.

Конкретный результат: с момента введения явной иерархии в AGENTS.md (март 2026) количество «нецелевых» задач, пришедших CEO напрямую от IC-агентов, упало с 8 в неделю до 0–1. Менеджеры стали настоящим буфером, а не декорацией в схеме.

Как раскатывать изменения на всех агентов: constitution_distribute.py

При изменении правила, которое касается всех агентов, нужна система раскатки. Вот как это устроено в Solar OS.

Шаг 1: изменение в constitution.md. Файл /opt/constitution.md — единственный источник правды для общих правил. Редактируется только он, никогда не AGENTS.md конкретного агента напрямую.

Шаг 2: constitution_distribute.py. Скрипт читает constitution.md и для каждого агента из базы данных: берёт его агент-специфичный блок AGENTS.md, ставит конституцию перед ним, сохраняет в базу. Если constitution.md не изменился с прошлого запуска (hash-проверка) — скрипт ничего не делает.

Шаг 3: cron каждые 15 минут. Скрипт запускается автоматически. За 6 месяцев (январь–июнь 2026) конституция обновлялась 14 раз — каждое обновление было раскатано на всех агентов без ручного вмешательства.

Правило бэкапа: перед каждым значимым изменением — backup /opt/constitution.md.bak.YYYY-MM-DD. За 6 месяцев я 3 раза откатывался на бэкап. Один раз — после того как экспериментальное правило сломало SEO-агент: он перестал публиковать статьи, потому что новый запрет был сформулирован слишком широко и захватил нужные действия.

Сессионный лог: каждое значимое изменение конституции я записываю в Архитектура/_sessions/YYYY-MM-DD.md с датой и мотивацией. Через 3 месяца, когда смотришь «почему это правило существует», ответ есть. Без лога правила без контекста удаляют «по ошибке».

Пять антипаттернов AGENTS.md, которые ломают систему

Собраны из 18 месяцев инцидентов. Каждый из них создавал реальные проблемы в продакшне.

1. Зона ответственности без запретов. Если написано только «агент ведёт SEO для 4bos.ru», агент неизбежно начнёт помогать с SEO для других сайтов — потому что это «то же самое». Явный запрет («НЕ трогать solarpropertybali.com — это другая компания») устраняет двусмысленность. Правило: каждый «делает» должен сопровождаться явным «не делает» в той же зоне.

2. Approval-gate без конкретной суммы. «Крупные расходы требуют согласования» — что такое крупные? Агент решит это за вас. В Solar OS: «≥ 1.5M IDR или ≥ 100 USDT разовый расход — NEED-APPROVAL от Юрия». Конкретная сумма, конкретный триггер. Без этого агент либо спрашивает на каждые 50 рублей, либо делает $500-расход самостоятельно.

3. Описание «как» вместо «что». AGENTS.md — операционный контракт, не пошаговая инструкция. «Публикуй статьи через agent_publish.py» — правильно. «Открой файл, создай JSON, заполни поля title, slug, meta_description в таком порядке...» — это руководство, не AGENTS.md. Подробности процедур живут в отдельных документах или heartbeat-задачах. AGENTS.md — что и почему, не как шаг за шагом.

4. Одинаковый AGENTS.md для всех агентов. Я видел системы, где у всех агентов один промпт и разница только в названии. Это не мультиагентная система — это один агент с разными именами. Каждый агент должен знать свой конкретный KPI, свои конкретные инструменты, своё место в иерархии. Без дифференциации в AGENTS.md дифференциации в поведении нет.

5. AGENTS.md без версионирования. Если вы меняете AGENTS.md без бэкапа и без лога мотивации, через 2 месяца вы не поймёте почему какое-то правило существует. Правило без мотивации — правило, которое удаляют «по ошибке» или нарушают, потому что контекст потерян. Git для AGENTS.md — не опция, а требование для любой production-системы.

Минимальный AGENTS.md для первого агента: шаблон из практики

Если у вас сейчас нет AGENTS.md и вы хотите начать — вот минимальный шаблон, который я бы написал в начале 2025 года, зная то, что знаю сейчас:

# [Имя агента]

**UUID:** [ваш UUID или уникальный идентификатор]
**Tier:** [1 CEO / 2 Manager / 3 IC]
**Reports to:** [кому подчиняется]

## Зона ответственности

[Конкретно что делает — 3-5 пунктов, без размытости]

## НЕ делает

[Явные запреты — минимум 3 пункта]
[Каждый запрет — из реального инцидента или понятного риска]

## Инструменты

[Список инструментов с ограничениями по доступу]

## Approval-gate

[Что требует согласования — конкретные пороги в числах]

## Handoff

| Что приходит | Куда |
|---|---|
| [сценарий 1] | [кому] |
| [сценарий 2] | [кому] |

## KPI

| Метрика | Целевое |
|---|---|
| [метрика 1] | [измеримое значение] |
| [метрика 2] | [измеримое значение] |

50–70 строк. Это лучше, чем 300 строк абстрактных правил на старте. Конкретность важнее полноты.

Первый агент с таким AGENTS.md проработает неделю. За неделю появится 3–5 инцидентов — моментов, когда агент сделал что-то не так. Каждый инцидент — новая строка в запретах или в handoff-протоколе. Через месяц у вас будет живой AGENTS.md, написанный из реальных столкновений с реальностью, а не из теоретических предположений о том, как агент должен работать.

Мой SEO-агент сейчас занимает 150 строк. Треть из них — запреты и handoff, написанные после конкретных инцидентов. Это лучшая документация, которую я мог бы написать — потому что она написана из опыта, а не до него.

AGENTS.md для клиентских проектов: что меняется

Когда я строю автоматизацию для клиентов (B2B-проекты от 180 000 рублей), AGENTS.md для клиентских агентов устроен иначе, чем для моих внутренних. Три принципиальных отличия.

Первое: клиент — не Юрий. В своей системе я знаю все нюансы и могу дать агенту широкие полномочия. У клиента агент работает в чужом контексте с чужими данными. Это означает более узкую зону ответственности, более высокий approval-gate и явный запрет на действия, которые клиент не предусмотрел при постановке задачи. Лучше агент остановится и спросит, чем сделает что-то необратимое с чужой базой клиентов.

Второе: агент работает от имени клиента, а не от моего. Это меняет тон, стиль ответов и список каналов. Агент для медицинской клиники в Санкт-Петербурге не пишет «Юрий сказал» — он пишет от лица клиники. AGENTS.md содержит персону: как называть компанию, какой тон (формальный/неформальный), какие каналы использует клиент (только Telegram, без Instagram), какие слова запрещены в коммуникациях.

Третье: версионирование и передача. Мои внутренние AGENTS.md могу менять в любой момент. Клиентские — только по согласованию. Это означает, что каждое изменение AGENTS.md клиентского агента фиксируется в changelog, клиент получает уведомление, изменение вступает в силу после его подтверждения. Это дополнительный слой governance, который защищает клиента от неожиданных изменений поведения агента.

На практике это добавляет 20–30 строк в AGENTS.md: блок «Клиентский контекст», блок «Запрещённые действия без согласования клиента», блок «Протокол изменений». Немного, но принципиально для production-системы, которую вы сдаёте заказчику.

Конкретный пример: для клиники в СПб агент отвечает на сообщения пациентов в Telegram. В AGENTS.md прописано: «не упоминать конкурентов», «не называть цены без актуального прайса», «если пациент упоминает скорую или ухудшение — немедленный handoff живому администратору». Это не фантазии — это три инцидента из первых двух недель работы агента, превращённые в правила. С момента добавления этих строк ни один из трёх сценариев не повторился.

Как AGENTS.md связан с multi-agent orchestration

AGENTS.md — это не только инструкция для одного агента. В мультиагентной системе AGENTS.md каждого агента является частью общего операционного договора между всеми участниками.

Когда агент Marketing создаёт задачу для SEO-агента, он опирается на то, что написано в AGENTS.md SEO-агента: какие инструменты тот умеет использовать, каков его approval-gate, по какому протоколу он отдаёт результат. Если AGENTS.md SEO-агента написан размыто, Marketing-агент не может корректно сформулировать задачу — он не знает границ исполнителя.

Это означает, что AGENTS.md — это интерфейс агента для других агентов в системе, не только инструкция для самого агента. Хорошо написанный AGENTS.md позволяет другим агентам делегировать задачи без ошибок. Плохой AGENTS.md создаёт неопределённость, которая накапливается по всей цепочке.

В Solar OS каждый менеджер Tier 2 знает AGENTS.md всех своих IC-агентов. CEO-агент Альтрон знает зоны ответственности всех менеджеров. Это позволяет routing входящих задач работать автоматически: когда Юрий через ассистента говорит «напиши статью про автоматизацию CRM», CEO знает что это → Marketing → SEO, и цепочка запускается без промежуточных уточнений.

В системе без явных AGENTS.md каждая задача требует ручного объяснения: кто за что отвечает, кому делегировать, какие ограничения. Это не автоматизация — это ручное управление с AI-интерфейсом.

Измеримый эффект в Solar OS: до введения структурированных AGENTS.md (декабрь 2024) я тратил около 40 минут в день на объяснение контекста агентам перед каждой сессией. После введения — 0–5 минут. Не потому что агенты стали умнее, а потому что весь контекст уже в AGENTS.md. Агент просыпается, читает файл, понимает кто он, что делает и чего не делает. Без ввода.

Если вы сейчас тратите больше 15 минут в день на объяснение контекста своим AI-инструментам — скорее всего, у вас нет нормального AGENTS.md. Это первое, что стоит починить, прежде чем добавлять новых агентов или новые инструменты.

Реальные AGENTS.md, конституция Solar OS, шаблоны для разных типов агентов и ежедневные обновления что в системе меняется — в клубе «Solar — внутрянка». Бери и адаптируй под свою задачу: https://4bos.ru/inside/, от 2 500 ₽/мес.

— Solar OS.