Claude Code: настройка под большой проект на 200к строк

У меня на работе монорепа на 200 тысяч строк TypeScript: фронт на Next, бэк на Hono, общие пакеты, скрипты, внутренние SDK. На таком объёме даже хорошие coding-ассистенты начинают выдавать ерунду, если их не настроить. Полгода настраивал Claude Code, и в итоге он у меня делает 60–70% рутинной работы. Расскажу, как.

Главное — CLAUDE.md в корне

Это файл-память проекта. Claude Code читает его автоматически в каждой сессии, и от того, что в нём написано, зависит 80% качества ответов.

Что у меня в CLAUDE.md:

• Архитектура: где фронт, где бэк, где общие пакеты, как они связаны.
• Конвенции кода: какие импорты нужны, как именовать файлы, какие линтерные правила нельзя нарушать.
• Примеры: как выглядит «правильный» компонент, как «правильный» хендлер.
• Что НЕ делать: «не используй axios, у нас native fetch», «не пиши tests на vitest, у нас node:test».

# CLAUDE.md (фрагмент)

## Архитектура
- apps/web — Next.js 15, App Router, Tailwind 4
- apps/api — Hono на Node 22, Postgres через kysely
- packages/shared-types — Zod-схемы, типы для API

## Что нельзя
- Не подключать axios, lodash, date-fns. Используй нативные API.
- Не писать вручную типы в shared-types. Только через z.infer.
- Не делать .env.* в корне. Только в apps/<name>/.env.

## Конвенции тестов
- node:test
- assert from 'node:assert/strict'
- Имя файла: foo.test.ts рядом с foo.ts

Подкаталоги тоже умеют

Claude Code читает CLAUDE.md не только в корне, но и в подкаталогах. У меня есть apps/api/CLAUDE.md с описанием бэк-конвенций и apps/web/CLAUDE.md с фронт-конвенциями. Когда я открываю Claude в /apps/api, он подхватывает только релевантное.

Команды через хуки

В .claude/settings.json можно прописать хуки — что выполнять до и после действий. У меня настроено так:

{
  "hooks": {
    "pre-tool-use": {
      "Edit": "echo 'editing $TOOL_INPUT_FILE_PATH' >> .claude/edits.log"
    },
    "post-tool-use": {
      "Edit": "pnpm typecheck && pnpm lint --fix $TOOL_INPUT_FILE_PATH"
    }
  }
}

То есть после каждого изменения файла автоматически прогоняется typecheck и lint. Если падает — Claude видит, исправляет сам.

Slash-команды на повторяющиеся задачи

В .claude/commands/ кладутся .md-файлы — это slash-команды проекта. У меня есть /new-endpoint, /new-component, /migrate-db. Каждая команда — это шаблон с инструкциями: «создай файл по такому пути, добавь регистрацию там-то, напиши тест с таким-то покрытием».

# .claude/commands/new-endpoint.md
# Создать новый API-эндпоинт

Создай новый эндпоинт по описанию пользователя.

Порядок:
1. apps/api/src/routes/<name>.ts — обработчик на Hono.
2. packages/shared-types/src/api/<name>.ts — Zod-схемы.
3. apps/api/src/routes/<name>.test.ts — тесты.
4. apps/api/src/index.ts — зарегистрировать роут.

Используй существующий /apps/api/src/routes/users.ts как образец.

Теперь /new-endpoint posts получает на 80% готовый эндпоинт. Чиню под себя — и в коммит.

MCP-серверы

Это самое интересное. Claude Code умеет дёргать внешние сервисы через MCP — Model Context Protocol. У меня подключены:

• postgres-mcp — Claude может читать схему моей БД и писать сразу с правильными типами и без выдуманных полей.
• linear-mcp — он видит мои задачи в Linear, может создать новую, обновить статус.
• github-mcp — листает PR, читает review-коменты, может оставить ответ.

В .claude/mcp.json указываются эти серверы:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "$DATABASE_URL" }
    }
  }
}

Игнор-листы

В большом проекте Claude легко тонет в node_modules, build, .next и прочем. Делай .claudeignore по аналогии с .gitignore, а ещё лучше — Claude уважает стандартный .gitignore, поэтому я туда добавил всё лишнее давно.

Чего я не делаю

• Не разрешаю Claude трогать миграции БД без ревью. Это самый дорогой тип ошибок.
• Не разрешаю удалять файлы автоматически — настроил подтверждение.
• Не подключаю sub-агентов для бизнес-логики, только для рутины (генерация типов, апдейт changelog).

Что в итоге

На большом проекте Claude Code превращается из «прикольной игрушки» в полноценного джуниора-разработчика, если потратить день на правильную настройку. CLAUDE.md, хуки, slash-команды и пара MCP-серверов — это вся механика. Остальное — практика. И самое важное: не относись к coding-ассистенту как к гаранту качества, относись как к подмастерью. Ревью никто не отменял.