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/ з параметром paths у frontmatter. Наприклад, файл testing-rules може завантажуватися лише під час редагування файлів тестів, що дозволяє уникнути наявності непотрібних інструкцій у контексті.

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

Що має бути всередині

Тримайте текст коротким. Розумною метою є не перевищувати 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, «лише для одного типу завдань» — навичка. Ваше вікно контексту — це бюджет: основний файл витрачає частину його на кожне повідомлення, тоді як навички витрачають ресурси лише під час використання, тож проектуйте структуру з урахуванням цього.