CLAUDE.md больше 200 строк в 2026: удалить и пересобрать короткий файл

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

Я проверял: внутри нет специального языка. Подойдут заголовки, списки и короткие фразы. Например:

## Commands
Коротко: здесь указаны основные команды для установки, запуска и проверки проекта.

- Start the app: `npm run dev`
- Run tests: `npm test`

## Rules
Коротко: здесь перечислены постоянные правила работы Claude с кодовой базой.

- Read a file before editing it.
- Do not change unrelated files.

Вот ключевая разница между файлами:

Разница заметна на простом примере. В README можно написать: «Установи зависимости и запусти приложение». В CLAUDE.md лучше указать точные команды, если они нестандартны или их нельзя надёжно вывести из файлов проекта.

Файл может описывать проектный, личный или организационный контекст. В статье речь в основном о проектном файле рядом с кодом.

Зачем Claude Code нужен файл с правилами проекта

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

• запускать проверку нужно нестандартной командой;
• конкретную папку нельзя редактировать вручную;
• бизнес-логику держат отдельно от компонентов интерфейса;
• перед изменением нужно найти уже существующую реализацию;
• определённый файл нельзя переименовывать без отдельного согласования.

CLAUDE.md передаёт такой контекст заранее. Это уменьшает число повторяющихся объяснений в каждой сессии.

Не путай файл с промптом для магии. Он не превращает Claude в автономного разработчика и не заставляет его безошибочно выполнить каждую строку. Файл только добавляет инструкции и контекст в рабочую сессию.

Anthropic описывает похожий сценарий так: Claude читает файлы CLAUDE.md, находит подходящие и разбирается в зависимостях незнакомой кодовой базы. Задача файла состоит в том, чтобы быстрее ввести Claude в правила проекта.

Я вывел простое практическое правило: добавляй строку, если без неё Claude уже ошибался или не способен понять важную особенность проекта. Правило должно появляться из конкретной потребности, а не только потому, что звучит разумно.

Где лежит CLAUDE.md и какой файл видит Claude

На практике встречаются такие уровни:

• корневой CLAUDE.md в папке проекта;
• CLAUDE.md в родительской папке;
• CLAUDE.md в дочерней папке;
• пользовательский файл ~/.claude/CLAUDE.md;
• локальный CLAUDE.local.md;
• проектный файл .claude/CLAUDE.md.

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

Найденные файлы объединяются в общий контекст. Поэтому одно и то же правило в нескольких местах может запутать Claude, а противоречие между уровнями нельзя автоматически считать решённым по простому правилу приоритета.

Для дополнительных материалов есть импорт через @путь/к/файлу:

@README.md
@docs/testing.md

Импорт появился в Claude Code версии 0.2.107. Импортированные файлы тоже могут подключать другие файлы. Документация указывает максимальную глубину в четыре перехода.

Что положить в CLAUDE.md, а что оставить за пределами файла

Я проверяю каждую строку через вопрос: без неё Claude с высокой вероятностью ошибётся?

Подходящее содержимое:

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

Не добавляй:

• полную API-документацию;
• длинный учебник;
• changelog;
• описание каждого файла;
• очевидные правила вроде «пиши чистый код»;
• то, что уже понятно из дерева проекта;
• длинную многошаговую процедуру;
• правило, которого команда сама не придерживается.

Например, строка «используй существующие зависимости» может быть полезна, если Claude уже добавлял новые пакеты без причины. А строка «соблюдай качество кода» слишком общая: по ней нельзя проверить конкретный результат.

Хорошее правило описывает действие:

- Read the file before editing it.
- Search for existing functionality before writing new code.
- Run the smallest relevant test after changes.
- Ask before deleting or significantly restructuring existing code.

Плохое правило оставляет всё на усмотрение модели:

- Always write perfect code.
- Follow best practices.
- Make the project maintainable.

Официальная документация предлагает добавлять команды Bash, стиль кода и рабочие правила. Подробную документацию API она рекомендует держать за пределами файла.

Если материал длинный, вынеси его в отдельный Markdown-файл и подключи через @. Не превращай CLAUDE.md в оглавление всей кодовой базы.

Когда правило держать в CLAUDE.md, а когда вынести в skills

CLAUDE.md загружается в каждую сессию. Поэтому он подходит для короткого постоянного контекста:

• где лежит основной код;
• какой командой запускать проект;
• какую проверку выполнять после изменения;
• какие папки нельзя менять;
• какое архитектурное решение нельзя нарушать.

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

Разделение можно проверить так:

1. Правило относится к любой работе в проекте. Оставь его в CLAUDE.md.
2. Процесс запускается только по конкретному запросу. Вынеси его в skill.
3. Материал длинный и нужен редко. Вынеси его в skill или отдельный файл.
4. Процесс требует нескольких последовательных действий. Подходит skill.
5. После добавления текста каждая сессия стала перегруженной. Убери редкий сценарий из CLAUDE.md.

Документация разделяет эти роли прямо: CLAUDE.md добавляет постоянный контекст, а skills дают повторно используемые знания и вызываемые рабочие процессы.

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

Удалить старый CLAUDE.md или переписать его с нуля

Создатель Claude Code Борис Черни описывает рабочий цикл своей команды: общий файл хранится в Git, а команда дополняет его несколько раз в неделю. Ошибка Claude превращается в короткое правило. Такой файл не служит архивом всех мыслей о проекте.

Борис Черни рекомендует при разрастании файла до тысяч токенов удалить его, начать заново и вернуть только инструкции, которые нужны, когда модель сбивается с пути (пересказ, оригинал на английском). Источник: Inside Claude Code with its creator Boris Cherny.

Есть два разных действия:

Пересборка нужна, когда файл превратился в свод правил на все случаи жизни. В моей практике в такой файл постепенно попадают:

• ответы на каждую старую ошибку;
• дублирующиеся формулировки;
• длинные объяснения;
• правила, которые больше не нужны;
• запреты без технической проверки;
• инструкции, относящиеся только к одной папке или задаче.

Перед удалением сохрани старую версию в истории Git. Затем создай короткий файл и проверь его на небольшой задаче. Не возвращай строку просто потому, что она была в старой версии.

Общий ориентир для короткого файла - до 200 строк. В рекомендациях Бориса Черни фигурирует размер примерно до 2 000 токенов: Токен, единица измерения контекста, накапливается быстро, и каждая лишняя строка отнимает место у полезных инструкций. Это не закон и не гарантия качества. Смысл в другом: каждая строка должна оправдывать постоянное присутствие в контексте.

Как проверить, что Claude действительно видит CLAUDE.md

Порядок проверки:

1. Открой терминал.
2. Перейди в корневую папку проекта.
3. Запусти Claude Code из этой папки.
4. Выполни команду /context.
5. Найди в выводе раздел Memory files.
6. Проверь, что там указан нужный CLAUDE.md.
7. Если файла нет, проверь имя, путь и текущую папку.

Команда для перехода зависит от расположения проекта:

cd path/to/project
claude

Внутри Claude Code введи:

/context

Проверка через /context важнее ответа «я прочитал файл» (подробнее о том, как Claude Code теряет контекст и чем отличается от Cursor). Модель может неверно описать состояние контекста. /context показывает, какие memory-файлы Claude Code загрузил в сессию.

Если файл найден, это ещё не означает, что каждое правило будет выполнено. Проверка отвечает только на вопрос «файл загружен или нет». Поведение нужно проверять отдельной небольшой задачей.

Как сделать CLAUDE.md для проекта: от пустого файла до первой проверки

1. Открой корень проекта

   Перейди в папку, из которой обычно запускаешь Claude Code. Проверь, что рядом лежит код проекта и файлы зависимостей.

2. Создай CLAUDE.md

   Имя должно быть именно CLAUDE.md. Не добавляй второе расширение вроде .txt.

   bash

   Скопировать

   touch CLAUDE.md

3. Запиши реальные команды

   Укажи команды запуска, тестирования, линтинга и сборки только после проверки, что они действительно работают в этом проекте.

   md

   Скопировать

   ## Commands
   Коротко: здесь указаны проверенные команды для установки, запуска, тестирования, линтинга и сборки проекта.
   
   - Install: `npm install`
   - Run locally: `npm run dev`
   - Test: `npm test`
   - Lint: `npm run lint`
   - Build: `npm run build`

4. Добавь стабильные правила

   Запиши расположение основного кода, порядок перед редактированием и границы изменений. Не добавляй общие пожелания без конкретного действия.

5. Запусти Claude из корня

   Это нужно для корректного поиска файлов по дереву папок.

   bash

   Скопировать

   cd path/to/project
   claude

6. Проверь файл через `/context`

   Внутри сессии введи команду и найди CLAUDE.md среди Memory files.

   Скопировать

   /context

7. Дай небольшую задачу

   Не начинай с большой переделки. Попроси изменить один понятный элемент и проверить результат.

   prompt

   Скопировать

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

8. Проверь результат руками

   Посмотри изменённый файл и результат работы приложения. Убедись, что Claude не изменил несвязанные файлы.

9. Добавь правило после ошибки

   Если Claude сделал конкретную нежелательную вещь, запиши короткое правило, которое предотвращает именно её. Не добавляй пять новых запретов «на всякий случай».

10. Повтори маленькую проверку

    Снова запусти задачу с тем же типом изменения и посмотри, помогло ли правило.

Для подключения отдельного файла используй импорт:

@docs/testing.md

Так можно не перегружать основной файл длинным, но нужным материалом. Импортируй только то, что действительно нужно рабочему процессу.

Пример короткого CLAUDE.md для первого проекта

Ниже - мой claude md examples: заготовка на 17 строк. Команды показаны для проекта с npm. Замени их на реальные команды своего проекта.

# Project instructions

## What this is
Коротко: это небольшое веб-приложение с основным кодом в `src/` и тестами в `tests/`.

- This is a small web application.
- Main code lives in `src/`.
- Tests live in `tests/`.

## Commands
Коротко: эти команды устанавливают зависимости, запускают, проверяют и собирают проект.

- Install: `npm install`
- Run locally: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Rules
Коротко: эти правила требуют искать существующий код, читать файлы перед изменением и проверять результат.

- Search for existing code before writing new code.
- Read a file before editing it.
- Do not change unrelated files.
- Ask before making an ambiguous choice.
- Check the result after every change.

Что здесь нужно заменить:

• описание проекта;
• src/, если основной код лежит в другой папке;
• tests/, если тесты лежат иначе;
• команды npm на команды своего проекта;
• формулировки правил под реальные ошибки.

Строка «Search for existing code before writing new code» нужна, чтобы Claude не создавал вторую реализацию той же функции. Строка «Read a file before editing it» задаёт порядок работы. Запрет несвязанных изменений ограничивает масштаб задачи. Вопрос при неоднозначности не даёт молча додумывать требования.

Не добавляй в этот шаблон полную структуру проекта, описание каждого компонента и длинные инструкции для редких процессов. Для них подойдут README, отдельные rules-файлы или skills.

Почему Claude нарушает правило, даже если оно написано в файле

Показательный пример описан в проверке компактного CLAUDE.md со skills и preflight-проверками. Скрипт нашёл 104 нарушения уже записанных правил:

• хардкод вместо enum;
• дублирующиеся helper-функции;
• логика в контроллерах вместо сервисов.

Проверка заняла меньше секунды и не имела зависимостей.

Из этого следует граница файла:

1. Инструкция подсказывает модели, как работать.
2. Модель может решить, что правило не относится к текущей задаче.
3. Модель может неверно применить правило.
4. Техническая проверка видит результат, а не намерение.
5. Линтер, тест или hook способен остановить процесс или показать ошибку.

Короткий CLAUDE.md не гарантирует TDD. Он не гарантирует, что Claude не сделает commit. Он не гарантирует отсутствие секретов в изменениях. Он не гарантирует архитектурную дисциплину.

Поэтому правило «после изменения запусти тесты» полезно как напоминание. Для обязательного запуска нужна автоматическая проверка. Если нужно дать Claude доступ к внешним инструментам, разберись с MCP-сервером - он связывает Claude Code с файлами, базами и сервисами. Правило «не коммить ключи» полезно как подсказка. Для защиты нужны permissions и проверка секретов.

Что делать с секретами, опасными командами и обязательными проверками

Разделяй задачи по механизму:

• объяснить Claude команды и правила проекта - CLAUDE.md;
• запретить чтение .env и secrets/** - permissions.deny в .claude/settings.json;
• настроить permissions, переменные окружения, плагины и поведение инструментов - settings.json;
• запускать действие каждый раз - hook в .claude/settings.json;
• описать редкий рабочий процесс - skill.

Пример запрета доступа оформляется настройками, текстом в Markdown его не заменить:

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(secrets/**)"
    ]
  }
}

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

Проблема текстового запрета подтверждена issue Claude Code: автор описал случай, когда правило не коммитить API-ключи было в CLAUDE.md, но реальные credentials всё равно попали в конфигурационные файлы и публичный репозиторий. GitGuardian обнаружил три секрета. Ключи пришлось отозвать и выпустить заново.

CLAUDE.md можно оставить с пояснением:

## Safety
Коротко: эти правила напоминают не читать и не коммитить секреты, а также спрашивать перед изменением схемы базы данных.

- Never read `.env` files.
- Never commit secrets.
- Ask before changing database schema.

Но эти строки не должны быть единственной защитой. Для доступа используй settings. Для действий, которые должны происходить всегда, используй hooks. Для проверки кода используй тесты, линтер или другую автоматическую проверку.

Чем CLAUDE.md отличается от README.md, AGENTS.md и rules

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

@README.md

AGENTS.md используют как общий источник для нескольких инструментов. Если в проекте работают Claude Code и Codex, общие правила можно держать в AGENTS.md, а Claude-специфичные дополнения оставить в CLAUDE.md.

Если используется только Claude Code, одного CLAUDE.md достаточно как прямого файла инструкций для этого инструмента.

.claude/rules/*.md подходит для path-scoped правил. Например, правило может относиться только к src/api/**, а не ко всему проекту. Точное сравнение старого .clauderules с современными rules здесь не приводится: в фактуре нет актуального подтверждённого источника для такого сравнения.

Короткие ответы на вопросы о CLAUDE.md

Вопросы и ответы