Структура проекта: что Claude Code помещает в ваш проект
📚 Навигация по серии: В предыдущей части 12 Инициализация проекта вы запустили
/initи создали первыйCLAUDE.mdдля проекта. В этой части продолжим — посмотрим, что находится в той папке.claude/, которая появилась после/init: что в ней хранится, кто ею управляет и нужно ли добавлять её в git.
Все говорят, что папка .claude «не требует внимания, она сама всем управляет», но честно говоря, понять её — значит по-настоящему освоить Claude Code.
Почему? Потому что почти все «продвинутые возможности» этого инструмента — пользовательские команды, управление правами, субагенты, навыки — хранятся на диске именно в виде нескольких файлов и папок внутри .claude/. Не понимая структуру, вы будете беспомощны перед вопросами «почему мои права не применились» или «коллега получил код, но у него нет моих команд».
Когда я только начинал, я сделал одну глупость: ради удобства записал конфигурацию с паролем базы данных прямо в .claude/settings.json и отправил её через git push. Когда я спохватился, ключ уже лежал в истории репозитория — пришлось менять пароль и переписывать историю, что заняло больше получаса. Потом я понял, что такие вещи должны храниться в settings.local.json — этот файл Claude Code по умолчанию добавляет в gitignore. Одна неправильно выбранная папка для файла — и вот в чём разница.
В этой части я не буду учить вас детально настраивать каждый файл (это оставим для специальных глав), а сделаю одно: дам вам полную карту, чтобы, взглянув на любой файл, вы сразу понимали «что это, где находится, относится ли к проекту или ко мне лично, и нужно ли его коммитить».
После прочтения вы получите:
- Полную карту директории
.claude/: за что отвечает каждый файл / поддиректория - Принципиальное различие между «уровнем проекта» и «уровнем пользователя» (следует за проектом vs следует за вами)
- Шпаргалку: что коммитить в git, что обязательно добавлять в
.gitignore - Практическое упражнение, чтобы наглядно увидеть эти два уровня директорий
01 Сначала поймите одно: у Claude Code есть «два дома»
Главный вывод: конфигурация Claude Code распределена по двум местам — одна следует за проектом, другая следует за вами. Поняв это, вы разберётесь во всём остальном.
Аналогия: «архив проекта» компании и ваш «личный ящик стола». В архиве проекта хранится то, что нужно видеть всем участникам — правила проекта, кто что может делать; новый человек придёт и сразу разберётся по материалам архива. В вашем ящике стола хранятся личные привычки — удобные для вас ярлыки, личные предпочтения, которые следуют за вами из проекта в проект.
На диске это соответствует двум расположениям:
| Уровень | Где | На кого влияет | Кому принадлежит |
|---|---|---|---|
| Уровень проекта (Project) | ./.claude/ внутри проекта | Все участники этого репозитория | Следует за проектом (коммитится в git, общий для команды) |
| Уровень пользователя (User) | ~/.claude/ в вашей домашней директории | Вы, во всех ваших проектах | Следует за вами (на вашей машине, никогда не коммитится) |
Два ключевых понятия:
Уровень проекта (Project scope): конфигурация хранится в репозитории, попадает в git и shared для всей команды. Вы изменили правило, закоммитили — коллеги сразу видят обновление.
Уровень пользователя (User scope): конфигурация хранится в ~/.claude/ на вашем компьютере, влияет только на вас и никогда не попадает ни в какой репозиторий. При переходе на любой другой проект компании эта конфигурация следует за вами.
Типичный пример использования: личные предпочтения — «отвечать на русском», «использовать определённый префикс для commit-сообщений» — хранятся на уровне пользователя в ~/.claude/CLAUDE.md. Тогда Claude будет следовать вашим привычкам в любом проекте. А факты проекта — «в этом проекте используется pnpm, а не npm» — пишутся в проектный ./CLAUDE.md, коммитятся и доступны всей команде. Личные привычки и правила проекта — с самого начала в разных местах, без лишних хлопот в будущем.
💡 Итог в одном предложении: У Claude Code есть «два дома» — проектный
./.claude/(следует за проектом, в git, общий для команды) и домашний~/.claude/(следует за вами, не в git, только для вас).
02 Открываем проектный .claude/: что там?
Давайте заглянем в папку ./.claude/ проекта. У активно используемого проекта структура выглядит примерно так:
your-project/
├── CLAUDE.md ← Описание проекта (можно также разместить в .claude/CLAUDE.md)
├── CLAUDE.local.md ← Ваши личные предпочтения по проекту (добавьте в .gitignore)
├── .mcp.json ← Конфигурация MCP-серверов для команды (в git)
└── .claude/
├── settings.json ← Общая конфигурация команды: права, хуки, значения модели по умолчанию
├── settings.local.json ← Ваши личные переопределения конфигурации (автоматически в gitignore)
├── commands/ ← Пользовательские команды с косой чертой, каждый .md — одна /команда
├── rules/ ← Модульные правила проекта (вынесены из CLAUDE.md)
├── skills/ ← Навыки: рабочие процессы, вызываемые через / или автоматически Claude
└── agents/ ← Субагенты: специализированные помощники с независимым контекстомОбъясню, что делает каждый элемент. В этой части только обозначаем «что это и кому принадлежит», детали — в специальных главах:
CLAUDE.md — описание проекта. Первый файл, который читает Claude при каждом входе в проект. Здесь записано, что представляет собой проект, как его запускать, какие есть соглашения. Ключевое различие с .claude/settings.json: CLAUDE.md — это «инструкция» для Claude (он читает и старается следовать, но без жёсткого принуждения), settings.json — это «конфигурация», которую Claude Code применяет принудительно.
Официально отмечено:
CLAUDE.mdможет находиться как в корне проекта, так и в.claude/CLAUDE.md— второй вариант делает корень проекта чище.
CLAUDE.local.md — ваши личные предпочтения по проекту. Инструкции поверх CLAUDE.md, относящиеся только к вам, например «мой локальный порт базы данных — 5433». Нужно вручную добавить в .gitignore (при запуске /init с личными настройками это делается автоматически).
settings.json — центральная конфигурация команды. Управляет тем, может ли Claude выполнять определённые операции (права), какие скрипты запускать в определённые моменты (хуки), а также позволяет задать модель по умолчанию для проекта. Попадает в git, является базовой линией безопасности команды.
settings.local.json — ваши личные переопределения конфигурации. Тот же формат JSON, но влияет только на вас и не коммитится. Если вы хотите временно расширить права, не затрагивая коллег, пишите сюда. Когда Claude Code впервые создаёт этот файл, он автоматически настраивает игнорирование в git — именно тот файл, который я в начале не использовал и забыл.
Важная деталь: игнорирующее правило добавляется в ваш глобальный
~/.config/git/ignore(не в.gitignoreпроекта), поэтому вы не найдёте эту строку в.gitignoreпроекта. Чтобы все члены команды игнорировали его, добавьте строку вручную в.gitignoreпроекта.
commands/ — пользовательские команды со слешем. Каждый файл .md в директории становится командой /имя-файла. Сохраните часто используемые инструкции в файл, и вы сможете вызывать их нажатием /. Официально commands/ и skills/ объединены в единый механизм, и для новых команд рекомендуется использовать skills/ (поддерживает пакетирование дополнительных файлов). commands/ по-прежнему работает, но больше не является рекомендованным путём.
rules/ — модульные правила проекта. Когда CLAUDE.md становится слишком длинным (официально рекомендуется удерживать в пределах 200 строк), правила разбиваются по темам в несколько файлов в rules/, например testing.md, api-design.md.
skills/ — навыки. Каждый навык — это поддиректория с файлом SKILL.md. Его можно вызвать вручную через /имя-навыка или позволить Claude автоматически определять, когда его применять.
agents/ — субагенты. Каждый .md определяет специализированного помощника с независимым окном контекста, который не засоряет основной диалог. Подходит для параллельной работы или изолированных задач.
.mcp.json — конфигурация MCP-серверов для команды. Находится в корне проекта рядом с .claude/. MCP (Model Context Protocol) серверы можно настраивать в двух местах: здесь в .mcp.json для общего доступа команды в git, например инструменты баз данных или внутренние API, которые использует вся команда; личная конфигурация MCP (например, инструменты только для вас) хранится в ~/.claude.json и не попадает ни в один репозиторий. Разница: общий для проекта vs личный.
💡 Итог в одном предложении: В проектном
.claude/—CLAUDE.md/rules/это «инструкции» для Claude,settings.json— это «принудительная конфигурация» Claude Code, аcommands/skills/agents/— «расширения», которые вы для него установили.
03 Та же структура директорий есть и в ~/.claude/
Это самая запутывающая новичков вещь, но на самом деле самая простая: почти те же имена директорий из проектного уровня существуют и в пользовательском ~/.claude/.
commands/, rules/, skills/, agents/, CLAUDE.md, settings.json — они есть в проекте и в ~/.claude/. Разница только одна:
(В пользовательском ~/.claude/ есть и несколько директорий, которых нет на уровне проекта — themes/, keybindings.json, output-styles/, workflows/ и другие. Они будут описаны в специальных главах.)
Всё, что в ~/.claude/, применяется ко всем вашим проектам; всё, что в проектном ./.claude/, применяется только к этому проекту.
Два примера, и вы сразу поймёте:
- Команда
/commit-zh(генерирует commit-сообщение на русском), помещённая в~/.claude/commands/— будет доступна в любом проекте, не нужно настраивать заново для каждого. - Но команда «деплой в тестовую среду компании» явно относится только к одному проекту — её помещают в
.claude/commands/проекта и коммитят для использования всей командой.
Помимо этих «парных» директорий, в домашней директории ~/ есть ещё два только для пользовательского уровня файла, которые практически не требуют ручного редактирования:
| Файл / директория | Где | Что это | Нужно ли вам вмешиваться |
|---|---|---|---|
~/.claude.json | Домашняя директория | Состояние приложения: авторизация (OAuth-сессия), темы, личные MCP-серверы, записи доверия и предпочтения UI для каждого проекта | Практически не трогайте, изменяйте через /config |
~/.claude/projects/ | Пользовательский уровень | Истории сессий по проектам; автоматические воспоминания хранятся в поддиректории <проект>/memory/ | Не нужно писать, сам поддерживается |
Добавлю слово об автоматических воспоминаниях (auto memory): они отличаются от CLAUDE.md. CLAUDE.md — это ваши инструкции для Claude; автоматические воспоминания — это собственные заметки Claude (например, команды сборки, на которые он наткнулся, или ошибки, которые он допустил), хранящиеся в ~/.claude/projects/<проект>/memory/ и переиспользуемые между сессиями. Не путайте: первое пишете вы, второе пишет он.
💡 Итог в одном предложении: Директории
commands/skills/существуют на обоих уровнях — проектном и пользовательском, разница лишь в том, «управляет ли одним проектом» или «управляет всеми вашими проектами»;~/.claude.jsonи~/.claude/projects/принадлежат только пользовательскому уровню и практически не требуют ручного вмешательства.
04 Что коммитить в git, что никогда не коммитить
Этот раздел самый практичный — именно здесь я попал в ловушку с утечкой ключа в начале. Железное правило: всё с «local» в имени и всё с ключами — никогда не в git.
Почему одно коммитим, другое нет? Логика проста: общее для команды — коммитим, личное или относящееся только к вашей машине — не коммитим.
Аналогия: вещи из архива проекта регистрируются и хранятся (в git), личные вещи из ящика стола не сдаются.
Классифицируем общие файлы проекта по принципу «коммитить / не коммитить»:
| Файл / директория | В git? | Почему |
|---|---|---|
CLAUDE.md | ✅ Коммитим | Общее описание проекта для команды |
.claude/settings.json | ✅ Коммитим | Базовые права / конфигурация команды |
.claude/commands/*.md | ✅ Коммитим | Стандартизированные команды для повторного использования командой |
.claude/rules/*.md | ✅ Коммитим | Общие модульные правила команды |
.claude/skills/, .claude/agents/ | ✅ Коммитим | Общие навыки и субагенты команды |
.claude/settings.local.json | ❌ Не коммитим | Личные переопределения; Claude Code автоматически добавляет в gitignore |
CLAUDE.local.md | ❌ Не коммитим | Личные предпочтения по проекту; нужно вручную добавить в .gitignore |
| Любой файл с ключами / token / паролями | ❌ Никогда | Попасть в историю репозитория = утечка |
Несколько практических напоминаний:
settings.local.json не нужно самостоятельно добавлять в gitignore. Официально: Claude Code при создании этого файла автоматически настраивает игнорирование в git. Если вы хотите временно расширить права локально, пишите сюда — это надёжнее всего.
CLAUDE.local.md нужно добавить в .gitignore самостоятельно. В отличие от settings.local.json, он не игнорируется автоматически. При запуске /init с личными настройками это делается автоматически, иначе добавьте строку вручную.
Никогда не записывайте ключи напрямую в конфигурационные файлы. Официальная рекомендация — использовать переменные окружения в конфигурации, например ${GITHUB_TOKEN}, а не вставлять token в открытом виде. Claude Code при запуске читает их из окружения shell, token вообще не попадает в файл. Это правило без исключений.
💡 Итог в одном предложении: Общее для команды (
CLAUDE.md,settings.json,commands/и т.д.) — в git; всё с «local» и всё с ключами — никогда не коммитим.settings.local.jsonигнорируется системой автоматически,CLAUDE.local.md— нужно добавить вручную.
05 Конфликт конфигураций — кто главнее: приоритеты в одной картинке
Вы могли задуматься: если в пользовательском settings.json и проектном settings.json задан одинаковый параметр — кто побеждает?
Официальный порядок приоритетов (от высшего к низшему):
Managed (управляемый организацией, высший, никто не перекрывает)
↓
Аргументы командной строки (--permission-mode и подобные, только для текущей сессии)
↓
Local (settings.local.json)
↓
Project (проектный settings.json)
↓
User (пользовательский ~/.claude/settings.json, низший)Мнемоника: чем «конкретнее» и «ближе к текущей операции» — тем выше приоритет. Управляемый организацией > временно заданный в командной строке > локальный для проекта > общий для проекта > ваш глобальный по умолчанию.
На этом рисунке два дерева рядом: слева проектный ./.claude/ (следует за проектом, по необходимости в git для совместного использования командой), справа пользовательский ~/.claude/ (следует за вами, управляет всеми вашими проектами). Запомните, какое дерево чем управляет — и вы никогда не запутаетесь с расположением конфигурации.
Но здесь есть ловушка, на которую очень легко наступить: не все настройки следуют логике «переопределения»:
| Тип настройки | При наличии в нескольких областях | Пример |
|---|---|---|
| Скалярное значение (одиночное) | Берётся наиболее конкретное — переопределение | model: если задана в проекте, используется проектная |
| Массив (список) | Объединяется через области, без переопределения | permissions.allow: пользовательская + проектная + локальная суммируются |
Я сам попался на это: добавил команду в deny на пользовательском уровне, думая, что заблокирую её глобально, — а она продолжала работать в одном из проектов. Долго смотрел на конфигурацию и не мог понять. Потом понял: правила прав объединяются, а не переопределяются — если на уровне проекта разрешено, это сочетается с правилами пользовательского уровня. Поэтому не рассчитывайте заблокировать что-то «раз и навсегда» на пользовательском уровне — нужно разбираться в правилах объединения.
💡 Итог в одном предложении: Приоритет от высшего к низшему: Managed → командная строка → Local → Project → User; но важно понять —
modelи подобные скалярные значения «переопределяются», аpermissions.allowи подобные массивы «объединяются».
06 Практика: увидеть эти два уровня директорий своими глазами
Лучше один раз посмотреть. Следующий набор команд только читает, ничего не записывает, он абсолютно безопасен. Следуйте инструкциям, и вы разберётесь в «двух домах».
Шаг 1: Посмотрите пользовательский ~/.claude/ в домашней директории
Откройте терминал и выполните (Mac / Linux):
ls -a ~/.claudeВ Windows PowerShell:
dir $HOME\.claudeОжидаемый результат: вы увидите settings.json, projects, возможно commands, skills и другие. Конкретный состав зависит от глубины использования Claude Code. Если что-то есть в списке — пользовательский «дом» существует и работает.
Шаг 2: Посмотрите проектный .claude/ в каком-нибудь проекте
Перейдите в любой проект, в котором использовался Claude Code (если такого нет, вернитесь к предыдущей части и создайте его через /init):
ls -a .claudeОжидаемый результат: как минимум должен быть settings.local.json (если вы ранее одобряли права), возможно settings.json. Это «архив» уровня проекта, отдельный от домашнего.
Шаг 3: Проверьте, что settings.local.json действительно игнорируется git
В этом проекте (должен быть git-репозиторием):
git check-ignore .claude/settings.local.jsonОжидаемый результат: терминал выводит путь к файлу (.claude/settings.local.json) — это доказывает, что git его игнорирует. Это именно то, что Claude Code делает автоматически. Если вывода нет — файл не игнорируется, лучше добавьте строку в .gitignore вручную.
Шаг 4 (необязательно): Взглянуть на описание проекта
cat CLAUDE.md(В Windows PowerShell: type CLAUDE.md)
Ожидаемый результат: выводится содержимое, сгенерированное в предыдущей части через /init. Это первый файл, который Claude читает при каждом входе в проект — теперь вы знаете, где он находится.
⚠️ Напоминание:
git check-ignoreимеет смысл только в git-репозитории. Если проект ещё не инициализирован черезgit init, команда выдастfatal: not a git repository. Сначала инициализируйте репозиторий.
💡 Итог в одном предложении:
ls -a ~/.claude— пользовательский уровень,ls -a .claude— проектный,git check-ignore .claude/settings.local.json— проверка игнорирования. Три команды только для чтения, и вы сразу разберётесь в «двух домах» и «что игнорирует git».
07 Итог
В этой части мы разобрали «содержимое» того, что Claude Code размещает в вашем проекте. Краткое резюме:
| Что запомнить | Конкретика |
|---|---|
| Два дома | Проектный ./.claude/ (следует за проектом, в git) + домашний ~/.claude/ (следует за вами, не в git) |
| Инструкция vs конфигурация | CLAUDE.md / rules/ — инструкции для Claude; settings.json — принудительно применяемая конфигурация |
| Парные директории | commands/ skills/ agents/ — по одному экземпляру на проектном и пользовательском уровне; разница — один проект vs все |
| Красные линии git | Всё с «local» и с ключами — никогда не коммитим; settings.local.json игнорируется системой автоматически |
| Приоритет | Managed → командная строка → Local → Project → User; скалярные переопределяются, массивы объединяются |
Теперь вы можете: открыть любой проект, взглянуть на файл в .claude/ и сразу понять, что это, принадлежит проекту или вам лично, нужно ли его коммитить; а также знаете, кто «побеждает» при конфликте конфигураций. Эта полная карта — основа всех последующих специальных глав. Когда будете изучать детальную настройку settings.json, написание CLAUDE.md или создание навыков и субагентов — вы всегда сможете найти их место на этой карте.
Следующая часть 14 «Интерфейс и горячие клавиши» — статическую карту структуры директорий мы разобрали, теперь пора познакомиться с «панелью управления» Claude Code. В следующей части вы узнаете каждый блок интерфейса и выработаете мышечную память для самых используемых горячих клавиш, чтобы работать быстро и уверенно.