Claude code настройка проекта начинается с трёх вещей: файла CLAUDE.md с контекстом, конфигурации разрешений и списка внешних инструментов. Такая структура экономит время на повторных объяснениях и не даёт агенту случайно полезть в закрытые папки. Я, Арина Михална, покажу это на одном сквозном примере: проекте с тестами, миграциями и подключённым MCP-сервером.

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

3 типаосновных файлов проекта
20–40 строкрабочий размер памятки

Хаотичная папка проекта без структуры конфигов Claude Code рядом с аккуратной

Claude code настройка проекта: из чего она состоит

Если открыть рабочий репозиторий, в корне может быть такой набор:

  • CLAUDE.md — файл памяти, который Claude Code читает при запуске в проекте.
  • .Claude/settings.json — общие настройки команды: разрешения, модель и хуки.
  • .Claude/settings.local.json — личные настройки, которые не нужны коллегам.
  • .mcp.json — список MCP-серверов: базы данных, Figma, Notion или другие интеграции.
  • .Claude/commands/ — собственные slash-команды.
  • .Claude/agents/ — описания агентов под отдельные подзадачи.

Ничего не нужно заводить всё сразу. Для маленького скрипта хватит CLAUDE.md. Для командного проекта добавляются общие настройки и команды. MCP появляется только тогда, когда агенту действительно нужен внешний источник данных.

Файл Где лежит Что делает Когда добавлять
CLAUDE.md корень проекта Контекст, правила, стек и команды В начале работы
settings.json .Claude/settings.json Разрешения, модель и хуки При командной настройке
settings.local.json .Claude/settings.local.json Личные параметры Когда локальные настройки отличаются
.mcp.json корень проекта Подключает внешние инструменты При работе с MCP
commands/*.md .Claude/commands/ Даёт собственные slash-команды Для повторяющихся сценариев
agents/*.md .Claude/agents/ Описывает агентов под роли Когда задач становится несколько

Сквозной пример будет таким: у нас веб-проект, где исходники лежат в src/, тесты запускаются через npm run test, миграции находятся в migrations/, а каталог secrets/ нельзя читать без отдельного разрешения. Уже из этого можно собрать полезную конфигурацию.

CLAUDE.md: файл, который задаёт контекст

CLAUDE.md — не презентация проекта и не место для всей истории легаси. Это памятка для агента: какой стек используется, какие команды запускать, где лежат важные файлы и какие действия запрещены.

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

У меня однажды этот файл разросся до простыни на три экрана: история проекта, причины старых решений, извинения за легаси и немного лирики про дедлайны. Агенту от этого не стало умнее. Рабочая версия обычно укладывается примерно в 20–40 строк:

# Проект

Веб-приложение на {{стек и версии}}.

## Команды

- `npm run dev` — локальный запуск
- `npm run test` — тесты
- `npm run build` — сборка

## Структура

- `src/` — исходный код
- `tests/` — тесты
- `migrations/` — миграции базы данных
- `secrets/` — закрытые файлы, не читать и не изменять

## Правила

- Перед изменением миграций сначала покажи план.
- Не меняй публичный API без теста.
- После правки запускай `npm run test`.
- Не добавляй секреты в код и git.

Здесь есть конкретный стек, команды, структура и ограничения. Нет фразы «пиши качественный код» — она не помогает принять ни одного решения.

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

Схема из трёх конфигов Claude Code: CLAUDE.md, settings.json и .mcp.json

Памятка проекта — только половина настройки, дальше нужно не дать агенту трогать опасные места.

В канале я разбираю реальные конфиги и показываю, какие ограничения оставляю в рабочих проектах:

подписаться на канал и забрать разборы

Claude code конфигурация: settings.json и права доступа

settings.json отвечает на вопрос: что Claude Code может делать без дополнительного подтверждения, а где должен остановиться и спросить.

Например, чтение файлов проекта обычно можно разрешить, а удаление, запуск неизвестной команды или работу с папкой secrets/ оставить под подтверждением. Конкретные разрешения зависят от проекта, поэтому бездумно копировать чужой файл не стоит.

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

Минимальный принцип настройки такой:

  1. Оставь безопасные операции доступными.
  2. Опасные действия переведи в режим подтверждения.
  3. Закрой доступ к секретам и личным файлам.
  4. После изменения кода запускай автоматическую проверку.
  5. Проверь конфиг на чистой копии проекта.

Честный минус: настройки не делают агента безопасным сами по себе. Если разрешить слишком много, красивый settings.json не спасёт от плохой команды или вредного файла из внешнего источника. Конфиг снижает количество случайных действий, но не отменяет ревью.

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

.mcp.json и Claude code workspace для нескольких проектов

MCP-серверы подключают Claude Code к внешним данным и действиям: базе, документации, Figma или Notion. Список серверов проекта хранится в .mcp.json. В этот файл не стоит записывать секреты напрямую: ключи лучше передавать через переменные окружения.

Пример структуры проекта:

my-project/
├── CLAUDE.md
├── .mcp.json
├── .gitignore
├── .claude/
│   ├── settings.json
│   ├── settings.local.json
│   ├── commands/
│   └── agents/
├── src/
├── tests/
├── migrations/
└── secrets/

Про Claude code workspace: если ты работаешь с несколькими проектами одновременно, у каждого должна быть своя корневая папка, свой CLAUDE.md и свои локальные настройки. Не смешивай рабочие правила клиента А с проектом клиента Б. Агент видит текущий контекст, а не твою красивую мысленную карту всех репозиториев.

Общие правила можно вынести в глобальный конфиг в домашней директории. Специфику проекта оставляй рядом с кодом: команды, структуру каталогов, ограничения и требования к тестам.

Если тема MCP тебе незнакома целиком, я отдельно писала, что такое MCP у Claude и зачем оно нужно, там разбор с примерами.

Однажды я забыла добавить общий .mcp.json в репозиторий. Коллега открыл проект, а агент не видел базу данных. Полдня переписки свелось к вопросу: «а у тебя точно установлен Claude Code?» Мораль простая: общий конфиг должен жить с проектом, личные пути и токены — отдельно.

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

Что кладём, а что не коммитим в git

Правило для командного проекта:

  • Коммитим: CLAUDE.md, общие настройки, .Claude/commands/, .Claude/agents/, .mcp.json без секретов.
  • Не коммитим: settings.local.json, токены, API-ключи, личные пути к папкам и содержимое secrets/.

В .gitignore можно добавить:

.claude/settings.local.json
.env
.env.*
secrets/

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

Перед первым общим коммитом пройди проект по короткому маршруту:

  1. Открой CLAUDE.md и убери лишнюю историю.
  2. Проверь, что команды из файла действительно запускаются.
  3. Посмотри, нет ли токенов в .mcp.json.
  4. Убедись, что личный конфиг добавлен в .gitignore.
  5. Запусти Claude Code из корня проекта и попроси кратко перечислить правила, которые он увидел.
  6. Дай небольшую задачу и проверь, не полез ли агент в закрытые каталоги.

Итоговая структура файлов проекта Claude Code: CLAUDE.md, .Claude и .mcp.json в дереве папок

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

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

По материалам: официальная документация Claude Code Anthropic и рекомендации Anthropic по работе с Claude Code. Факты о чтении CLAUDE.md, структуре скиллов и работе Claude Code взяты из документации Anthropic.

Читайте также

Конфиги настроены, теперь нужны живые примеры того, как ими пользоваться в работе.

В Telegram-канале «А.М. решает вопросы» я показываю рабочие файлы, разбираю ошибки и выкладываю практические настройки без причёсанной теории: .

зайти в канал и забрать материалы