Skip to main content
Все гайды
Содержание гайда

Содержание гайда

Время на изучение: 12 мин
#automation#claude-code#claude-md#best-practices#devtools
Средний12 мин

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

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

Опубликовано:
ДЛЯ АГЕНТАChatGPTClaude

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.

Связанные материалы экосистемы

Практические гайды, терминология и агентские скиллы

Практический гайд

MCP Servers и Claude Code: практическое руководство по подключению и разработке

Как расширить возможности Claude Code с помощью Model Context Protocol: подключение файловой системы, GitHub, PostgreSQL, Brave Search и создание собственного сервера на TypeScript.

Практический гайд

Claude Code Projects: как один ИИ координирует команду автономных агентов

Глубокий разбор Claude Code Projects: архитектура Coordinator и Threads, параллельные ветки, общая память MEMORY.md и управление облачными агентами.

Термин в глоссарии

Мета-промптинг (ИИ улучшает ваш промпт вместо вас)

Техника составления запросов высшего порядка (Meta-Prompting). Вместо того чтобы самостоятельно подбирать сложные формулировки, вы поручаете мощной модели написать, структурировать и протестировать идеальный промпт для вашей задачи.

Термин в глоссарии

Claude Code

Официальный терминальный агент разработки от Anthropic, работающий непосредственно в командной строке через Claude 3.7 Sonnet с нативной поддержкой Bash, Git, файловой системы и протокола MCP.

Новость

Claude Code сократил стоимость обновления статуса фоновых субагентов на 99%

В CLI-версии Claude Code обновление статуса фоновых субагентов теперь выполняет Haiku 5.5 на основе коротких заметок, что снижает расход лимитов.

Новость

Пользователь Reddit объяснил почти четырёхкратный расход недельных лимитов Claude Code

Сравнение токенов за две недели показало, что эффективность использования недельного лимита Claude Code упала в 3,8 раза; вероятные причины — субагенты, рост времени рассуждений и фоновые запросы интерфейса.

Этот гайд полностью бесплатный. Если он сэкономил вам вечер — вы можете поддержать развитие проекта.
Поддержать автора