CLAUDE.md: постоянный контекст и правила проекта
Автор: Казачкин Даниил Михайлович · Обновлено
CLAUDE.md — файл постоянных инструкций Claude Code. В нём фиксируют то, что иначе пришлось бы объяснять в каждом сеансе: команды проверки, структуру проекта, соглашения и важные…
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 и AGENTS.md
Claude Code не читает AGENTS.md как файл памяти напрямую. Если репозиторий уже использует этот формат для других агентов, не обязательно копировать правила: создайте CLAUDE.md с импортом.
@AGENTS.mdТак у команды остаётся один поддерживаемый документ, а Claude Code получает его через документированный механизм импорта. Если Claude-специфичное правило нужно добавить отдельно, запишите его рядом с импортом в CLAUDE.md.
Auto memory — рабочие заметки агента
Auto memory включена по умолчанию и отличается от CLAUDE.md. Claude Code сам сохраняет полезные заметки о проекте в каталоге ~/.claude/projects/<project>/memory/; эти данные локальны для машины, относятся к репозиторию и используются совместно всеми его worktree. В начале каждого сеанса загружается начало индекса MEMORY.md, а подробные файлы читаются по необходимости.
Команда /memory показывает загруженные источники и позволяет открыть или отключить auto memory. Командные соглашения всё равно следует хранить в репозитории: автоматическая память не проходит review и не заменяет CLAUDE.md.
Практика: ревизия инструкций
Создайте таблицу из последних пяти исправлений агента:
| Повторялась ли ошибка? | Нужно всем участникам? | Куда перенести? |
|---|---|---|
| Да | Да | CLAUDE.md |
| Да | Только один пакет | Вложенный CLAUDE.md или rule |
| Нет | Нет | Оставить в задаче |
| Это жёсткий запрет | Да | permissions/hook |
Затем сократите каждое правило до проверяемой формулировки: вместо «пиши хороший код» — «после изменения API запусти integration test».
Что важно запомнить
- CLAUDE.md хранит устойчивые инструкции, а не секреты.
- Область файла должна соответствовать области правила.
- Конкретные короткие требования выполняются надёжнее расплывчатых.
- Принудительное ограничение реализуется не текстовой инструкцией.
Частые вопросы
CLAUDE.md гарантирует выполнение правила?
Нет. Это инструкция в контексте модели. Технически обязательные ограничения следует реализовать permissions, sandbox, CI или PreToolUse hook.
Нужно ли дублировать README?
Нет. Добавляйте только сведения, влияющие на работу агента. При необходимости CLAUDE.md может импортировать поддерживаемый документ.
Когда обновлять файл?
Когда одна и та же коррекция повторилась, review выявил неизвестное агенту правило или изменились команды и архитектура проекта.