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 некарэктны, і кожны з іх — з разных прычын. Схема становіцца застарэлай, калі хтось дадае новы столбец. Крокі развертання опісваюць толькі адну задачу з назвай. Адрэса 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. Навык для перагляду просьбаў про з’явленне патчоў, іншы для міграцый баз дадзеных і ўжо іншы для прымітак да выдання не конкуруюць за прастор, як толькі не ведзецца самэй гэтае заведама.

.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. Oficыяльны сервер 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 PR у запіт, фактычна робіць вручную тое, што 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 і паскладзіце, сколькі абзацаў на самай працэ ёсць навыкамі, якія маюць некорэктную расшырэння файлу. Чысла зазвычай вышэй, чым можна было спадзявацца.