⚡ Продвинутый · Архитектура

Иерархия конфигов

Три уровня конфигурации Claude Code — от глобального до стека. Паттерн DRY: общее один раз, специфичное рядом с кодом.

3 уровня override-правила Laravel · FastAPI · Nuxt

#📐 Универсальный паттерн: три уровня

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.md читается при запуске из любой подпапки.
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.

Частая ошибка новичков

settings.local.json предназначен для личных настроек, которые не должны попасть в git — API-ключи, локальные пути, docker socket. Убедитесь что он добавлен в .gitignore. Если вы случайно закоммитили его с API-ключом — ключ нужно немедленно отозвать в console.anthropic.com.

#⚡ Правила приоритета

Когда одно и то же настраивается на нескольких уровнях, выигрывает самый конкретный (нижний) уровень.

Уровень 1 / 2		Уровень 2 / 3 (побеждает)
`~/.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	+	Проектный: добавляет 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 Key, локальный путь к 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 стек

🔴 PHP-специфичные правила

laravel-project/CLAUDE.md

Тестирование: Pest с фабриками, не phpunit напрямую. Feature тест на каждый endpoint.

Архитектура: Service layer обязателен. Controllers — тонкие. Eloquent в репозиториях.

Форматирование: Pint после каждого PHP файла. Конфиг: pint.json в корне проекта.

Миграции: Только additive-изменения. Никаких dropColumn без review.

🔌 Стек-специфичные MCP

laravel-project/.mcp.json

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-специфичные правила

python-etl/CLAUDE.md

Форматирование: 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. Никаких глобальных переменных состояния.

🔌 Только postgres, без laravel-boost

python-etl/.mcp.json

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": {
    "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 *)"
    ]
  }
}

#⚠️ Антипаттерны — что не делать

✗ ПлохоАнтипаттерны

Один CLAUDE.md в корне с 500 строками для всех стеков
MCP laravel-boost подключён глобально — нагружает Python-проекты
API Key в settings.json (не local) — попадут в git
Дублировать Caddy/proxy правила в каждом проектном CLAUDE.md
Хранить hooks в проектной папке — при смене проекта потеряются
Разные версии правил без понимания приоритета

✓ ХорошоBest Practices

Короткий корневой CLAUDE.md + детальные проектные
MCP только там, где нужен — экономит токены
Секреты в settings.local.json + .gitignore
Proxy-правила один раз в корневом CLAUDE.md
Все hooks в ~/.claude/helpers/ — работают везде
Добавлять настройки на самый нижний подходящий уровень

#🔍 Диагностика: почему Claude не читает нужный конфиг

# Посмотреть какие настройки реально применились
claude config

# Посмотреть активные MCP серверы
claude mcp list

# Файл не читается? Проверить кодировку (должна быть 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 применяются?». Это самый быстрый способ убедиться, что иерархия настроена правильно.