AI Setup Subagents

Настройка подагентов

Перед существенной правкой политики подагентов получи ai-work-control/full; продолжай по его результату без повторения контроля.

Переносимость

P0 проектирует и записывает политику средствами агента по процедуре навыка. До запуска файла из scripts/** проверь его интерпретатор и платформу. Если Python или POSIX-среда недоступны, продолжи настройку вручную по справкам и пометь автоматическое обнаружение, запуск либо анализ как непроверенные. Не устанавливай недостающую среду без явного решения пользователя.

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

Главная граница

Разделяй четыре слоя:

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

Не записывай роли, модели, лимиты, Git-правила и исключения конкретного проекта в переносимый навык. Если нужно изменить AGENTS.md, сначала применяй профильный навык сопровождения AGENTS.md; ai-setup-subagents отвечает только за содержание политики подагентов.

Режимы

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

Явный запрет правок всегда означает policy. Запросы «настрой», «внедри», «зафиксируй», «обнови схему», «исправь настройку» означают implementation или repair, если пользователь не ограничил работу черновиком.

Состояние и срок проверки

Для проекта-потребителя различай три состояния: политика настроена, пользователь явно отказался от её создания, решение ещё не принято. Храни состояние, срок повторной проверки и дату последней успешной проверки в проектном локальном слое. Рекомендуемый переносимый формат описан в assets/subagents.local.toml.sample.

Во время настройки спроси срок повторной проверки и предложи 30 дней как значение по умолчанию. Полную проверку запускай по явному запросу, при отсутствии и политики, и зафиксированного отказа либо после истечения срока существующей политики. Отсутствующую, нечитаемую или будущую дату считай требующей проверки. Явный отказ подавляет автоматический запуск из-за отсутствия политики, но прямой запрос пользователя имеет приоритет. Срок повторной проверки применяется только к состоянию configured; для creation_declined не вычисляй следующую дату.

После успешной проверки предложи отдельным изменением обновить дату. В режиме без записи только сообщи дату, которую нужно зафиксировать: не выдавай её за сохранённую. Если пользователь отказался создавать политику и разрешил записать решение, зафиксируй состояние creation_declined; не подменяй отказ пустой или неполной политикой.

Обязательный порядок

1. Зафиксируй цель оптимизации: стоимость, скорость, пропускная способность, изоляция контекста, независимая проверка или сочетание целей.
2. Определи оснастки в порядке: явно названная пользователем, текущая среда и встроенные средства, пользовательская и проектная настройки, затем найденные исполняемые файлы. Собери точки входа инструкций, настройки всех активных оснасток, их пользовательские и проектные слои, профили, определения агентов, запускатели, доступные модели, лимиты, правила проекта и источники истины.
3. Классифицируй задачи по риску, неоднозначности, размеру контекста, обратимости, цене ошибки и стоимости проверки.
4. Реши, где должна жить политика. По умолчанию используй пользовательский слой активной оснастки либо subagents.local.toml, исключённый через .git/info/exclude. Перед созданием или изменением политики в Git отдельно получи прямое согласие пользователя. Если проект использует несколько оснасток, не создавай расходящиеся копии правил: оставь одну политику и тонкие точки входа. В AGENTS.md оставляй только условия чтения процедуры.
5. Проверь оснастки и модели отдельно. Для каждой оснастки сначала получи её собственный каталог через discover-subagent-models; совпадающие имена не делают модели общей настройкой. Семейство модели — условие поиска в каталоге, а не точный идентификатор запуска. При сбое каталога зафиксируй статус «список не получен» и перейди к локальной настройке или простому вопросу пользователю. Коротко проверяй через check-subagent-models только уже назначенные классам исполнения точные идентификаторы.
6. Для уже используемого проекта до выбора ролей рекомендуй анализ журналов через analyze-subagent-sessions. Начальная настраиваемая эвристика достаточности: 10 родительских сессий, 30 завершённых ходов, два дня и сведения о модели и инструментах для большинства ходов. При нехватке истории опирайся на структуру проекта, правила и запрос пользователя.
7. Сопоставь классы исполнения и модели сам: узкий поиск, малые обратимые правки, ограниченная проверка, редкая сильная проверка и работа родителя. Если для одного класса остаётся несколько кандидатов, а сопоставимое качество экономичного назначения не подтверждено, примени процедуру из references/model-selection-evaluation.md. Сначала выполни дешёвый отсев, затем малый пилот и последовательный выбор. Полный перебор используй один раз как исследовательскую базовую линию, а не как постоянную проверку.
8. Для каждого делегируемого класса задай контракт: входные данные, разрешённые инструменты, область записи, запреты, схему результата, обязательные свидетельства, уверенность, условия остановки и бюджет.
9. Определи приёмку результата: что проверяет родитель, какие детерминированные проверки запускаются, когда нужен независимый проверяющий и когда нужна сильная модель.
10. В режиме implementation или repair измени самый узкий долговечный слой: конфигурацию, проектную политику, запускатели или инструкции. Не подменяй техническую конфигурацию текстом в AGENTS.md.
11. Проверь фактическую работоспособность: конфигурацию, наличие классов, доступность каждой модели, переключение модели, журналы, лимиты и отчёт расхода. Используй run-execution-class: он передаёт только явные входные файлы и инструкцию, выбирает назначение для активной оснастки и сохраняет класс, назначенную и фактическую модель, длительность, расход, журнал, итог и вывод ошибок. Точный идентификатор должен совпасть с фактическим. Для псевдонима оснастки в локальной политике задай допустимый префикс фактической модели. Отдельный поток не доказывает маршрутизацию: agent_path = null, отсутствие класса, неизвестная модель или наследование модели родителя — провал. Одинаковая модель допустима только при явно заданной цели параллельности или изоляции контекста. run-subagent-role сохраняй только для совместимости со старой политикой ролей. Если запуск обслуживает обязательство профильной роли, передай запускателю --obligation <идентификатор>: его запись свяжет это обязательство с фактом запуска, но не подтверждает закрытие обязательства или пригодность результата. Если встроенный интерфейс не выбирает класс и модель, запускай отдельный процесс с явной моделью. Если запуск невозможен или небезопасен, явно назови блокер.
12. Перед ответом проверь, что конкретная политика и сведения о сроке её проверки зафиксированы вне переносимого навыка, а результат содержит изменённые файлы, способ проверки, остаточные риски и следующий шаг. Если режим запрещал запись, явно назови сведения, которые остались незафиксированными.

Право на запись

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

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

Что читать дополнительно

• references/operation-policy.md — режимы работы, пользовательское взаимодействие, Codex-конфигурация, выбор моделей, право на запись и приёмка.
• references/routing-patterns.md — матрицы маршрутизации, контракты, шаблоны результата, Codex-конфигурация, запускатели, диагностика и измерение.
• references/model-selection-evaluation.md — проектные проверочные задания, предварительный отсев, последовательный выбор и накопление свидетельств.

Формат результата

Для policy верни:

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

Для implementation и repair дополнительно верни:

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

Ограничения

• Не выдавай политику маршрутизации за техническую настройку.
• Не считай один AGENTS.md полной настройкой подагентов.
• Не подставляй конкретные модели без проверки доступности в текущей среде или явного списка пользователя.
• Не разрешай совпадение модели только по названию семейства, если локальная политика не содержит явный допустимый префикс фактического идентификатора.
• Не сохраняй настройки моделей в Git без отдельного прямого согласия пользователя.
• Не создавай сложную схему, если доступна только одна или две модели.
• Не меняй назначение модели автоматически по результату пилота. Даже статус confirmed служит основанием решения владельца, а не самим решением.
• Не добавляй отчётность по моделям и лимитам для задач без фактического запуска подагентов.
• Не выводи и не сохраняй тексты запросов, содержимое сессий или пути вне целевого проекта в отчёте анализа истории.
• Не исправляй общие дефекты AGENTS.md, Git-правил или документации внутри этого навыка; подключай профильный навык и фиксируй проектные правила в целевом проекте.