Где должны находиться инструкции Claude Code: CLAUDE.md, правила пути или хуксы

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

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

CLAUDE.md — это контекст, а не конфигурация

Все остальные проблемы сводятся к этому заблуждению. Claude Code вставляет файл в разговор в виде сообщения; он не сливается с системным промптом, и ничто во время выполнения не обеспечивает его соблюдение. Модель читает его и пытается следовать ему. Более никаких гарантий нет, а шансы снижаются ещё больше, когда формулировки неоднозначны или две инструкции противоречат друг другу.

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

Сохраняйте количество строк в основном файле ниже 200

Текущая рекомендация — не превышать примерно 200 строк. При большем количестве строк файл занимает больше места в окне контекста, что ухудшает возможность его использования, а не улучшает.

Это кажется противоречивым: чем больше инструкций, тем меньше из них выполняется. Каждая строка конкурирует за ограниченное внимание с другими строками и самим ходом диалога. Возьмем команду, у которой файл содержал 340 строк. Сокращение его до примерно 120 строк позволило Claude более надежно следовать инструкциям. Ни одна из удаленных строк не была неверной; они просто представляли собой шум, мешающий пониманию важных инструкций.

Существует также жесткий предел, с которым не стоит работать: согласно документации на момент написания, файлы размером более 4 МБ полностью игнорируются. Способность Claude следовать инструкциям снижается задолго до того, как файл достигнет такого размера.

Удалите то, что Claude может найти в репозитории

Самое эффективное правило редактирования просто: удаляйте всё, что Claude может понять, прочитав кодовую базу. Это соответствует тем упрощениям, которые рекомендует встроенная функция /doctor в Claude Code — она удаляет структуру папок, списки зависимостей и описания архитектуры высокого уровня, сохраняя при этом проблемные моменты, обоснования и конвенции, отклоняющиеся от стандартов инструмента. Другими словами, она переворачивает обычное содержимое этих файлов.

Что следует удалять:

• Структуру папок, поскольку Claude может сам перечислить каталоги.
• Список зависимостей, который уже содержится в файле package.json.
• Описательный обзор архитектуры, который код отражает более точно.

Что следует сохранять:

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

Любые конвенции, противоречащие документации фреймворка.

Команды, которые никто не смог бы найти самостоятельно.

Хороший критерий: если компетентный инженер, имеющий открытый репозиторий, сможет ознакомиться с ним за десять минут, его следует исключить. Если же он сможет узнать об этом только путем нарушения чего-либо, его следует записать.

Оставляйте примечания для людей без затрат на токены

Комментарии на уровне блока в HTML удаляются до того, как содержимое файла попадает в контекст Claude. Это позволяет добавлять аннотации к файлу для тех, кто им управляет, не тратя никаких ресурсов модели, например, для указания причины перемещения раздела:

<!-- Deleted the API section — moved to .claude/rules/api.md, Sep 2026 -->

Ваши коллеги видят историю изменений; модель никогда за это не платит.

@imports организуют файл, но не сохраняют контекст

Когда файл CLAUDE.md становится слишком длинным, первым побуждением является разделение его на несколько документов и их импорт:

@docs/architecture.md
@docs/api-conventions.md
@docs/testing.md

Это похоже на ленивую загрузку, но на самом деле это не так. Импортируемые файлы раскрываются и загружаются в контекст при запуске вместе с CLAUDE.md, который на них ссылается. Разделение 340 строк на четыре отдельных файла не приводит к тому, что будет загружено меньше строк — всё равно загружаются те же 340 строк.

Импорты действительно имеют законные применения. Они помогают в организации кода и позволяют делиться единым каноническим набором инструкций между различными инструментами. Если в репозитории уже есть файл AGENTS.md, одна строка вида @AGENTS.md в CLAUDE.md позволяет избежать необходимости поддерживания двух разных версий. Просто не ожидайте, что импорты сократят объем загружаемого контекста. Для инструкций, которые должны загружаться только время от времени, требуются правила с ограничением по пути.

Установка условных правил с использованием .claude/rules и путей

Файлы в папке .claude/rules/ могут указывать поле paths в своем фронтматтере. Именно эта функция обеспечивает то, чего ожидают пользователи при импорте: правило с глобальным охватом остается вне контекста до тех пор, пока Claude не прочитает или не изменит соответствующий файл. Фронтматтер файла с правилами API может выглядеть следующим образом:

---
paths:
  - "src/api/**/*.ts"
---

Под фронтматтером находится тело правила, в котором задаются конвенции, применимые только к этой части структуры, такие как проверка входных данных, общая структура ошибок и места, где разрешен SQL:

# API rules- Every endpoint validates input before touching the database
- Errors use the standard envelope in `src/api/errors.ts`
- No direct SQL outside `src/api/repositories/`

В результате работа фронтенда больше не оплачивает затраты на соблюдение конвенций API, а работа API — затраты на тестирование.

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

Форматы glob поддерживают расширение скобок, поэтому одно правило может охватывать несколько расширений и отдельный шаблон проверки:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "tests/**/*.test.ts"
---

Шаги, которые обязательно нужно выполнить, должны находиться в хуках

Фразы вроде «провести lint перед каждым коммитом», «не публиковать изменения непосредственно в main» или «форматировать каждый файл после редактирования» часто встречаются в CLAUDE.md. В большинстве случаев к ним прислушиваются, исключения замечаются, после чего команды приходят к выводу, что модели нельзя доверять.

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

Практический способ классификации различных типов инструкций:

• Общие правила, которых должен придерживаться Claude, указываются в CLAUDE.md.
• Правила для определенной области кодовой базы размещаются в папке .claude/rules/ вместе с параметром paths.
• Требования, не терпящие никаких исключений, преобразуются в хуки.
• Повторяемые многоэтапные процедуры превращаются в навыки.

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

Проверка того, что действительно загружено

Запустите команду /context и ознакомьтесь с разделом файлов памяти, в котором отражается точный список того, что загружено текущей сессией. Команда /memory дополняет её, перечисляя файлы на уровне пользователя и проекта и позволяя открыть их. Вместе они превращают вопрос «Не игнорирует ли Claude это?» из предположений в нечто, что можно проверить. Удивительно легко тратить время на доработку формулировок в файлах, которые вообще не загружаются.

Противоречия в объединённых файлах

Ничто не переопределяется; всё объединяется вместе. Начиная с рабочей директории, Claude Code поднимается к корню файловой системы и собирает по пути все файлы CLAUDE.md, затем сортирует их от корня вниз. На любом уровне, где также существует файл CLAUDE.local.md, этот файл находится после своего аналога CLAUDE.md. В монорепозитории два файла могут легко давать противоположные указания. В таком случае Claude может просто выбрать один из них, и вы не получите никакого уведомления о конфликте.

Файлы-предки, которых вы не запрашивали

Если файл CLAUDE.md из родительской директории попадает в ваши сессии, настройка claudeMdExcludes в ваших локальных настройках позволяет исключать файлы с помощью шаблонов.

Что сохраняется после сжатия

Файл CLAUDE.md, находящийся в корне проекта, снова считывается с диска и вставляется после выполнения команды /compact, поэтому его инструкции сохраняются. Всё, что было сказано только в ходе разговора, теряется. Если вы постоянно повторяете одни и те же коррективы после каждой компактации, это явный сигнал того, что они должны быть записаны в файл.

Исходная схема

Если бы вы создавали структуру проекта с нуля, разумная цель выглядела бы так:

• Корневой файл CLAUDE.md объемом около 120 строк, содержащий только те данные, которые верны везде.
• Условные рекомендации, расположенные в папке .claude/rules/ с использованием шаблонов путей.
• Каждое обязательное требование вида «всегда» реализуется в виде специального механизма.
• Ничего такого, что кто-то мог бы узнать, прочитав репозиторий в течение десяти минут.
• Быстрая проверка с помощью команды /context после каждой изменения.

Полная информация, включая такие функции, как автоматическая память, которые требуют отдельного рассмотрения, содержится в документации Claude Code по памяти. Поведение и ограничения могут меняться, поэтому проверяйте её, если что-то не соответствует ожидаемому.

Основные выводы

• Пишите файлы CLAUDE.md для человека, который будет их читать, а не для машины, которая будет их выполнять: кратко, конкретно и без противоречий.
• Более короткие файлы обрабатываются надежнее; удаляйте всё, что уже указано в кодбазе для Claude.
• Импорты переупорядочивают содержимое, но загружают всё его; именно правила, связанные с путями, фактически откладывают загрузку.
• Всё, что должно происходить каждый раз, требует использования хука, поскольку контекст может влиять только на поведение.
• Считайте /context источником правды перед тем, как корректировать формулировки.