Полный гайд по файлу CLAUDE.md: как поднять продуктивность Claude Code в 10 раз

Что такое файл CLAUDE.md и почему он важен

Если вы используете Claude Code без файла CLAUDE.md, вы оставляете большую часть его силы за бортом.

CLAUDE.md — это Markdown-файл конфигурации, который Claude Code автоматически читает в начале каждой сессии. Он рассказывает Claude об архитектуре проекта, стандартах кодинга, предпочитаемых инструментах, паттернах тестирования и правилах workflow. Вместо повторения одних и тех же инструкций в каждом разговоре вы пишете их один раз, и Claude следует им каждый раз.

Считайте это разницей между наймом подрядчика, ничего не знающего о вашей компании, и тем, кто прочёл весь ваш инженерный гайдбук. Файл CLAUDE.md и есть этот гайдбук.

Почему CLAUDE.md лучше повторяющихся промптов

Одна только экономия токенов значительна. Если вы тратите 500 токенов на установку контекста на разговор и у вас 20 разговоров в день, это 10 000 токенов в день — примерно $0,15–$0,75 в день в зависимости от модели. За месяц файл CLAUDE.md экономит $4,50–$22,50 на чистых API-расходах при лучших результатах.

Кредиты Anthropic | Кредиты AWS | Кредиты Google Cloud

---

Как Claude Code читает файлы CLAUDE.md

Claude Code ищет файлы CLAUDE.md в определённом порядке приоритета. Понимание этой иерархии критично для эффективной организации инструкций.

Порядок загрузки файлов

Claude Code мерджит все применимые файлы. Если ваш глобальный файл говорит «использовать отступ 2 пробела», а файл проекта — «использовать табы 4 пробела», файл проекта побеждает для этого проекта.

Что куда положить

Глобальный CLAUDE.md (~/.claude/CLAUDE.md) — предпочтения, применимые везде:

# Global Preferences
- Always use TypeScript over JavaScript when possible
- Prefer functional components over class components in React
- Write concise commit messages under 72 characters
- Use ESM imports, never CommonJS require()

CLAUDE.md проекта (корень проекта) — всё специфичное для этой кодовой базы:

# Project: Acme Dashboard
## Tech Stack
- Next.js 15 with App Router
- TypeScript 5.x strict mode
- Tailwind CSS 4.0
- Prisma ORM with PostgreSQL
- Jest + React Testing Library for tests

## Architecture
- /app — Next.js routes (App Router only, no Pages Router)
- /components — reusable UI components
- /lib — business logic and utilities
- /prisma — database schema and migrations

---

Создание вашего первого файла CLAUDE.md

Вот пошаговая настройка для старта с Claude Code и правильно сконфигурированным CLAUDE.md.

Шаг 1: установите Claude Code

npm install -g @anthropic-ai/claude-code

Шаг 2: создайте CLAUDE.md в корне проекта

touch CLAUDE.md

Шаг 3: добавьте базовую конфигурацию

Начните с этого минимального шаблона и расширяйте по необходимости:

# Project: [Your Project Name]

## Tech Stack
- [Language/Framework]
- [Database]
- [Key libraries]

## Coding Standards
- [Indentation preference]
- [Naming conventions]
- [Import ordering]

## Rules
- Always write tests for new functions
- Never commit directly to main
- Use conventional commit messages

Шаг 4: запустите Claude Code

claude

Claude Code автоматически обнаружит и загрузит ваш CLAUDE.md. Вы увидите подтверждение в выводе сессии.

---

Шаблоны CLAUDE.md: стартовый, продвинутый и командный

Шаблон 1: простой проект (20 строк)

Лучше всего для соло-разработчиков, сайд-проектов и небольших кодовых баз.

# My App

## Stack
- Python 3.12, FastAPI, SQLAlchemy, PostgreSQL
- pytest for testing

## Rules
- Use type hints on all function signatures
- Write docstrings for public functions
- Keep functions under 30 lines
- Use async/await for all database operations
- Format with black, lint with ruff

## Patterns
- Repository pattern for data access
- Pydantic models for request/response validation
- Dependency injection via FastAPI Depends()

Шаблон 2: продвинутый full-stack проект (80+ строк)

Для продакшен-приложений с несколькими разработчиками и сложной архитектурой.

# Acme SaaS Platform

## Tech Stack
- Frontend: Next.js 15, TypeScript 5.x, Tailwind CSS 4.0
- Backend: Node.js 22, tRPC, Prisma ORM
- Database: PostgreSQL 16, Redis 7
- Infrastructure: Vercel (frontend), Railway (backend)
- Testing: Vitest, Playwright, MSW

## Architecture
All code follows Clean Architecture principles:
- /packages/web — Next.js frontend (App Router only)
- /packages/api — tRPC backend
- /packages/shared — shared types and utilities
- /packages/db — Prisma schema and client

## Coding Standards
- Strict TypeScript: no any, no ts-ignore
- All components must be functional with hooks
- Server Components by default, "use client" only when needed
- All API routes must have Zod input validation
- Database queries go through repository layer, never raw SQL

## Testing Requirements
- Minimum 80% coverage for new code
- Unit tests for all business logic
- Integration tests for API endpoints
- E2E tests for critical user flows
- Use MSW for API mocking, never mock fetch directly

## Git Workflow
- Conventional commits: feat:, fix:, chore:, docs:
- All PRs require passing CI before merge
- Squash merge to main
- Branch naming: feature/TICKET-123-description

## Security Rules
- NEVER hardcode secrets or API keys
- Always use environment variables for config
- Sanitize all user input
- Use parameterized queries (Prisma handles this)
- NEVER expose internal error details to clients

Шаблон 3: командная конфигурация (расшаривается через Git)

Для команд, которым нужно консистентное поведение Claude Code у всех участников.

# Team Engineering Standards — Acme Corp

## Overview
This file ensures Claude Code follows our team's engineering
standards. Committed to Git so all engineers get identical behavior.

## Code Review Checklist (Claude must follow before suggesting code)
1. Does this change have tests?
2. Are error cases handled?
3. Is the function documented?
4. Does it follow our naming conventions?
5. Are there any security implications?

## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with use prefix (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE (MAX_RETRIES)
- Database tables: snake_case (user_profiles)
- API routes: kebab-case (/api/user-settings)

## Forbidden Patterns
- DO NOT use console.log in production code (use our logger)
- DO NOT use any TypeScript escape hatches (any, @ts-ignore)
- DO NOT install new dependencies without justification
- DO NOT modify database schema without migration file
- DO NOT use default exports (use named exports only)

## Preferred Libraries (do not suggest alternatives)
- State management: Zustand (not Redux)
- Forms: React Hook Form + Zod (not Formik)
- HTTP client: native fetch (not Axios)
- Date handling: date-fns (not Moment.js)
- Animation: Framer Motion (not React Spring)

---

Сравнение: CLAUDE.md vs .cursorrules vs .github/copilot-instructions.md

Если вы оцениваете AI-инструменты кодинга, понимание того, как каждый обрабатывает конфигурацию, критично.

Главная фишка Claude Code — экосистема вокруг CLAUDE.md: hooks, кастомные команды, MCP-серверы и поддержка мульти-агентов превращают его из конфигурационного файла в полноценный фреймворк автоматизации.

---

Hooks: автоматизация вашего workflow в Claude Code

Hooks конфигурируются в .claude/settings.json, а не в самом CLAUDE.md. Они автоматически запускают shell-команды до или после событий Claude Code.

Структура конфигурации hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo 'File about to be modified'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "PreCommit": [
      {
        "command": "npm run lint && npm run test:changed"
      }
    ]
  }
}

Самые полезные паттерны hooks

Практические примеры hooks

Авто-форматирование после каждой правки файла:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Запуск тестов для изменённых файлов:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx vitest run --reporter=verbose --changed"
      }
    ]
  }
}

---

Кастомные слэш-команды

Слэш-команды позволяют создавать переиспользуемые шаблоны промптов, запускающиеся одной командой /.

Как создать слэш-команды

1. Создайте директорию .claude/commands/ в проекте
2. Добавьте Markdown-файлы — каждый файл становится командой
3. Используйте $ARGUMENTS как плейсхолдер для динамического ввода

Пример: .claude/commands/review.md

Review the following code for:
1. Security vulnerabilities
2. Performance issues
3. Missing error handling
4. Test coverage gaps

Code to review: $ARGUMENTS

Provide a severity rating (low/medium/high/critical) for each finding.

Использование в Claude Code:

/project:review src/auth/login.ts

Полезные идеи слэш-команд

---

MCP-серверы: расширение возможностей Claude Code

MCP-серверы (Model Context Protocol) подключают Claude Code к внешним инструментам и сервисам. Правильно настроенный Claude Code может запрашивать БД, бродить по вебу, управлять файлами, взаимодействовать с GitHub и многое другое — всё в рамках сессии кодинга.

Как настроить MCP-серверы

MCP-серверы настраиваются в .claude/settings.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

Самые популярные MCP-серверы для разработчиков

Ссылка на MCP в CLAUDE.md

Ваш CLAUDE.md может инструктировать Claude Code, когда и как использовать подключённые MCP-серверы:

## Available Tools
- Use the postgres MCP to check schema before writing migrations
- Use the github MCP to create PRs after completing feature branches
- Use the memory MCP to track progress on multi-step tasks

---

Вирусная схема с 27 агентами: как инженер Google автоматизировал 80% своей работы

В начале 2026 года вирусной стала ветка в Twitter инженера Google, описывающего, как он настроил 27 специализированных агентов Claude Code для разных частей workflow. У каждого агента был свой CLAUDE.md с узкими, сфокусированными инструкциями.

Основной инсайт

Вместо одной универсальной сессии Claude Code, пытающейся делать всё, он декомпозировал работу на специализированные роли. У каждого агента было:

• Выделенный CLAUDE.md с доменными знаниями
• Ограниченный доступ к инструментам (только то, что нужно агенту)
• Чёткие границы, что трогать и что нет
• Конкретные форматы вывода и стандарты качества

Пример разбивки агентов

Как воспроизвести схему

Не нужно 27 агентов, чтобы получить пользу от этого паттерна. Стартуйте с 3–5 специализированных конфигураций:

1. Создайте отдельные файлы CLAUDE.md по ролям:

.claude/agents/frontend.md
.claude/agents/backend.md
.claude/agents/testing.md

2. Запускайте Claude Code с конкретной конфигурацией:

# Use different profiles by combining global + agent-specific context
claude --profile frontend

3. Определите чёткие точки передачи:

Ваш основной CLAUDE.md может ссылаться на то, когда переключать агентов:

## Agent Workflow
- Frontend changes: use the frontend agent profile
- API changes: use the backend agent profile
- After any code change: run the test agent
- Before merging: run the review agent

Почему это работает

Подход с 27 агентами работает из-за фундаментального принципа AI-продуктивности: узкий контекст даёт лучший вывод, чем широкий. Сессия Claude Code, загруженная 400 строками инструкций про фронтенд, бэкенд, DevOps, тесты и документацию, сработает хуже на любой одной задаче, чем сессия с 50 высокорелевантными строками.

---

Частые ошибки в CLAUDE.md (и как их исправить)

Ошибка 1: слишком расплывчато

Плохо:

Write good code that follows best practices.

Хорошо:

- Use TypeScript strict mode, no implicit any
- All functions must have JSDoc comments
- Error handling: wrap async operations in try/catch
- Max function length: 30 lines

Ошибка 2: перегрузка инструкциями

Размещение 500+ строк инструкций заставляет Claude Code понижать приоритет важных правил. Держите CLAUDE.md сфокусированным.

Ошибка 3: не версионирование CLAUDE.md

Ваш CLAUDE.md должен быть закоммичен в Git. Это обеспечивает:

• Командную консистентность
• Историю изменений и подотчётность
• Лёгкий откат, если инструкции вызывают проблемы
• Ревью PR для изменений инструкций

Ошибка 4: игнорирование секции безопасности

Всегда включайте правила безопасности в CLAUDE.md:

## Security (CRITICAL — never ignore)
- NEVER hardcode API keys, tokens, or passwords
- NEVER commit .env files
- ALWAYS use parameterized database queries
- ALWAYS validate and sanitize user input
- NEVER expose stack traces or internal errors to users

Ошибка 5: забыли упомянуть стек

Claude Code может вывести ваш стек из кода, но явные декларации предотвращают неверные допущения:

## Stack (authoritative — do not infer differently)
- Runtime: Node.js 22 (NOT Deno, NOT Bun)
- Framework: Next.js 15 App Router (NOT Pages Router)
- ORM: Prisma (NOT Drizzle, NOT TypeORM)
- Package manager: pnpm (NOT npm, NOT yarn)

---

Лучшие практики Claude Code: советы power user'а

Совет 1: используйте условные инструкции

## Environment-Specific Rules
- In development: use verbose logging, skip minification
- In production: no console.log, enable all optimizations
- In CI: run full test suite, fail on any warning

Совет 2: определяйте форматы вывода

## When I ask for a code review, respond with:
1. **Summary** (1-2 sentences)
2. **Issues found** (bulleted, severity-tagged)
3. **Suggested fixes** (with code snippets)
4. **Overall grade** (A/B/C/D/F)

Совет 3: задавайте границы для зависимостей

## Dependency Rules
- NEVER install packages with fewer than 1,000 weekly downloads
- NEVER install packages with known CVEs
- Prefer built-in Node.js APIs over third-party packages
- Always check bundle size impact before adding frontend deps

Совет 4: используйте memory-файлы для длинных проектов

## Memory
- Track all completed features in .claude/memory/features.md
- Log all architecture decisions in .claude/memory/decisions.md
- Update progress after each session

Совет 5: интегрируйте с CI/CD

CLAUDE.md может инструктировать Claude Code уважать ваш CI-пайплайн:

## Before pushing any code:
1. Run `pnpm lint` — fix all errors
2. Run `pnpm test` — all tests must pass
3. Run `pnpm build` — build must succeed
4. Check bundle size — must not exceed 250KB

---

Сколько стоит Claude Code? (И как получить кредиты)

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

Разбивка стоимости Claude Code

Типичный интенсивный день Claude Code использует 500K–2M токенов, стоит $2–$30 в зависимости от модели. Хорошо настроенный CLAUDE.md снижает использование токенов, устраняя повторный контекст.

Получение бесплатных кредитов для Claude Code

Лучший способ финансировать использование Claude Code — программы кредитов:

Суммарно для стекинга: до $230 000+ по всем программам.

Кредиты Anthropic | Кредиты AWS | Кредиты Google Cloud | Кредиты Azure

Один файл CLAUDE.md в сочетании с $5 000–$25 000 стартап-кредитов даёт вам 3–6 месяцев интенсивной разработки на Claude Code с нулевой стоимостью. Смотрите все доступные программы кредитов на ClaimAICredits, чтобы найти, под что вы квалифицируетесь.

---

Быстрая шпаргалка по CLAUDE.md

---

Начните сегодня

Файл CLAUDE.md — самая высокоэффективная конфигурация, которую можно поставить для AI-разработки. Начните с простого шаблона из этого гайда, закоммитьте в репо и итерируйте по тому, что работает.

Инженеры, получающие больше всего от Claude Code, не пишут лучшие промпты — они пишут лучшие файлы CLAUDE.md. Вирусная схема с 27 агентами доказывает, что продуманная конфигурация бьёт brute-force промптинг каждый раз.

Если API-расходы Claude Code останавливают вас от экспериментов с продвинутыми схемами вроде мульти-агентных workflow, изучите бесплатные программы кредитов на ClaimAICredits. Складывание кредитов от Anthropic, AWS и Google Cloud может дать вам месяцы бесплатного времени разработки, чтобы отточить вашу конфигурацию CLAUDE.md.