CLAUDE.md: что это, шаблон и правила для агента
CLAUDE.md это текстовый файл в корне проекта, который Claude Code читает в начале каждой сессии. В него пишут то, что иначе пришлось бы повторять в каждом чате: команды тестов, устройство кода, договорённости и запреты. Первый вариант создаёт команда /init: агент осмотрит проект и предложит черновик. Хороший CLAUDE.md короткий и содержит только то, чего агент не поймёт из кода сам. А правило, которое обязано выполняться всегда, одним файлом не удержать: для агента это инструкция без гарантии.
Где лежит CLAUDE.md
Файлов может быть несколько, Claude Code собирает их вместе. Какие загрузились и сколько весят, покажет /context.
Проект
CLAUDE.md или .claude/CLAUDE.md в корне
общие правила, лежат в git
Личный
~/.claude/CLAUDE.md
ваши привычки для всех проектов
Локальный
CLAUDE.local.md в корне
личное, в git не добавляют
Подпапка
CLAUDE.md внутри папки
грузится, когда агент читает эту папку
Правила по путям
.claude/rules/*.md с полем paths:
грузятся при чтении подходящих файлов
Шаблон CLAUDE.md
Я проверил 1 октября в Claude Code 2.1.280, что агент читает этот файл: без доступа к файлам он назвал команду тестов дословно.
# Проект: магазин открыток ## Команды - Запуск: `npm run dev` - Тесты одного файла: `npx vitest run <путь>` - Проверка типов: `npm run typecheck` ## Как устроен код - `app/` страницы, `lib/` логика, `db/` схема и миграции. - Цены и права доступа проверяются на сервере. ## Правила - Перед правкой прочитай файл целиком и найди, кто его вызывает. - Миграции только новым файлом, старые не редактируем. - Сервер, который поднял для проверки, гаси по PID своего порта. ## Без спроса не делать - `git push --force`, `rm -rf`, запись в боевую базу. ## Подробности @docs/architecture.md - Деплой: docs/deploy.md, открой перед любой выкладкой.
Команды окупаются первыми: без них агент угадывает, чем запускать тесты, и гоняет весь набор там, где хватило бы одного файла.
Как устроен код держит две-три строки карты, стек агент прочитает в package.json сам.
Без спроса не делать перечисляет то, что нельзя откатить. Текстом агента не остановить, поэтому продублируйте список в .claude/settings.json: это правило проверяет сам Claude Code.
{"permissions": {"ask": ["Bash(git push *)", "Bash(rm -rf *)"]}}Я положил этот файл рядом с шаблоном и попросил агента удалить папку командой rm -rf. Агент сразу попробовал её выполнить, и Claude Code остановил команду: в режиме -p спросить было некого. Обёртку вроде bash -c правило не ловит, но от обычной ошибки страхует.
Подробности подключаются двумя способами, и грузятся они в разный момент.
Импорт через @ и обычная ссылка
Строка @docs/architecture.md вставляет файл в контекст при старте целиком. Путь без значка @ остаётся текстом: агент знает, что файл есть, и откроет его, когда решит, что пора. Я положил в architecture.md и deploy.md по кодовому слову и спросил агента, лишённого доступа к файлам, какие слова он знает.
Три запуска из трёх, два на Haiku 4.5 и один на Opus 5.5: слово из импорта агент знает, из упомянутого файла нет. По /context импорт сразу занял 128 токенов. Когда агенту разрешили читать файлы и спросили, что знать перед выкладкой, он сам открыл deploy.md по подсказке и приписал от себя команду npm run test, которой в проекте нет.
Вывод: импорт оплачивается в каждой сессии, поэтому через @ подключайте то, что нужно почти всегда. Остальное оставляйте путём с пометкой, когда открывать, а знание об одной папке кладите в CLAUDE.md этой папки.
Какие правила агент выполняет
Правило работает, когда по нему можно проверить действие.
Процессы
Проверь, что процесс твой
Свой сервер гаси по PID порта: kill $(lsof -ti:3001). Через pkill -f "next dev" нельзя
База
Осторожно с базой
Запись в боевую базу только после моего подтверждения
Тесты
Покрывай код тестами
После правки в lib/ запусти тест изменённого файла
Расплывчатое правило про процессы стоит в нашем файле с июня. 1 сентября агент поднял свой сервер на порту 3001, обошёл занятый 3000, а в конце командой pkill -f "next dev" погасил оба: она ищет процессы по имени. Через два дня его дополнили конкретным, с датой случая.
К правилу дописывайте причину: по руководству Anthropic, зная её, модель переносит правило на соседние случаи. Слово «IMPORTANT» ставьте только на строку, которую агент упорно пропускает: когда им отмечено много строк, не выделяется ни одна.
Как устроены правила fomenko.by
Наш CLAUDE.md живёт с 14 мая 2026 года, за это время 71 правка, и с первого дня мы ведём журнал изменений правил: повод, что изменили, вывод. Корневой файл держит 19 разделов общих правил: короткая формулировка, у двенадцати строка «Почему» с поводом, у тринадцати ссылка на полную версию в отдельном файле. Такой файл агент открывает, когда задача совпадает с пометкой у ссылки.
Слабое место я вижу сам: 333 строки при ориентире документации в 200. Вот что показывает /context в нашем проекте.
Tokens: 47.3k / 1m (5%) | Memory files | 35.3k | | Project | …/CLAUDE.md | 29.2k | | AutoMem | …/MEMORY.md | 6.1k |
Строки у нас длинные, поэтому мерить надо токенами: 29,2 тысячи в начале каждой сессии, почти в сто раз больше шаблона. Вынос шести разделов в скилы стоит в бэклоге с 19 сентября. Во что это обходится, я разбирал в статьях про токены и про контекст.
Чего CLAUDE.md не гарантирует
Документация Anthropic называет CLAUDE.md контекстом, а для запретов, которые должны срабатывать всегда, советует хуки и настройки прав. 8 сентября в тексте задания для агента стояло: закончив статью, отметь в карте запросов, какие фразы она закрыла. Хватило на один цикл. 12 сентября по карточке из очереди пришла задача, три дня как сделанная на проде, и нашлись ещё три такие. Тогда в CLAUDE.md появилось правило с этой датой, а рядом тест: если карточка предлагает сделанное, коммит с правкой карты не проходит.
Отсюда деление: что агент должен знать, пишем в CLAUDE.md, а что обязано случиться всегда, ставим проверкой. У нас git-хук блокирует коммит с нейросетевыми штампами, а деплой не начнётся без свежей копии базы. В CLAUDE.md эти правила тоже есть, чтобы агент понимал, почему его остановили.
CLAUDE.md чужого репозитория агент загрузит так же, как ваш, и будет ему следовать. Прочитайте файл до первого запуска; как агент выполняет чужие приписки, мы проверяли в статье про промпт-инъекцию.
Как вести файл
Начните с /init и сократите черновик: агент охотно описывает то, что видно из кода. Про каждую строку документация советует спросить: если её убрать, агент начнёт ошибаться? Если нет, вычёркивайте. Новое правило добавляйте, когда агент повторил ошибку. Если он нарушает уже записанное, сначала сократите файл: в длинном правило теряется. Процедуры на десять шагов выносите в скилы: на старте от них грузится только описание. Если с проектом работает ещё и Codex, общие правила перенесите в AGENTS.md, а в CLAUDE.md оставьте строку @AGENTS.md.
Частые вопросы
Что сделать сегодня: откройте /context и посмотрите, сколько весит то, что агент получает на старте. Вычеркните строки, которые он узнает из кода, допишите одну по его последней ошибке, а обязательное поставьте запретом в настройках. Если файл перерос двести строк и непонятно, что выносить, разберём это на вашем репозитории на менторинге по вайб-кодингу.
Читайте также
Как создать сайт с помощью нейросети и проверить
Как создать сайт с помощью нейросети: лендинг с заявкой, три дефекта и лишние обещания. Прогон Claude Code, задания, исходники и проверка перед запуском.
AGENTS.md: что это и пример для Codex и Claude
Что такое файл AGENTS.md и кто из агентов его читает: пример, проверенный в Codex и Claude Code, и строка, без которой Claude Code может его не увидеть.
Контекст в Claude Code: что это и когда кончается
Рабочая память агента: правила, файлы, выводы команд. Что происходит, когда окно заполняется, что переживает сжатие и как продолжить проект после обрыва.