CLAUDE.md у Claude Code: як написати файл-інструкцію, яку агент справді виконує

Коротко (TL;DR)

CLAUDE.md — це текстовий файл у корені проєкту, який Claude Code читає на початку кожної сесії й тримає як контекст: правила, команди збірки, домовленості команди. Це не програма і не конфіг із жорстким синтаксисом — звичайний Markdown, який ви пишете людською мовою.

Що важливо зрозуміти одразу:

• Claude Code читає саме CLAUDE.md (не AGENTS.md і не README). Створити стартовий файл можна командою /init.
• Файлів може бути кілька на різних рівнях — від загальнокорпоративного до особистого — і вони складаються в контекст по порядку.
• CLAUDE.md — це контекст, а не примус. Anthropic офіційно підтвердила: вміст подається моделі як підказка, а не як жорстке правило. Тому «claude code не виконує інструкції» — часта і зрозуміла скарга.
• Оптимальний розмір — до ~200 рядків. Довгий файл модель дотримується гірше: це підтверджує і документація, і аналіз 2500 реальних репозиторіїв.
• Для того, що «мусить спрацьовувати без винятків» (не чіпати секрети, запускати лінтер), CLAUDE.md не годиться — там потрібні хуки.

Нижче — як влаштована ієрархія, як створити й правильно написати файл, як він живе в сесії і чому на нього не можна покладатися як на захист.

Що таке CLAUDE.md простими словами

CLAUDE.md — це файл пам’яті проєкту: інструкція, яку агент підвантажує на початок розмови, щоб працювати за вашими правилами, а не «взагалі». Без нього Claude Code щоразу стартує з чистого аркуша й вгадує ваші домовленості; з ним — одразу знає, чим збирати проєкт, як оформлювати коміти й чого робити не можна.

Іноді CLAUDE.md шукають як файл налаштувань — це не зовсім так. За технічну конфігурацію (права, змінні, модель) відповідає settings.json, а CLAUDE.md — це контекст для моделі, написаний звичайною мовою. Плутати їх не варто: один примушує, інший спрямовує.

Хуки Claude Code: як автоматизувати дії агента і не підірватися на власних налаштуваннях

MCP у Claude Code: як підключити сервери, не спалити контекст і коли він не потрібен

Плагіни в Claude Code: як встановити, створити власний маркетплейс і не спіймати шкідливий

SKILL.md без магії: збираємо власну навичку Claude Code за інженерними патернами

Agent Skills у Claude Code: як працюють, де взяти і як не поставити шкідливий скіл

Механічно це працює так: вміст CLAUDE.md доставляється моделі як користувацьке повідомлення одразу після системного промпту — а не як частина самого системного промпту. Різниця тонка, але принципова: файл впливає на поведінку як дуже вагома підказка, але не як вбудоване в модель обмеження. Звідси й усі подальші властивості — і користь, і межі.

CLAUDE.md — це інструкція для моделі, яка веде ваш проєкт (наприклад, Claude Sonnet 5 або Opus). Тому файл описує не «як влаштований Claude», а «як влаштований ваш проєкт і як ви хочете, щоб із ним працювали».

Де лежить CLAUDE.md і в якому порядку завантажується

Файлів може бути кілька, і вони не конфліктують, а накопичуються. Claude Code збирає їх за рівнями видимості — від загального до конкретного.

У межах однієї теки CLAUDE.local.md дописується після CLAUDE.md — тобто ваші особисті нотатки Claude читає останніми на цьому рівні. CLAUDE.local.md у спільний репозиторій зазвичай не комітять (це особисте), а managed-файл на різних ОС лежить за своїм шляхом: macOS — /Library/Application Support/ClaudeCode/CLAUDE.md, Linux і WSL — /etc/claude-code/CLAUDE.md, Windows — C:\Program Files\ClaudeCode\CLAUDE.md. Проєктний файл, до речі, документація допускає і як ./CLAUDE.md, і як ./.claude/CLAUDE.md — обидва варіанти робочі.

Для новачка практичний висновок простий: почніть з одного файлу ./CLAUDE.md у корені проєкту — цього достатньо для більшості завдань. Особистий ~/.claude/CLAUDE.md заводять пізніше, коли з’являються звички, спільні для всіх проєктів.

Як створити CLAUDE.md: /init і що туди писати

Швидкий старт — команда:

/init

Вона аналізує кодову базу й генерує стартовий CLAUDE.md з командами збірки, інструкціями щодо тестів і структурою проєкту. Одна прихована деталь: якщо файл уже існує, /init не затирає його мовчки — але зібраний автоматично файл усе одно варто вичитати руками, він часто виходить «водянистим».

Що справді варто тримати в CLAUDE.md, а що — ні:

Хороший CLAUDE.md відповідає на три питання: навіщо цей проєкт (контекст), що в ньому де лежить (карта), як тут заведено працювати (правила). Це зручний кістяк: WHY / WHAT / HOW.

Ось як виглядає компактний робочий приклад для вебпроєкту:

# Проєкт: інтернет-магазин на Next.js

## Стек і команди
- Next.js 15 + TypeScript, база — Postgres (Prisma).
- Збірка: `npm run build` · Тести: `npm test` · Лінт: `npm run lint`.
- Перед комітом завжди виконуй лінт і тести.

## Домовленості
- Компоненти — у `src/components`, по одному на файл.
- Коміти — Conventional Commits (`feat:`, `fix:`).

## Чого не робити
- Не чіпай `src/legacy/` — там ручні патчі, зміни ламають оплату.
- Не пиши бізнес-логіку в компонентах — виноси в `src/lib`.

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

Як писати правила, які агент виконує

Тут і криється відповідь на «чому Claude читає файл, але ігнорує правило». Річ рідко в самому Claude — частіше у формулюваннях. Аналітичний розбір реальних CLAUDE.md (інструмент ccmd.dev) виділяє конкретні патерни, які модель пропускає:

• Надто довгі правила. Інструкція, довша за ~28 слів, розмивається — модель «губить» її суть. Дробіть на короткі пункти.
• Розпливчасті слова. «Пиши якісно», «будь акуратний», «правильно оформлюй» — модель не знає, що це означає в цифрах. Замінюйте на перевірюване.
• Абсолюти без винятків. «Ніколи не роби X» без вказівки, що робити натомість, працює гірше, ніж правило з явною альтернативою.
• Відсутність «чому». Правило з причиною («не чіпай legacy/, там ручні патчі») дотримується краще за голу заборону.
• Дублі й конфлікти. Два правила, що суперечать одне одному, гарантовано валять обидва.

Різницю видно на одному рядку. Слабко: «Пиши хороший, чистий код і покривай його тестами». Модель не знає, що для вас «хороший», і правило розчиняється. Сильно: «Кожна нова функція в src/lib — з юніт-тестом поруч; перед комітом npm test має бути зеленим». Другий варіант перевірюваний і прив’язаний до вашого проєкту — його агент виконає, бо розуміє, чого саме від нього хочуть.

Простий тест для кожного рядка: «якщо я це приберу, Claude помилиться?» Ні — викреслюйте. CLAUDE.md — це контракт поведінки, а не документація: що він коротший і конкретніший, то краще дотримується.

Про довжину є й цифри. Офіційна рекомендація — тримати файл коротшим за ~200 рядків: довгі файли з’їдають контекст і знижують дотримання правил. Емпірика підтверджує: аналіз 2500 публічних репозиторіїв із Claude Code (дані на червень 2026) показав, що CLAUDE.md є у 84,9% проєктів, а медіанний файл — 6,2 КБ, це приблизно 100–150 рядків. Розумний орієнтир, а не «що більше, то краще».

Є й оцінка практиків (першоджерело — гайд HumanLayer, який часто переказують): фронтир-моделі надійно тримають близько 150–200 інструкцій за раз, і ~50 з них уже «з’їдає» системний промпт Claude Code. Це community-оцінка, а не виміряний факт Anthropic, але як орієнтир корисна: бюджет правил не безмежний, витрачайте його на важливе.

Пам’ять, імпорти й життєвий цикл у сесії

Навколо CLAUDE.md є кілька механік, що збивають новачка з пантелику. Розберемо коротко.

Імпорти @path. Усередині CLAUDE.md можна підключити інший файл рядком @path/to/file, а той може імпортувати наступний. Тут є розбіжність джерел: офіційна документація називає максимальну глибину чотири «стрибки», а деякі гайди пишуть про п’ять — імовірно, через різний спосіб рахунку. Орієнтуйтеся на офіційну цифру (4) і не будуйте надто глибокі ланцюжки.

Сумісність із AGENTS.md. Claude Code читає CLAUDE.md, а не AGENTS.md (відкритий стандарт, який використовують інші агенти). Якщо в репозиторії вже є AGENTS.md, зв’яжіть їх: рядком @AGENTS.md усередині CLAUDE.md або симлінком. У Windows створення симлінка потребує прав адміністратора — там простіше імпорт.

Auto memory (автопам’ять Claude Code) — це не те саме, що CLAUDE.md. Починаючи з версії 2.1.59, Claude Code вміє вести власну пам’ять у MEMORY.md; на старті кожної сесії з неї завантажуються перші 200 рядків або перші 25 КБ (що настане раніше). CLAUDE.md ви пишете самі й комітите в проєкт; auto memory агент накопичує сам. Якщо цікаво, як ШІ-агент узагалі веде свою базу знань і чим це відрізняється від простого пошуку по документах, — це окрема велика тема.

Правила під конкретні файли — .claude/rules/. Для великих проєктів замість роздування CLAUDE.md зручніша тека .claude/rules/*.md: там правило через YAML-заголовок paths можна прив’язати до конкретних файлів і підвантажувати лише тоді, коли Claude працює саме з ними.

Що переживає /compact. Кореневий CLAUDE.md проєкту переживає стиснення контексту: після /compact Claude перечитує його з диска й вставляє заново. А от CLAUDE.md у підкаталогах на старті взагалі не завантажуються — вони підтягуються на вимогу, коли агент заходить у відповідну теку.

Коментарі для людей. Блокові HTML-коментарі (<!-- ... -->) вирізаються перед подачею файлу в контекст моделі — у них можна лишати нотатки для колег, не витрачаючи на це токени агента.

Чого CLAUDE.md не вміє: ризики й обмеження

Найважливіший і майже ніде не проговорений момент. CLAUDE.md — це контекст, а не захист. Команда безпеки Anthropic офіційно підтвердила це через HackerOne (20 травня 2026): CLAUDE.md, AGENTS.md і .claudeignore — «механізми контексту й пам’яті, їхній вміст подається моделі як настанова, а не примушується як жорстке обмеження». Правило можна перевизначити мовчки, без логу й попередження.

Це не абстракція. Кілька підтверджених прикладів:

• Витік секретів попри заборону. У відкритих GitHub-issue (перший — #44868, квітень 2026) користувачі показали, що Claude Code читав і виводив у чат вміст .env і файлів із ключами, попри явну заборону в CLAUDE.md, — через cat, grep, Edit. Людям доводилося ротувати витеклі credentials.
• CVE-2026-21852. Знайдено й пропатчено (у версії 2.1.90, 6 квітня 2026) баг: команда з понад 50 зчеплених підкоманд обходила перевірку deny-правил у permissions без попередження. Небезпека в тому, що така команда могла прийти з чужого CLAUDE.md — наприклад, під час роботи з недовіреним репозиторієм.

Звідси практичний висновок, і він не про алармізм. Для того, що мусить виконуватися без винятків, використовуйте не текст у CLAUDE.md, а детерміновані механізми: хуки (PreToolUse/Stop у settings.json) і permissions.deny. Сама документація Anthropic прямо розподіляє працю: settings — для технічного примусу, CLAUDE.md — для поведінкових домовленостей. Це не «CLAUDE.md зламаний», а чесно позначена межа відповідальності. Правило «ніколи не читай .env» у CLAUDE.md — побажання; та сама мета через permissions.deny — бар’єр.

І тут же — куди рухатися далі. Той самий аналіз 2500 репозиторіїв показав розрив: CLAUDE.md завели 84,9% проєктів, але до субагентів і хуків доходить лише близько чверті. Тобто більшість зупиняється на базовому файлі й не бере інструменти, які якраз закривають слабкі місця CLAUDE.md. Опанувавши файл-інструкцію, логічно наступним кроком розібратися з settings.json і хуками — вони перетворюють ваші домовленості з побажань на гарантії.

FAQ

Чим CLAUDE.md відрізняється від auto memory? CLAUDE.md ви пишете й комітите самі — це усвідомлені правила проєкту. Auto memory (MEMORY.md, з версії 2.1.59) агент веде сам, накопичуючи факти між сесіями. Перший — ваш контракт з агентом, друга — його власний блокнот.

Чому Claude читає CLAUDE.md, але не виконує правило? Дві причини. Перша — формулювання: надто довге, розпливчасте або суперечливе правило модель «губить». Друга — фундаментальна: CLAUDE.md подається як підказка, а не як жорстке обмеження, тому в рідкісних випадках його можна проігнорувати. Критичні речі виносьте в хуки.

Який оптимальний розмір CLAUDE.md? Орієнтир — до ~200 рядків (медіана в реальних проєктах — близько 100–150 рядків). Довше — гірше дотримується й дорожче за контекстом. Якщо не вміщаєтеся, виносьте деталі в .claude/rules/ або в README.

Чи потрібно комітити CLAUDE.md у git? Проєктний ./CLAUDE.md — так, щоб правила отримала вся команда. А CLAUDE.local.md — це особисті нотатки, їх зазвичай тримають поза спільним репозиторієм.

Чи можна покластися на правило «NEVER» у CLAUDE.md як на захист? Ні. Це підтверджено і офіційно, і інцидентами. Для секретів і деструктивних команд використовуйте permissions.deny і хуки в settings.json — вони детерміновані, на відміну від порад у CLAUDE.md.

Чи читає Claude Code AGENTS.md? Безпосередньо — ні, він читає CLAUDE.md. Якщо в репозиторії є AGENTS.md, зв’яжіть їх імпортом @AGENTS.md або симлінком (у Windows симлінк потребує прав адміністратора).