03 / 06 · Продвинутый

⚙️ Преднастроенные конфиги Claude Code

Подготовь CC под стек до первого промпта — CLAUDE.md, permissions, MCP, hooks и скелет доков как переиспользуемые шаблоны, а не как то, что придумывается на ходу.

📐

Часть группы «Проектирование» — обзор на Большая проектная документация.

⚙️ Ключевая мысль

Без преднастройки агент первые часы работы над проектом «угадывает» конвенции: какой тест-раннер использовать, можно ли трогать миграции, где лежат компоненты, каким стилем писать код. Часть догадок окажется неверной — и это правки постфактум, потерянное время, а иногда откат уже закоммиченного изменения. Преднастроенный шаблон под конкретный стек переворачивает порядок: агент с первого промпта работает как участник команды, который прочитал онбординг-документ, а не как новичок, который методом проб нащупывает правила проекта.

Состав преднастройки

Шесть компонентов закрывают разные слои: что агенту можно делать, что он обязан знать, чем пользоваться и что проверять автоматически.

Компонент	Зачем	Когда обязателен
`CLAUDE.md`	Конвенции проекта, точные команды (тест/линт/сборка), явные запреты — то, что агент обязан знать в каждой сессии	Всегда, для любого проекта без исключений
`.claude/settings.json`	Права доступа (`permissions.allow/deny`) — что агент может выполнять без подтверждения, что запрещено категорически	Обязателен при работе с продакшен-данными, платежами, миграциями без отката
`.mcp.json`	MCP-серверы под стек — доступ к реальному состоянию приложения (БД, роуты, доки) вместо пересказа руками	Обязателен, если для стека есть готовый MCP (Laravel Boost, context7, playwright)
hooks	Автопроверки на события агента — форматирование после правки файла, прогон тестов перед коммитом	Желателен везде; обязателен там, где есть жёсткий стайлгайд (Pint, ESLint)
`.claude/commands`	Slash-команды проекта — типовые многошаговые операции, зафиксированные один раз (например, деплой, генерация отчёта)	По необходимости — для проектов с повторяющимися ритуалами
Скелет `docs/`	Заготовки `spec.md`, `PLAN.md` — структура, в которую агент и человек сразу пишут, а не изобретают на ходу	Обязателен для среднего-крупного проекта под ключ, см. проектную документацию

Чек-лист: преднастройка перед стартом на стеке

☐ CLAUDE.md содержит стек, точные версии и команды теста/линта — не общие фразы, а конкретные вызовы
☐ .claude/settings.json настроен точечными allow/deny — без постоянного --dangerously-skip-permissions
☐ MCP под стек подключён и реально отвечает (проверено первым вызовом, а не «должен работать»)
☐ Hooks настроены хотя бы на автоформатирование и/или прогон тестов на значимых событиях
☐ Скелет docs/ создан — есть куда писать spec и план, не только код
☐ Итоговый шаблон сохранён отдельно для переиспользования на следующем проекте того же стека

Готовые шаблоны под 4 стека

Копируй и адаптируй под конкретный проект — это стартовые заготовки, а не готовые решения на все случаи. Секреты (.env, пароли, ключи) в шаблоны не входят — см. предупреждение ниже.

a) Laravel

Специфика: тест-раннер — Pest, а не PHPUnit-стиль; форматирование — Pint, обязательно перед коммитом; миграции — зона повышенного риска, трогать только по явному запросу; контроллеры тонкие, бизнес-логика в Service-слое.

# Стек
Laravel 12, PHP 8.3, MySQL, Pest (не PHPUnit-синтаксис)

# Команды
php artisan test          — прогон тестов
vendor/bin/pint           — форматирование, ОБЯЗАТЕЛЬНО перед коммитом
php artisan migrate       — только по явному запросу

# Конвенции
- Controller тонкий: валидация + вызов Service, без бизнес-логики внутри
- Бизнес-логика — в app/Services, не в моделях и не в контроллерах
- Eloquent-связи описывать явно, избегать N+1 (eager loading)

# Запреты
- НЕ трогать миграции без явного разрешения — необратимо на проде
- НЕ ослаблять и не удалять Pest-тесты, чтобы прогон стал зелёным
- НЕ коммитить без прогона vendor/bin/pint

php artisan boost:install
claude mcp add -s local -t stdio laravel-boost php artisan boost:mcp

Hook: PostToolUse на Edit для PHP-файлов → автозапуск vendor/bin/pint на изменённый файл. Подробнее про Boost — на странице Laravel Boost.

b) Python / FastAPI

Специфика: асинхронный код по умолчанию, строгая типизация через Pydantic v2, ruff вместо связки flake8+black+isort, pytest как единственный тест-раннер.

# Стек
Python 3.12, FastAPI, Pydantic v2, PostgreSQL (asyncpg)

# Команды
uvicorn app.main:app --reload   — локальный запуск
ruff check .                    — линт
ruff format .                   — форматирование
pytest                          — тесты

# Конвенции
- Async-first: эндпоинты и I/O — async def, не блокирующий код
- Типы обязательны везде — функции, Pydantic-модели, возвращаемые значения
- Схемы запрос/ответ — отдельные Pydantic-модели, не сырые dict
- Зависимости — через Depends(), не глобальные синглтоны

# Запреты
- НЕ использовать pydantic v1 синтаксис (проект на v2)
- НЕ коммитить без ruff check . без ошибок

claude mcp add -s local -t stdio context7 npx -y @upstash/context7-mcp

Hook: PostToolUse на Edit/Write для *.py → ruff check на изменённые файлы, чтобы ловить нарушения сразу, а не на коммите.

c) 1С-Битрикс

Специфика: ядро D7 вместо старого процедурного API, весь кастом — в local/, ядро bitrix/ не трогать никогда, доступ к БД — через D7 ORM, а не сырой SQL.

# Стек
PHP 8.x, 1С-Битрикс, ядро D7 (не устаревший процедурный API)

# Конвенции
- Весь кастомный код — в local/ (модули, компоненты, php_interface)
- Работа с БД — через D7 ORM (Bitrix\Main\...\Table), не CDatabase/сырой SQL
- Обработчики событий и агенты — регистрировать в local/php_interface/init.php
- Компоненты — копировать в local/components перед правкой, не редактировать в bitrix/

# Запреты
- НЕ трогать и НЕ редактировать файлы внутри bitrix/ — ядро, слетит при обновлении
- НЕ использовать устаревшие CIBlockElement/CDatabase в новом коде — только D7

# Важно
Модель хуже знает специфику Битрикса, чем «обычный» PHP-фреймворк —
давай примеры кода из local/ этого проекта как образец стиля, не полагайся
на то, что Claude «и так знает, как принято в Битриксе».

claude mcp add -s local -t stdio context7 npx -y @upstash/context7-mcp
claude mcp add -s local -t stdio fetch npx -y @modelcontextprotocol/server-fetch

Hook: без готового официального форматтера под D7 — как минимум запрет коммита файлов из bitrix/ через PreToolUse-проверку пути.

d) Фронтенд (Vite + vanilla/Vue)

Специфика: сборка через Vite, ESLint+Prettier как единый источник стиля, компоненты живут в едином месте, методологию стилей (BEM или Tailwind) фиксировать явно — иначе агент будет чередовать подходы в одном проекте.

# Стек
Vite, Vue 3 (Composition API), ESLint + Prettier

# Команды
npm run dev      — локальный сервер разработки
npm run build     — продакшен-сборка
npm run lint       — ESLint-проверка

# Конвенции
- Компоненты — в src/components, один компонент = один файл
- Стили — Tailwind-классы в разметке, БЕЗ отдельных BEM-модулей (проектное решение)
- Composition API (