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

Конфигурационный файл проекта для Codex — определяет правила поведения AI-ассистента, аналог CLAUDE.md для Claude Code

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

AGENTS.md для Codex — то же, что CLAUDE.md для Claude Code: файл, который сообщает AI правила вашего проекта.

AGENTS.md vs CLAUDE.md¶

Оба файла могут сосуществовать в одном проекте.

Базовая структура¶

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

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

## Стандарты кода

- TypeScript, запрещён тип any
- Имена функций в camelCase
- Обработка ошибок через try-catch

## Тестирование

- Jest для тестов
- Покрытие минимум 80%
- Запуск: `npm test`

## Структура

- src/ — исходный код
- tests/ — тесты
- docs/ — документация

3 уровня конфигурации¶

Уровень 1: Глобальный (~/.codex/AGENTS.md)¶

# Глобальные правила

- Комментарии на русском языке
- Коммиты на английском
- Никаких захардкоженных секретов

Уровень 2: Репозиторий (~/project/AGENTS.md)¶

# Проект: My App
## Стек: Next.js 15 + TypeScript + Tailwind CSS + PostgreSQL
## Правила: функциональные компоненты, Server Components по умолчанию

Уровень 3: Директория (~/project/src/api/AGENTS.md)¶

# Правила API

- Валидация входных данных через Zod
- Ответы об ошибках в формате RFC 7807

Приоритет: Директория > Репозиторий > Глобальный

Шаблоны¶

React фронтенд¶

# Frontend Rules

- React 19 + TypeScript 5.x + Vite + Tailwind CSS v4
- Только функциональные компоненты
- Props через interface (не type)
- Состояние: useState/useReducer (локальное), TanStack Query (серверное)
- Тесты: Vitest + Testing Library

Python бэкенд¶

# Backend Rules

- Python 3.12 + FastAPI + SQLAlchemy 2.0
- Обязательные type hints
- async/await предпочтительнее
- Тесты: pytest + httpx

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

80% содержимого CLAUDE.md можно скопировать напрямую:

Лучшие практики¶

1. Конкретность: Не «пиши чистый код», а «следуй правилам ESLint»
2. Примеры: Показывайте хорошие и плохие образцы
3. Актуальность: Обновляйте при изменении стека
4. Версионирование: Добавляйте в Git (не в .gitignore)
5. Краткость: До 500 строк (длинные файлы расходуют контекст)

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

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

Сначала посчитайте, сколько инструментов вы используете¶

• Только Claude Code (один инструмент): достаточно CLAUDE.md. Claude Code читает CLAUDE.md нативно и поверх него накладывает глобальную memory и правила по путям (вложенные 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 получал и общие командные правила, и свои специфичные дополнения:

# CLAUDE.md

@AGENTS.md

## Дополнения только для Claude Code

- Используйте `/model` для переключения между Sonnet 4.6 / Opus 4.8 по задаче
- Запускайте `/plan` перед крупными изменениями
- Используйте `/clear` между несвязанными задачами; `/compact` на логических точках в длинных сессиях

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

Таблица быстрого выбора¶

О слоях, шаблонах и контроле контекста CLAUDE.md см. Руководство по CLAUDE.md.

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

• Руководство по CLAUDE.md
• Полный учебник Codex
• Codex vs Claude Code