CLAUDE.md: настройка Claude Code под проект

Каждый раз объяснять агенту «у нас NestJS, тесты запускаются вот так, any не используем» — это потеря времени: с новой сессией контекст пуст, и всё нужно повторять заново. Решение называется CLAUDE.md. Это файл, который агент читает автоматически при старте — и дальше работает по вашим правилам без напоминаний. Разберём, что туда писать, какова правильная структура и как не превратить «конституцию проекта» в роман, который раздувает контекст.

Что такое CLAUDE.md и зачем он нужен

CLAUDE.md — это постоянная память проекта. Всё, что вы туда напишете, попадает в контекст агента автоматически в начале каждой рабочей сессии. Не документация для команды, не README — это инструкции для агента: стек, структура каталогов, команды запуска, конвенции кода и явный список «чего не делать».

Без CLAUDE.md агент работает по «среднему интернету»: угадывает менеджер пакетов, предполагает структуру, игнорирует ваши соглашения по именованию. С CLAUDE.md — работает по-вашему с первого запроса.

Существуют два уровня:

• Проектный CLAUDE.md — в корне репозитория, коммитится в git, общий для всей команды. Описывает правила конкретного проекта.
• Личный ~/.claude/CLAUDE.md — в домашнем каталоге, ваши персональные предпочтения, которые работают во всех проектах.

Когда набор правил вырастает, его можно дробить на модульные файлы (например, в .claude/rules/), чтобы не раздувать один файл. Но на старте достаточно одного хорошо написанного CLAUDE.md в корне.

Как сгенерировать черновик: команда /init

Не нужно писать CLAUDE.md с нуля. Запустите команду /init прямо в Claude Code — агент просканирует проект: структуру папок, package.json, конфигурации, скрипты — и сгенерирует черновик.

Но черновик — это только старт. Команда /init даёт вам базу, которую нужно доработать руками. Именно доработка превращает дефолтный файл в реальный инструмент: добавьте конвенции, которых агент сам не угадает, уточните команды, напишите список запретов.

Структура хорошего CLAUDE.md

Главный принцип: коротко, конкретно, проверяемо. Агент читает этот файл при каждом запуске — лишнее раздувает контекст и снижает качество ответов. Держите файл на одном экране.

Пример для сквозного проекта курса — CoffeeCRM (монорепо NestJS + Next.js):

# CoffeeCRM

CRM для кофейни. Монорепо: backend (NestJS) + frontend (Next.js) + PostgreSQL.

## Стек
- Backend: NestJS (TypeScript), PostgreSQL
- Frontend: Next.js (App Router, TypeScript)
- Менеджер пакетов: npm

## Структура
- `backend/`  — API (NestJS)
- `frontend/` — UI (Next.js App Router)
- `docker-compose.yml` — локальный PostgreSQL

## Команды
- Backend dev:  `cd backend && npm run start:dev`  (порт 3001)
- Frontend dev: `cd frontend && npm run dev`        (порт 3000)
- БД:           `docker compose up -d`
- Тесты back:   `cd backend && npm test`

## Конвенции
- Только TypeScript, без `any`.
- Один ресурс = один модуль NestJS (controller + service + dto).
- DTO валидируем через class-validator.
- Имена файлов — kebab-case.

## Чего НЕ делать
- Не коммитить `.env` и любые секреты.
- Не трогать `docker-compose.yml` без явной просьбы.
- Не добавлять платные внешние API — проект работает локально.

Разберём каждую секцию:

Стек и структура — чтобы агент не гадал, где что лежит и какой менеджер пакетов использовать. Это базовое ориентирование в проекте.

Команды — самая ценная секция. Агент запускает их в цикле: прогнал тест, увидел ошибку, поправил, снова прогнал. Точные команды с портами и путями = меньше промахов, меньше вопросов «как запустить?».

Конвенции — то, что отличает ваш код от «среднего по интернету». Запрет на any, нейминг, архитектурные решения — именно это делает результат «вашим», а не типовым сгенерированным кодом.

Чего НЕ делать — короткий список запретов, которые агент должен держать в голове. Дополняет технические ограничения permissions (о них ниже).

Permissions: технические границы агента

CLAUDE.md — это инструкции. Permissions — это техническая стена, которую агент не может обойти, даже если хочет. Настраиваются в .claude/settings.json (проектный) или ~/.claude/settings.json (личный).

Три типа правил:

• allow — выполнять без вопросов. Сюда попадает рутина, которую вы и так разрешили бы: линт, тесты, запуск dev-сервера.
• ask — спросить подтверждение. Для действий с последствиями: git push, миграции, операции с базой.
• deny — запрещено всегда, без исключений. Чтение секретов, произвольные сетевые вызовы, деструктивные операции.

Пример для CoffeeCRM:

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(npm run start:dev)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Ключевой принцип — наименьшие привилегии: разрешайте узко и конкретно (Bash(npm run test *)), а не широко («всё подряд»). Узкое правило безопаснее.

Подробнее о режимах и механике разрешений — в статье про permissions и безопасность Claude Code.

Безопасность: почему секреты — главная дыра

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

Базовый чек-лист:

1. В deny — Read(./.env), Read(./.env.*), Read(./secrets/**).
2. .env — в .gitignore. Базовая гигиена, но об этом часто забывают.
3. Произвольные curl и сетевые вызовы — в deny или ask.
4. Деструктивные операции (удаление, перезапись вне рабочих файлов) — требуют подтверждения, не allow.

Хороший тест: попросите агента «прочитай .env» — он должен упереться в запрет. Если упёрся — защита работает.

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

Итог

Хороший CLAUDE.md — это один экран текста: стек, структура, команды, конвенции, запреты. Плюс settings.json с осознанными permissions. Вместе они превращают агента из «умного автокомплита» в инструмент, который работает по вашим правилам с первого запроса.

Если вы только начинаете — прочитайте про основы Claude Code: понимание того, как устроен контекст и цикл агента, сделает настройку CLAUDE.md очевидной, а не механической.

Всё это — CLAUDE.md, permissions, реальные задачи на сквозном проекте — разбирается системно в полном курсе по Claude Code.