Какой длины должен быть файл CLAUDE.md?

Anthropic рекомендует стремиться к менее чем 200 строкам на файл. Файл загружается в контекст в начале каждой сессии, поэтому длинные файлы тратят больше токенов, а на практике агент выполняет их менее надёжно.

Чем CLAUDE.md отличается от AGENTS.md?

Они выполняют одну задачу. CLAUDE.md — файл, который читает Claude Code; AGENTS.md — открытый формат, который читают Codex, Gemini CLI (при настройке), Cursor, Copilot, opencode, Aider, goose и многие другие. Свежие версии Claude Code тоже читают AGENTS.md, когда нет CLAUDE.md.

Можно ли использовать один файл инструкций для Claude Code, Codex и Gemini CLI?

Да. Держите общие правила в AGENTS.md, положите рядом CLAUDE.md со строкой @AGENTS.md (и заметками только для Claude), а в настройках Gemini CLI добавьте AGENTS.md в context.fileName.

Нужно ли коммитить CLAUDE.md в git?

Проектный CLAUDE.md — да: это общее знание команды. Личные предпочтения кладите в ~/.claude/CLAUDE.md или в CLAUDE.local.md, который добавьте в .gitignore.

Гарантирует ли CLAUDE.md, что агент выполнит правило?

Нет. Это контекст, а не принуждение. Агент обычно выполняет чёткие и конкретные правила, но если действие не должно происходить никогда, заблокируйте его hook или настройкой разрешений, а не фразой в CLAUDE.md.

CLAUDE.md: лучшие практики (и AGENTS.md, GEMINI.md)

Лучший CLAUDE.md короткий (заметно меньше 200 строк), конкретный и проверяемый: команды для сборки и тестов, соглашения, которые агент не угадает по коду, и ошибки, которые он уже один раз допустил. Всё остальное, например обзор дерева папок, длинные процедуры или общие советы вроде «пиши чистый код», либо принадлежит другому месту, либо не нужно вовсе.

В руководстве разбираем, что такое CLAUDE.md, AGENTS.md и GEMINI.md, где их ищет каждый агент, что писать и что не писать, как работают импорты и как вести один файл, который читают все агенты проекта.

Что это за файлы

Кодинг-агенты начинают каждую сессию, ничего не помня о вашем проекте. Файл инструкций — это записка для них: обычный Markdown-файл, который CLI читает при запуске и добавляет в контекстное окно модели до вашего первого сообщения.

Файл	Кто читает	Примечания
`CLAUDE.md`	Claude Code	Поддерживает импорты `@path` и правила по путям
`AGENTS.md`	Codex, Cursor, Copilot, opencode, Aider, goose, Amp, Gemini CLI (при настройке) и другие	Открытый формат, его часто называют «README для агентов»
`GEMINI.md`	Gemini CLI	Поддерживает импорты `@file.md`; имя файла настраивается

AGENTS.md возник в сотрудничестве OpenAI Codex, Amp, Google Jules, Cursor и Factory, и теперь им занимается Agentic AI Foundation при Linux Foundation. Это самое близкое к общему стандарту. Claude Code сохранил собственное имя, но свежие версии (v2.1.277 и новее) читают AGENTS.md напрямую, когда в рабочей директории и выше нет ни CLAUDE.md, ни CLAUDE.local.md.

Где лежат файлы

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

Claude Code

Область	Расположение	Общий?
Политика администратора	`/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows)	Задаётся администратором для всех
Пользователь	`~/.claude/CLAUDE.md`	Только вы, во всех проектах
Проект	`./CLAUDE.md` или `./.claude/CLAUDE.md`	В коммите, вся команда
Локальный	`./CLAUDE.local.md`	Только вы; добавьте в `.gitignore`
Вложенный	`src/payments/CLAUDE.md` и так далее	Загружается, когда Claude читает или правит там файлы

Файлы в рабочей директории и выше загружаются при запуске и объединяются, а не переопределяют друг друга. Вложенные файлы в поддиректориях загружаются по требованию, когда Claude впервые обращается к файлам в этой папке. Выполните /context, чтобы увидеть, какие файлы памяти действительно загружены, и /memory, чтобы открыть один из них для правки.

Codex

Codex читает глобальный ~/.codex/AGENTS.md (или AGENTS.override.md), затем идёт от корня git вниз до текущей директории и берёт по одному файлу из каждой папки: AGENTS.override.md, если он есть, иначе AGENTS.md. Более глубокие файлы идут в объединённом тексте позже, поэтому при конфликте двух правил побеждают они. Общий размер ограничен project_doc_max_bytes, по умолчанию 32 KiB, а цепочка строится один раз за сессию. Подробнее о самом CLI на странице Codex.

Gemini CLI

Gemini CLI загружает ~/.gemini/GEMINI.md, затем файлы в директориях вашей рабочей области и их родительских, и подхватывает ещё файлы, когда его инструменты заходят в другие папки. Всё объединяется и отправляется с каждым запросом. /memory show выводит объединённый текст, а /memory reload перечитывает его после правки.

Что включать

Пишите для толкового нового коллеги, который не видел репозиторий и не станет задавать вопросов. Каждая строка должна быть тем, на что агент может действовать, а вы можете проверить.

Команды. Как установить, собрать, запустить один тест, запустить все тесты, проверить линтером и типами. Это самый полезный раздел; без него агент гадает.
Соглашения, которых не видно в коде. «Используй pnpm, а не npm». «Новые маршруты API проходят через withAuth()». «Даты хранятся в UTC».
Границы. «Никогда не правь файлы в generated/». «Не трогай папку миграций, не спросив».
Как завершать задачу. «Запусти pnpm test и pnpm typecheck, прежде чем говорить, что закончил». «Сообщения коммитов следуют Conventional Commits».
Известные ловушки. Ошибка, которую агент совершил дважды на прошлой неделе, оформленная как правило.

Хорошее правило конкретно. «Используй отступ в 2 пробела» работает; «форматируй код как следует» не работает. «Запускай npm test перед коммитом» работает; «убедись, что всё работает» не работает.

Компактный пример

# Project notes

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 5173)
- One test: `pnpm vitest run path/to/file.test.ts`
- Before finishing: `pnpm lint && pnpm typecheck && pnpm test`

## Conventions
- TypeScript strict; no `any` in new code.
- Server code lives in `src/server`, UI in `src/ui`; never import server code from UI.
- Database access only through `src/server/db.ts`.

## Don’t
- Don’t edit `src/generated/` (run `pnpm codegen` instead).
- Don’t add dependencies without saying why in the summary.

## Learned the hard way
- The payments tests need `STRIPE_KEY=test`; they fail silently without it.

Это около 20 строк, и они покрывают большую часть того, что агенту нужно в первый день.

Что не включать

Что не включать	Почему	Куда это деть
Обзор репозитория файл за файлом	Агент сам может вывести список папок, а обзор устаревает	Никуда или инструмент карты кода
Длинные пошаговые процедуры (релиз, миграции)	Загружаются на каждом ходу, даже когда не нужны	Skill или документ, на который ссылается файл
Правила только для одной папки	Занимают контекст везде	Вложенный CLAUDE.md / AGENTS.md или `.claude/rules/` с `paths:`
Общие советы («пиши чистый код»)	Не влияют на поведение	Удалить
Секреты, токены, внутренние URL	Файл попадает в коммит и отправляется модели	Переменные окружения
То, чего не должно случаться никогда	Инструкции — это контекст, а не принуждение	Hook или правило разрешений

Пишите коротко

Каждая строка CLAUDE.md отправляется в начале каждой сессии и остаётся в контексте на весь диалог. В документации Anthropic советуют держаться меньше 200 строк на файл и отмечают, что более длинные файлы снижают надёжность выполнения. Закономерность знакома: чем больше правил, тем сильнее размывается каждое.

Помогают несколько привычек:

Добавляйте правило, только когда оно нужно. Агент дважды ошибся одинаково, ревью что-то поймало или вы снова и снова вводите одну и ту же поправку. Это и есть сигнал.
Прореживайте при добавлении. Если правило не имело значения месяц, уберите его.
Указатели лучше вставок. «Процесс релиза описан в docs/release.md» стоит одну строку; вставка самого процесса стоит пятьдесят.
Для заметок людям используйте HTML-комментарии. Claude Code вырезает блочные комментарии  перед отправкой файла.

Если вас волнует расход токенов, в руководстве по расходу токенов Claude Code разобрано, что ещё заполняет контекст.

Импорты и правила по путям

Claude Code позволяет CLAUDE.md подтягивать другие файлы через @path:

See @README.md for the overview.
Coding rules: @docs/conventions.md
@~/.claude/my-preferences.md

Пути отсчитываются от файла с импортом, импорты могут вкладываться до четырёх уровней, а @ внутри фрагментов кода и блоков кода игнорируется. Когда проект впервые импортирует файлы вне репозитория, Claude Code просит вас их одобрить.

Один подвох: импорты упорядочивают текст, но не экономят токены. Импортированный файл загружается целиком при запуске, как и родительский. Для правил, важных только в части дерева, используйте .claude/rules/*.md с glob-шаблоном paths: во frontmatter, чтобы они загружались, только когда Claude работает с подходящими файлами:

---
paths: ["src/api/**/*.ts"]
---
- Every handler validates input with zod before touching the database.

Gemini CLI поддерживает тот же синтаксис импорта @file.md в GEMINI.md.

Один файл для всех агентов

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

Положите общие правила в AGENTS.md. Codex, Cursor, Copilot, opencode и большинство остальных читают его напрямую.
Создайте CLAUDE.md, который импортирует его и добавляет всё, что относится только к Claude:
```
@AGENTS.md

## Claude Code only
- Use the project's /review skill before opening a PR.
```
В Gemini CLI добавьте AGENTS.md в список искомых имён файлов в .gemini/settings.json:
```
{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }
```

Символическая ссылка (ln -s AGENTS.md CLAUDE.md) тоже работает на macOS и Linux, но подход с импортом понятнее и не зависит от того, как Windows обращается со ссылками. В Claude Code есть и настройка «Project instructions» в /config, если хотите, чтобы он читал и CLAUDE.md, и AGENTS.md вместе.

Первая версия

Начинать с пустого листа не обязательно. В Claude Code /init читает репозиторий и составляет черновик CLAUDE.md. Относитесь к нему как к сырью: оставьте команды, удалите обзор папок и уберите всё, что не сказали бы новому коллеге в его первое утро.

Затем пусть файл растёт из реальной работы. Каждый раз, поправляя агента, спрашивайте себя, применима ли поправка и на следующей неделе. Если да, это кандидат в правила.

Как это делается в AgentVera

AgentVera запускает Claude Code, Codex, Gemini CLI и другие CLI рядом в настоящих терминалах. Каждый агент по-прежнему читает свой CLAUDE.md, AGENTS.md или GEMINI.md ровно так, как описано выше; AgentVera эти файлы не заменяет. Рядом с ними работают несколько функций:

Предложения правил из ваших поправок. Когда вы возвращаете работу агента из инбокса ревью с комментарием или Verify находит невыполненный критерий, небольшая модель Claude превращает поправку в одно короткое правило. Оно появляется в разделе Rule suggestions; Add to instructions дописывает его в CLAUDE.md и AGENTS.md проекта (в те, что существуют), а правила, которые в файлах уже есть, пропускаются. Если нет ни одного из файлов, создаются AGENTS.md и CLAUDE.md, который импортирует его через @AGENTS.md.
Роли отдельных агентов вместо раздутого общего файла. Поле «Role and instructions» в диалоге агента передаётся только этому агенту (Claude получает его в дополнение к системному промпту, Codex как инструкции разработчика). Роли конкретных агентов остаются вне общего файла. Cursor, Gemini CLI и Amp это поле не используют и опираются на AGENTS.md проекта или файлы правил.
Карта кода, чтобы не писать обзор папок. Карта проекта строится локально и предлагается агентам как MCP-инструменты (map_related, map_outline, map_usages и другие), а новые агенты получают краткую сводку модулей, точек входа и команды тестов. Именно это люди обычно вставляют в CLAUDE.md вручную.
Память проекта. AgentVera Brain читает отслеживаемые Git документы, включая CLAUDE.md и AGENTS.md, а также коммиты, PR и прошлые диалоги и отслеживает, какие решения актуальны, а какие устарели. Необязательный пакет контекста (по умолчанию выключен) можно добавить в инструкции новых агентов.
Процедуры как skills. Галерея skills управляет папками SKILL.md для Claude Code и Codex, и именно там место длинным процедурам.
Правила, которые должны выполняться всегда. CLAUDE.md — это совет; для проверок, которые должны происходить каждый раз, используйте hooks Claude Code, а узкие побочные задачи передавайте субагентам.

Чек-лист

Меньше 200 строк; в идеале меньше 100.
Команды сборки, тестов, линтера и проверки типов указаны и верны.
Каждое правило достаточно конкретно, чтобы его проверить.
Нет обзора папок, секретов и общих советов.
Правила для отдельных папок лежат во вложенных файлах или правилах по путям.
Длинные процедуры вынесены в skills или документы, на которые ведёт одна строка.
Жёсткие ограничения обеспечены hooks или разрешениями, а не текстом.
Общие правила лежат в AGENTS.md; CLAUDE.md его импортирует.
Личные предпочтения лежат в ~/.claude/CLAUDE.md или CLAUDE.local.md.

Итоги

Файл инструкций — самый дешёвый способ заставить агента вести себя так, будто он уже работал над вашим проектом. Держите его коротким и конкретным и давайте ему расти только из ошибок, которые вы действительно видели. Общие правила кладите в AGENTS.md, чтобы каждый CLI читал одно и то же, процедуры выносите в skills, а действительно важное обеспечивайте hooks, а не фразами.