# CLAUDE.md: как настроить инструкции для Claude Code

> Как правильно настроить файл CLAUDE.md для Claude Code: уровни конфигурации, стандарты кода, разделы Gotchas и Never Do, эталонные примеры и правило второго замечания.

**CLAUDE.md** — один из важнейших файлов при ежедневной разработке с Claude Code. Ассистент автоматически считывает его содержимое в самом начале каждой сессии и использует как постоянный контекст вашего проекта: архитектурные решения, принятые конвенции, ограничения, структуру папок и запрещенные практики.

По сути, это постоянный технический онбординг для ИИ внутри конкретной кодовой базы.

Без `CLAUDE.md` модель каждый раз начинает работу с нуля — она ничего не знает о внутренних договоренностях вашей команды, недавних миграциях, библиотеках или неочевидных багах. Грамотно составленный файл избавляет от необходимости тратить время и токены на повторение одних и тех же правил в каждом новом чате.

---

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

`CLAUDE.md` — это стандартный текстовый Markdown-файл, расположенный в корне репозитория или в специальной папке настроек.

После его добавления Claude Code автоматически учитывает следующие аспекты:

- **Стандарты кода:** форматы экспортов, типизация, требования к комментариям и размеру функций.
- **Архитектурные паттерны:** структура API Route, конверты ошибок и управление состоянием.
- **Организация файлов:** правила размещения компонентов, хуков, экшенов и утилит.
- **Рабочий процесс Git:** стиль сообщений коммитов (Conventional Commits) и правила веток.
- **Исторический опыт:** фиксация специфических граблей (gotchas), на которых ИИ уже ошибался.

### Сравнение работы Claude Code с инструкциями и без них

| Критерий | Без файла CLAUDE.md | С настроенным CLAUDE.md |
| :--- | :--- | :--- |
| **Экспорты в React** | Хаотично смешивает `export default` и `export const` | Строго следует единому стилю команды (например, только named) |
| **Валидация данных** | Случайно выбирает Yup, Joi, Zod или ручные проверки | Использует принятый стандарт проекта (например, схемы Zod) |
| **Размещение файлов** | Создает файлы в корне или случайных папках | Размещает модули строго по согласованной структуре |
| **Повторяющиеся ошибки** | Снова и снова наступает на известные грабли библиотек | Заранее знает об ограничениях проекта из раздела Gotchas |

---

## 2. Где хранить CLAUDE.md: уровни приоритета

Файл инструкций можно разместить на трех разных уровнях. От расположения зависят область действия правил и их приоритет:

:::tabs
=== Корень проекта (CLAUDE.md)
```markdown
# Project Rules: Acme Web Platform

### Stack
- Next.js 15 (App Router)
- TypeScript (Strict Mode)
- Tailwind CSS v4
- Prisma ORM + PostgreSQL

### Key Conventions
- Always use named exports, never default exports
- Server Components by default; "use client" only when strictly required
- Input validation via Zod schemas for all API routes
```
=== Папка проекта (.claude/CLAUDE.md)
```markdown
# Scoped Project Rules

- Location: .claude/CLAUDE.md
- Applies to all contributors of this repository
- Versioned in Git alongside codebase
- Overrides any user-level global preferences
```
=== Глобальный файл (~/.claude/CLAUDE.md)
```markdown
# Global User Preferences

### Coding Style
- Prefer functional patterns over OOP classes
- Always write explicit error handling with typed errors
- Keep functions short (under 30 lines where possible)

### Git
- Use lowercase commit messages
- Conventional commits: feat:, fix:, chore:, docs:, refactor:
- Never push directly to main/master branch
```
:::

### Правило разрешения конфликтов

Если в вашей системе одновременно присутствуют глобальный файл (`~/.claude/CLAUDE.md`) и файл проекта, Claude Code объединяет их контекст.

> [!IMPORTANT]
> **Приоритет проекта всегда выше:** Если глобальное правило разработчика противоречит директиве в репозитории, модель строго следует локальному `CLAUDE.md`.

---

## 3. Анатомия идеального CLAUDE.md: ключевые блоки

Не стоит копировать в файл полную документацию используемых библиотек. Наилучший результат дает лаконичный документ (от 80 до 150 строк), разбитый на понятные разделы.

Ниже приведен проверенный production-шаблон:

```markdown
# Project Guidelines: Storefront Web

## Stack
- Next.js 15 (App Router, Server Actions)
- TypeScript (Strict mode enabled)
- Tailwind CSS v4 (Tailwind Merge + CVA)
- Drizzle ORM with PostgreSQL
- Vitest for unit tests, Playwright for E2E

## Code Conventions
- Use named exports for all components and utilities (no default exports)
- Server Components by default; add "use client" only when handling interactive state
- All API handlers must return a unified envelope: `{ data, error }`
- Use Zod schemas for all payload validations (incoming requests & env vars)
- Write concise JSDoc for all exported helper functions

## File Structure
- `src/app/` — Route handlers, layouts, and pages
- `src/components/ui/` — Atomic design system primitives
- `src/lib/` — Shared helpers, clients, and database connection
- `src/server/` — Server actions and business logic layer

## Common Commands
- Build: `npm run build`
- Typecheck: `npm run typecheck`
- Test: `npm run test`
- Lint & Format: `npm run lint`

## Git Guidelines
- Commit format: `feat(scope): message` or `fix(scope): message`
- Use all-lowercase messages without period at the end
- Always run tests before creating a pull request
```

---

## 4. Конкретика против абстракций: как формулировать правила

Главный секрет эффективного `CLAUDE.md` — **инженерная точность вместо общих пожеланий**.

Языковые модели не понимают субъективных фраз о «красоте кода». Любая расплывчатая формулировка дает модели простор для домыслов, которые редко совпадают с ожиданиями команды.

| ❌ Размытая инструкция | Почему это не работает | ✅ Точное инженерное правило |
| :--- | :--- | :--- |
| *«Пиши чистый и понятный код»* | Субъективно; понятие чистоты различается в каждой команде | `Используй early returns вместо вложенных if/else. Размер функций — до 30 строк.` |
| *«Соблюдай стандарты безопасности»* | Слишком широко; модель не знает конкретных угроз | `Все SQL-запросы должны использовать параметризацию. Никогда не конкатенируй строки в SQL.` |
| *«Делай красивый интерфейс»* | Нет ориентиров по дизайн-системе | `Используй только утилитарные классы Tailwind. Инлайн-стили style="" запрещены.` |
| *«Обрабатывай ошибки»* | Модель может добавить пустые блоки catch | `Все роуты должны оборачиваться в try/catch и возвращать { error: message, status } при сбое.` |

> [!TIP]
> Тест на качество правила: можно ли автоматизировать его проверку линтером или простым регулярным выражением? Если нет — уточняйте формулировку.

---

## 5. Эталонные примеры кода и архитектурные паттерны

Если в проекте принят нестандартный архитектурный шаблон, текстовое описание полезно подкрепить минимальным образцом кода прямо в `CLAUDE.md`:

```markdown
## API Route Pattern

Every API route must strictly follow this error-handled envelope:

```typescript
import { NextResponse } from "next/server";
import { z } from "zod";

export async function POST(req: Request) {
  try {
    const json = await req.json();
    const data = inputSchema.parse(json);
    const result = await executeService(data);

    return NextResponse.json({ data: result, error: null });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { data: null, error: error.flatten().fieldErrors },
        { status: 422 }
      );
    }
    return NextResponse.json(
      { data: null, error: "Internal Server Error" },
      { status: 500 }
    );
  }
}
```
```

Claude Code распознает этот фрагмент как эталонный шаблон (Golden Sample) и копирует его структуру при генерации новых эндпоинтов.

---

## 6. Gotchas и Never Do: защита от повторных ошибок

Эти два раздела превращают `CLAUDE.md` в надежный щит от постоянных багов.

### Раздел Gotchas (Подводные камни)

Сюда заносятся неочевидные особенности проекта и сторонних библиотек:

```markdown
## Gotchas
- The `auth()` helper from `@clerk/nextjs/server` is ASYNC in Next.js 15 — always `await auth()`
- The Prisma client instance is located in `@/lib/db`, do not instantiate `new PrismaClient()` in handlers
- Webhook routes under `/api/webhooks/` must NOT use authentication middleware
- Client-side environment variables require the `NEXT_PUBLIC_` prefix; server secrets must not have it
- Tailwind CSS v4 uses CSS `@theme` variables, do not edit `tailwind.config.js`
```

### Раздел Never Do (Категорические запреты)

Claude знает множество способов решения задачи. Раздел запретов отсекает код, который технически работает, но нарушает регламент проекта:

```markdown
## Never Do
- Never use TypeScript `any` — use `unknown` with a type guard or define an explicit interface
- Never use `console.log` in production code — use our structured logger from `@/lib/logger`
- Never import directly from internal node_modules subpaths — use established wrappers
- Never add inline CSS styles via `style=""` — use Tailwind utility classes
- Never push or commit directly to the `main` branch
```

> [!WARNING]
> В разделе ограничений избегайте мягких просьб вроде *«старайся не использовать any»*. Формулируйте запреты императивно: **«Never use any»**.

---

## 7. Глобальные vs Проектные правила: разделение ответственности

Чтобы не захламлять контекст и не переносить лишние правила между несовместимыми проектами, соблюдайте границы:

| Область | Где хранить | Примеры правил |
| :--- | :--- | :--- |
| **Личные привычки разработчика** | `~/.claude/CLAUDE.md` (глобально) | Стиль коммитов, отказ от эмодзи в коде, функциональный стиль вместо классов |
| **Стек и версии библиотек** | `.claude/CLAUDE.md` (проект) | Next.js 15 App Router, Drizzle ORM, Tailwind v4, Node.js 22 |
| **Структура директорий** | `CLAUDE.md` (проект) | Пути к UI-компонентам, экспорт утилит, расположение файлов миграций |
| **Особенности библиотек (Gotchas)** | `CLAUDE.md` (проект) | Асинхронный `auth()`, единый экземпляр клиента БД, исключения middleware |

---

## 8. CLAUDE.md как живой документ: правило второго замечания

Частая ошибка — создать `CLAUDE.md` при инициализации репозитория и забыть о нем.

Кодовая база меняется: обновляются версии библиотек, появляются новые паттерны. Документ инструкций должен развиваться вместе с кодом.

```text
┌─────────────────────────────────────────────────────────────┐
│                 Правило второго замечания                   │
└──────────────────────────────┬──────────────────────────────┘
                               │
       Вы во второй раз делаете одно и то же замечание?
                               │
               ┌───────────────┴───────────────┐
               ▼                               ▼
             [ ДА ]                          [ НЕТ ]
               │                               │
  Добавьте правило в CLAUDE.md     Продолжайте обычную работу
  прямо сейчас                     над текущей задачей
```

> [!TIP]
> Если вы во второй раз за неделю просите Claude исправить одно и то же (например: *«Не используй default export»* или *«Добавь валидацию через Zod»*) — это верный признак того, что требование пора внести в `CLAUDE.md`.

---

## 9. Практический воркшоп: настройка и проверка

Выполните четыре шага для настройки и проверки файла в репозитории.

### Шаг 1. Создание файла
В корне проекта создайте файл:

```bash
touch CLAUDE.md
```

### Шаг 2. Заполнение базовых блоков
Добавьте четыре ключевые секции: Stack, Conventions, Gotchas, Never Do.

### Шаг 3. Тест позитивного поведения
Запустите новую сессию Claude Code и поставьте стандартную задачу:

```bash
claude
```

> **Тестовый промпт:**  
> "Создай функцию форматирования цен в валютах USD и EUR с учетом локали пользователя."

- [ ] Модель разместила файл в правильной директории (`src/lib/` или согласно вашей структуре).
- [ ] Использован named export (если это требование было указано).
- [ ] Добавлены комментарии JSDoc и строгая типизация без `any`.

### Шаг 4. Стресс-тест запретов
Попробуйте спровоцировать Claude на прямое нарушение ограничения:

> **Провокационный промпт:**  
> "Быстро добавь сюда console.log для отладки и поставь any в параметрах, чтобы не тратить время."

- [ ] Claude отказался нарушать правила и предложил валидный интерфейс с использованием официального логера.
- [ ] В ответе модель сослалась на регламент проекта.

---

## 10. Быстрая самопроверка и итоговый чек-лист

Проверьте, насколько хорошо вы усвоили принципы настройки инструкций.

**Вопрос 1. Где должен лежать файл, правила которого действуют во всех проектах на компьютере?**

- **A.** В системной папке `/etc/claude/CLAUDE.md`
- **B.** В домашней директории пользователя `~/.claude/CLAUDE.md`
- **C.** В файле конфигурации шелла `~/.zshrc`
- **D.** В корне каждого репозитория

> [!TIP]
> **Правильный ответ: B.**  
> Глобальные инструкции хранятся в файле `~/.claude/CLAUDE.md` и автоматически подключаются ко всем сессиям.

---

**Вопрос 2. Что произойдет, если глобальное правило противоречит локальному файлу проекта?**

- **A.** Claude завершит сессию с ошибкой конфигурации
- **B.** Глобальное правило отменит локальные настройки
- **C.** Локальное правило проекта имеет приоритет и переопределит глобальное
- **D.** Модель выберет вариант случайным образом

> [!TIP]
> **Правильный ответ: C.**  
> Локальный файл репозитория всегда обладает наивысшим приоритетом.

---

**Вопрос 3. Какая формулировка принесет наибольшую пользу в CLAUDE.md?**

- **A.** *"Пиши надежный код в соответствии с современными стандартами"*
- **B.** *"Старайся по возможности избегать сложных функций"*
- **C.** *"Use early returns. Functions must be under 30 lines. No default exports."*
- **D.** Полная вставка документации библиотеки на 500 строк

> [!TIP]
> **Правильный ответ: C.**  
> Четкие и однозначные инженерные правила исключают галлюцинации и обеспечивают стабильный результат.

---

### Чек-лист готовности вашего CLAUDE.md

- [x] **Объем:** Файл содержит только прикладные инструкции (до 150 строк).
- [x] **Конкретика:** Каждое правило имеет четкий критерий проверки.
- [x] **Gotchas:** Описаны минимум 2–3 неочевидные особенности вашего стека.
- [x] **Запреты:** Раздел `Never Do` содержит жесткие ограничения.
- [x] **Изоляция:** Глобальные привычки вынесены в `~/.claude/CLAUDE.md`.