Как настроить Claude Code: контекст проекта, CLAUDE.md и разрешения

Q: Где лучше хранить CLAUDE.md?

Для командных правил — в корне проекта или .claude/CLAUDE.md. Для личных настроек используйте локальный файл, который не попадает в Git. Выбор зависит от того, кто должен видеть и применять инструкцию.

Практическая настройка Claude Code: где хранить CLAUDE.md, как задать правила проекта, ограничить доступ и проверять действия агента перед изменениями.

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

Официальная документация Anthropic описывает иерархию CLAUDE.md, проектные правила и отдельные настройки доступа (How Claude remembers your project). Для полного понимания продукта начните с руководства по Claude AI, а перед настройкой установите Claude Code по quickstart-инструкции.

Короткий ответ

Обратите внимание:

Key Takeaways

Обратите внимание:

- CLAUDE.md хранит проектные инструкции: архитектуру, команды, стиль и рабочие ограничения.

Обратите внимание:

- Чем конкретнее правило и критерий проверки, тем легче понять, выполнено ли оно.

Обратите внимание:

- Разрешения и deny-правила задают технические границы; текст инструкции не заменяет их.

Обратите внимание:

- Начинайте с минимального доступа и расширяйте его только под конкретную задачу.

Обратите внимание:

- После настройки проведите пробный сеанс без изменений, затем проверьте diff и тесты.

CLAUDE.md и permissions решают разные задачи

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

Permissions — это настройки, которые определяют, какие действия требуют подтверждения, разрешены или запрещены. На них следует опираться для технических границ: доступа к каталогам, запуска команд и потенциально опасных операций. Подробные правила описаны в Configure permissions.

Упрощённо:

Вопрос	Где описать
Как устроен проект?	CLAUDE.md
Какой стиль кода использовать?	CLAUDE.md
Какие команды запускать для проверки?	CLAUDE.md
К каким инструментам нельзя обращаться?	permissions deny
Какие пути требуют отдельного контроля?	permissions
Что всегда нужно подтверждать?	permissions ask и рабочая дисциплина

Шаг 1. Создайте короткий проектный CLAUDE.md

Файл проекта можно хранить в корне как ./CLAUDE.md или внутри ./.claude/CLAUDE.md. Документация Claude Code перечисляет оба варианта и описывает их как проектный контекст, общий для команды.

Минимальная структура:

markdown

# Project context

## What this project is
- Короткое описание продукта и главных точек входа.

## Conventions
- Правила именования и форматирования.
- Где должны находиться новые файлы.

## Verification
- Команды typecheck, test и build.
- Что считать успешным результатом.

## Safety
- Не изменять секреты и production без отдельного подтверждения.
- Перед завершением показать git diff и статус рабочей ветки.

Пишите только правила, которые относятся ко всему проекту. Локальные особенности лучше вынести в отдельный файл или path-scoped rule. Длинный документ потребляет контекст и труднее проверяется.

Шаг 2. Добавьте конкретные критерии готовности

Плохое правило:

Обратите внимание:

Делай код качественно.

Хорошее правило:

Обратите внимание:

Для API-изменений добавляй обработку ошибки, тест на неуспешный ответ и команду проверки. Не изменяй публичный формат без описания миграции.

Критерий должен быть наблюдаемым. Укажите:

что нужно прочитать перед изменением;

какие файлы считаются точками входа;

какие команды обязательны;

какие изменения требуют остановки;

в каком формате показывать итог;

что делать при нехватке данных.

Не дублируйте в CLAUDE.md коммерческие секреты, токены и персональные данные. Для личных предпочтений существует локальный файл, который не следует коммитить; перед использованием проверьте актуальную документацию и .gitignore.

Шаг 3. Настройте правила и области действия

Для большого проекта Claude Code поддерживает каталог .claude/rules/, где можно разделить инструкции по темам: тестирование, стиль, безопасность, frontend или backend. Правила могут быть общими или ограниченными путями.

Пример логики:

.claude/rules/testing.md — общие команды и критерии тестов;

.claude/rules/security.md — секреты, доступ и опасные операции;

.claude/rules/frontend.md — правило только для UI-файлов;

.claude/rules/data.md — ограничения для миграций и схем.

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

Шаг 4. Проверьте, какой контекст загружается

Перед изменениями попросите Claude Code перечислить:

найденные CLAUDE.md;

применимые правила;

рабочий каталог;

ограничения permissions;

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

Это диагностический запрос, он не должен менять файлы:

Обратите внимание:

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

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

Шаг 5. Начните с разрешений по умолчанию

Официальная страница permissions описывает режимы allow, ask и deny, а также правила для инструментов и команд. Для незнакомого проекта безопаснее оставить действия, меняющие файлы, запускающие команды или обращающиеся к сети, под подтверждением.

Рабочая схема:

чтение нужных файлов — разрешать в пределах проекта;

запись — подтверждать после просмотра плана;

shell-команды — подтверждать по смыслу, особенно с удалением, публикацией и сетевым доступом;

секретные каталоги — запрещать;

Git push и операции с удалёнными ресурсами — выполнять только после отдельного решения.

Не используйте режим, который отключает подтверждения, просто ради скорости. Если его всё же рассматривают для изолированного тестового окружения, сначала зафиксируйте каталог, ветку, резервную копию и команды отката. Документация предупреждает о рисках широкого обхода разрешений (Security).

CLAUDE.md не должен хранить секреты

Инструкции проекта часто попадают в Git и становятся доступными всей команде. Поэтому в них нельзя хранить:

ключи API;

содержимое .env;

данные клиентов;

закрытые ссылки;

постоянные учётные данные;

инструкции, раскрывающие внутреннюю инфраструктуру без необходимости.

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

Как настроить хороший рабочий цикл

Соедините правила с последовательностью действий:

Explore: Claude читает только необходимый контекст.

Plan: формулирует изменение, затронутые файлы и проверки.

Approve: человек подтверждает план и разрешения.

Edit: инструмент вносит небольшую правку.

Review: человек проверяет diff.

Verify: запускаются тесты, typecheck и build.

Report: Claude перечисляет сделанное и нерешённые риски.

Такой цикл полезнее, чем длинный файл с десятками абстрактных требований. Для Git-части используйте отдельный workflow, а для повторяющихся рабочих материалов — Claude Projects.

Частые ошибки настройки

CLAUDE.md превращается в энциклопедию. Инструкции становятся дорогими для загрузки и противоречивыми. Оставьте краткие правила и вынесите детали в path-scoped файлы.

Текстом пытаются запретить техническое действие. Поведенческая инструкция не заменяет permissions deny. Для жёсткой границы используйте техническую настройку.

Разрешения открываются слишком широко. Каталог «на уровень выше» может содержать секреты и соседние проекты. Разрешайте минимальный путь.

Нет команды проверки. Если правило нельзя проверить, его трудно соблюдать. Добавьте точные команды и признаки успешного результата.

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

Минимальная конфигурация для нового репозитория

Для нового проекта достаточно начать с трёх документов:

CLAUDE.md с архитектурой, основными командами и критериями готовности;

.claude/rules/testing.md с проверками, которые должны выполняться после изменений;

.claude/rules/security.md с правилами для секретов, внешних систем и опасных команд.

Сначала оставьте запись и выполнение команд под подтверждением. Проведите диагностический сеанс, затем маленькую правку в отдельной ветке. Если Claude Code просит доступ, который не нужен текущей задаче, отклоните его и уточните границы.

По мере роста проекта добавляйте path-scoped правила, а не расширяйте один общий файл бесконечно. После каждой ревизии удаляйте противоречия и проверяйте, что README, CLAUDE.md и permissions описывают одну и ту же рабочую реальность.

Частые вопросы

Где лучше хранить CLAUDE.md?

Для командных правил — в корне проекта или .claude/CLAUDE.md. Для личных настроек используйте локальный файл, который не попадает в Git. Выбор зависит от того, кто должен видеть и применять инструкцию.

Нужно ли писать в CLAUDE.md все команды проекта?

Только основные команды, которые Claude должен знать перед типичной задачей: тесты, линтер, сборка и проверки миграций. Полный справочник оставьте в README.

Может ли CLAUDE.md остановить удаление файла?

Сам по себе текст не даёт жёсткой гарантии. Для опасных действий нужны permissions и обязательное подтверждение, а также резервный план.

Как проверить, что правило работает?

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

Что почитать дальше?

Начните с первого запуска Claude Code, затем используйте Git-workflow с diff, тестами и ревью.

Заключение

Хорошая настройка Claude Code не пытается заменить разработчика большим сводом запретов. Она даёт инструменту короткий и актуальный контекст, а технические границы закрепляет разрешениями. Создайте CLAUDE.md, разделите правила по темам, проверьте иерархию загрузки и начните с минимального доступа.

После каждого существенного изменения смотрите diff, запускайте тесты и обновляйте инструкции вместе с проектом. Затем переходите к Claude Code и Git, где тот же подход превращается в воспроизводимый процесс разработки.