Де мають знаходитися інструкції Claude Code: у CLAUDE.md, правилах маршруту чи хуках

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

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

CLAUDE.md – це контекст, а не конфігурація

Усі інші проблеми походять від цього хибного уявлення. Claude Code вставляє файл у розмову як повідомлення; він не об’єднується з системним запитом, і ніщо під час виконання не змушує його дотримуватися. Модель читає його та намагається дотримуватися його вказівок. Більше немає жодних гарантій, а шанси ще більше зменшуються, коли формулювання є нечіткими або дві інструкції суперечать одна одній.

Корисною ментальною моделлю є нотатка з передачі обов’язків для кваліфікованого колеги, який швидко її прочитує за ранковою кавою, а потім приступає до справжньої роботи. Те, що залишається після цього процесу, — це матеріал, який є коротким, конкретним та послідовним. Тож довжина, точність та внутрішня послідовність є єдиними справжніми інструментами, які у вас є, а не питання стилю.

Зберігайте основний файл менше ніж на 200 рядків

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

Це суперечить здоровому глузду: чим більше інструкцій, тим менше з них дотримується Claude. Кожен рядок конкурує за ту саму обмежену кількість уваги з усіма іншими рядками та з самою розмовою. Уявіть команду, чий файл містив 340 рядків. Його скорочення до приблизно 120 рядків дозволило Claude більш надійно його слідувати. Жоден з вилучених рядків не був неправильним; вони просто були шумом, який додавався до важливих інструкцій.

Існує також жорсткий ліміт, проти якого не варто проєктувати систему: згідно з документацією на момент написання, файли розміром понад 4 МБ повністю ігноруються. Дотримання вимог починає погіршуватися задовго до того, як файл наблизиться до такого розміру.

Видаліть те, що Claude може знайти у репозиторії

Найефективніше правило редагування є простим: видаляйте все, що Claude може з’ясувати, прочитавши кодову базу. Це узгоджується з рекомендаціями власної функції /doctor у Claude Code, яка передбачає видалення структури папок, списків залежностей та описів архітектури високого рівня, залишаючи при цьому проблемні моменти, обґрунтування та конвенції, які відрізняються від стандартних налаштувань інструменту. Іншими словами, це змінює звичайний вміст цих файлів.

Що потрібно видалити:

• Структуру папок, адже Claude може самостійно перелічити каталоги.
• Список залежностей, який вже записаний у package.json.
• Опис архітектури у вигляді оповіді, оскільки код передає цю інформацію точніше.

Що потрібно залишити:

• Код, який виглядає як помилка, але є навмисним.
• Причину відхилення очевидного підходу.

Будь-яка конвенція, яка суперечить документації фреймворку.

Команди, які ніхто не знайде самостійно.

Хороший тест: якщо компетентний інженер з відкритим репозиторієм може ознайомитися з ним протягом десяти хвилин, залиште його без уваги. Якщо він дізнається про нього лише шляхом пошкодження чогось, запишіть це.

Залишайте примітки для людей без жодних витрат

Коментарі на рівні блоків HTML видаляються перед тим, як зміст файлу потрапить у контекст Claude. Це дозволяє вам робити примітки до файлу для тих, хто ним керує, не витрачаючи жодних ресурсів моделі, наприклад, щоб записати, чому певний розділ було переміщено:

<!-- Deleted the API section — moved to .claude/rules/api.md, Sep 2026 -->

Ваші колеги бачать історію змін; модель ніколи за це не платить.

@imports організовують файл, але не зберігають контекст

Коли файл CLAUDE.md стає занадто довгим, першою реакцією є розділення його на кілька документів та їх імпорт:

@docs/architecture.md
@docs/api-conventions.md
@docs/testing.md

Це схоже на лежачу завантаження, але це не так. Імпортовані файли розгортаються та завантажуються в контекст під час запуску разом із CLAUDE.md, який на них посилається. Розділення 340 рядків на чотири окремі файли все одно призводить до завантаження тих самих 340 рядків.

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

Обмежте умовні правила за допомогою .claude/rules та шляхів

Файли у директорії .claude/rules/ можуть вказати поле paths у своєму frontmatter. Саме ця функція забезпечує те, чого очікують користувачі від імпорту: правило з глобальним охопленням залишається поза контекстом, доки Claude не прочитає або не змінить відповідний файл. Frontmatter файла правил API може виглядати ось так:

---
paths:
  - "src/api/**/*.ts"
---

Після frontmatter тіло правила містить конвенції, які застосовуються лише до цієї частини структури, такі як перевірка вхідних даних, спільна структура помилок та місця, де дозволений SQL:

# API rules- Every endpoint validates input before touching the database
- Errors use the standard envelope in `src/api/errors.ts`
- No direct SQL outside `src/api/repositories/`

У результаті робота фронтенду більше не оплачує витрати на токени, пов’язані з конвенціями API, а робота з API — витрати на тестування.

На практиці це є рішенням проблеми надмірного розростання CLAUDE.md. Розділіть контент за темами, приєднайте кожну тему до відповідних директорій, а кореневий файл залиште для інструкцій, що стосуються всього проекту. Файл правил без поля paths завантажується при кожній сесії, тому сприймайте це як свідомий вибір, а не стандартну практику.

Flobs підтримують розширення за допомогою дужок, тож одне правило може охоплювати кілька розширень та окремий шаблон перевірки:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "tests/**/*.test.ts"
---

Кроки, які обов’язково потрібно виконати, мають бути у hooks

Фрази на кшталт „lint перед кожним commit“, „не підтягувати зміни безпосередньо до main“ чи „форматувати кожен файл після редагування“ є поширеними в CLAUDE.md. Їх зазвичай дотримуються, винятки помічаються, і команди роблять висновок, що цій системі не можна довіряти.

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

Практичний спосіб розподілу кожного типу інструкцій:

• Загальноприйняті правила, яких Claude слід дотримуватися, записуються у CLAUDE.md.
• Правила для певної частини кодової бази розміщуються у .claude/rules/ разом із параметром paths.
• Вимоги, які не допускають жодних винятків, перетворюються на хуки.
• Багатокрокові процедури, які можна повторювати, стають навичками.

Перенесення кількох правил типу „завжди“ до механізму hooks має подвійну перевагу: тепер вимоги дійсно виконуються, а файл позбавляється рядків, які ніколи не можуть спрацювати, що дозволяє приділити більше уваги інструкціям, які справді можуть бути корисними.

Перевірка того, що насправді завантажилося

Запустіть команду /context та перегляньте розділ з файлами пам’яті — він точно відображає те, що було завантажено під час роботи сесії. Команда /memory доповнює її, перелічуючи файли на рівні користувача та проєкту та дозволяючи їх відкрити. Разом вони перетворюють запитання „Чи ігнорує Claude це?“ з припущень на щось, що можна перевірити. Дивно, але досить легко витрачати час на доопрацювання формулювань у файлі, який взагалі не завантажується.

Суперечності у об’єднаних файлах

Ніщо не переважується; все об’єднується. Починаючи з робочої директорії, Claude Code просувається до кореня файлової системи та збирає кожен файл CLAUDE.md по дорозі, а потім впорядковує їх від кореня донизу. На будь-якому рівні, де також є файл CLAUDE.local.md, цей файл йде після свого „брата“ — файла CLAUDE.md. У монорепозиторії два файли можуть легко давати протилежні вказівки. У такому разі Claude може просто обрати один з них, і ви не отримаєте жодних попереджень про конфлікт.

Файли-предки, яких ви не просили

Якщо файл CLAUDE.md у батьківській директорії потрапляє до ваших сеансів, параметр claudeMdExcludes у ваших локальних налаштуваннях дозволяє ігнорувати певні файли за допомогою шаблонів.

Що залишається після стиснення

Файл CLAUDE.md у корені проекту знову читається з диска та вставляється після команди /compact, тож його інструкції залишаються. Усе, що було сказано лише під час розмови, втрачається. Якщо ви постійно повторюєте однакові корективи після кожної стиснення, це є явним сигналом того, що вони мають потрапити до файлу.

Шаблон для початку

Якби ви створювали налаштування з нуля, розумна мета виглядала б так:

• Кореневий файл CLAUDE.md об’ємом близько 120 рядків, який містить лише те, що є актуальним у всіх випадках.
.claude/rules/ з використанням шаблонів для шляхів.
• Нічого такого, що хтось міг би дізнатися, прочитавши репозиторій протягом десяти хвилин.
• Швидка перевірка за допомогою команди /context після кожної зміни.

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

Основні висновки

• Пишіть CLAUDE.md для колеги, який читає, а не для машини, яка виконує код: коротко, конкретно та без суперечностей.
• Коротші файли обробляються надійніше; видаліть усе, що кодбаза вже повідомляє Claude.
• Імпорти реорганізовують вміст, але завантажують усе; саме правила, пов’язані з шляхом, насправді відкладають завантаження.
• Усе, що має відбуватися щоразу, потребує спеціального механізму, оскільки контекст може впливати лише на поведінку.
• Перш ніж коригувати формулювання, вважайте /context своїм джерелом істини.