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: уровни приоритета

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

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) и файл проекта, Claude Code объединяет их контекст.

Важно

Приоритет проекта всегда выше: Если глобальное правило разработчика противоречит директиве в репозитории, модель строго следует локальному 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 } при сбое.`

Совет

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

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 } ); } }

terminal

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

Внимание

В разделе ограничений избегайте мягких просьб вроде «старайся не использовать 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 Продолжайте обычную работу прямо сейчас над текущей задачей

Совет

Если вы во второй раз за неделю просите 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. В корне каждого репозитория

Совет

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

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

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

Совет

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

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

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

Совет

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

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

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