CLAUDE.md в 2026: как писать рабочие инструкции для Claude Code

Короткая версия

Хороший CLAUDE.md в 2026 обычно:

• короткий;
• конкретный;
• project-specific;
• не дублирует то, что уже лежит в AGENTS.md;
• говорит Claude Code, как работать именно в этом repo.

Что туда обычно входит

Какой минимальный CLAUDE.md полезен для TypeScript backend?

1. Что такое CLAUDE.md сейчас

Official Anthropic docs про memory показывают, что CLAUDE.md - это часть memory system Claude Code, а не отдельная магическая фича в вакууме.

Практически это означает:

• файл влияет на поведение агента;
• но работает он в контексте других memory layers;
• его полезность зависит от качества, краткости и актуальности;
• он не заменяет prompts, settings, hooks или repo-wide contracts.

2. Где CLAUDE.md сильнее всего

CLAUDE.md особенно полезен там, где нужно закрепить долговременные правила проекта для Claude Code:

• стек;
• folder layout;
• команды;
• naming;
• validation/testing conventions;
• список forbidden patterns;
• expectations к verification и summary.

Именно в этом он силён. Он слабее там, где люди пытаются запихнуть в него:

• все возможные workflow на все случаи жизни;
• личные предпочтения каждого разработчика;
• длинные объяснения архитектуры, которые уже лежат в docs;
• task-specific instructions, которые должны жить в prompt files.

3. Memory hierarchy важнее, чем казалось раньше

Старые обзоры CLAUDE.md часто были слишком упрощёнными. Current Anthropic docs показывают иерархию памяти гораздо яснее.

Практически для команды важны как минимум:

• project-level CLAUDE.md;
• local overrides;
• user-level context;
• другие instruction surfaces вокруг Claude Code.

Это значит:

• не всё должно жить в одном project file;
• personal preferences лучше держать вне коммитимого слоя;
• repo contract и local override должны быть разведены.

Что обычно коммитить

• project CLAUDE.md

Что обычно не коммитить

• локальные персональные настройки;
• private notes;
• machine-specific paths или secrets.

4. CLAUDE.md и AGENTS.md: как их не дублировать

После появления общего AGENTS.md для mixed-agent workflows статья про CLAUDE.md должна быть точнее.

Хорошее разделение выглядит так:

• AGENTS.md - общий repo contract для разных coding agents;
• CLAUDE.md - только то, что специфично именно для Claude Code.

Например, в CLAUDE.md логично держать:

• Claude-specific workflow expectations;
• local terminal assumptions;
• Claude-oriented summary format;
• notes about hooks/subagents usage;
• project-specific instructions, если команда реально использует Claude Code как primary tool.

А в AGENTS.md - то, что нужно всем агентам:

• stack;
• structure;
• commands;
• testing;
• forbidden patterns.

5. Что писать в хорошем CLAUDE.md

Stack

Нужны только реально важные технологические детали:

## Stack
- Next.js 15 App Router
- TypeScript strict
- Prisma + PostgreSQL
- Vitest + Playwright

Structure

Только полезная карта repo:

## Structure
- app/ - routes and UI
- server/ - backend logic
- lib/ - shared utilities
- tests/ - automated tests

Rules

Максимально конкретные правила:

## Rules
- do not use any
- use Zod for all external input validation
- prefer existing service layer in server/services/
- do not add dependencies unless necessary

Commands

Команды, которые агент реально должен знать:

## Commands
- pnpm test
- pnpm lint
- pnpm build

Verification / Summary

Это особенно полезно для agent workflows:

## Verification
- run relevant tests for behavior changes
- summarize files changed, commands run, and residual risks

6. Антипаттерны

1. Слишком длинный файл

Если CLAUDE.md превращается в энциклопедию, Claude Code теряет signal.

2. Абстрактные лозунги

Плохо:

• "пиши качественный код"
• "следуй best practices"
• "делай production-ready"

Хорошо:

• "use TypeScript strict"
• "do not use any"
• "run pnpm test when changing behavior"

3. Дублирование README

CLAUDE.md не должен повторять всё onboarding-docs слово в слово.

4. Противоречащие правила

Самая частая проблема в зрелых repo - не отсутствие правил, а их конфликт между:

• CLAUDE.md;
• AGENTS.md;
• local overrides;
• prompts;
• old docs.

7. Hooks, settings и почему одного CLAUDE.md уже мало

Current official docs по settings и hooks показывают, что Claude Code сегодня настраивается не только инструкциями.

CLAUDE.md задаёт контекст и правила, но:

• settings управляют поведением и environment aspects;
• hooks помогают добавить guardrails и автоматизацию;
• subagents влияют на decomposition workflows.

То есть зрелый setup почти всегда шире, чем один markdown-файл.

Например:

• CLAUDE.md говорит "run tests for behavior changes";
• hooks могут реально enforce или напоминать это;
• settings влияют на execution and permissions;
• subagents помогают разделить review/debug/implementation roles.

8. Когда нужен отдельный CLAUDE.md guide

После обновления общей статьи про repo rules отдельный guide по CLAUDE.md всё ещё полезен, если:

• команда действительно использует Claude Code как primary tool;
• нужны Claude-specific patterns;
• важна memory hierarchy;
• хочется понять, что из project rules держать в Claude-specific слое.

Если же команда работает сразу в Cursor, Copilot, Codex, Windsurf и Claude Code, то отдельный CLAUDE.md guide уже не должен делать вид, что этого файла достаточно для всего.

9. Минимальный practical template

# CLAUDE.md

## Project
- TypeScript strict
- Fastify
- Prisma + PostgreSQL

## Structure
- src/api/ - route handlers
- src/services/ - business logic
- src/db/ - prisma access
- tests/ - mirrors src/

## Rules
- do not use any
- use Zod for all request validation
- do not add dependencies unless necessary
- keep changes scoped to the task

## Commands
- pnpm test
- pnpm lint
- pnpm build

## Closeout
- summarize files changed
- list commands run
- mention residual risks

Проверьте себя