Каждая сессия агента начинается с чистого контекста: он не помнит вчерашних договорённостей. Всё, что вы иначе объясняли бы заново, записывается в файл правил проекта: CLAUDE.md для Claude Code и AGENTS.md для Codex и других инструментов. Хороший файл короткий, состоит из проверяемых фактов и не содержит секретов. Важная оговорка: документация Claude Code называет такие файлы контекстом, а не принудительной настройкой, поэтому запреты, которые обязаны выполняться, настраиваются разрешениями (урок 6).
После урока вы сможете
- Написать короткий файл правил проекта с командами сборки, тестов и запретами
- Подключить один набор правил к Claude Code и Codex без дублирования
- Проверить, что агент действительно загрузил файл
Содержание
Какие файлы читает каждый инструмент
Claude Code
- Файлы
./CLAUDE.mdили./.claude/CLAUDE.md- Примечание
- Правила проекта, коммитятся в git
Claude Code
- Файлы
~/.claude/CLAUDE.md- Примечание
- Личные правила для всех проектов
Claude Code
- Файлы
./CLAUDE.local.md- Примечание
- Личное для проекта, добавьте в
.gitignore
Claude Code
- Файлы
.claude/rules/*.md- Примечание
- Правила по темам; с полем
pathsзагружаются только для подходящих файлов
Codex
- Файлы
~/.codex/AGENTS.md- Примечание
- Глобальные правила (или
AGENTS.override.md)
Codex
- Файлы
AGENTS.mdв корне и в подпапках- Примечание
- От корня проекта вниз до текущей папки
Codex собирает файлы от корня к текущей папке и склеивает их: более близкие к рабочей папке читаются позже и уточняют общие. Суммарный размер по умолчанию ограничен 32 КиБ (project_doc_max_bytes). На каждую папку берётся не больше одного файла: сначала AGENTS.override.md, затем AGENTS.md.
Claude Code читает AGENTS.md напрямую, начиная с версии 2.1.277, но только если в рабочей папке и выше нет CLAUDE.md или CLAUDE.local.md. Если есть оба файла, Claude берёт только CLAUDE.md. Поэтому надёжная схема для проекта с двумя инструментами: общие правила лежат в AGENTS.md, а короткий CLAUDE.md подключает их строкой @AGENTS.md и добавляет то, что относится только к Claude Code. Строка с @путь импортирует файл; в обратных кавычках она остаётся простым текстом.
Что писать, а что нет
Критерий из документации Claude Code: для каждой строки спросите себя, ошибётся ли агент без неё. Если нет — вычеркните.
Команды сборки, тестов и линтера, которые нельзя угадать
- Не писать
- То, что агент поймёт, прочитав код
Правила кода, отличающиеся от общепринятых
- Не писать
- Общие советы вроде «пиши чистый код»
Структура проекта и решения, которых нет в коде
- Не писать
- Описание каждого файла
Запреты и порядок работы (git push, миграции, деплой)
- Не писать
- Длинные инструкции и учебники
Критерии готовности задачи
- Не писать
- Подробную документацию API: дайте ссылку
Особенности окружения, обязательные переменные (только имена)
- Не писать
- Данные, которые часто меняются
Правила должны быть проверяемыми. Не «аккуратно форматируй код», а «отступ два пробела»; не «тестируй изменения», а «перед коммитом запусти npm test».
Пример файла
Файл для небольшого учебного проекта на Node.js. Адаптируйте команды и пути под свой проект.
# Проект
- Сервис записи на приём: Node.js 22, TypeScript, PostgreSQL.
- Код в `src/`, тесты в `tests/`, миграции в `db/migrations/`.
# Команды
- Установка зависимостей: `npm ci`
- Проверка типов: `npm run typecheck`
- Линтер: `npm run lint`
- Все тесты: `npm test`
- Один файл тестов: `npm test -- tests/booking.test.ts`
# Правила
- TypeScript в строгом режиме, без `any` в новом коде.
- Внешний ввод проверяется схемой на границе (`src/schemas/`).
- Доступ к базе только через `src/db/`.
- Сложную правку (больше одного файла) сначала опиши планом и дождись ответа.
- Не добавляй зависимости без согласования.
# Запреты
- Не читай и не выводи `.env`, ключи и токены. Нужна новая переменная — назови её в отчёте, значение вносит человек.
- Применённые миграции не редактируй: создай новую.
- Не запускай `git push`, деплой и команды против боевой базы.
# Готово, когда
- Типы, линтер и тесты проходят, вывод показан.
- Новое поведение покрыто тестом.В файле 22 непустые строки. Парный файл для Claude Code выглядит так:
@AGENTS.md
# Claude Code
- Для правок в `src/payments/` сначала включай режим плана.В Markdown-файле правил можно оставлять блочные HTML-комментарии <!-- заметка -->: Claude Code вырезает их перед загрузкой в контекст, так что заметки для людей не тратят токены.
Как держать файл коротким и живым
Документация Claude Code советует укладываться меньше чем в 200 строк на файл: длинные файлы расходуют контекст, и важные правила в них теряются. Если правило касается одной части кода, вынесите его в .claude/rules/ с полем paths или во вложенный AGENTS.md в этой папке. Импорты через @ помогают организовать файл, но размер контекста не уменьшают: подключённые файлы загружаются вместе с основным.
Дописывайте строку, когда агент второй раз повторил одну и ту же ошибку или ревью нашло то, что он должен был знать. Периодически чистите: противоречащие правила агент выполняет выборочно. В Claude Code команда /doctor prompt-audit проверяет файлы на устаревшее и противоречивое, а /init создаёт начальный черновик; в Codex /init создаёт заготовку AGENTS.md. Черновик не принимайте вслепую: прочитайте и сократите.
Проверьте, что файл подхватился. В Claude Code команда /context показывает загруженные файлы памяти. В Codex документация предлагает запустить codex --ask-for-approval never "Summarize the current instructions.": агент должен процитировать правила из ваших файлов.
Что дальше
Следующий урок — цикл «план → правки → проверка»: как формулировать задачи, чтобы правила из файла работали. Глубже про границы модулей и миграции — в уроке библиотеки Архитектурные границы и миграции в AI-проекте. Если нужна помощь с настройкой процесса в команде, посмотрите техническое наставничество.