🗂️ Иерархия конфигов
Три уровня конфигурации Claude Code — от глобального до стека. Паттерн DRY: общее один раз, специфичное рядом с кодом.
📐 Универсальный паттерн: три уровня
Claude Code читает конфиги по каскаду. Нижние уровни дополняют и переопределяют верхние. Знать этот порядок критично — иначе непонятно, почему Claude ведёт себя не так, как ожидается.
1
🌐 Глобальный уровень
для всех проектов
~/.claude/ (C:\Users\Имя\.claude\)
Настройки применяются всегда, в любом проекте, в любой папке.
Здесь — то, что неизменно для всей рабочей станции: модель по умолчанию,
глобальные permissions, базовые hooks, MCP-серверы которые нужны везде.
settings.json
settings.local.json
helpers/*.cjs
CLAUDE.md
2
📁 Корень монорепо / workspace
для всех стеков
E:\Clients\ (или корень git-репо)
Правила, общие для всей команды / монорепо: код-стандарты, запрещённые операции,
доменные правила.
CLAUDE.md в этой папке — «командный договор».
Claude читает его при запуске из любой подпапки.
CLAUDE.md
.claude/settings.json
PORTS.md
3
🔧 Папка стека / проекта
специфично для технологии
E:\Clients\my-laravel-app\ (конкретный проект)
Стек-специфичные MCP, инструменты форматирования, правила архитектуры.
Переопределяет только то, что нужно для этого стека — остальное наследует
с верхних уровней. Каждая технология знает о себе больше.
CLAUDE.md
.mcp.json
pint.json
ruff.toml
eslint.config.js
Порядок чтения CLAUDE.md:
Файлы читаются снизу вверх и конкатенируются. Claude видит сначала глобальный,
потом корневой, потом проектный. Поздние правила не перезаписывают ранние —
они дополняют. Конкретность проектного CLAUDE.md перевешивает через контекст,
а не через override.
⚡ Правила приоритета
Когда одно и то же настраивается на нескольких уровнях, выигрывает самый конкретный (нижний) уровень.
⚖️ Примеры слияния настроек
~/.claude/settings.json: model=opus
→
.claude/settings.json в проекте: model=sonnet ✓
Глобальный .mcp.json: postgres-mcp
+
Проектный .mcp.json: laravel-boost + postgres-mcp (оба работают) ✓
Глобальный CLAUDE.md: «всегда Pest для PHP»
+
Проектный CLAUDE.md добавляет: «и Service pattern» (конкатенация) ✓
Глобальный allowedTools: Bash, Read, Write
+
Проектный allowedTools: добавляет mcp__laravel__* (merge, не replace) ✓
🤔 Что куда класть: правила выбора
?
Нужно это во всех проектах на машине?
→ Глобальный
~/.claude/settings.json. Пример: модель по умолчанию, cost-tracker hook, secret-scanner hook.?
Нужно всем разработчикам в команде / всем стекам монорепо?
→
CLAUDE.md и .claude/settings.json в корне репо. Пример: запрет на миграции без подтверждения, список портов, proxy-правила.?
Специфично для одного стека (Laravel, FastAPI, Nuxt)?
→
.mcp.json и CLAUDE.md в папке проекта. Пример: laravel-boost MCP только для Laravel, ruff только для Python.?
Только для меня локально (не в git)?
→
settings.local.json (добавить в .gitignore). Пример: личные API ключи, локальный путь к docker socket.?
MCP-сервер нужен только в конкретном проекте?
→
.mcp.json в папке проекта (не в глобальном settings). Это изолирует инструменты и не нагружает контекст других проектов.🏗️ Реализация для Laravel / FastAPI / Windows-стека
Структура E:\Clients\ — монорепо с тремя стеками. Каждый стек имеет свою папку с изолированными конфигами, но все используют общий Caddy proxy и базовые hooks.
E:\Clients\
├── CLAUDE.md ← уровень 2: общие правила для всех стеков
├── PORTS.md ← актуальный список портов проектов
├── .claude\
│ ├── settings.json ← глобальные permissions + hooks
│ ├── settings.local.json ← docker-mcp + ruflo (не в git)
│ └── helpers\
│ ├── dangerous-command-guard.cjs
│ ├── bash-mcp-guard.cjs
│ ├── secret-scanner.cjs
│ ├── critical-files-guard.cjs
│ ├── auto-format.cjs
│ └── cost-tracker.cjs
│
├── Windows\
│ └── proxy\ ← Caddy reverse proxy (общий для всех)
│
├── projects\
│ ├── laravel-project\ ← Уровень 3: Laravel стек
│ │ ├── CLAUDE.md ← PHP/Laravel правила
│ │ ├── .mcp.json ← laravel-boost + postgres-mcp
│ │ ├── pint.json ← форматирование PHP
│ │ └── examples\ ← примеры кода для Claude
│ │
│ ├── nuxt-frontend\ ← Уровень 3: Vue/Nuxt стек
│ │ ├── CLAUDE.md ← Vue/Nuxt/TypeScript правила
│ │ └── .mcp.json ← chrome-devtools MCP
│ │
│ └── python-etl\ ← Уровень 3: Python стек
│ ├── CLAUDE.md ← FastAPI/Python правила
│ └── .mcp.json ← postgres-mcp (без laravel-boost)
Уровень 2 — корневой CLAUDE.md (общий для всех стеков)
## Сервер и инфраструктура
- RAM: 47 GB, OS: Windows Server 2025, Docker: WSL2-бэкенд
- Reverse proxy: Caddy в E:\Clients\Windows\proxy (порты 80/443)
- Актуальные порты проектов: E:\Clients\PORTS.md
## Безопасность — всегда
- НИКОГДА не запускать DROP TABLE / migrate:fresh без явного подтверждения
- НИКОГДА не коммитить .env, credentials, API ключи
- Все docker-команды — через MCP, не через bash (hook блокирует)
## Код-стандарты (общие)
- Новые функции = новые тесты
- Коммиты: feat/fix/chore, не "update" или "changes"
- Все файлы — UTF-8 без BOM
Уровень 3 — Laravel стек
laravel-project/CLAUDE.md
PHP-специфичные правила
Тестирование
Pest с фабриками, не phpunit напрямую. Feature тест на каждый endpoint.
Архитектура
Service layer обязателен. Controllers — тонкие. Eloquent в репозиториях.
Форматирование
Pint после каждого PHP файла. Конфиг: pint.json в корне проекта.
Миграции
Только additive-изменения. Никаких dropColumn без review.
laravel-project/.mcp.json
Стек-специфичные MCP
laravel-boost
Artisan команды, роуты, модели через MCP без bash
postgres-mcp
Read-only доступ к БД. Роль claude_readonly с REVOKE ALL.
{
"mcpServers": {
"laravel": {
"command": "npx",
"args": ["-y", "@laravel/mcp-server"],
"env": { "LARAVEL_PROJECT_PATH": "." }
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://claude_readonly:pass@localhost:5432/mydb"
}
}
}
}
Уровень 3 — Python/FastAPI стек
python-etl/CLAUDE.md
Python-специфичные правила
Форматирование
Ruff после каждого .py файла. Mypy для type hints.
Тесты
pytest-asyncio для async кода. Coverage ≥ 80%.
ETL-операции
Перед массовым UPDATE: SET max_parallel_workers_per_gather=1
FastAPI
Pydantic v2. Dependency injection через Depends. Никаких глобальных переменных состояния.
python-etl/.mcp.json
Только postgres, без laravel-boost
postgres-mcp
Тот же сервер что в Laravel, но с другой строкой подключения (другая БД)
Нет laravel-boost
Artisan-команды Python-проекту не нужны. Меньше MCP = меньше токенов.
Уровень 3 — Vue/Nuxt фронтенд
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["-y", "@chrome-devtools/mcp-server"],
"env": { "CHROME_DEBUG_PORT": "9222" }
}
}
}
Почему chrome-devtools только в nuxt-frontend?
MCP с Chrome нужен только когда Claude дебажит SSR/гидратацию или тестирует UI.
Подключать его к Python-проекту — лишний шум и токены без пользы.
Изоляция по стекам — ключевой принцип.
🌐 Уровень 1 — глобальный settings.json
Три категории настроек: всегда-активные, стоимость/безопасность, hooks.
{
"model": "sonnet",
"alwaysThinkingEnabled": true,
"env": {
"MCP_TOOL_SEARCH": "1",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "400000",
"DISABLE_TELEMETRY": "1",
"COST_ALERT_THRESHOLD": "5"
},
"permissions": {
"allow": [
"Bash(git:*)",
"Bash(npm:*)",
"Bash(node:*)",
"Read(**)",
"Write(**)",
"Edit(**)",
"mcp__docker__*"
],
"deny": [
"Bash(docker:*)",
"Bash(rm -rf *)",
"Bash(format *)",
"Bash(diskpart *)"
]
},
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "node C:/Users/Имя/.claude/helpers/dangerous-command-guard.cjs" },
{ "type": "command", "command": "node C:/Users/Имя/.claude/helpers/bash-mcp-guard.cjs" },
{ "type": "command", "command": "node C:/Users/Имя/.claude/helpers/secret-scanner.cjs" }
]
},
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{ "type": "command", "command": "node C:/Users/Имя/.claude/helpers/critical-files-guard.cjs" }
]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{ "type": "command", "command": "node C:/Users/Имя/.claude/helpers/auto-format.cjs" }
]
}
],
"Stop": [
{
"matcher": ".*",
"hooks": [
{ "type": "command", "command": "node C:/Users/Имя/.claude/helpers/cost-tracker.cjs" }
]
}
]
}
}
{
"mcpServers": {
"docker": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-docker"],
"env": { "DOCKER_HOST": "npipe:////./pipe/docker_engine" }
}
}
}
⚠️ Антипаттерны — что не делать
✗ Плохо
- Один CLAUDE.md в корне с 500 строками для всех стеков
- MCP laravel-boost подключён глобально — нагружает Python-проекты
- API ключи в settings.json (не local) — попадут в git
- Дублировать Caddy/proxy правила в каждом проектном CLAUDE.md
- Хранить hooks в проектной папке — при смене проекта потеряются
- Разные версии правил на разных уровнях без понимания приоритета
✓ Хорошо
- Короткий корневой CLAUDE.md + детальные проектные
- MCP только там, где нужен — экономит токены и ускоряет старт
- Секреты в settings.local.json + .gitignore
- Proxy-правила один раз в корневом CLAUDE.md
- Все hooks в ~/.claude/helpers/ — работают везде
- Добавлять настройки на самый нижний подходящий уровень
🔍 Диагностика: почему Claude не читает нужный конфиг
# Посмотреть какие настройки реально применились
claude config
# Посмотреть активные MCP серверы
claude mcp list
# Проверить нет ли конфликтов — попросить Claude самого
# "Покажи какие CLAUDE.md ты читаешь в этой сессии"
# Файл не читается? Проверить кодировку (должна быть UTF-8)
file E:\Clients\projects\laravel\CLAUDE.md
# Где находится глобальный settings.json
echo %USERPROFILE%\.claude\settings.json
Частая ошибка: запустить Claude из папки C:\ вместо проектной папки.
Тогда проектный .mcp.json не читается. Всегда запускать
claude
из папки конкретного проекта или передавать путь явно.
Проверить что всё работает: откройте Claude в каждом проекте и попросите
"Список MCP серверов, которые ты видишь" и "Какие правила из CLAUDE.md применяются?".
Это самый быстрый способ убедиться, что иерархия настроена правильно.