Папка .claude: полный разбор того, что внутри - UPROGER

Большинство разработчиков, работающих с Claude Code, смотрят на папку .claude как на черный ящик. Знают, что она есть. Видели, как она появляется в корне проекта. Но никогда не открывали и уж точно не понимали, что там лежит и зачем.

А зря. Папка .claude – это центр управления поведением Claude в вашем проекте. Здесь хранятся инструкции, кастомные команды, правила доступа и даже память модели между сессиями. Разберемся с каждым файлом и папкой по порядку.

Источник: оригинальная статья @akshay_pachaar на X

Две папки, не одна

Важный момент, который многие упускают: папок .claude на самом деле две. Первая живет внутри вашего проекта, вторая – в домашней директории пользователя.

Папка на уровне проекта хранит командную конфигурацию. Ее коммитят в git, и все члены команды получают одинаковые правила, команды и политики доступа. Глобальная папка ~/.claude/ хранит личные настройки и состояние конкретной машины: историю сессий и авто-память.

CLAUDE.md: инструкция для модели

Это самый важный файл во всей системе. Когда запускается сессия Claude Code, первое, что читает модель – это CLAUDE.md. Файл загружается прямо в системный промпт и остается там на протяжении всего разговора.

Если написать в CLAUDE.md “всегда пиши тесты перед реализацией” – Claude будет это делать. Если написать “никогда не используй console.log, только кастомный логгер” – будет соблюдать каждый раз.

CLAUDE.md в корне проекта – самый распространенный вариант. Но можно также иметь ~/.claude/CLAUDE.md для глобальных предпочтений, которые применяются ко всем проектам, и даже отдельные файлы в поддиректориях для правил конкретной папки. Claude читает все и объединяет их.

Что писать в CLAUDE.md

Большинство людей пишут или слишком много, или слишком мало. Вот что реально работает:

Писать стоит: команды сборки, тестов и линтинга; ключевые архитектурные решения; неочевидные особенности (“TypeScript strict mode включен, неиспользуемые переменные – это ошибки”); соглашения по импортам, именованию, обработке ошибок; структуру папок основных модулей.

Не стоит писать: всё, что можно вынести в линтер или форматтер; полную документацию, на которую можно просто дать ссылку; длинные теоретические объяснения.

Держите CLAUDE.md в пределах 200 строк. Файлы длиннее этого начинают съедать слишком много контекста, и точность следования инструкциям падает.

CLAUDE.local.md для личных настроек

Если у вас есть предпочтения, специфичные только для вас, а не для всей команды – создайте CLAUDE.local.md в корне проекта. Claude читает его наряду с основным CLAUDE.md, и он автоматически добавляется в .gitignore, так что ваши личные настройки никогда не попадут в репозиторий.

Папка rules/: модульные инструкции

CLAUDE.md отлично работает для одного проекта. Но когда команда растет, появляется 300-строчный CLAUDE.md, который никто не поддерживает и все игнорируют. Папка rules/ решает эту проблему.

Каждый markdown-файл внутри .claude/rules/ загружается вместе с вашим CLAUDE.md автоматически. Вместо одного огромного файла вы разбиваете инструкции по зонам ответственности. Настоящая сила – в правилах, привязанных к путям. Claude не загрузит файл с API-правилами при редактировании React-компонента. Правила без поля paths загружаются безусловно в каждой сессии.

.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md

Система хуков: детерминированный контроль

Инструкции из CLAUDE.md – это рекомендации. Модель следует им большую часть времени, но не всегда. Хуки делают такие поведения детерминированными. Это обработчики событий, которые автоматически срабатывают в определенные моменты рабочего процесса Claude. Ваш shell-скрипт запускается каждый раз, без исключений.

Вся конфигурация хуков хранится в settings.json под ключом hooks. Критически важный момент: код выхода 2 – единственный код, который блокирует выполнение. Выход 0 означает успех. Выход 1 означает ошибку, но не блокирует. Выход 2 означает “стоп, отправь stderr в Claude для самокоррекции”. Использование кода выхода 1 для хуков безопасности – самая распространенная ошибка.

Наиболее полезные события: PreToolUse (до выполнения любого инструмента – ваш шлюз безопасности), PostToolUse (после успешного выполнения инструмента – для форматтеров и линтеров), Stop (когда Claude заканчивает работу – для проверки качества), UserPromptSubmit (когда вы нажимаете Enter).

Папка skills/: переиспользуемые workflows

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

Каждый скил живет в собственной поддиректории с файлом SKILL.md. YAML frontmatter описывает, когда его использовать. Когда вы говорите “проверь этот PR на безопасность” – Claude читает описание, определяет совпадение и автоматически вызывает скил. Можно также вызвать его явно через /security-review.

Ключевое отличие от команд: скилы могут объединять вспомогательные файлы рядом с собой. Команды – это одиночные файлы. Скилы – это пакеты. Личные скилы можно хранить в ~/.claude/skills/ и они будут доступны во всех проектах.

Папка agents/: специализированные субагенты

Когда задача достаточно сложная, чтобы выиграть от выделенного специалиста, можно определить персону субагента в .claude/agents/. Каждый агент – это markdown-файл со своим системным промптом, доступом к инструментам и предпочтением модели.

Когда Claude нужно провести ревью кода, он порождает этого агента в собственном изолированном контекстном окне. Агент делает свою работу, сжимает результаты и докладывает обратно. Ваша основная сессия не засоряется тысячами токенов промежуточного исследования. Поле model позволяет использовать более дешевую и быструю модель для сфокусированных задач – Haiku хорошо справляется с большинством задач только на чтение.

settings.json: разрешения и конфигурация

Файл settings.json внутри .claude/ контролирует, что Claude может и не может делать. Здесь живут хуки, здесь определяются разрешенные инструменты, файлы для чтения и то, нужно ли спрашивать разрешения перед определенными командами.

Список allow содержит команды, которые выполняются без запроса подтверждения. Список deny содержит команды, заблокированные полностью. Разумный список deny блокирует деструктивные команды вроде rm -rf, прямые сетевые команды вроде curl и чувствительные файлы вроде .env. Если что-то не попало ни в один список – Claude спрашивает перед выполнением.

Практический старт

Если начинаете с нуля, вот прогрессия, которая работает хорошо. Запустите /init внутри Claude Code – он сгенерирует стартовый CLAUDE.md, читая ваш проект. Отредактируйте до самого необходимого. Добавьте .claude/settings.json с правилами allow/deny, подходящими для вашего стека. Создайте одну-две команды для workflows, которые вы делаете чаще всего. По мере роста проекта начните разбивать инструкции на файлы в .claude/rules/. Добавьте ~/.claude/CLAUDE.md с личными предпочтениями.

Это всё, что нужно для 95% проектов. Скилы и агенты приходят тогда, когда есть повторяющиеся сложные workflows, стоящие упаковки. CLAUDE.md – ваш файл с наибольшим рычагом. Начните с него. Всё остальное – оптимизация.