Командные стандарты: AGENTS.md, навыки, конфигурация

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

Три уровня настройки

Тимлид отвечает за средний уровень. Верхний — зона техдира и администратора (см. «Администрирование: роли и управляемая конфигурация»). Важная деталь из документации: конфигурация из репозитория не может выдать агенту доступы, которых нет у рабочего пространства, — к моделям, API или подключённым системам (admin setup).

AGENTS.md: шаблон для команды

Codex собирает инструкции от корня репозитория до текущего каталога, по одному файлу на каталог; более близкий к коду файл идёт позже и уточняет общий. Суммарный объём по умолчанию ограничен 32 KiB (project_doc_max_bytes), всё сверх лимита не попадёт в контекст (AGENTS.md). Поэтому корневой файл — короткое оглавление, а подробности — в docs/ и во вложенных AGENTS.md.

Шаблон для типичного проекта агентства:

# Проект: сайт на OctoberCMS + тема на Vite

## Структура
- `plugins/<vendor>/<name>/` — бэкенд: компоненты, модели, сервисы
- `themes/site/` — шаблоны, SCSS, JS
- `tests/e2e/` — Playwright
- Подробности архитектуры: `docs/ARCHITECTURE.md`

## Команды
- Установка: `composer install && npm ci --prefix themes/site`
- Линт PHP: `vendor/bin/phpstan analyse`
- Юнит-тесты: `vendor/bin/phpunit`
- E2E: `npx playwright test` (нужен поднятый стенд, см. `docs/STAND.md`)
- Сборка фронта: `npm run build --prefix themes/site`

## Соглашения
- `declare(strict_types=1);` в каждом новом PHP-файле
- CSS — по БЭМ, стили страниц в `resources/scss/pages/<slug>.scss`
- Входные данные валидируем на границе: в компонентах и контроллерах

## Нельзя
- Менять миграции, которые уже на продакшене, — только новые
- Добавлять зависимости без упоминания в описании MR
- Трогать `.env`, ключи, конфиги окружений

## Готово, когда
- Линт и тесты зелёные, новые сценарии покрыты тестом
- В описании MR: что изменено, как проверено, что не проверено

## Code Review Rules
- Любое изменение схемы БД сопровождается обратимой миграцией
- Запросы с пользовательским вводом — только через query builder
  или параметры, без конкатенации строк
- Изменения в оплате и авторизации помечать как требующие
  второго ревьюера

Раздел ## Code Review Rules читает ревью-агент в GitLab и GitHub. Документация советует начинать с двух-трёх правил о существенном для репозитория поведении и оставлять форматирование и линт CI (GitHub). Подробно — в уроке «Codex как ревьюер».

Для мобильного приложения в монорепозитории добавьте mobile/AGENTS.md со своими командами сборки и правилами — он уточнит корневой, но только для файлов в mobile/. Как устроить иерархию в большом репозитории, разобрано в «AGENTS.md в большом репозитории».

Если вы проходили курс по Claude Code, AGENTS.md — аналог CLAUDE.md. Проекту, где уже есть CLAUDE.md, не нужно два источника правды: одна из возможностей — project_doc_fallback_filenames в конфигурации, другая — короткий CLAUDE.md, который ссылается на AGENTS.md.

Когда добавлять правило

Главная ошибка — написать сразу трактат. Документация советует держать файл коротким и добавлять правила после повторяющихся ошибок (best practices). Рабочий цикл:

1. Агент второй раз делает одно и то же не так.
2. Автор MR формулирует правило одной строкой и предлагает его в MR к AGENTS.md.
3. Если правило проверяется машиной — лучше линтер или тест, а в AGENTS.md только ссылка.

Последний пункт важен: правило в тексте агент может проигнорировать, проверку в CI — нет. Об этом урок «Ворота качества».

Навыки: повторяемая работа

Навык (skill) — каталог с SKILL.md, где описано, когда и как выполнять типовую работу. Командные навыки кладутся в .agents/skills/ репозитория; Codex видит сначала только имя и описание и загружает полный текст, когда навык подходит к задаче (skills).

Кандидаты в командные навыки — то, что в агентстве повторяется из проекта в проект: «новая страница-посадочная из блоков», «миграция плагина OctoberCMS», «e2e-тест на форму заявки», «релизная заметка по MR». Один навык — одна задача. Как писать навыки — в «Пишем свой навык»; если навыки нужны на нескольких проектах, их можно распространять плагином («Плагины»).

Правила команд и проектная конфигурация

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

prefix_rule(
    pattern = ["git", "push"],
    decision = "prompt",
    justification = "Пуш только после того, как человек посмотрел дифф",
)

prefix_rule(
    pattern = ["php", "artisan", "migrate:fresh"],
    decision = "forbidden",
    justification = "Сносит локальную базу; используйте migrate",
)

Две оговорки. Проектные .codex/config.toml, правила и хуки загружаются только для доверенных (trusted) проектов. Часть ключей в проектном конфиге игнорируется намеренно — например, провайдер модели и телеметрия, — чтобы чужой репозиторий не мог подменить учётные данные (advanced config). Синтаксис правил помечен как экспериментальный: перед внедрением проверьте его по документации Rules и командой codex execpolicy check. Подробнее — в уроке «Rules».

Что делает администратор

Ограничения, которые нельзя обойти локально, задаются в управляемой конфигурации: допустимые режимы одобрений и профили прав, список разрешённых MCP-серверов, правила команд. Например, только чтение и запись в рабочий каталог по умолчанию (managed configuration):

default_permissions = ":workspace"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true

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

Задача тимлида — сформулировать для администратора, что нужно команде (например, MCP-сервер для GitLab или браузер для QA), а не настраивать это самому.

Как владеть стандартом

• У стандарта есть владелец — обычно техлид проекта.
• Все изменения — через MR с понятным описанием «какую ошибку это предотвращает».
• Раз в месяц — чистка: что устарело, что дублирует линтер, что агент и так делает правильно. С новыми моделями часть старых инструкций становится лишней.
• Проверка, что агент реально видит: codex --sandbox read-only --ask-for-approval never "Summarize the current instructions." из корня и из подкаталога.