AGENTS.md: как написать инструкции для Codex и OpenCode

Антон Ларичев

19 сентября 2026

AI-инструментыopenaiDevOpsразработкаmiddle

AGENTS.md: как написать инструкции для Codex и OpenCode

AGENTS.md — это файл в корне репозитория, из которого кодовый агент узнаёт, как собирать проект, чем запускать тесты и каких соглашений держаться. Формат открытый и намеренно простой: обычный Markdown, обязательных полей нет, заголовки любые. Codex, OpenCode, Cursor, Gemini CLI, Aider, Zed, Windsurf, Roo Code, Kilo Code, Junie и ещё полтора десятка инструментов ищут файл с этим именем сами — вы пишете один файл, и вся команда получает одинаково настроенных агентов независимо от того, кто каким пользуется.

Ниже — что писать внутрь, как этот файл читают Codex и OpenCode (а читают они его по-разному), и почему иногда он молча не применяется.

Что такое AGENTS.md и зачем он нужен

Идея формата описана его авторами как «README для агентов»: у людей есть README и CONTRIBUTING, а у агента до этого не было предсказуемого места, куда заглянуть за контекстом проекта. AGENTS.md занял это место.

Практическая польза вылезает быстро. Агент не знает, что в вашем монорепозитории пакеты ставятся не через npm, что тесты гоняются одной командой, а линтер — другой, и что в этом проекте не принято трогать сгенерированные файлы. Без такого файла он каждый раз угадывает заново, а угадывает он по содержимому репозитория и не всегда верно. С файлом — читает и делает.

Ключевых свойств формата три:

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

Последнее стоит принять всерьёз: AGENTS.md — живой документ, который стоит править вместе с проектом, а не написать один раз и забыть.

Что писать внутри: минимальный пример

Авторы формата показывают минимальный набор из трёх секций — окружение, тесты и правила для пул-реквестов. Вот такой файл уже приносит пользу:

# Инструкции для агента

## Окружение
- Пакетный менеджер — pnpm, не npm и не yarn.
- Установка зависимостей одного пакета: `pnpm install --filter <package>`.
- Имя пакета смотрите в поле name его package.json, а не в корневом.

## Тесты
- Полный прогон по пакету: `pnpm turbo run test --filter <package>`.
- Из папки пакета достаточно `pnpm test`.
- Один тест по названию: `pnpm vitest run -t "<test name>"`.
- После переноса файлов или правки импортов запускайте `pnpm lint`.
- Не считайте задачу сделанной, пока падают тесты или проверка типов.

## Пул-реквесты
- Заголовок в формате [<package>] Краткое описание.
- Перед коммитом прогоняйте `pnpm lint` и `pnpm test`.

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

Хорошие кандидаты в файл: нестандартные команды сборки, порядок запуска проверок, структура каталогов, которую по именам не угадать, настройки линтера, которые легко нарушить, и операционные особенности вроде «миграции применяются только вручную». Если у вас настроен ESLint для TypeScript, упомяните команду запуска — агент будет чинить замечания сам.

Как AGENTS.md читает Codex

Codex собирает не один файл, а цепочку. Алгоритм по исходникам агента такой:

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

В каждой папке он проверяет имена по порядку: сначала AGENTS.override.md, потом AGENTS.md, потом то, что вы сами добавили в project_doc_fallback_filenames. Первое совпадение в этой папке и выигрывает — остальные имена в ней уже не смотрятся.

Из этого следует неочевидное. AGENTS.override.md — это локальная подмена: если он лежит рядом с AGENTS.md, командный файл в этой папке не прочитается вообще, а не дополнится. Удобно, когда нужно временно переопределить правила у себя на машине, но такой файл стоит сразу занести в .gitignore, иначе ваши личные правила уедут в репозиторий и подменят командные у всех.

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

Поведение настраивается в ~/.codex/config.toml:

# Общий бюджет на все файлы инструкций, в байтах
project_doc_max_bytes = 65536

# Запасные имена, если AGENTS.md в папке нет
project_doc_fallback_filenames = ["CLAUDE.md"]

# По чему определять корень проекта
project_root_markers = [".git"]

Про остальные секции этого конфига и про подключение самого агента — в статье Codex в России: как установить и настроить без VPN.

Диаграмма поиска AGENTS.md в Codex

Как AGENTS.md читает OpenCode

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

Локальные файлы — обход вверх от текущей директории, ищутся AGENTS.md и CLAUDE.md.
Глобальный файл ~/.config/opencode/AGENTS.md.
Файл Claude Code ~/.claude/CLAUDE.md.

Внутри каждой категории побеждает первый найденный. То есть если в проекте лежат и AGENTS.md, и CLAUDE.md, прочитается только AGENTS.md, а второй будет проигнорирован — это самый частый источник недоумения при переезде с одного агента на другой.

Писать файл с нуля необязательно. В OpenCode есть команда /init: она проходит по значимым файлам репозитория, при необходимости задаёт пару уточняющих вопросов и создаёт AGENTS.md — с командами сборки, линта и тестов, структурой проекта и локальными соглашениями. Если файл уже есть, /init дополнит его, а не перезапишет вслепую.

# запустить агента в папке проекта
opencode

# и уже внутри — собрать AGENTS.md по репозиторию
/init

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

Отдельная возможность — подключить уже существующие документы вместо дублирования их в AGENTS.md. Список задаётся полем instructions в opencode.json в корне проекта или в глобальном ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md",
    "packages/*/AGENTS.md"
  ]
}

Поддерживаются маски и удалённые адреса — файл правил можно держать в отдельном репозитории и подключать по URL, на его загрузку отводится 5 секунд. Всё перечисленное складывается с вашими AGENTS.md, а не заменяет их. Остальная настройка OpenCode, включая провайдера моделей, разобрана в статье OpenCode в России: установка и настройка без VPN.

Совместимость с CLAUDE.md

У Claude Code свой файл инструкций — CLAUDE.md, и в списке совместимости на сайте формата AGENTS.md его нет. Мост между двумя мирами строит OpenCode: он по умолчанию понимает соглашения Claude Code и подхватывает CLAUDE.md в проекте, если рядом нет AGENTS.md, а также глобальный ~/.claude/CLAUDE.md, если нет ~/.config/opencode/AGENTS.md.

Иногда это мешает — например, когда в ~/.claude/CLAUDE.md лежат правила под другой рабочий процесс и они начинают протекать в OpenCode. Совместимость отключается переменными окружения:

# отключить поддержку .claude целиком
export OPENCODE_DISABLE_CLAUDE_CODE=1

# отключить только чтение ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1

# отключить только скиллы из .claude/skills
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1

Со стороны Codex совместимость делается вручную — через тот самый project_doc_fallback_filenames, куда достаточно добавить "CLAUDE.md". Про сам Claude Code и его подключение — в статье Claude Code в России: как подключить и настроить без VPN.

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

ln -s AGENTS.md CLAUDE.md

Так содержимое остаётся в одном месте, и оба файла не расходятся.

Приоритет файлов инструкций в OpenCode

AGENTS.md в монорепозитории

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

AGENTS.md                      # общее: пакетный менеджер, стиль коммитов
packages/api/AGENTS.md         # своё: миграции, переменные окружения
packages/web/AGENTS.md         # своё: сборка фронтенда, правила компонентов

Дальше важно помнить, что результат зависит от агента. Codex, запущенный в packages/api, прочитает корневой файл и файл пакета и склеит их — общие правила плюс частные. У OpenCode правило другое: в категории локальных файлов побеждает первый найденный при обходе вверх, то есть ближайший. Рассчитывать на автоматическую склейку корневого и пакетного файла здесь не стоит — надёжнее перечислить их явно в instructions в opencode.json, благо маски это позволяют.

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

Частые ошибки при настройке

Файл лежит выше корня проекта. Codex не поднимается выше папки с маркером .git. AGENTS.md в домашней директории или на уровень выше репозитория просто не будет найден.

AGENTS.override.md забыт в репозитории. Он перекрывает AGENTS.md в своей папке целиком. Один случайно закоммиченный override — и вся команда работает по чужим локальным правилам.

Инструкции не влезли в бюджет. 32 КиБ по умолчанию — это много для осмысленного файла и мало для свалки из всей документации проекта. Хвост обрежется тихо, поэтому лучше держать файл коротким, чем поднимать лимит.

CLAUDE.md остался рядом с AGENTS.md. В OpenCode он будет проигнорирован. Это не ошибка конфигурации, это документированное поведение, но выглядит как «правила не работают».

В файле общие слова вместо команд. Строка «пишите качественный код» не меняет поведение агента. Строка с конкретной командой линтера — меняет.

Что делать дальше

AGENTS.md решает вопрос «что агент должен знать о проекте», но остаётся вопрос «каким агентом работать». Формат для того и придуман, чтобы этот выбор был свободным: один файл читают и Codex, и OpenCode, и Cursor с Windsurf, так что менять инструмент можно без переписывания инструкций.

Чтобы пользоваться этими агентами из России, нужен доступ к моделям. На тарифах AI для кода один ключ и общий баланс токенов работают и с Codex, и с Claude Code, и с OpenCode, и с Cursor — без VPN и с оплатой российской картой. Попробовать разные агенты на одном и том же AGENTS.md и оставить тот, что удобнее, ничего дополнительно не стоит.