# Руководство по AGENTS.md

`AGENTS.md` для Codex — то же, что `CLAUDE.md` для Claude Code. Это Markdown-файл в вашем проекте, который сообщает AI-ассистенту: каким стандартам следует проект, как писать код и чего избегать.

Если вы уже пользуетесь `CLAUDE.md` в Claude Code, идея `AGENTS.md` покажется знакомой. Философия у них общая, различаются лишь детали оформления. В этом руководстве подробно разобрана настройка `AGENTS.md` и то, как эффективно переиспользовать стандарты проекта в обоих инструментах.

---

> **Это больше не файл только для Codex.** В марте 2026 года Anthropic, OpenAI, Google, AWS, Microsoft
> и Salesforce основали **Agentic AI Foundation (AAIF)**, который принял три открытых спецификации
> как общую основу: **MCP** (слой инструментов и контекста), **AGENTS.md** (спецификация поведения
> агента) и **Goose** (эталонная реализация). На практике это значит, что один `AGENTS.md` читает
> всё больше инструментов, а не только Codex.

## AGENTS.md vs CLAUDE.md

Прежде чем углубляться в `AGENTS.md`, вот сравнение с `CLAUDE.md`:

| Аспект | AGENTS.md (Codex) | CLAUDE.md (Claude Code) |
|--------|---------------------|--------------------------|
| Инструмент | OpenAI Codex CLI | Anthropic Claude Code |
| Формат файла | Markdown | Markdown |
| Иерархия загрузки | Глобально / корень репозитория / подкаталог (три уровня) | Глобально / корень проекта / подкаталог (три уровня) |
| Расположение глобального | `~/.codex/AGENTS.md` | `~/.claude/CLAUDE.md` |
| Механизм переопределения | Подкаталог может переопределить правила родителя | Подкаталог может дополнять и переопределять правила |
| Стиль изложения | Тяготеет к кратким спискам и директивам | Допускает подробные объяснения и разговорный стиль |
| Распространённость | Быстро растёт, уже принят многими OSS-проектами | Широко распространён, зрелая экосистема |
| Контроль версий | Рекомендуется коммитить в репозиторий | Рекомендуется коммитить в репозиторий |
| Взаимное распознавание | Не читает CLAUDE.md | Не читает AGENTS.md |

> **Главное**: файлы не видят друг друга. Если вы используете оба инструмента, придётся вести `AGENTS.md` и `CLAUDE.md` отдельно. Хорошая новость: основное содержимое можно сделать общим.

---

## Базовая конфигурация

### Где размещать файл

Создайте `AGENTS.md` в корне проекта:

```
your-project/
  AGENTS.md          <- конфигурация уровня репозитория
  src/
  tests/
  package.json
```

### Базовый синтаксис

`AGENTS.md` — обычный Markdown-файл. Codex читает его при запуске и следует указанным инструкциям. Чаще всего используют **маркированные списки**:

```markdown
# AGENTS.md

- Весь код писать на TypeScript в строгом режиме
- Форматирование через Prettier, статический анализ через ESLint
- Тесты на Vitest, размещать в каталогах `__tests__/`
- Перед завершением задачи выполнять `npm run lint && npm test`
- Не изменять файлы в каталоге `vendor/`
- Ответы API должны следовать стандартному формату-конверту: `{ code, data, message }`
```

Можно организовать правила по категориям с помощью заголовков:

```markdown
# AGENTS.md

## Стандарты кода
- Использовать строгий режим TypeScript
- Переменные — camelCase, типы — PascalCase
- Не более 50 строк на функцию

## Требования к тестам
- Целевое покрытие модульными тестами: 80%
- Файлы тестов повторяют имя исходника с суффиксом `.test.ts`
- Внешние зависимости мокать; никаких реальных сетевых запросов в тестах

## Запрещено
- Использовать тип `any`
- Напрямую работать с DOM (используйте управление состоянием React)
- Использовать `await` внутри циклов (используйте `Promise.all`)
```

### Выбор языка

Содержимое `AGENTS.md` можно писать **по-русски** или **по-английски** — Codex корректно понимает оба языка. С точки зрения командной работы:

- **Личные проекты**: пишите на удобном вам языке
- **Командные проекты**: рекомендуется английский (согласуется с кодом)
- **Русскоязычные команды**: русский работает совершенно нормально

---

## Многоуровневая конфигурация

`AGENTS.md` поддерживает три уровня конфигурации, уточняя правила от глобальных к конкретным каталогам:

### Уровень 1: глобальная конфигурация

Расположение: `~/.codex/AGENTS.md`

Универсальные стандарты, применимые ко всем вашим проектам:

```markdown
# Глобальный AGENTS.md

## Общие стандарты
- Комментарии в коде писать по-английски
- Сообщения коммитов по схеме Conventional Commits
- Никогда не зашивать пароли, ключи и токены в исходный код
- Перед генерацией нового кода прочитать существующий связанный код, чтобы сохранить единообразие
- Если влияние изменения непонятно — добавить поясняющий комментарий, а не строить догадки

## Предпочтения по выводу
- Отдавать предпочтение уже имеющимся зависимостям; не добавлять новые без нужды
- Обработка ошибок должна быть полной; не проглатывать исключения молча
- Сообщения в логах должны быть осмысленными и содержать контекст
```

### Уровень 2: конфигурация уровня репозитория

Расположение: `AGENTS.md` в корне проекта

Стандарты конкретного проекта:

```markdown
# AGENTS.md

## О проекте
Фулстек-проект интернет-магазина на React + Node.js, написанный на TypeScript.

## Технологический стек
- Фронтенд: React 19 + TailwindCSS + Zustand
- Бэкенд: Node.js + Fastify + Prisma
- База данных: PostgreSQL 16
- Тесты: Vitest + Playwright

## Стандарты кода
- Файлы компонентов — PascalCase: `UserProfile.tsx`
- Вспомогательные функции — camelCase: `formatDate.ts`
- Маршруты API — kebab-case: `/api/user-orders`
- Поля базы данных — snake_case: `created_at`

## Структура проекта
- `src/components/` - компоненты React
- `src/pages/` - компоненты страниц
- `src/api/` - маршруты бэкенд-API
- `src/lib/` - общая библиотека утилит
- `prisma/` - схема базы и миграции

## Команды
- `npm run dev` - запустить dev-сервер
- `npm run build` - production-сборка
- `npm test` - запустить все тесты
- `npm run lint` - статический анализ
- `npx prisma migrate dev` - выполнить миграции базы
```

### Уровень 3: конфигурация подкаталога

Расположение: `AGENTS.md` в любом подкаталоге

Дополнительные правила для конкретного модуля, **накладываемые поверх правил родителя**:

```
your-project/
  AGENTS.md                  <- правила уровня проекта
  src/
    components/
      AGENTS.md              <- правила каталога компонентов
    api/
      AGENTS.md              <- правила каталога API
```

Пример `src/components/AGENTS.md`:

```markdown
# Стандарты компонентов

- Все компоненты — функциональные (классовые запрещены)
- У Props должно быть определение interface на TypeScript
- У каждого компонента должен быть displayName
- Стилизация через TailwindCSS; инлайновые стили запрещены
- Сложные компоненты разбивать на подкомпоненты; файл не длиннее 200 строк
- Переиспользуемые компоненты класть в подкаталог `ui/`
```

Пример `src/api/AGENTS.md`:

```markdown
# Стандарты API

- Все эндпоинты обязаны валидировать параметры запроса (схемы Zod)
- Единый формат ошибки: `{ code: number, message: string, details?: any }`
- Операции с базой выполнять внутри транзакций
- Чувствительные операции записывать в журнал аудита
- Для пагинации использовать курсорный подход
```

### Приоритет переопределения

Когда правила на разных уровнях `AGENTS.md` конфликтуют, **побеждает ближайшее**:

```
Глобальный (~/.codex/AGENTS.md)
  | переопределяется уровнем репозитория
Корень репозитория (project/AGENTS.md)
  | переопределяется подкаталогом
Подкаталог (project/src/api/AGENTS.md) <- высший приоритет
```

На практике:

- Правила `AGENTS.md` из подкаталога важнее родительских
- Родительские правила, которые не были переопределены, продолжают действовать
- Правила разных уровней **складываются**, а не заменяют друг друга целиком

---

## Практические шаблоны

Ниже — проверенные шаблоны, которые можно скопировать в свой проект.

### Фронтенд-проект на React

```markdown
# AGENTS.md

## О проекте
Фронтенд-проект на React 19 + TypeScript + TailwindCSS.

## Стандарты кода
- Использовать функциональные компоненты и Hooks; классовые запрещены
- Управление состоянием — Zustand; Redux не вводить
- Стилизация через TailwindCSS; CSS-файлы не создавать
- Для модулей из src использовать псевдоним пути `@/`
- Props компонента описывать интерфейсом с именем `{ComponentName}Props`

## Именование файлов
- Компоненты: PascalCase (`UserAvatar.tsx`)
- Хуки: camelCase с префиксом use (`useAuth.ts`)
- Утилиты: camelCase (`formatDate.ts`)
- Константы: camelCase (`apiEndpoints.ts`)

## Правила для компонентов
- Экспортировать и тип Props, и сам компонент
- Чисто презентационные компоненты оборачивать в `React.memo`
- Обработчики событий называть `handle{EventName}`
- Не создавать новые объекты и функции внутри render

## Тесты
- Стек: Vitest + React Testing Library
- Файлы тестов класть в каталоги `__tests__/`
- Тестировать поведение пользователя, а не детали реализации
- Команда запуска: `npm test`

## Управление зависимостями
- Перед добавлением новой зависимости проверить, не покрывают ли задачу существующие
- Предпочитать лёгкие библиотеки
- У всех зависимостей должны быть определения типов TypeScript
```

### Бэкенд-проект на Python/FastAPI

```markdown
# AGENTS.md

## О проекте
Бэкенд-сервис на Python 3.12 + FastAPI + SQLAlchemy.

## Стандарты кода
- Аннотации типов: у всех параметров и возвращаемых значений
- Асинхронность в первую очередь: все IO-операции через async/await
- Docstring: у всех публичных функций в стиле Google
- Порядок импортов: стандартная библиотека -> сторонние -> локальные модули (управляется isort)

## Структура проекта
- `app/api/` - маршруты API (router на каждую функциональность)
- `app/models/` - модели данных SQLAlchemy
- `app/schemas/` - модели запросов и ответов Pydantic
- `app/services/` - слой бизнес-логики
- `app/core/` - конфигурация, безопасность, внедрение зависимостей
- `tests/` - тесты, повторяющие структуру каталога app
- `alembic/` - миграции базы данных

## Соглашения по коду
- Именование функций маршрутов: `get_users`, `create_order` (глагол_существительное)
- Методы сервисного слоя соответствуют функциям маршрутов
- Поля моделей данных — snake_case
- Все операции с базой идут через сервисный слой; маршруты не трогают ORM напрямую
- Чувствительные данные (пароли, токены) не должны попадать в логи и ответы

## Обработка ошибок
- Бизнес-исключения — собственные классы Exception
- Единый обработчик исключений возвращает стандартный формат: `{"code": int, "message": str}`
- Операции с базой оборачивать в try/except и ловить IntegrityError и подобные
- Никогда не использовать голый except

## Тесты
- Стек: pytest + pytest-asyncio + httpx
- Тестовую базу и клиент вести через fixtures
- Команда запуска: `pytest -v --cov=app`
- Минимальное целевое покрытие: 80%

## Управление окружением
- Конфигурация в .env, загружается через pydantic-settings
- Различия между окружениями решаются переопределением переменных окружения
- Не зашивать строки подключения к базе и секреты в код
```

### Фулстек-проект

```markdown
# AGENTS.md

## О проекте
Фулстек веб-приложение: фронтенд на Next.js 15 + API Routes + PostgreSQL.
Структура monorepo под управлением Turborepo.

## Структура каталогов
- `apps/web/` - фронтенд на Next.js
- `apps/api/` - отдельный сервис API (Node.js + Fastify)
- `packages/ui/` - общая библиотека UI-компонентов
- `packages/types/` - общие типы TypeScript
- `packages/utils/` - общие вспомогательные функции
- `packages/db/` - схема базы данных (Drizzle ORM)

## Общие стандарты
- Язык: TypeScript в строгом режиме
- Форматирование: Prettier (настроен в корне)
- Lint: ESLint (настроен в корне)
- Перед коммитом выполнять: `turbo lint test`

## Стандарты фронтенда (apps/web/)
- Использовать App Router, а не Pages Router
- Server Components в первую очередь; Client Components только при необходимости
- Получение данных через Server Actions или Route Handlers
- Стилизация через TailwindCSS
- Изображения через компонент next/image

## Стандарты API (apps/api/)
- RESTful-дизайн, URL в kebab-case
- Валидация запросов через Zod
- Формат ответа: `{ success: boolean, data?: T, error?: string }`
- Аутентификация по JWT, проверяется в middleware
- Правила ограничения частоты — в декораторах маршрутов

## Стандарты базы данных (packages/db/)
- Использовать Drizzle ORM; схема в каталоге `schema/`
- Команда миграции: `pnpm db:migrate`
- Именование: имена таблиц во множественном числе (`users`), поля snake_case
- У всех таблиц должны быть `created_at` и `updated_at`
- Мягкое удаление через поле `deleted_at`

## Стандарты общих пакетов
- Пакеты ссылаются друг на друга через workspace
- Общие определения типов — в `packages/types/`
- Пакеты не должны импортировать из apps
```

---

## Продвинутые приёмы

### Сосуществование с CLAUDE.md

Если в проекте используются и Codex, и Claude Code, оба файла конфигурации можно вести рядом:

```
your-project/
  AGENTS.md          <- читает Codex
  CLAUDE.md          <- читает Claude Code
  src/
  ...
```

**Основные стандарты можно сделать общими.** Большая часть содержимого обоих файлов (стек, соглашения по именованию, структура каталогов) будет одинаковой — различаются лишь директивы, специфичные для инструмента.

Рекомендуемый подход:

1. Написать один набор основных стандартов
2. Скопировать его и в `AGENTS.md`, и в `CLAUDE.md`
3. Подстроить оформление под соглашения каждого инструмента

Или элегантнее — сослаться друг на друга в начале каждого файла:

```markdown
# AGENTS.md

> В этом проекте используются и Codex, и Claude Code. Основные стандарты ниже.
> Пользователям Claude Code — см. CLAUDE.md.

## Основные стандарты
(общее содержимое)
```

### Практики командной работы

#### Коммитьте файл в систему контроля версий

`AGENTS.md` следует коммитить в репозиторий Git, чтобы вся команда работала по одним стандартам AI-разработки:

```bash
git add AGENTS.md
git commit -m "feat: add AGENTS.md for Codex configuration"
```

#### Включайте AGENTS.md в код-ревью

Изменения `AGENTS.md` должны проходить ревью так же, как изменения стандартов кодирования:

```markdown
<!-- Описание PR -->
## Суть изменений
Обновления AGENTS.md:
- Добавлен стандарт пагинации API (курсорный)
- Явно запрещены прямые вызовы fetch в компонентах
- Добавлены требования к формату логов
```

#### Развивайте постепенно

Не нужно писать всё сразу. Рекомендуемый порядок:

1. **В первый день**: записать базовый стек и соглашения по именованию (10–20 строк)
2. **В первую неделю**: добавлять правила исходя из фактического поведения Codex
3. **Дальше**: каждый раз, когда Codex делает нежелательное, добавлять правило в `AGENTS.md`

### Формулировки, которые работают

В `AGENTS.md` лучше всего работают такие инструкции:

```markdown
## Эффективные инструкции (Codex надёжно им следует)

- Явное требование к формату: имена файлов компонентов в PascalCase
- Явный запрет: не использовать тип any
- Команда запуска: после завершения задачи выполнить npm test
- Правило размещения файлов: файлы тестов класть в каталоги __tests__
- Ограничение зависимостей: не добавлять новые npm-пакеты, использовать существующие
```

```markdown
## Малоэффективные инструкции (лучше избегать)

- Слишком расплывчато: пиши хороший код
- Субъективно: следуй лучшим практикам
- Вне зоны действия: подумай об удобстве для пользователя (AI не запускает UI)
- Противоречиво: приоритет производительности + приоритет читаемости (нужен явный приоритет)
```

### Условные правила

Можно задать разные правила для разных типов файлов или каталогов:

```markdown
## Правила по типам файлов

### Файлы *.test.ts
- Не больше 10 тестов в одном блоке describe
- Тестовые данные создавать фабричными функциями, не зашивать
- У асинхронных тестов должен быть таймаут

### Файлы *.api.ts
- Обязательно валидировать параметры запроса
- Обязательно предусмотреть обработку ошибок
- У возвращаемых значений должны быть аннотации типов

### Файлы migrations/*.sql
- Не редактировать напрямую; генерировать через инструмент миграций ORM
```

---

## Миграция с CLAUDE.md

Если у вас уже есть `CLAUDE.md`, превратить его в `AGENTS.md` несложно. Оба в формате Markdown, и основное содержимое переносится напрямую.

### Шаги миграции

**Шаг 1: скопировать базовое содержимое**

```bash
cp CLAUDE.md AGENTS.md
```

**Шаг 2: заменить упоминания, специфичные для Claude Code**

Замените понятия Claude Code на эквиваленты Codex:

| В CLAUDE.md | В AGENTS.md |
|--------------|--------------|
| «Когда Claude изменяет файлы…» | «При изменении файлов…» |
| «Используй `/compact` для сжатия контекста» | (Убрать — у Codex нет такой команды) |
| «Ссылайся на файлы через `@`» | (Убрать — в Codex другой способ ссылок) |
| «Hook: PostToolUse…» | «После завершения задачи выполнить…» |
| «Субагент обрабатывает…» | «Использовать Cloud Exec…» |

**Шаг 3: упростить формат**

Codex предпочитает краткие директивы списком. Если в `CLAUDE.md` есть длинные пояснительные абзацы, сожмите их в пункты:

До миграции (стиль `CLAUDE.md`):

```markdown
## Стиль кода

В этом проекте мы следуем руководству по стилю TypeScript от Google. Все имена
переменных пишутся в camelCase, имена классов — в PascalCase. Обратите внимание,
что значения перечислений пишутся в SCREAMING_SNAKE_CASE. Импорты должны идти
в таком порядке: сначала встроенные модули Node.js, затем сторонние пакеты и
в конце локальные модули. Группы разделяются пустой строкой.
```

После миграции (стиль `AGENTS.md`):

```markdown
## Стиль кода
- Следовать руководству по стилю TypeScript от Google
- Переменные: camelCase
- Классы: PascalCase
- Значения перечислений: SCREAMING_SNAKE_CASE
- Порядок импортов: встроенные модули -> сторонние пакеты -> локальные модули (между группами пустая строка)
```

**Шаг 4: добавить директивы, специфичные для Codex**

```markdown
## Настройки, специфичные для Codex
- После всех изменений файлов выполнить `npm run lint && npm test` для проверки
- Если тесты падают — исправить и перезапустить автоматически
- Не изменять файлы .env и .env.local
```

### Справочная таблица миграции

| Понятие | Стиль CLAUDE.md | Стиль AGENTS.md |
|---------|-----------------|-----------------|
| Описание проекта | Свободные абзацы | Краткий список или абзац |
| Стандарты кода | Списки Markdown | Списки Markdown (так же) |
| Запреты | «Не делай X» | «Никогда не делай X» или «Не делай X» |
| Команды запуска | «Пожалуйста, выполни `npm test`» | «Выполнить `npm test`» или просто перечислить |
| Структура файлов | Дерево каталогов в блоке кода | Дерево каталогов в блоке кода (так же) |
| Настройка инструмента | Ссылки на settings.json | Ссылки на config.toml |

### Если нужно вести оба файла

Если `AGENTS.md` и `CLAUDE.md` придётся поддерживать долго:

1. **Назначьте один «главным»**: обычно это файл того инструмента, которым вы пользуетесь чаще
2. **После правки главного — синхронизируйте**: это можно автоматизировать простым скриптом
3. **Держите специфичные для инструмента правила отдельно**: общие стандарты в начале, специфичные — в конце

---

## Отладка и проверка

### Как убедиться, что AGENTS.md работает

Проще всего дать Codex задачу, на которой правило должно сработать:

```bash
# Предполагаем, что AGENTS.md требует TypeScript
codex "Создай функцию hello world"

# Если AGENTS.md действует, Codex создаст файл .ts, а не .js
```

### Что делать, если правила не срабатывают

1. **Расположение файла**: `AGENTS.md` лежит в корне проекта или в нужном подкаталоге?
2. **Имя файла**: должно быть `AGENTS.md` (заглавными, не `agents.md`)
3. **Проблемы формата**: корректен ли Markdown (пустая строка перед списком и т. п.)
4. **Конфликт правил**: нет ли противоречивых директив на разных уровнях `AGENTS.md`
5. **Слишком расплывчато**: попробуйте сформулировать конкретнее

---

## Как выбрать между CLAUDE.md и AGENTS.md

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

### Начните с того, сколько инструментов вы используете

- **Только Claude Code (один инструмент)**: достаточно `CLAUDE.md`. Claude Code читает `CLAUDE.md` нативно и накладывает глобальную память и правила по путям (вложенные `CLAUDE.md` / `.claude/rules`). Вести ещё и `AGENTS.md` не нужно.
- **Команда с несколькими инструментами (Claude Code + Codex / Cursor / Copilot / Cline / Gemini / Aider / Zed и т. д.)**: сделайте `AGENTS.md` **единственным источником истины**. Большинство инструментов, кроме Claude Code, читают `AGENTS.md`, а Claude Code по умолчанию читает только `CLAUDE.md`.

### Рекомендация для мультиинструментальных команд: тонкий CLAUDE.md, импортирующий AGENTS.md

Не держите две полные копии, которые разойдутся. Общие стандарты храните в `AGENTS.md`, а подтягивайте их **тонким `CLAUDE.md`** — так Claude Code получит и командные правила, и свои специфичные дополнения:

```markdown
# CLAUDE.md

@AGENTS.md

## Дополнения только для Claude Code
- Переключаться между Sonnet 4.6 / Opus 4.8 через `/model` по типу задачи
- Перед крупными изменениями запускать `/plan`
- Между несвязанными задачами использовать `/clear`, в длинных сессиях — `/compact` на логических рубежах
```

Так у общих стандартов остаётся единственный источник (`AGENTS.md`), а в `CLAUDE.md` живут только директивы для Claude Code — расходящихся дубликатов в корне не возникает.

### Таблица быстрого решения

| Ситуация | Что вести | Примечание |
|----------|------------------|-------|
| Только Claude Code | Только `CLAUDE.md` | Читается нативно, `AGENTS.md` не нужен |
| Только Codex и другие инструменты | Только `AGENTS.md` | Эти инструменты не читают `CLAUDE.md` |
| Команда с несколькими инструментами | `AGENTS.md` (источник истины) + тонкий `CLAUDE.md` (`@AGENTS.md`) | Один источник, без расхождений |

> Об уровнях, шаблонах и управлении контекстом в `CLAUDE.md` см. [Конфигурацию CLAUDE.md](/docs/usage/claude-md).

---

## Следующие шаги

- [Быстрый старт Codex](/docs/getting-started/codex-quick-start) -- установка и настройка Codex
- [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code) -- полное сравнение двух инструментов
- [Система Hooks](/docs/advanced/hooks) -- событийные хуки Claude Code (похожая идея)
- [Приёмы работы в CLI](/docs/usage/cli-tips) -- практические приёмы для продуктивной AI-разработки