AGENTS.md в 2026: 3 раздела правил для Claude Code и Codex

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

Если каждый раз писать в чате «сначала посмотри существующие файлы», «не трогай .env» и «после изменений запусти тесты», правила быстро теряются. Файл остаётся рядом с кодом. ИИ-агент получает его как часть контекста проекта.

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

Идея простая:

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

Файл задаёт агенту рабочий контекст. Ошибки и отдельные строки он сам не исправляет и не проверяет. Повторяющееся объяснение исчезает, а исходные рамки работы заданы заранее. Подробнее о формате CLAUDE.md и его поиске по дереву каталогов читайте в статье CLAUDE.md больше 200 строк в 2026: удалить и пересобрать.

Где лежит файл AGENTS.md и что в нём хранится

В корне файл проще заметить и подключить к инструментам. Для первого варианта хватит нескольких разделов:

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

Пример структуры:

# Правила проекта

## Команды

- Установка: `npm install`
- Запуск: `npm run dev`
- Тесты: `npm test`
- Сборка: `npm run build`

## Стиль

- Сначала изучай существующие файлы.
- Не создавай новую библиотеку без согласия.

## Структура

- `src/` - исходный код.
- `tests/` - тесты.

## После изменений

- Запусти тесты.
- Проверь сборку.

Заголовки помогают сгруппировать связанные инструкции. Списки делают отдельные требования заметными. Такая форма рекомендована для файлов с постоянными правилами.

Не превращай AGENTS.md в энциклопедию проекта. Нерелевантный текст становится шумом в контексте. Для CLAUDE.md документация Claude Code рекомендует держать файл меньше 200 строк. Для AGENTS.md в документации нет отдельного подтверждённого ограничения, поэтому не переноси это число на Codex как спецификацию.

AGENTS.md остаётся текстовым контекстом и не заменяет систему исполнения. Строка «всегда запускай тесты» не гарантирует запуск сама по себе.

Пример готового файла AGENTS.md

В официальном минимальном примере используются раздел Dev environment tips, команда pnpm test и требование обновлять тесты. Для другого проекта команды надо заменить. Саму логику можно сохранить.

Ниже вариант для проекта с npm:

# Правила проекта

## Команды

- Для установки используй `npm install`.
- Для запуска используй `npm run dev`.
- Для тестов используй `npm test`.
- Для сборки используй `npm run build`.

## Стиль

- Сначала изучи существующие файлы, потом редактируй.
- Не создавай новые библиотеки без моего согласия.
- Не трогай `.env`.

## Как работать

- Перед изменением найди связанные файлы.
- Делай небольшие изменения.
- Не переписывай рабочий код без причины.

## Что проверить после изменений

- Запусти `npm test`.
- Запусти `npm run build`.
- Обнови тесты, если поведение изменилось.

Строки с npm - шаблон. Замени их командами конкретного проекта. Если проект запускается через pnpm, в файл должны попасть команды pnpm. При отсутствии отдельной сборки не добавляй выдуманную команду.

Правила «не трогай .env» и «сначала изучи существующие файлы» можно оставить, если они подходят рабочему процессу. Формулировки «делай небольшие изменения» и «не переписывай рабочий код без причины» задают направление, но не создают технический запрет. Для контроля нужны внешние проверки.

Готовый промпт поможет проверить, понял ли ИИ-агент файл:

Прочитай AGENTS.md и кратко перечисли:
1. команды установки, запуска, тестирования и сборки;
2. файлы или действия, которые нельзя менять;
3. проверки после изменений.
Не изменяй файлы. Если в AGENTS.md нет ответа, напиши «не указано».

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

Как подключить AGENTS.md к Claude Code и Codex по шагам

1. Открой корень проекта

   Перейди в каталог репозитория. Проверь, что это нужная папка, а внутри нет случайного .git в подкаталоге.

2. Создай общий файл правил

   Добавь в корень файл AGENTS.md. Запиши команды, структуру каталогов и постоянные правила поведения.

   md

   Скопировать

   # Правила проекта
   
   ## Команды
   
   - Для установки используй `npm install`.
   - Для запуска используй `npm run dev`.
   - После изменений запускай `npm test`.
   
   ## Стиль
   
   - Не трогай `.env`.
   - Сначала изучи существующие файлы, потом редактируй.

3. Подключи файл к Claude Code

   В той же папке создай CLAUDE.md. Оставь в нём импорт общего файла.

   md

   Скопировать

   @AGENTS.md

4. Добавь особые правила Claude Code

   Если отдельное правило относится только к Claude Code, напиши его ниже импорта.

   md

   Скопировать

   @AGENTS.md
   
   ## Claude Code
   
   - Перед изменениями кратко перечисли файлы, которые собираешься затронуть.

5. Запусти инструмент из корня

   Открой Claude Code или Codex в каталоге, где лежат AGENTS.md и CLAUDE.md. Не начинай настройку из src/ или другого подкаталога.

6. Открой новую сессию

   Заверши активную сессию и запусти новую после создания или изменения файлов. Только новая сессия должна использовать свежий текст правил.

7. Проверь поведение

   Дай задачу без изменения файлов и попроси перечислить команды, ограничения и проверки из AGENTS.md. Для Codex не считай отсутствие глобального файла в /status доказательством, что инструкции не загрузились.

Как Claude Code читает правила из AGENTS.md

Документация Claude Code формулирует это прямо:

Поэтому одного файла AGENTS.md для Claude Code недостаточно. Нужна связка:

AGENTS.md       # общие правила проекта
CLAUDE.md       # импорт общего файла

В CLAUDE.md импорт выглядит так:

@AGENTS.md

@AGENTS.md - специальный импорт. Обычная Markdown-ссылка на файл лишь открывает его для чтения человеком:

[Правила проекта](AGENTS.md)

Такая строка выглядит как ссылка для чтения человеком. Она не подключает содержимое к контексту Claude Code тем способом, который нужен для общих инструкций.

После импорта можно добавить правила только для Claude Code:

@AGENTS.md

## Только для Claude Code

- Перед редактированием перечисли план действий.

Подробнее о поиске CLAUDE.md по дереву каталогов и формате файла читайте в статье CLAUDE.md больше 200 строк в 2026: удалить и пересобрать. Для этой статьи важно: AGENTS.md без импорта в CLAUDE.md не попадает в контекст Claude Code.

Как Codex читает правила из AGENTS.md

Claude Code получает инструкции через CLAUDE.md. Codex использует имя AGENTS.md как основной способ передать инструкции проекту.

Для первой настройки держи AGENTS.md в корне репозитория. Запускай Codex из этой же директории. Если внутри проекта случайно оказался отдельный .git, ближайшая папка с ним может быть принята за корень. Тогда выше этого места Codex уже не ищет.

Глобальные инструкции зависят от фактического значения CODEX_HOME. Глобальный файл может лежать по одному из путей:

$CODEX_HOME/AGENTS.md
$CODEX_HOME/AGENTS.override.md

Если CODEX_HOME указывает не на ~/.codex, проверка только ~/.codex/AGENTS.md не даст правильного ответа.

Порядок для Codex выглядит так:

1. Уточни, какая папка указана в CODEX_HOME.
2. Проверь глобальный AGENTS.md или AGENTS.override.md в этой папке.
3. Проверь проектный файл в корне.
4. Запусти Codex из каталога проекта.
5. Отдельно проверь, какой текст попал в текущую сессию.

Команда /status не всегда показывает глобальный AGENTS.md. Она может показать только проектный файл. Поэтому надпись без глобального файла не доказывает, что глобальные инструкции не применились.

Точные каталоги поиска проектных файлов и полный алгоритм наследования AGENTS.md в открытых источниках не подтверждены. Не воспринимай неподтверждённую схему как спецификацию Codex.

Сравнение Claude Code и Codex

Почему агент не соблюдает правила из AGENTS.md

Первая причина - слишком большой файл. Нерелевантные инструкции увеличивают шум в контексте. Правило про frontend не помогает задаче, где меняется только серверная часть. Для локальных требований подходят path-scoped rules.

Вторая причина - расплывчатая формулировка. «Правильно форматируй код» оставляет много вариантов. Лучше указать точное действие, компонент, импорт и поведение при отсутствии подходящего варианта.

## Frontend

- Для интерактивных элементов используй `GoodButton`, `GoodInput` и `GoodSelect`.
- Не добавляй обычные элементы `<button>`, `<input>` и `<select>`.
- Импортируй их из `@/components/ui`.
- Если подходящего компонента нет, остановись и спроси перед созданием нового.

Третья причина - конфликт файлов. Если AGENTS.md, CLAUDE.md и вложенный файл дают разные указания, Claude Code может выбрать инструкцию произвольно. Один источник истины безопаснее:

AGENTS.md       # общие правила проекта
CLAUDE.md       # @AGENTS.md и дополнения Claude Code

Четвёртая причина - ожидание жёсткого запрета. Фраза «никогда не коммить без тестов» остаётся текстовой инструкцией. Она не превращается в системное ограничение.

Если действие должно выполняться в фиксированный момент, перенеси контроль в механизм проверки:

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

Что проверить, если правило не применилось

1. Заверши активную сессию. Изменение AGENTS.md на диске не означает, что уже запущенный агент получил новую версию.

2. Открой новую сессию. После изменения файла запусти Claude Code или Codex заново. Проверяй правило только после нового старта.

3. Перейди в корень проекта. Убедись, что запуск идёт из каталога, где лежит проектный AGENTS.md.

4. Проверь лишний .git. Найди случайный каталог .git внутри проекта. Codex может принять ближайшую папку с ним за корень и загрузить другой набор инструкций.

5. У Claude Code должны лежать рядом AGENTS.md и CLAUDE.md. Внутри CLAUDE.md должна быть строка:

@AGENTS.md

6. Проверь глобальный Codex-файл отдельно. Узнай фактическое значение CODEX_HOME. Затем проверь наличие одного из файлов:

$CODEX_HOME/AGENTS.md
$CODEX_HOME/AGENTS.override.md

7. Не делай вывод по /status. Эта команда не всегда показывает глобальный AGENTS.md Codex. Отсутствие строки там не равно отсутствию глобальных инструкций.

8. Попроси агента пересказать правило. Дай задачу без изменений и попроси назвать команды, ограничения и проверку после работы. Так станет ясно, попал ли текст в контекст.

Запуск из подкаталога и дополнительные файлы в дереве могут дать другой набор правил. Подробнее о поиске файлов читайте в статье про CLAUDE.md.

Вопросы и ответы