CLAUDE.md: инструкции для Claude Code в командном репозитории

Как Claude Code загружает CLAUDE.md

Claude Code собирает инструкции из нескольких мест. Все найденные файлы попадают в контекст, более конкретные дополняют общие. Актуальная схема описана в документации Claude Code.

Файлы в подкаталогах экономят контекст: правила фронтенда не попадают в сессию, где агент правит миграции. Это тот же принцип, что у вложенных AGENTS.md.

CLAUDE.md и AGENTS.md в одном репозитории

Claude Code читает CLAUDE.md. Codex, Cursor, Copilot, Gemini CLI и большинство других агентов читают AGENTS.md. Если в команде пользуются разными агентами, дублировать правила в двух файлах опасно: через месяц они разойдутся.

Рабочая схема — общие правила в AGENTS.md, в CLAUDE.md импорт и только то, что специфично для Claude Code:

# CLAUDE.md
@AGENTS.md

## Только для Claude Code
- Для поиска по коду запускай субагента Explore, основной контекст береги для решения.
- Длинный вывод тестов не читай целиком: запускай scripts/test-summary.sh.

Строка @AGENTS.md подставляет содержимое файла в контекст. Импорты работают и для других документов: @docs/architecture.md. Путь считается от файла, в котором стоит импорт. Импорты внутри блоков кода не срабатывают.

Импорт загружает документ целиком в каждую сессию. Для длинных документов лучше обычная ссылка с пояснением, когда их читать: агент откроет файл сам, когда задача его коснётся.

Правила по путям: .claude/rules

В каталоге .claude/rules/ правила раскладывают по темам: один файл на тему. Файл с полем paths во frontmatter загружается только при работе с подходящими файлами:

---
paths:
  - "services/billing/**"
  - "packages/money/**"
---
# Деньги
- Суммы только в Decimal, никаких float.
- Округление — банковское, функция roundMoney из packages/money.
- Любое изменение расчётов сопровождается тестом на граничные суммы.

Без поля paths файл загружается всегда, как основной CLAUDE.md. Разбивка по темам упрощает ревью правил: изменение в правилах про деньги смотрит владелец биллинга.

Что писать в CLAUDE.md

Состав тот же, что у AGENTS.md: команды, структура, договорённости, границы, процесс сдачи. Несколько правил, которые особенно влияют на качество работы Claude Code:

• Точные команды с флагами. Как запустить один тест, как прогнать линтер только по изменённым файлам. Агент запускает их десятки раз за задачу.
• Как проверить результат. Какие команды должны пройти перед сдачей, как поднять сервис локально и проверить сценарий.
• Чего не делать. Не трогать миграции, не ослаблять тесты, не добавлять зависимости без согласования.
• Где лежат знания. Ссылки на архитектурную карту, ADR, спеки.

Команда /init создаёт черновик CLAUDE.md по содержимому репозитория. Черновик полезен как старт, но в нём много того, что агент и так видит из кода. Его стоит сократить до правил, которые нельзя вывести из файлов.

Что не стоит доверять CLAUDE.md

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

В CLAUDE.md остаётся то, что проверить автоматически нельзя: договорённости, контекст, порядок работы.

Правила Cursor и Copilot

Если часть команды работает в Cursor или с GitHub Copilot, у них свои форматы правил:

• Cursor: файлы .cursor/rules/*.mdc с frontmatter. Поле alwaysApply: true включает правило всегда, globs — для файлов по маске, по description агент сам подключает правило, если оно подходит к задаче. Старый файл .cursorrules в корне считается устаревшим. Cursor также читает AGENTS.md.
• GitHub Copilot: общий файл .github/copilot-instructions.md и файлы .github/instructions/*.instructions.md с полем applyTo для масок путей. Copilot coding agent читает и AGENTS.md.

Схема для смешанной команды: источник правды — AGENTS.md и база знаний. CLAUDE.md, правила Cursor и инструкции Copilot ссылаются на них и добавляют только специфичное для инструмента.

Как вести CLAUDE.md командой

1. Файл в git, изменения через PR. Правило, которое влияет на работу агента у всех, проходит ревью как код.
2. Владелец. Один-два человека отвечают за то, чтобы правила не противоречили друг другу и не устаревали.
3. Правило появляется из случая. Агент ошибся, человек поправил результат руками — разбираем причину и меняем правило или проверку. Правила «на всякий случай» раздувают файл.
4. Регулярная чистка. Раз в месяц удалить правила, которые уже закреплены линтером или потеряли смысл.

Вопросы