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

URL: https://agentvera.dev/ru/blog/claude-md-agents-md/ · Опубликовано: 2026-10-22

Лучшие практики CLAUDE.md: где лежит файл, что включать и что нет, импорты, краткость и один AGENTS.md на всех: Claude, Codex и Gemini.

**Коротко:**

- CLAUDE.md работает лучше всего, когда он короче 200 строк и содержит команды сборки и тестов, соглашения, которых не видно в коде, и ошибки, которые агент уже допускал.
- Обзор папок, длинные процедуры, секреты и общие советы туда не нужны; правила, которые нельзя нарушать, обеспечивайте через hooks или разрешения, а не текстом.
- Чтобы делить правила между CLI, держите их в AGENTS.md, импортируйте его в CLAUDE.md через @AGENTS.md и добавьте AGENTS.md в context.fileName в настройках Gemini CLI.

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

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

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

Кодинг-агенты начинают каждую сессию, ничего не помня о вашем проекте. Файл инструкций — это записка для них: обычный Markdown-файл, который CLI читает при запуске и добавляет в [контекстное окно](/ru/glossary/context-window/ "Контекстное окно") модели до вашего первого сообщения.

| Файл | Кто читает | Примечания |
| --- | --- | --- |
| `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](/ru/agents/codex/ "Codex CLI").

### 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` перед коммитом» работает; «убедись, что всё работает» не работает.

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

```markdown
# 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](/ru/glossary/agent-skills/ "Skills агентов") или документ, на который ссылается файл |
| Правила только для одной папки | Занимают контекст везде | Вложенный CLAUDE.md / AGENTS.md или `.claude/rules/` с `paths:` |
| Общие советы («пиши чистый код») | Не влияют на поведение | Удалить |
| Секреты, токены, внутренние URL | Файл попадает в коммит и отправляется модели | Переменные окружения |
| То, чего не должно случаться никогда | Инструкции — это контекст, а не принуждение | [Hook](/ru/glossary/claude-code-hooks/ "Hooks Claude Code") или правило разрешений |

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

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

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

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

Если вас волнует расход токенов, в [руководстве по расходу токенов Claude Code](/ru/blog/claude-code-token-usage/ "Расход токенов Claude Code") разобрано, что ещё заполняет контекст.

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

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

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

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

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

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

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

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

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

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

   ```markdown
   @AGENTS.md

   ## Claude Code only
   - Use the project's /review skill before opening a PR.
   ```

3. В **Gemini CLI** добавьте AGENTS.md в список искомых имён файлов в `.gemini/settings.json`:

   ```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](/ru/download/ "Скачать AgentVera") запускает Claude Code, Codex, Gemini CLI и другие CLI рядом в настоящих терминалах. Каждый агент по-прежнему читает свой CLAUDE.md, AGENTS.md или GEMINI.md ровно так, как описано выше; AgentVera эти файлы не заменяет. Рядом с ними работают несколько функций:

- **Предложения правил из ваших поправок.** Когда вы возвращаете работу агента из [инбокса ревью](/ru/features/review-inbox/ "Инбокс ревью") с комментарием или 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 проекта или файлы правил.
- **Карта кода, чтобы не писать обзор папок.** [Карта проекта](/ru/features/project-map/ "Карта проекта") строится локально и предлагается агентам как MCP-инструменты (`map_related`, `map_outline`, `map_usages` и другие), а новые агенты получают краткую сводку модулей, точек входа и команды тестов. Именно это люди обычно вставляют в CLAUDE.md вручную.
- **Память проекта.** [AgentVera Brain](/ru/features/brain/ "AgentVera Brain") читает отслеживаемые Git документы, включая CLAUDE.md и AGENTS.md, а также коммиты, PR и прошлые диалоги и отслеживает, какие решения актуальны, а какие устарели. Необязательный пакет контекста (по умолчанию выключен) можно добавить в инструкции новых агентов.
- **Процедуры как skills.** [Галерея skills](/ru/features/skill-gallery/ "Галерея skills") управляет папками SKILL.md для Claude Code и Codex, и именно там место длинным процедурам.
- **Правила, которые должны выполняться всегда.** CLAUDE.md — это совет; для проверок, которые должны происходить каждый раз, используйте [hooks Claude Code](/ru/blog/claude-code-hooks-guide/ "Руководство по hooks Claude Code"), а узкие побочные задачи передавайте [субагентам](/ru/blog/claude-code-subagents/ "Субагенты Claude Code").

## Чек-лист

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

## Итоги

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

## Частые вопросы

**Какой длины должен быть файл 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.

---

**Об AgentVera.** AgentVera — настольное приложение для macOS, Windows и Linux от Solviera Teknoloji. Оно запускает 18 ИИ-агентов для программирования (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) рядом, по проектам, в настоящих терминалах с собственными установками CLI и входами пользователя. В бесплатном тарифе количество агентов не ограничено. Скачать: https://agentvera.dev/ru/download/ · Цены: https://agentvera.dev/ru/pricing/