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-файлі. Інструкції з перевірки PR — це навичка, одягнена у „шати“ 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 налаштування здійснюється за допомогою одного команди без необхідності ручної edycії 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. Це вже не нішова функція. Будь-хто, хто досі вставляє схему чи PR з GitHub у запит, робить вручну те, що MCP-з’єднання робить у режимі реального часу, і вставлена копія стає застарілою як тільки щось змінюється на вихідних ресурсах.

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

1. Чи має це бути правдою у кожній сесії, незалежно від завдання? Якщо так, додайте це до CLAUDE.md. Якщо ні, продовжуйте.
2. Чи це конкретне, назване, повторюване завдання з власними кроками? Якщо так, створіть документ SKILL.md. Якщо ні, продовжуйте.

Чи потрібні Claude актуальні дані, чи йому необхідно діяти поза межами розмови? Якщо так, використовуйте MCP. Якщо ні, це може взагалі не потребувати наявності у налаштуваннях агента. Деякі речі краще залишити у вигляді документації, яку ніхто не просить ШІ запам’ятати.

Пастка з найменуваннями

Будь-хто, хто переходить між різними інструментами, рано чи пізно зіткнеться з цим. Claude Code та Cursor читають CLAUDE.md, тоді як Codex CLI та кілька інших середовищ виконання читають AGENTS.md, який виконує ту саму функцію під іншою назвою. Antigravity від Google, створений колишньою командою Windsurf після угоди з Google у середині 2025 року, також використовує власну конвенцію AGENTS.md. Проте всі ці інструменти — Claude Code, Cursor, Codex та Antigravity — читають один і той самий формат SKILL.md для опису навичок. Отже, шар правил розділяється за інструментом, але шар навичок залишається єдиним. Це має значення, перш ніж припускати, що навичку, написану для одного агента, потрібно переписувати для іншого.

Звичка, яка це вирішує

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