# CLAUDE.md: как написать файл инструкций для Claude Code + шаблон

> Что такое CLAUDE.md, где лежит, как грузится и что писать: иерархия, импорты @, рекомендация 200 строк, .claude/rules, hooks и готовый шаблон.
> Author: Roman Belov · Published: 2026-09-30 · Source: https://futurecraft.pro/ru/blog/claude-md-guide/

CLAUDE.md - markdown-файл с постоянными инструкциями, который Claude Code загружает в контекст в начале каждой сессии. Документация прямо называет его статус: Claude воспринимает такие файлы «as context, not enforced configuration». Модель читает файл и обычно ему следует, но гарантии нет. Если действие нужно заблокировать при любом решении модели, нужен hook.

Из этой разницы вырастают многие проблемы с CLAUDE.md. Файл растёт, в нём множатся CRITICAL и ВАЖНО, а модель всё равно пропускает правила. [Официальное руководство](https://code.claude.com/docs/en/memory) рекомендует держать каждый CLAUDE.md короче 200 строк. Исследователи из ETH Zurich и LogicStar.ai пришли к похожему выводу с другой стороны: контекст-файлы в среднем удорожают работу агента больше чем на 20% и в целом не повышают долю решённых задач.

Статья о том, как устроен CLAUDE.md в текущих версиях Claude Code: где лежат файлы, в каком порядке грузятся, как работают импорты и `.claude/rules/`, что писать в файл и что выносить в hooks и skills. В конце есть шаблон и чек-лист аудита. Общий для разных агентов формат AGENTS.md разобран отдельно в [гайде по AGENTS.md](https://futurecraft.pro/ru/blog/agents-md-guide/). Примеры взяты из реальных файлов рабочего пространства автора (около 15 проектов) и обезличены, поведение AGENTS.md проверено на Claude Code 2.1.318.

## Что такое CLAUDE.md и чем он отличается от auto memory

### Контекст, а не конфигурация

У Claude Code два механизма, которые переносят знания между сессиями. CLAUDE.md пишет человек. Auto memory ведёт сам Claude по вашим поправкам. Оба грузятся в начале каждой сессии.

| | CLAUDE.md | Auto memory |
|---|---|---|
| Кто пишет | Вы | Claude |
| Что внутри | Инструкции и правила | Выводы и паттерны из поправок |
| Область | Проект, пользователь, организация | Репозиторий, общая для worktrees |
| Что грузится | Весь файл и его импорты | Первые 200 строк или 25 КБ |
| Для чего | Команды, соглашения, ограничения | Ваши предпочтения и поправки |

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

Страница [best practices](https://code.claude.com/docs/en/best-practices) делит инструкции на два вида. Недетерминированные (промпт, CLAUDE.md, skills) читает модель и сама решает, применять ли их. Детерминированные (hooks, deny-правила, managed settings) исполняет Claude Code, и решение модели на них не влияет. CLAUDE.md всегда остаётся в первой группе.

## Где лежит CLAUDE.md и как грузится

### Четыре уровня

| Уровень | Путь | Кто видит |
|---|---|---|
| Managed policy | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`; Linux и WSL: `/etc/claude-code/CLAUDE.md`; Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | Все пользователи машины |
| User | `~/.claude/CLAUDE.md` | Только вы, во всех проектах |
| Project | `./CLAUDE.md` или `./.claude/CLAUDE.md` | Команда, через git |
| Local | `./CLAUDE.local.md` (добавить в `.gitignore`) | Только вы, в этом проекте |

Таблица идёт в порядке загрузки, от широкого уровня к узкому: проектная инструкция окажется в контексте после пользовательской. Managed-файл раскатывают через MDM, Group Policy или Ansible. Вместо отдельного файла его текст можно положить в ключ `claudeMd` в `managed-settings.json`. Документация советует держать в управляемом CLAUDE.md поведенческие правила, а запреты на инструменты и пути оформлять через `permissions.deny` в managed settings.

### Родительские и вложенные папки

Claude Code читает `CLAUDE.md` и `CLAUDE.local.md` из рабочей директории и из каждой директории выше. Если запустить его в `foo/bar/`, загрузятся `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` и лежащие рядом с ними `CLAUDE.local.md`.

Три детали, которые часто путают:

1. **Файлы склеиваются.** Ни один не переопределяет другой. Порядок идёт от корня файловой системы к рабочей директории, поэтому инструкции ближе к месту запуска модель читает последними. Внутри одной директории `CLAUDE.local.md` стоит после `CLAUDE.md`. Если два файла противоречат друг другу, Claude, по документации, может выбрать любой вариант.
2. **Подпапки грузятся по требованию.** `CLAUDE.md` в подпапке ниже рабочей директории при старте не грузится. Claude Code подтягивает его, когда Claude читает, пишет или правит файл в этой подпапке, включая чтение через `cat` или `head` в Bash.
3. **У файлов, которые грузятся по требованию, есть лимит на символы.** При контекстном окне 200K это 40 000 символов на файл. Если вложенный CLAUDE.md или path-scoped правило длиннее, Claude получает только начало и пометку дочитать остальное через Read. Размер проверяется командой `wc -m`, лимит действует с v2.1.309.

Для заметок мейнтейнерам есть бесплатный способ: блочные HTML-комментарии `<!-- ... -->` вырезаются перед отправкой в контекст и токенов не тратят. Комментарии внутри блоков кода сохраняются.

### Монорепо: `claudeMdExcludes` и `--add-dir`

В большом монорепо подгружаются чужие CLAUDE.md из родительских папок. Отключить их можно настройкой `claudeMdExcludes`, glob-шаблоны в ней сравниваются с абсолютными путями:

```json
{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}
```

Документация советует класть эту настройку в `.claude/settings.local.json`, чтобы исключение осталось на вашей машине. Работает она на любом уровне settings, массивы из разных уровней объединяются. Managed CLAUDE.md исключить нельзя.

С `--add-dir` ситуация обратная: CLAUDE.md из дополнительных директорий по умолчанию не грузятся. Включает их переменная окружения:

```bash
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config
```

Подробнее о раскладке файлов в больших репозиториях написано на странице [Monorepos and large repos](https://code.claude.com/docs/en/large-codebases).

## Импорты `@path` в CLAUDE.md

### Синтаксис и ограничения

Строка `@path/to/file` в любом месте CLAUDE.md подставляет содержимое файла в контекст:

```markdown
См. @README для обзора и @package.json для npm-команд.

# Дополнительно
- git workflow @docs/git-instructions.md
```

Правила разбора:

- относительный путь считается от файла, в котором стоит импорт, а не от рабочей директории;
- импортированные файлы могут импортировать другие, глубина ограничена четырьмя прыжками;
- внутри code span и блоков кода импорт не срабатывает, поэтому путь, который нужно упомянуть без загрузки, оборачивают в обратные кавычки (`` `@README` ``);
- пробел в пути экранируют обратным слэшем (`@Design\ Docs/api.md`), путь в кавычках не импортируется вообще;
- импорт из проектного файла, который ведёт за пределы рабочей директории, при первом появлении вызывает диалог одобрения. Если отказаться, импорты останутся выключенными. Файлы пользовательского уровня (`~/.claude/CLAUDE.md`, `~/.claude/rules/`) импортируют без диалога, исключение составляют сессии Cowork.

Главное ограничение: **импорт не экономит контекст.** Импортированный файл грузится вместе с родителем. Разбивка на файлы упрощает поддержку, но 300 строк в трёх импортах стоят столько же, сколько 300 строк в одном файле.

### Паттерн: тонкий глобальный файл

В рабочем пространстве автора глобальный `~/.claude/CLAUDE.md` состоит из одной строки:

```markdown
@shared-rules.md
```

Личные правила лежат в отдельном файле на 225 строк. Он версионируется сам по себе и импортируется во все проекты. Это импорт как способ организации: файл удобно редактировать и переносить между машинами. Контекст при этом платит за все 225 строк, и сам файл выходит за рекомендацию в 200.

Тот же приём пригодится для worktrees. Игнорируемый git'ом `CLAUDE.local.md` существует только в том worktree, где его создали. Чтобы личные инструкции были во всех копиях репозитория, документация предлагает импортировать файл из домашней директории: `@~/.claude/my-project-instructions.md`.

## Что писать в CLAUDE.md и чего не писать

### Что писать

Best practices оставляют в файле то, что Claude не выведет из кода сам:

- **как проверить работу**: точные команды тестов, typecheck, линтера и запуска одного тестового файла. По документации, команда проверки и есть самая полезная строка во всём файле;
- **места, где код вводит в заблуждение**: старый паттерн, который встречается везде, но который нельзя копировать, или директория, которая выглядит мёртвой, хотя используется;
- **решения, которых нет в репозитории**: какой error-хелпер выбрала команда, как устроен деплой, что требует ревью миграций;
- **то, что пришлось поправлять дважды.**

В разделе «When to add to CLAUDE.md» есть четыре сигнала, что запись пора добавить. Claude повторил ту же ошибку. Code review поймал то, что Claude должен был знать о кодовой базе. Вы вводите в чат ту же поправку, что и в прошлой сессии. Новому человеку в команде понадобился бы тот же контекст.

Формулировки должны быть проверяемыми. «Отступ 2 пробела» лучше, чем «форматируй код правильно». «Запускай `npm test` перед коммитом» лучше, чем «тестируй изменения». «Обработчики API лежат в `src/api/handlers/`» лучше, чем «держи файлы в порядке».

### Чего не писать

- **Архитектуру и раскладку файлов, которые видны из кода.** В таблице устаревших советов best practices этому отведена отдельная строка: Claude читает репозиторий сам.
- **Общие пожелания без критерия проверки.** «Никаких костылей» и «пиши эталонный код» модель не может проверить, а значит, не может и надёжно исполнить.
- **Многошаговые процедуры.** Релиз, runbook инцидента, порядок миграции данных оформляют как skill. Если Claude может запускать skill сам, в каждой сессии видны только его name и description, а полный текст грузится, когда задача его требует.
- **Правила для одной части кода.** Их место в `.claude/rules/` с полем `paths`.
- **Секреты.** Схему работы с ними (откуда берутся, каким скриптом синхронизируются) описать можно, значения нельзя.

У этого подхода есть эмпирическая опора. В работе [«Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?»](https://arxiv.org/abs/2602.11988) (Gloaguen и соавторы, ETH Zurich и LogicStar.ai, arXiv 2602.11988) агентов прогнали на задачах SWE-bench с контекст-файлами, которые сгенерировала LLM, и на новой выборке issues из репозиториев, где такие файлы написали сами разработчики. Выводы из аннотации: контекст-файлы в целом не повышают долю решённых задач и увеличивают стоимость инференса в среднем больше чем на 20%. Инструкции агенты выполняют хорошо, обзоры репозитория им не помогают, а пользу файлы приносят там, где описывают нестандартные практики. Работа посвящена AGENTS.md, но формат тот же, и вывод совпадает с рекомендацией docs: писать только неочевидное.

### Правило, причина, способ проверки

Самые устойчивые правила в файлах автора устроены одинаково: запрет, причина и ссылка на то, что проверит результат за человека. Пример (обезличенный):

```markdown
## Deploy
- Не деплоить функции голой CLI-командой: она сбрасывает флаг
  проверки JWT, после чего ломается регистрация.
  Деплой только через `scripts/deploy.sh`: он после выкладки сверяет флаги.
```

У такой записи три полезных свойства. Причина показывает модели границы правила, и та не растягивает его на случаи, где оно не нужно. Шаги не пересказаны: правило отсылает к скрипту как к источнику истины. И наконец, скрипт проверяет результат, даже если модель про правило забыла.

С git-правилами работает тот же подход. В одном из проектов запрет `git stash -u` сопровождается описанием реального инцидента: опубликованные материалы ушли в untracked-часть stash и пропали из рабочего дерева. Рядом описан установленный git hook, который блокирует удаление такого stash. Текст объясняет причину, hook следит за исполнением.

Ещё два паттерна, которые хорошо себя показали:

- **Пара списков «спрашивать перед изменением» и «можно менять свободно».** Так зона риска очерчена явно, и запрещать всё подряд не приходится.
- **Одно главное правило в самом начале файла.** В файлах автора первым стоит правило об атомарных коммитах: этот пункт должен быть виден раньше остальных.

## Размер CLAUDE.md и цена в контексте

### Рекомендация в 200 строк

Формулировка документации: «target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence». Это ориентир. Текст после 200-й строки никто не обрезает. На практике происходит следующее:

- если файл длиннее рекомендованного, Claude Code показывает предупреждение при старте и в `/status`;
- отдельное предупреждение появляется, когда файлы, каждый в пределах нормы, вместе превышают общий лимит на старте (каждый CLAUDE.md, файл правил и `@`-импорт считается отдельным файлом);
- файл больше 4 MiB Claude Code пропускает целиком;
- для файлов, которые грузятся по требованию, действует лимит в символах (40 000 при окне 200K), после которого модель видит только начало.

Цифры из рабочего пространства автора (`wc`, ноябрь 2026):

| Файл | Строк | Слов | Оценка |
|---|---|---|---|
| Небольшой проект (бот) | 43 | ~190 | Структура, стек, запуск, ссылка на ADR, этого достаточно |
| Блог | 116 | ~670 | Команды, архитектура, git-правила |
| Корневой файл рабочего пространства | 174 | ~1280 | Карта проектов, схема секретов, правила |
| Глобальные правила (через импорт) | 225 | ~1870 | Выше рекомендации |
| Продуктовый монорепо | 708 | ~3860 (41 КБ) | В 3,5 раза выше рекомендации |
| `~/.claude/CLAUDE.md` | 1 | - | Только `@shared-rules.md` |

Сколько токенов занимает самый большой файл, автор не измерял, поэтому оценки здесь нет. Для своего файла это число показывает `/context`.

### Как измерить: `/context` и `/memory`

`/context all` выводит раздел **Memory files**: какие CLAUDE.md, CLAUDE.local.md и AGENTS.md загружены при старте и сколько токенов занимает каждый. Если файла нет в списке, модель его не видит. В полноэкранном режиме `/context` без аргумента сворачивает этот список.

`/memory` перечисляет файлы памяти на уровне пользователя и проекта, открывает их в редакторе и включает или выключает auto memory.

Для чистки есть две встроенные проверки:

- `/doctor` предлагает сократить проектный CLAUDE.md. Он убирает то, что Claude выведет из кода (раскладку директорий, списки зависимостей, обзоры архитектуры), и оставляет подводные камни, обоснования и соглашения, которые отличаются от дефолтов;
- `/doctor prompt-audit` (с v2.1.283) ищет инструкции, написанные под старые модели, ссылки на несуществующие файлы и команды, противоречия между файлами. Он проверяет CLAUDE.md, CLAUDE.local.md, AGENTS.md, а также rules, skills, commands, subagents и output styles в `.claude/` и `~/.claude/`. Отчёт ничего не меняет, пока вы не попросите применить правки.

Почему компактный и релевантный контекст работает лучше большого, подробно разобрано в [гайде по context engineering](https://futurecraft.pro/ru/blog/context-engineering-guide/).

## `.claude/rules/` и path-scoped правила

Если правило нужно только в части кодовой базы, его выносят в `.claude/rules/`. Каждый `.md`-файл в этой папке отвечает за одну тему, поддиректории обходятся рекурсивно.

Правила без поля `paths` грузятся при старте с тем же приоритетом, что и `.claude/CLAUDE.md`. Правила с полем `paths` грузятся, когда Claude читает, пишет или правит подходящий файл:

```markdown
---
paths:
  - "src/api/**/*.ts"
---
- Тела запросов валидировать zod-схемами из src/api/schemas/
- Каждому новому endpoint нужна запись в openapi.yaml, иначе падает CI
```

Из frontmatter файла правил Claude Code читает только `paths`, остальные поля молча игнорируются. Если YAML не парсится, frontmatter отбрасывается, и правило грузится как безусловное. Ошибку разбора показывает `claude --debug`.

Есть ещё два механизма. Личные правила для всех проектов кладут в `~/.claude/rules/`, они грузятся раньше проектных. Общий набор правил можно подключить симлинком в `.claude/rules/`, но симлинк за пределы рабочей директории считается внешним импортом и требует одобрения.

Хорошие кандидаты на перенос в rules - разделы CLAUDE.md, которые начинаются словами «при работе с …»: при работе с миграциями, при правке мобильного клиента, при изменении edge-функций.

## CLAUDE.md, hook или skill: что куда

| Что нужно | Механизм | Почему |
|---|---|---|
| Факты для каждой сессии: команды, соглашения | `CLAUDE.md` | Грузится всегда |
| Правила для одной части кода | `.claude/rules/` с `paths` | Грузится только при работе с нужными файлами |
| Процедура из нескольких шагов | Skill | Полный текст грузится по необходимости |
| Правило без исключений | Hook, deny-правило, managed settings | Исполняет Claude Code, решение модели не участвует |
| Личные настройки в проекте | `CLAUDE.local.md` | Не попадает в git |
| Проверка перед завершением работы | `Stop` hook или CI | Возвращает Claude к работе, пока проверка не пройдёт или не сработает лимит блокировок |

Граница между CLAUDE.md и hook проходит по исключениям. Best practices разбирают три правила: «не читать .env», «запускать форматтер после правки», «не трогать папку migrations». Модель соблюдает их почти всегда. Если «почти» недостаточно, правило переносят в конфигурацию: форматтер в `PostToolUse` hook, запрет на migrations в `PreToolUse` hook, который завершается с кодом 2. А вот «Prefer named exports» остаётся в CLAUDE.md, потому что у такого правила много законных исключений.

Признак, что строку пора превращать в hook, документация описывает так: вы раз за разом усиливаете её эмфазой, а Claude всё равно её пропускает. Верно и обратное: hooks для того, что на деле просто предпочтение, лучше удалить и дать модели решать. События, коды выхода и примеры разобраны в [гайде по hooks Claude Code](https://futurecraft.pro/ru/blog/claude-code-hooks/), вынос исследования в отдельный контекст описан в [статье о субагентах](https://futurecraft.pro/ru/blog/claude-code-subagents/).

## Шаблон CLAUDE.md

Шаблон ниже собран по принципу «только неочевидное». Значения в нём - пример для TypeScript-проекта, их нужно заменить своими. HTML-комментарии в контекст не попадают, так что подсказки для людей можно оставить прямо в файле.

```markdown
# CLAUDE.md
<!-- Только то, что Claude не выведет из кода. Цель: меньше 200 строк. -->

## Commands
- Install: `pnpm install --frozen-lockfile`
- Один тест: `pnpm vitest run path/to/file.test.ts`
- Typecheck: `pnpm tsc --noEmit`
- Полная проверка перед PR: `pnpm lint && pnpm test && pnpm build`

## Constraints
- Не править сгенерированный клиент в `src/gen/`: его перезаписывает `pnpm codegen`.
- Изменение схемы БД делать только новой миграцией в `db/migrations/`.

## Conventions
- Ошибки бросать через хелперы из `src/lib/errors.ts`, не строками.
- `src/legacy/` живой, но его паттерны в новый код не переносить.

## Gotchas
- Интеграционным тестам нужен `DATABASE_URL`, см. `.env.example`.

## Ask before changing
- `infra/`, `.github/workflows/`, существующие файлы в `db/migrations/`

## Learned rules
<!-- Формат: правило / почему (что сломалось) / дата. Пересматривать раз в квартал. -->
- Деплой только через `scripts/deploy.sh`: голая CLI-команда сбрасывает
  флаги безопасности функции. (YYYY-MM)

## References
- Архитектурные решения: @docs/decisions/README.md
```

Шаблон `CLAUDE.local.md` для личных настроек в том же проекте (файл добавляют в `.gitignore`):

```markdown
# CLAUDE.local.md: только для меня, не коммитится
- Тестовое окружение: http://localhost:3000, тестовый пользователь из `seed/users.ts`
- Отвечать по-русски, термины и код писать на английском
- Перед большими правками показывать план
```

Писать файл с нуля не обязательно. `/init` сгенерирует первую версию по кодовой базе, а при существующем CLAUDE.md предложит улучшения и не станет его перезаписывать. С переменной `CLAUDE_CODE_NEW_INIT=1` команда работает интерактивно: спрашивает, что настроить (CLAUDE.md, skills, hooks), исследует код субагентом и показывает предложение до записи файлов. По формулировке best practices, дальше работа в основном сводится к удалению строк.

Короткий стартовый вариант с проверенными командами и ограничениями есть в [полном гайде по Claude Code](https://futurecraft.pro/ru/blog/claude-code-complete-guide/).

## Как поддерживать CLAUDE.md

### Learned Rules и аудит

Раздел «Learned Rules» в файлах автора пополняется только после реальной ошибки, с датой и коротким «почему». Пример из практики, обезличенный: определение «готово» для security-фикса из четырёх проверок (повтор атаки снаружи, CVE запущенной версии, все пути входа, детектор с бэктестом). Правило появилось после случая, когда «фикс» проверили только по конфигурации.

Без ухода такой раздел быстро разрастается. Рабочий ритм выглядит так:

1. После ошибки добавить правило в формате «что делать, почему, дата».
2. Раз в квартал прогнать `/doctor prompt-audit` и удалить правила, которые перекрыты hook'ом или линтером либо устарели вместе с моделью.
3. Правило, которое модель продолжает нарушать, перенести в hook.
4. Заметки для людей оставлять в HTML-комментариях, они не стоят токенов.

### Типичные ошибки

Все примеры ниже нашлись в собственных файлах автора:

| Ошибка | Чем плоха | Что делать |
|---|---|---|
| Файл на 708 строк: поведение, архитектура, философия тестов, оркестрация агентов | Лишний контекст в каждой задаче, правила теряются | Разнести по `.claude/rules/` с `paths` и skills, в CLAUDE.md оставить команды и ограничения |
| Две независимые копии: CLAUDE.md и AGENTS.md | Копии расходятся, в части проектов дрейф уже виден | Один источник: `@AGENTS.md` в CLAUDE.md или симлинк |
| CRITICAL и ВАЖНО больше чем в девяти местах одного файла | Эмфаза обесценивается; по документации, современные модели из-за неё применяют правило шире нужного | Сократить файл, правила без исключений перенести в hooks |
| Общие принципы без критерия («без костылей») | Нечего проверять | Переписать в проверяемую форму или удалить |
| Описание структуры папок и стека | Claude прочитает это сам | Удалить или заменить ссылкой на ADR |
| Пути и команды, которых уже нет | Модель следует несуществующим инструкциям | `/doctor prompt-audit` |

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

## CLAUDE.md и AGENTS.md

В части руководств до сих пор написано, что Claude Code читает только CLAUDE.md. Для версий начиная с v2.1.277 это неверно: встроенный плагин читает AGENTS.md напрямую. Поведение по умолчанию:

| В репозитории | Claude читает |
|---|---|
| AGENTS.md, нет CLAUDE.md и CLAUDE.local.md в рабочей директории и выше | AGENTS.md |
| AGENTS.md и CLAUDE.md (или CLAUDE.local.md) | Только CLAUDE.md |
| CLAUDE.md с импортом `@AGENTS.md` | CLAUDE.md и AGENTS.md через импорт |

Автор проверил четыре конфигурации на Claude Code 2.1.318 (`claude -p`, изолированные папки, в каждом файле уникальный маркер) и сверил ответ модели с выводом `/context all`. Результат совпал с документацией. Одну ловушку легко пропустить: личный `CLAUDE.local.md` в проекте на AGENTS.md отключает чтение AGENTS.md, и модель видит только локальный файл. Импорт `@AGENTS.md` дубля не создаёт, в Memory files оба файла показаны по одному разу.

Чтобы Claude читал оба файла, в `/config` выставляют **Project instructions** = `claude-md-and-agents-md`. В файле настроек это ключ `pluginConfigs["cc-plugin-agents-md@builtin"].options.instructionFiles`. Читается он только из `~/.claude/settings.json`, файла `--settings` или managed settings, а в проектных settings игнорируется. Формат, совместимость с Codex, Cursor и Copilot и способы держать один файл для всех агентов разобраны в [гайде по AGENTS.md](https://futurecraft.pro/ru/blog/agents-md-guide/). Если правила синхронизирует отдельный инструмент, пригодится разбор [AgentSync](https://futurecraft.pro/ru/blog/agentsync-mcp-config-sync/): после появления прямого чтения AGENTS.md часть таких сценариев упростилась.

## Ограничения и что не проверено

- Документация Claude Code меняется часто. Номера версий (v2.1.277, v2.1.283, v2.1.285, v2.1.309) и ID плагина `cc-plugin-agents-md@builtin` актуальны на ноябрь 2026. До v2.1.285 плагин назывался `agents-md@builtin`.
- Поведение после `/compact` описано по документации. Корневой CLAUDE.md после компакции перечитывается с диска и снова вставляется в сессию, вложенные CLAUDE.md и правила с `paths` подгружаются заново по требованию. Инструкции, которые звучали только в разговоре, теряются, поэтому их стоит переносить в файл. Живым `/compact` это не проверялось.
- Проверка AGENTS.md проведена в неинтерактивном режиме `claude -p`. Интерактивный `/config`, `--add-dir`, симлинк `CLAUDE.md` на `AGENTS.md` и вложенные AGENTS.md не проверялись.
- Данные ETH Zurich взяты из аннотации статьи. Проценты по отдельным агентам и моделям здесь не приводятся.
- Как сокращение файла на 708 строк меняет качество работы, не измерялось. Таблица размеров показывает объём, а не эффект.

## С чего начать

1. Запустите `/context all` и посмотрите, какие файлы на самом деле загружены и сколько они стоят.
2. Если CLAUDE.md нет, сгенерируйте его через `/init` и сразу удалите всё, что Claude прочитает из кода сам.
3. Поставьте в начало файла точные команды проверки: тесты, typecheck, линтер, запуск одного теста.
4. Прогоните `/doctor prompt-audit` и разберите противоречия и мёртвые ссылки.
5. Найдите правила с CRITICAL и ВАЖНО: каждое либо переформулируйте спокойно, либо перенесите в hook.
6. Разделы «при работе с …» вынесите в `.claude/rules/` с `paths`, процедуры переведите в skills.

Если в проекте живут и CLAUDE.md, и AGENTS.md, продолжите [гайдом по AGENTS.md](https://futurecraft.pro/ru/blog/agents-md-guide/): там разобрано, как оставить один источник правил. Более широкий обзор skills, субагентов и hooks есть в статье [Claude Code Skills и Agents](https://futurecraft.pro/ru/blog/claude-code-skills-agents/).