CLAUDE.md в Claude Code: как написать файл-инструкцию, которую агент действительно выполняет

Коротко (TL;DR)

CLAUDE.md — это текстовый файл в корне проекта, который Claude Code читает в начале каждой сессии и держит как контекст: правила, команды сборки, договорённости команды. Это не программа и не конфиг с жёстким синтаксисом — обычный Markdown, который вы пишете по-человечески.

Что важно понять сразу:

• Claude Code читает именно CLAUDE.md (не AGENTS.md и не README). Создать стартовый файл можно командой /init.
• Файлов может быть несколько на разных уровнях — от общекорпоративного до личного, — и они складываются в контекст по порядку.
• CLAUDE.md — это контекст, а не принуждение. Anthropic официально подтвердила: содержимое подаётся модели как подсказка, а не как жёсткое правило. Поэтому «claude code не следует инструкциям» — частая и объяснимая жалоба.
• Оптимальный размер — до ~200 строк. Длинный файл модель соблюдает хуже: это подтверждает и документация, и анализ 2500 реальных репозиториев.
• Для того, что «обязано срабатывать без исключений» (не трогать секреты, запускать линтер), CLAUDE.md не годится — там нужны хуки.

Ниже — как устроена иерархия, как создать и правильно написать файл, как он живёт в сессии и почему на него нельзя полагаться как на защиту.

Что такое CLAUDE.md простыми словами

CLAUDE.md — это файл памяти проекта: инструкция, которую агент подгружает в начало разговора, чтобы работать по вашим правилам, а не «вообще». Без него Claude Code каждый раз стартует с чистого листа и угадывает ваши соглашения; с ним — сразу знает, чем собирать проект, как оформлять коммиты и чего делать нельзя.

Иногда CLAUDE.md ищут как файл настроек — это не совсем так. За техническую конфигурацию (права, переменные, модель) отвечает settings.json, а CLAUDE.md — это контекст для модели, написанный обычным языком. Путать их не стоит: один принуждает, другой направляет.

Хуки Claude Code: как автоматизировать действия агента и не подорваться на своих же настройках

MCP в Claude Code: как подключить серверы, не сжечь контекст и когда он не нужен

Плагины в Claude Code: как установить, создать свой маркетплейс и не поймать вредоносный

SKILL.md без магии: собираем свой скилл Claude Code по инженерным паттернам

Agent Skills в Claude Code: как работают, где взять и как не поставить вредоносный скилл

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

CLAUDE.md — это инструкция для модели, которая ведёт ваш проект (например, Claude Sonnet 5 или Opus). Поэтому файл описывает не «как устроен Claude», а «как устроен ваш проект и как вы хотите, чтобы с ним работали».

Где лежит CLAUDE.md и в каком порядке грузится

Файлов может быть несколько, и они не конфликтуют, а накапливаются. Claude Code собирает их по уровням видимости — от общего к частному.

В пределах одной папки CLAUDE.local.md дописывается после CLAUDE.md — то есть ваши личные заметки Claude читает последними на этом уровне. CLAUDE.local.md в общий репозиторий обычно не коммитят (это личное), а managed-файл на разных ОС лежит по своему пути: macOS — /Library/Application Support/ClaudeCode/CLAUDE.md, Linux и WSL — /etc/claude-code/CLAUDE.md, Windows — C:\Program Files\ClaudeCode\CLAUDE.md. Проектный файл, кстати, документация допускает и как ./CLAUDE.md, и как ./.claude/CLAUDE.md — оба варианта рабочие.

Для новичка практический вывод простой: начните с одного файла ./CLAUDE.md в корне проекта — этого достаточно для большинства задач. Личный ~/.claude/CLAUDE.md заводят позже, когда появляются привычки, общие для всех проектов.

Как создать CLAUDE.md: /init и что туда писать

Быстрый старт — команда:

/init

Она анализирует кодовую базу и генерирует стартовый CLAUDE.md с командами сборки, инструкциями по тестам и структурой проекта. Одна подводная деталь: если файл уже существует, /init его не затирает молча — но собранный автоматически файл всё равно стоит вычитать руками, он часто получается «водянистым».

Что реально стоит держать в CLAUDE.md, а что — нет:

Хороший CLAUDE.md отвечает на три вопроса: зачем этот проект (контекст), что в нём где лежит (карта), как здесь принято работать (правила). Это удобный скелет: WHY / WHAT / HOW.

Вот как выглядит компактный рабочий пример для веб-проекта:

# Проект: интернет-магазин на Next.js

## Стек и команды
- Next.js 15 + TypeScript, база — Postgres (Prisma).
- Сборка: `npm run build` · Тесты: `npm test` · Линт: `npm run lint`.
- Перед коммитом всегда прогоняй линт и тесты.

## Договорённости
- Компоненты — в `src/components`, по одному на файл.
- Коммиты — Conventional Commits (`feat:`, `fix:`).

## Чего не делать
- Не трогай `src/legacy/` — там ручные патчи, изменения ломают оплату.
- Не пиши бизнес-логику в компонентах — выноси в `src/lib`.

Обратите внимание: у каждого запрета есть короткое «почему», команды — конкретные и копируемые, а весь файл умещается в пару десятков строк. Это и есть рабочий CLAUDE.md — не пересказ документации, а плотный список решений.

Как писать правила, которые агент выполняет

Здесь и кроется ответ на «почему Claude читает файл, но игнорирует правило». Дело редко в самом Claude — чаще в формулировках. Аналитический разбор реальных CLAUDE.md (инструмент ccmd.dev) выделяет конкретные паттерны, которые модель пропускает:

• Слишком длинные правила. Инструкция длиннее ~28 слов размывается — модель «теряет» её суть. Дробите на короткие пункты.
• Расплывчатые слова. «Пиши качественно», «будь аккуратен», «правильно оформляй» — модель не знает, что это значит в цифрах. Заменяйте на проверяемое.
• Абсолюты без исключений. «Никогда не делай X» без указания, что делать вместо, работает хуже, чем правило с явной альтернативой.
• Отсутствие «почему». Правило с причиной («не трогай legacy/, там ручные патчи») соблюдается лучше голого запрета.
• Дубли и конфликты. Два правила, противоречащие друг другу, гарантированно роняют оба.

Разница видна на одной строке. Слабо: «Пиши хороший, чистый код и покрывай его тестами». Модель не знает, что для вас «хороший», и правило растворяется. Сильно: «Каждая новая функция в src/lib — с юнит-тестом рядом; перед коммитом npm test должен быть зелёным». Второй вариант проверяем и привязан к вашему проекту — его агент выполнит, потому что понимает, что именно от него хотят.

Простой тест для каждой строки: «если я это уберу, Claude ошибётся?» Нет — вычёркивайте. CLAUDE.md — это контракт поведения, а не документация: чем он короче и конкретнее, тем лучше соблюдается.

Про длину есть и цифры. Официальная рекомендация — держать файл короче ~200 строк: длинные файлы съедают контекст и снижают соблюдение правил. Эмпирика подтверждает: анализ 2500 публичных репозиториев с Claude Code (данные на июнь 2026) показал, что CLAUDE.md есть у 84,9% проектов, а медианный файл — 6,2 КБ, это примерно 100–150 строк. Разумный ориентир, а не «чем больше, тем лучше».

Есть и оценка практиков (первоисточник — гайд HumanLayer, тиражируется в рунете): фронтир-модели надёжно держат порядка 150–200 инструкций разом, и ~50 из них уже «съедает» системный промпт Claude Code. Это community-оценка, а не измеренный факт Anthropic, но как ориентир полезна: бюджет правил не бесконечен, тратьте его на важное.

Память, импорты и жизненный цикл в сессии

Вокруг CLAUDE.md есть несколько механик, которые новичка путают. Разберём коротко.

Импорты @path. Внутри CLAUDE.md можно подключить другой файл строкой @path/to/file, и тот может импортировать следующий. Здесь есть расхождение источников: официальная документация называет максимальную глубину четыре «прыжка», а некоторые русские гайды пишут про пять — вероятно, из-за разного способа счёта. Ориентируйтесь на официальную цифру (4) и не стройте слишком глубокие цепочки.

Совместимость с AGENTS.md. Claude Code читает CLAUDE.md, а не AGENTS.md (открытый стандарт, который используют другие агенты). Если в репозитории уже есть AGENTS.md, свяжите их: строкой @AGENTS.md внутри CLAUDE.md или симлинком. На Windows создание симлинка требует прав администратора — там проще импорт.

Auto memory (память Claude Code) — это не то же самое, что CLAUDE.md. Начиная с версии 2.1.59, Claude Code умеет вести собственную память в MEMORY.md; при старте каждой сессии из неё грузятся первые 200 строк или первые 25 КБ (что наступит раньше). CLAUDE.md вы пишете сами и коммитите в проект; auto memory агент накапливает сам. Если интересно, как ИИ-агент вообще ведёт свою базу знаний и чем это отличается от простого поиска по документам, — это отдельная большая тема.

Правила под конкретные файлы — .claude/rules/. Для больших проектов вместо раздувания CLAUDE.md удобнее папка .claude/rules/*.md: там правило через YAML-заголовок paths можно привязать к конкретным файлам и подгружать только тогда, когда Claude работает именно с ними.

Что переживает /compact. Корневой CLAUDE.md проекта переживает сжатие контекста: после /compact Claude перечитывает его с диска и вставляет заново. А вот CLAUDE.md в подкаталогах при старте вообще не грузятся — они подтягиваются по требованию, когда агент заходит в соответствующую папку.

Комментарии для людей. Блочные HTML-комментарии (<!-- ... -->) вырезаются перед подачей файла в контекст модели — в них можно оставлять заметки для коллег, не тратя на это токены агента.

Чего CLAUDE.md не умеет: риски и ограничения

Самый важный и почти нигде не проговорённый момент. CLAUDE.md — это контекст, а не защита. Anthropic Security Team официально подтвердила это через HackerOne (20 мая 2026): CLAUDE.md, AGENTS.md и .claudeignore — «механизмы контекста и памяти, их содержимое подаётся модели как руководство, а не принуждается как жёсткое ограничение». Правило может быть переопределено молча, без лога и предупреждения.

Это не абстракция. Несколько подтверждённых примеров:

• Утечка секретов вопреки запрету. В открытых GitHub-issue (первый — #44868, апрель 2026) пользователи показали, что Claude Code читал и выводил в чат содержимое .env и файлов с ключами, несмотря на явный запрет в CLAUDE.md, — через cat, grep, Edit. Людям приходилось ротировать утёкшие credentials.
• CVE-2026-21852. Найден и пропатчен (в версии 2.1.90, 6 апреля 2026) баг: команда из более чем 50 сцепленных подкоманд обходила проверку deny-правил в permissions без предупреждения. Опасность в том, что такая команда могла прийти из чужого CLAUDE.md — например, при работе с недоверенным репозиторием.

Отсюда практический вывод, и он не про алармизм. Для того, что обязано выполняться без исключений, используйте не текст в CLAUDE.md, а детерминированные механизмы: хуки (PreToolUse/Stop в settings.json) и permissions.deny. Сама документация Anthropic прямо разделяет труд: settings — для технического принуждения, CLAUDE.md — для поведенческих договорённостей. Это не «CLAUDE.md сломан», а честно обозначенная граница ответственности. Правило «никогда не читай .env» в CLAUDE.md — пожелание; та же цель через permissions.deny — barrier.

И здесь же — куда двигаться дальше. Тот же анализ 2500 репозиториев показал разрыв: CLAUDE.md завели 84,9% проектов, но до субагентов и хуков доходит лишь около четверти. То есть большинство останавливается на базовом файле и не берёт инструменты, которые как раз закрывают слабые места CLAUDE.md. Освоив файл-инструкцию, логично следующим шагом разобраться с settings.json и хуками — они превращают ваши договорённости из пожеланий в гарантии.

FAQ

Чем CLAUDE.md отличается от auto memory? CLAUDE.md вы пишете и коммитите сами — это осознанные правила проекта. Auto memory (MEMORY.md, с версии 2.1.59) агент ведёт сам, накапливая факты между сессиями. Первый — ваш контракт с агентом, вторая — его собственный блокнот.

Почему Claude читает CLAUDE.md, но не выполняет правило? Две причины. Первая — формулировка: слишком длинное, расплывчатое или противоречивое правило модель «теряет». Вторая — фундаментальная: CLAUDE.md подаётся как подсказка, а не как жёсткое ограничение, поэтому в редких случаях может быть проигнорирован. Критичные вещи выносите в хуки.

Какой оптимальный размер CLAUDE.md? Ориентир — до ~200 строк (медиана в реальных проектах — около 100–150 строк). Длиннее — хуже соблюдается и дороже по контексту. Если не влезаете, выносите детали в .claude/rules/ или в README.

Нужно ли коммитить CLAUDE.md в git? Проектный ./CLAUDE.md — да, чтобы правила получила вся команда. А CLAUDE.local.md — это личные заметки, их обычно держат вне общего репозитория.

Можно ли положиться на правило «NEVER» в CLAUDE.md как на защиту? Нет. Это подтверждено и официально, и инцидентами. Для секретов и деструктивных команд используйте permissions.deny и хуки в settings.json — они детерминированы, в отличие от советов в CLAUDE.md.

Claude Code читает AGENTS.md? Напрямую — нет, он читает CLAUDE.md. Если в репозитории есть AGENTS.md, свяжите их импортом @AGENTS.md или симлинком (на Windows симлинк требует прав администратора).