CLAUDE.md, SKILL.md и MCP: Какой слой хранит какие инструкции

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

На деле происходит обратное. Рабочая память перегружается, ответы становятся менее точными, а те запросы, которые раньше работали корректно, перестают срабатывать. Что-то идет не так, но трудно понять что именно. При каждом простом запросе модели сначала приходится просматривать сотни строк нерелевантных инструкций, прежде чем она доберется до хотя бы одной строки кода. Вина не в модели и не в запросе — от простого текстового файла просто требуют выполнить три разных задачи.

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

Почему три уровня

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

• CLAUDE.md отвечает за то, что должно всегда соблюдаться.
• SKILL.md отвечает за то, что важно лишь иногда.
• MCP обрабатывает данные, которые становятся устаревшими сразу после записи.

Это три разных способа возникновения сбоев, а не три варианта одного и того же. Если объединить все навыки в CLAUDE.md, получится один огромный файл, который загружается полностью при каждой сессии, независимо от того, требуется ли чек-лист для развертывания. Любой дополнительный уровень окажется лишь подразделением одного из трех основных способов сбоев, а не новой задачей.

Что должно находиться в CLAUDE.md или AGENTS.md

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

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

Хорошими примерами являются конвенции кодирования, структура проекта, строгие ограничения, правила безопасности, такие как никогда не разглашать ключи API в коде, а также роль, которую агент должен играть при проверке работы.

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

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

Файл, который выполняет свою функцию, выглядит следующим образом; он адаптирован из широко распространённого набора руководящих принципов поведения.

# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

Он короткий и конкретный, и в нем нет ничего, что требовало бы корректировки на следующей неделе. Вот как он выглядит, когда что-то идёт не так — это типичная проблема в ранних версиях.

# Project Notes

Our database has these tables: users, orders, products, sessions,

audit_log (schema pasted below, 340 lines)...

To deploy, first SSH into staging, then run these 47 commands...

Here's our Slack webhook URL for notifications: hooks.slack.com/...

When reviewing PRs, check for: [12 paragraphs of instructions]

Каждый пункт во втором примере неверен для CLAUDE.md, причем каждый по своей причине. Схема устаревает сразу после добавления кого-либо новой колонки. Шаги развертывания описывают лишь одну задачу с указанным названием. URL webhook является секретной информацией и должен храниться в переменной окружения, а не в сохранённом файле Markdown. Инструкции по ревью pull-реквестов — это навык, одетый в облик CLAUDE.md.

Полезный тест: останется ли эта фраза верной, если прочитать её снова через три месяца, в случайный вторник, занимаясь чем-то не связанным? Если нет, её не следует находить в файле.

SKILL.md: экспертиза, которая появляется только тогда, когда это необходимо

Agent Skills появился от Anthropic в октябре 2025 года; он был разработан таким образом, что инструкции для конкретной задачи могли храниться в папке и загружаться по мере необходимости, вместо того чтобы постоянно занимать пространство в контексте. В декабре 2025 года этот формат был выпущен как независимый стандарт, и другие инструменты быстро его приняли. VS Code, Cursor, IDE Antigravity от Google, Gemini CLI, Goose и несколько других инструментов для программирования теперь поддерживают тот же формат SKILL.md, что и Claude Code. Именно этот формат сделал MCP общепринятым стандартом для подключения инструментов в индустрии.

Идея становится полезной, когда до неё доходишь: не всем знаниям нужно постоянно находиться в памяти агента. Большая часть знаний инженера становится актуальной лишь для конкретной задачи. Никто не вспоминает чек-лист развертывания, пиша вспомогательную функцию. Навыки следуют той же логике. Папка с файлом SKILL.md остаётся неприменяемой до тех пор, пока не поступит запрос вроде «проверь этот PR», и тогда Claude загружает реальный чек-лист для проверки.

Файл с навыком начинается с краткого описания, называемого frontmatter, в котором указывается, что делает данный навык и когда он должен срабатывать. Когда поступает соответствующее сообщение, Claude загружает оставшуюся часть файла. Если же сообщение не соответствует, этот контент совсем не занимает места в разговоре. Именно поэтому навыки кажутся более легкими по использованию, чем хранение всего в CLAUDE.md. Навыки для проверки pull request, миграций баз данных и записей о выпусках не конкурируют за пространство, если только именно эта задача не выполняется в данный момент.

.claude/skills/
├── code-review/
│   └── SKILL.md
├── pr-description/
│   └── SKILL.md
└── anti-sycophancy/
    └── SKILL.md

Навыки проектного уровня хранятся в папке .claude/skills/ внутри репозитория. Личные навыки, которые должны сопровождать пользователя повсюду, находятся в папке ~/.claude/skills/. Такое разделение соответствует структуре CLAUDE.md: проектные навыки против глобальных. Вот его урезанная версия:

---
name: production-code-validation-checklist
description: "Run this checklist before pushing code to GitHub"
---

# Production Code Validation Checklist

**Run this checklist before pushing code to GitHub.**

This is not optional. This is how you prevent broken repositories.

## Secrets Audit
- [ ] Searched for: password, secret, token, key, api_key, credential
- [ ] All secrets are in environment variables or .env, not in code
- [ ] .env file is in .gitignore

## Failure Scenario Testing: Deliberately Break It
This is the most important step. Production code breaks. Can your code
handle it?
- [ ] Run without a required environment variable, does it fail with a
      clear error?
- [ ] Simulate a timeout on any HTTP request, does the code handle it?
- [ ] Feed it empty input, null input, and malformed input, one at a time

## Final Production Readiness Assessment
Choose ONE:
- [ ] PROTOTYPE: concept proven, not production ready
- [ ] DEVELOPMENT READY: works for development, not production
- [ ] PRODUCTION CANDIDATE: ready for real-world testing
- [ ] PRODUCTION VERIFIED: tested in a real environment, known to work

**If you cannot check a box, you are not done.**

Обратите внимание, чего оно не включает. В нём также отсутствуют стандарты кодирования и схема базы данных. В нём есть одна задача с указанным именем, запускаемая при определённом условии, и именно это делает его навыком, а не упрощённой версией CLAUDE.md. Простой критерий — это наличие необходимости в чём-то только при выполнении одной конкретной, именованной задачи. Если так, то это навык, а не правило.

MCP: доступ, а не просто знания

CLAUDE.md и SKILL.md — это файлы в формате Markdown, написанные кем-то. MCP отличается: он связывает работающего Claude с ресурсом вне чата, будь то база данных, GitHub, Slack, файловая система или любой другой подключённый ресурс.

В проектах, ориентированных на технологию RAG, типичным случаем является прямое подключение Chroma. Официальный сервер chroma-mcp предоставляет коллекции в виде инструментов, которые Claude может использовать для запросов.

{
  "mcpServers": {
    "chroma": {
      "command": "uvx",
      "args": [
        "chroma-mcp",
        "--client-type", "persistent",
        "--data-dir", "/path/to/your/chroma/data"
      ]
    }
  }
}

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

claude mcp add --scope project chroma \
  -- uvx chroma-mcp --client-type persistent --data-dir ./chroma-data

Он регистрирует сервер и записывает конфигурацию в файл .mcp.json внутри проекта, который можно добавить в репозиторий, чтобы вся команда имела одинаковое подключение без необходимости его ручной настройки. Claude Code предлагает три уровня доступа: локальный, что означает одного пользователя на одном устройстве; проектный, когда конфигурация хранится в репозитории и делится с другими; и пользовательский, когда применяется ко всем проектам, с которыми работает данный пользователь. Тот же принцип различия между проектным и глобальным уровнями используется в третий раз, что облегчает запоминание после первого знакомства.

Протокол развивается настолько быстро, что сам процесс роста уже является частью его истории. В официальном реестре серверов указано более 9 000 серверов, а ежемесячные загрузки оригинального SDK выросли примерно с 2 миллионов до почти 100 миллионов за примерно 16 месяцев, согласно данным, предоставленным Anthropic. Это уже не нишевая функция. Любой, кто по-прежнему вставляет схему или предложение из GitHub в запрос, делает вручную то, что MCP-соединение выполняет в реальном времени, причем вставленная копия устаревает сразу же при любых изменениях в исходном коде.

Дерево принятия решений

1. Должно ли это соблюдаться в каждой сессии, независимо от задачи? Если да, добавьте это в CLAUDE.md. Если нет, продолжайте.
2. Является ли это конкретной, имеющей название повторяемой задачей с собственными шагами? Если да, преобразуйте её в SKILL.md. Если нет, продолжайте.

Нужны ли Claude актуальные данные или необходимо действовать вне рамок разговора? Если да, используйте MCP. Если нет, это вообще может не входить в настройки агента. Некоторые вещи лучше оставить в виде документации, которую никто не просит ИИ запоминать.

Ловушка с именованием

Любой, кто будет переключаться между инструментами, рано или поздно столкнётся с этой проблемой. Claude Code и Cursor читают файл CLAUDE.md, в то время как Codex CLI и ещё несколько сред выполнения используют файл AGENTS.md, который выполняет ту же функцию, но под другим названием. Google’s Antigravity, разработанный бывшей командой Windsurf после сделки Google с ними в середине 2025 года, также применяет собственную конвенцию AGENTS.md. Однако все они — Claude Code, Cursor, Codex и Antigravity — читают файлы формата SKILL.md для хранения информации о навыках. Следовательно, правила работы с инструментами различаются, но формат хранения навыков остаётся единым. Это важно перед тем, как предполагать, что навык, написанный для одного агента, обязательно нужно переписывать для другого.

Привычка, которая решает проблему

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