CLAUDE.md проты AGENTS.md проты SKILL.md: Чаго дзе і чаму.

Кожны, хто пачынае выкарыстоўваць Claude Code, зазвычай стварае файл CLAUDE.md і кладзе туды ўсё: настройкі праекта, правілы кодавання, правіла падачы запрошэнняў да спалучэння, дэталі тэхналогій, прыміткі для адчынення працы. Пасля да размовы прыўлекаецца файл 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/ з настройкай paths у 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 порынае гэты запіт з опісамі всіх вашых навыкаў і выбірае той, які падходзіць. Калі задача завершыцца, навык выключаецца. Ось як можа выглядаць фронтматэр:

---
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 выбірае на адной падставе апісання. Нечыткая фраза на кшталт "дапамагае з кодам" або не будзе дзейсніцца, або працаваць для всего. Точнае апісанне, напрыклад "пераглядае запросы змін у Python на наявнасць вразломаў, такіх як SQL injection або зашчытаныя у кодзе секрэты", працавае надзейна і толькі тады, калі цэлкам актуальна. Назва папкі прызначаная для вас, а апісанне — для Claude, таму пішыце яго для Claude.

Два корыстныя варыянты frontmatter

allowed-tools абмежоўвае тое, што можа робіць Claude калі навык ўвёрнуты. Для навыку, які аналізуе кодавую базу, настройка на чытанне, 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, «толькі для аднаго тыпу заданняў» — навык. Ваша вікна кантэксту — гэта бюджэт: галоўны файл выкарыстоўвае частку яго за кожнае паведамленне, а навыкі — толькі калі ўжо вікорыстоўваюцца, таму праектаваць структуру трэба са гэтым у вачоўку.