CLAUDE.md против AGENTS.md против SKILL.md: что находится где и почему.

Каждый, кто начинает использовать Claude Code, обычно создаёт файл CLAUDE.md и записывает в него всё: настройку проекта, правила программирования, правила отправки pull request, детали технологической стека, инструкции по адаптации. Затем в игру вступает файл AGENTS.md, за ним — SKILL.md, и создаётся впечатление, что для одной и той же работы нужны три файла. На самом деле это не так. Их путаница приводит к трате токенов, которые ничего для вас не дают.

Краткая модель мышления

Представьте компанию. CLAUDE.md — это руководство для сотрудников, которое каждый новичок читает с первого дня, оно всегда на виду. AGENTS.md — это то же самое руководство, написанное так, чтобы его могли понимать внешние подрядчики из любой агентства, а не только постоянные сотрудники. SKILL.md — это руководство, лежащее на полке; его берут только тогда, когда нужно выполнять конкретную задачу. Три файла, три типа задач и три способа загрузки информации.

CLAUDE.md: всегда загружается

Это основной файл конфигурации Claude Code. При запуске сессии Claude читает его и сохраняет в своем системном промпте. Он загружается один раз, становится частью контекста, используемого в течение всей сессии, и не требует повторного загрузки с диска при каждом сообщении. Поэтому когда вы пишете приветствие, эти инструкции уже находятся в системном промпте, и они снова будут доступны, когда вы позже попросите исправить баг.

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

Три уровня

Инструкции поступают из нескольких источников и объединяются:

1. Личный файл в пути ~/.claude/CLAUDE.md, содержащий настройки, применимые ко всем проектам, такие как стиль отступов или правила написания сообщений о коммитах. Коллеги по команде его никогда не видят.

Файл проекта — либо .claude/CLAUDE.md, либо файл, находящийся в корне репозитория. Он сохраняется в Git, поэтому все, кто клонирует репозиторий, получают одни и те же правила. Здесь указываются детали стека, команды и стандарты команды.

Правила, применимые к конкретным путям, хранятся в папке .claude/rules/ с указанием путей в поле frontmatter. Например, файл с правилами тестирования может загружаться только во время редактирования файлов тестов, что предотвращает появление нерелевантных инструкций в контексте.

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

Что должно находиться внутри

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

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

Важный момент

Если изменить файл CLAUDE.md во время сессии, текущая сессия этого не заметит. Файл читается один раз при старте, поэтому для применения изменений требуется новая сессия. Именно по этой причине часто кажется, что только что добавленное правило проигнорировано.

AGENTS.md: для команд с несколькими инструментами

AGENTS.md выполняет ту же функцию — хранит контекст проекта и инструкции. Разница заключается в том, кто может его читать. Claude Code читает CLAUDE.md, в то время как OpenAI Codex, Cursor, Gemini CLI и GitHub Copilot читают AGENTS.md.

Судя по описанию, Claude Code не поддерживает AGENTS.md из коробки, но символическая ссылка решает эту проблему, направляя оба имени на один файл (проверьте актуальную документацию на случай изменений в поддержке):

ln -s AGENTS.md CLAUDE.md

Теперь существует единый файл, который читают все инструменты, и ничто не теряется.

Когда это необходимо

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

Незаметная потеря инструкций

У многоагентных пайплайнов есть серьезная проблема с отказами. Представьте, что один этап выполняется в Claude Code, а другой — в инструменте от другого поставщика. Если ваши правила хранятся только в CLAUDE.md, второй инструмент игнорирует их без каких-либо ошибок или предупреждений. Агент работает нормально, но не соблюдает правила, которые вы считали обязательными. Результаты становятся неоднородными, поведение меняется, и поскольку ничего не выглядит сломанным, причину трудно найти. Использование AGENTS.md в качестве общего стандарта позволяет всем инструментам в пайплайне видеть одни и те же правила.

SKILL.md: загружается по требованию

Этот вариант работает иначе. Предыдущие два типа загружаются в начале каждой сессии и остаются в контексте. Навык загружается только тогда, когда текущая задача соответствует его описанию.

Навык — это папка, содержащая файл SKILL.md. Файл начинается с краткого YAML-заголовка, в котором указано название навыка и однострочное описание; именно это описание читает Claude для определения соответствия. При отправке сообщения Claude сравнивает его с описаниями всех ваших навыков и загружает тот, который соответствует. По окончании задачи навык удаляется. Вот пример того, как может выглядеть frontmatter:

---
name: pr-review
description: Use when the user asks to review a pull request or check code quality.
allowed-tools: [Read, Grep, Glob]
---

Почему это экономит токены

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

Описание имеет наибольшее значение

Claude опирается на описание для принятия решений. Размытое описание вроде «помогает с кодом» либо никогда не будет использовано, либо будет применяться ко всему. Точное описание, например, проверка pull-запросов на Python на наличие уязвимостей вроде SQL-инъекций или жестко закодированных секретов, будет вызываться надежно и только в соответствующих случаях. Название папки предназначено для вас, а описание — для Claude, поэтому пишите его для Claude.

Два полезных варианта frontmatter

allowed-tools ограничивает возможности Claude во время активности навыка. Для навыка, предназначенного для анализа кодовой базы, установка параметров read, grep и glob позволяет Claude изучать её без редактирования или создания файлов, причем это ограничение действует даже в случае запроса на изменения.

context: fork запускает работу навыка в изолированном контексте. Промежуточные шаги остаются скрытыми, и в основную сессию возвращается только окончательный результат, что подходит для задач, генерирующих большое количество контента, который не требуется читать, например при сканировании пятидесяти файлов для получения одного резюме.

Сохраняйте навыки компактными

Большой навык потребляет больше контекста после загрузки. Если в рабочем процессе требуется обширная документация, примеры или справочные материалы, разместите их в отдельных файлах и пусть навык загружает их по мере необходимости. Основные инструкции должны находиться непосредственно в рабочем процессе.

Сравнение трёх подходов

Как выбрать

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

Определённый рабочий процесс, который вы повторяете — например, рассмотрение PR-запросов, составление резюме или поиск документации — должен превратиться в навык.

Если для выполнения рабочего процесса Claude должен работать только в режиме чтения, сделайте его навыком с параметром allowed-tools.

Если вы хотите вручную запустить какую-либо операцию с помощью одного команды, используйте команду со слешом в папке .claude/commands/.

Аккуратная структура

your-project/
├── AGENTS.md                   <- shared source of truth for all tools
├── CLAUDE.md                   <- imports AGENTS.md, adds Claude-specific rules
├── .claude/
│   ├── rules/
│   │   ├── testing.md          <- loads only when editing test files
│   │   └── security.md         <- loads only when editing auth-related files
│   ├── skills/
│   │   ├── pr-review/
│   │   │   └── SKILL.md        <- loads when you ask for a PR review
│   │   └── latex-resume/
│   │       └── SKILL.md        <- loads when you ask to build a resume
│   └── commands/
│       └── standup.md          <- /standup generates your daily update
└── ~/.claude/
    └── CLAUDE.md               <- your personal preferences, not in the repo

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

Ориентир

Если длина CLAUDE.md превышает 200 строк или количество токенов — примерно 1 200–1 500, скорее всего, вы платите за каждое сообщение за инструкции, которые вам не нужны. Расставьте инструкции в порядке их необходимости: «всегда» — это CLAUDE.md, «для разных инструментов» — AGENTS.md, «только для одного типа задач» — способность. Ваш окно контекста — это бюджет: основной файл тратит часть его на каждое сообщение, а способности — только при использовании, поэтому проектируйте структуру с учётом этого.