CLAUDE.md: постоянный контекст и правила проекта

Краткий ответ

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

Области действия инструкций

Проектный файл размещают в ./CLAUDE.md или ./.claude/CLAUDE.md и коммитят для команды. Личные инструкции для всех проектов находятся в ~/.claude/CLAUDE.md. Локальные особенности конкретного проекта можно хранить в CLAUDE.local.md и исключить из Git.

В монорепозитории допускаются вложенные CLAUDE.md. Инструкции поддиректории становятся актуальны, когда Claude работает с файлами в этой части дерева.

Что стоит записать

Полезное содержание:

точные команды lint, test, typecheck и build;
карта пакетов и разрешённые зависимости;
стиль именования и обязательные паттерны;
ограничения миграций, API и обратной совместимости;
определение готовности изменения.

Не стоит помещать сюда секреты, длинные учебники, временные детали одной задачи и правила, которые требуется технически запретить. Для запрета нужны permissions, sandbox или hooks.

Пример компактного файла

# Project guide

## Commands
- Unit tests: pnpm test
- Type check: pnpm typecheck

## Architecture
- UI must not import database modules.
- Public API changes require an integration test.

## Delivery
- Preserve unrelated worktree changes.
- Report the exact verification commands and results.

Документация рекомендует конкретные и краткие инструкции; ориентир для одного CLAUDE.md — менее 200 строк.

Импорты и диагностика

CLAUDE.md может включать другой файл синтаксисом @path/to/file. Импорты разрешаются относительно файла, в котором записана ссылка. Команда /init создаёт стартовый CLAUDE.md или предлагает улучшения существующего. Команды /context и /memory помогают проверить загрузку и отредактировать память.

Практика: ревизия инструкций

Создайте таблицу из последних пяти исправлений агента:

Повторялась ли ошибка? Нужно всем участникам? Куда перенести?

Да Да CLAUDE.md

Да Только один пакет Вложенный CLAUDE.md или rule

Нет Нет Оставить в задаче

Это жёсткий запрет Да permissions/hook

Затем сократите каждое правило до проверяемой формулировки: вместо «пиши хороший код» — «после изменения API запусти integration test».

Частые вопросы

CLAUDE.md гарантирует выполнение правила?

Нет. Это инструкция в контексте модели. Технически обязательные ограничения следует реализовать permissions, sandbox, CI или PreToolUse hook.

Нужно ли дублировать README?

Нет. Добавляйте только сведения, влияющие на работу агента. При необходимости CLAUDE.md может импортировать поддерживаемый документ.

Когда обновлять файл?

Когда одна и та же коррекция повторилась, review выявил неизвестное агенту правило или изменились команды и архитектура проекта.

Что важно запомнить

CLAUDE.md хранит устойчивые инструкции, а не секреты.
Область файла должна соответствовать области правила.
Конкретные короткие требования выполняются надёжнее расплывчатых.
Принудительное ограничение реализуется не текстовой инструкцией.

https://yadro-code.ru/lessons/without-university/claude-code-workflows/claude-code-04