CLAUDE.md — це markdown-файл, який Claude Code автоматично завантажує на старті кожної сесії; він не виконується як конфіг, а просто вставляється в промпт як текст.
Головна технічна помилка, яку роблять майже всі: розбивають файл на @imports, думаючи, що це економить контекст. Насправді імпорти завантажуються цілком одразу — контекст реально економлять лише path-scoped rules у .claude/rules/.
Орієнтир розміру: до 200 рядків для project CLAUDE.md, до 30 рядків для особистого ~/.claude/CLAUDE.md — моделі надійно тримають у голові приблизно 150-200 інструкцій одночасно, а системний промпт самого Claude Code вже займає близько 50 із них.
CLAUDE.md, AGENTS.md і Cursor Rules — не взаємозамінні: Claude Code читає лише CLAUDE.md, Cursor — .cursor/rules/ і AGENTS.md, а сам AGENTS.md як відкритий стандарт зараз стоїть у понад 60 000 репозиторіїв.
У статті — робочий приклад CLAUDE.md для Spring Boot-проєкту, розбір типових помилок і два задокументовані баги, про які мовчить більшість гайдів.
CLAUDE.md — це звичайний markdown-файл, який Claude Code автоматично підвантажує на старті кожної сесії, даючи моделі те, що можна назвати постійною пам'яттю про проєкт: команди, архітектуру, конвенції — усе те, що модель не може вивести з самого коду (офіційна документація Claude Code). Я б сформулював суть файлу максимально просто: CLAUDE.md не робить Claude розумнішим — він робить так, щоб Claude перестав забувати.
Це не гіпербола. Я особисто стикався з ситуацією, коли протягом тижня доводилось щосесії повторювати одне й те саме зауваження про архітектурний паттерн проєкту — і як тільки цей рядок переїхав у CLAUDE.md, потреба повторювати зникла (схожий досвід описаний у розборі maketocreate.com на прикладі Laravel-проєкту з патерном "репозиторій замість Eloquent у контролерах").
Відмінність від README.md: README пишеться для людей, які відкривають репозиторій вперше, — це вітрина проєкту. CLAUDE.md пишеться для моделі, яка вже "знає", як виглядає типовий код, і потребує лише того, що відрізняє саме ваш проєкт від дефолтних припущень.
Відмінність від AGENTS.md: AGENTS.md — відкритий крос-інструментальний стандарт, який читають Codex, Cursor, Copilot, Gemini CLI та інші. Claude Code його нативно не читає — лише CLAUDE.md (TECHSY, перевірено на живому репозиторії). Детальніше про це — у розділі порівняння нижче.
Відмінність від Cursor Rules: Cursor Rules — формат, специфічний для Cursor (.cursor/rules/*.mdc), з власною системою YAML-frontmatter і режимів активації. Це паралельна, не сумісна з CLAUDE.md система: покласти CLAUDE.md у Cursor-проєкт — і Cursor його просто проігнорує.
Як Claude використовує CLAUDE.md
Claude Code шукає файли CLAUDE.md за ієрархією каталогів і завантажує їх з різною поведінкою залежно від рівня:
Глобальний (~/.claude/CLAUDE.md) — особисті налаштування, що діють у кожному проєкті на вашій машині.
Project root (./CLAUDE.md) — головний файл, який комітиться в git і працює для всієї команди.
Вкладені CLAUDE.md у піддиректоріях — підвантажуються не одразу, а лише коли Claude реально звертається до файлів у відповідній піддиректорії. Це навмисний дизайн: монорепо з 50 піддиректоріями не роздує контекст інструкціями, які прямо зараз не потрібні (Serenities AI).
Коли інструкції з різних рівнів конфліктують, діє просте правило: більш специфічна інструкція перебиває загальнішу. Якщо організаційна політика каже "4 пробіли для відступів", а проєктний CLAUDE.md каже "2 пробіли" — для цього проєкту виграє проєктна інструкція (Serenities AI). Це правило варто тримати в голові й тоді, коли ви вирішуєте, на якому рівні писати те чи інше — щось справді спільне для всіх ваших проєктів краще одразу класти в глобальний файл, а не дублювати в кожному проєктному.
Як Claude Code технічно завантажує CLAUDE.md: imports vs rules vs compaction
Це той розділ, заради якого я взагалі сів писати цю статтю — тому що майже всі гайди, які я переглянув перед написанням, дають пораду "тримайте файл коротким", але жоден нормально не пояснює, чому саме одні техніки скорочення контексту працюють, а інші — лише здаються, що працюють.
@imports завантажуються eagerly. Якщо ви розіб'єте 500-рядковий CLAUDE.md на п'ять імпортів по 100 рядків кожен, ви отримаєте зручніший у підтримці набір файлів — але контекст, який реально завантажується в модель, залишиться тим самим 500-рядковим обсягом. Імпорт розгортається цілком у момент старту сесії, ніби ви вставили вміст файлу напряму (Claude Certification Guide). Це та пастка, у яку я сам мало не потрапив: здавалось логічним, що розбиття на файли зменшує навантаження, а насправді воно лише зменшує хаос у вашому редакторі.
`.claude/rules/*.md` з `paths:` frontmatter завантажуються on-demand. На відміну від імпортів, файли правил у .claude/rules/ підвантажуються лише тоді, коли Claude реально працює з файлом, що підпадає під зазначений glob-патерн. Це єдиний механізм у цій системі, який справді, а не умовно, скорочує контекст (офіційна документація). Якщо ваша мета — зменшити обсяг контексту, а не просто навести лад у файлах, вам потрібні саме rules, а не imports.
Компакція сесії. Кореневий CLAUDE.md переживає /compact — після стиснення історії розмови Claude заново читає його з диска й переінжектить у сесію. А ось вкладені CLAUDE.md і path-scoped rules після компакції автоматично не повертаються — вони підвантажуються знову лише тоді, коли Claude наступного разу звертається до відповідної піддиректорії чи файлу (офіційна документація).
Вбудований трімінг. Починаючи з Claude Code v2.1.206, є команда /doctor, яка сама аналізує ваш закомічений CLAUDE.md і пропонує, що прибрати: усе, що модель може вивести безпосередньо з коду (структуру папок, список залежностей, огляд архітектури), — на видалення; граблі, обґрунтування рішень і нестандартні конвенції, які код сам по собі не показує, — залишити (офіційна документація). Я вважаю цей критерій — "чи можна це вивести з коду" — найкращим практичним тестом для будь-якого рядка у вашому файлі, і повертатимусь до нього нижче в розділі найкращих практик.
Що обов'язково має бути в CLAUDE.md
Я підходжу до цього списку не як до довільного набору категорій, а через один критерій, який вже згадував вище: сюди йде тільки те, чого модель не може впевнено вивести сама з коду. Якщо архітектуру можна на 90% зрозуміти, просто відкривши три файли — не варто її описувати. Але є категорії, де без явної інструкції модель майже завжди вгадує неправильно або витрачає кроки на з'ясування — і саме вони складають цей список з мого практичного досвіду.
Стек технологій — мова, фреймворк, версії, які не завжди однозначно видно з package.json чи pom.xml. Особливо це стосується перехідних періодів: якщо проєкт частково на Java 17, частково вже на 21, або використовує Spring Boot 3.x з окремими модулями на старішій версії — модель цього не вгадає, а помилково застосований API новішої версії призведе до помилки компіляції, яку доведеться виправляти вручну.
Архітектура — як організовані шари застосунку, куди має йти новий код. Без цього пункту я регулярно бачив, як модель кладе бізнес-логіку прямо в контролер, бо це найпростіший робочий шлях — технічно код працює, але ламає прийняту в проєкті шарову структуру.
Правила іменування — конвенції, які відрізняються від дефолтних для мови чи фреймворку. Модель за замовчуванням піде за загальноприйнятими стандартами Java чи Spring; якщо у вашій команді є власне відхилення (наприклад, суфікс Dto замість Request/Response), це треба сказати прямо — сама вона про цю домовленість не здогадається.
Команди збірки — реальні команди вашого проєкту (make build, ./gradlew build), а не загальні припущення. Без цього модель часто пропонує генеричну команду на кшталт mvn install, навіть якщо ваш проєкт давно на Gradle — і ви втрачаєте час на банальне виправлення.
Тестування — який фреймворк, як запускати, чи потрібно писати тести до фічі чи після. Це пункт, який найбільше впливає на те, чи модель сама перевіряє свою роботу перед тим, як сказати "готово", чи просто здає код на віру.
Обмеження — директорії чи файли, яких Claude не повинен торкатись без явного дозволу. Я б виділив це окремо як єдиний пункт зі списку, що працює не на якість коду, а на безпеку: без явної заборони модель може змінити файл міграції, який уже застосований у production, просто тому що це технічно "найпростіше" рішення задачі.
Definition of Done — коли задачу вважати завершеною: тести пройшли, лінтер чистий, документація оновлена. Без цього пункту межа між "код написано" і "задача виконана" стає розмитою, і саме тут найчастіше виникає розрив очікувань між тим, що видала модель, і тим, що насправді потрібно було здати.
Що ніколи не варто писати в CLAUDE.md
Це, на мою думку, найважливіший розділ усієї статті — і саме той, де найбільше конкурентів обмежуються загальними словами. Я навмисно поясню не просто "що не варто писати", а що конкретно ламається, коли ви це все ж пишете — тому що "не потрібне" звучить як порада на смак, а насправді за кожним пунктом стоїть конкретний механізм шкоди.
Величезні шматки коду. CLAUDE.md — не місце для прикладів реалізації; посилайтесь на конкретний файл, а не вставляйте вміст. Проблема не тільки в об'ємі: вставлений код застаріває швидше за текстовий опис. Опис архітектури "сервіс не звертається напряму до repository іншого модуля" залишається правдивим і через рік. Вставлений приклад коду, який давно відрефакторили, буде активно вводити модель в оману — вона орієнтуватиметься на приклад, а не на те, як код виглядає насправді сьогодні.
Документацію API. Вона змінюється частіше за CLAUDE.md і швидко застаріє; посилання на реальну документацію живе довше за копію. Тут проблема гірша, ніж просто "застаріє" — застаріла копія API-документації в CLAUDE.md активно шкідлива, бо модель довіряє їй так само, як і решті файлу. Вона з упевненістю запропонує ендпоінт, якого вже немає, або поле, яке перейменували два спринти тому, і ви отримаєте не помилку компіляції, а тиху логічну помилку, яку легко пропустити на рев'ю.
README. Дублювання README у CLAUDE.md означає подвійну підтримку одного й того ж контенту — рано чи пізно вони розійдуться. Я на власному досвіді бачив, як команда оновлює README при кожному релізі, бо на нього дивляться нові розробники, а копію в CLAUDE.md забувають — просто тому, що це файл, який відкривають рідше за очима, хоча й читають частіше моделлю.
Changelog. Історія змін не впливає на те, як писати новий код сьогодні — це баласт, який їсть контекст щосесії. Тут аргумент суто економічний: кожен рядок про те, що сталося в лютому, конкурує за увагу моделі з рядком про те, як писати код зараз, — а модель не вміє автоматично зважувати "це історія" проти "це актуальне правило", вона просто читає весь файл як рівнозначний контекст.
Інструкції на один раз. "Сьогодні онови залежність X" — це задача для чату, не для файлу, який завантажується постійно. Якщо цю інструкцію не прибрати після виконання, вона продовжить завантажуватись у кожній наступній сесії й може навіть плутати модель, коли задача вже давно виконана, а файл усе ще каже "онови X" — модель або спробує зробити це повторно, або витратить крок на з'ясування, чи це вже зроблено.
Очевидні речі. "Пиши чистий код", "додавай коментарі де потрібно" — не дають моделі нічого, чого вона й так не робить за замовчуванням, і просто займають рядки з ліміту в 150-200 інструкцій, про який я писав вище. Це найкоштовніший тип баласту з усіх перелічених: він не просто марний, а витісняє місце, яке міг би зайняти рядок із реальним ефектом — наприклад, те саме правило іменування DTO, яке модель дійсно не могла вгадати сама.
Оптимальна структура CLAUDE.md
За результатами того, що я бачив у робочих production-файлах і в рекомендаціях спільноти, оптимальна структура виглядає так:
Project overview
Architecture
Coding conventions
Directory structure
Commands
Testing
Security
Definition of Done
Agent behaviour
Useful references
Порядок тут не випадковий: спочатку — контекст, у якому модель має розуміти, що взагалі за проєкт (overview, architecture), потім — правила, за якими писати код (conventions, structure), потім — як перевіряти власну роботу (commands, testing, security, DoD), і насамкінець — поведінкові інструкції та посилання на додаткові матеріали.
Найкращі практики написання CLAUDE.md
Робіть файл коротким — конкретно. Орієнтир: до 200 рядків для project CLAUDE.md, до 30 рядків для особистого ~/.claude/CLAUDE.md. Це не довільна цифра — frontier-моделі надійно слідують приблизно 150-200 інструкціям одночасно, а системний промпт самого Claude Code вже займає близько 50 з них (HumanLayer, через maketocreate.com). Тобто кожен зайвий рядок у вашому файлі — це реальна конкуренція за увагу моделі з іншими інструкціями, а не безкоштовний бонус.
Використовуйте абсолютні правила. "Намагайся використовувати named exports" гірше за "Використовуй named exports, не default exports" — модель краще слідує чіткій, однозначній інструкції, ніж м'якому побажанню.
Уникайте протиріч — і розумійте, як система резолвить конфлікт, якщо він виник. Я вже писав це вище, але повторю тут навмисно: більш специфічна інструкція перебиває загальнішу. Знання цього правила означає, що ви можете свідомо покласти виняток на нижчому рівні (наприклад, в CLAUDE.md конкретної піддиректорії), а не намагатись утримати одне гігантське несуперечливе правило на весь проєкт.
Розділяйте загальні й локальні інструкції. Загальні особисті вподобання (улюблений формат діффа, часовий пояс) — у глобальний файл. Командні конвенції — у проєктний, під git.
Регулярно оновлюйте файл. CLAUDE.md, який не редагувався три місяці на проєкті, що активно розвивається, — це майже гарантовано файл із застарілими командами.
Не зберігайте історію проєкту. "Раніше ми використовували Redux, зараз перейшли на Zustand" — цікаво для людини, марно для моделі, якій потрібен лише поточний стан.
Посилайтесь на документацію замість копіювання. Один рядок з посиланням живе довше за скопійований параграф, який ніхто не буде синхронізувати вручну.
Додавайте реальні команди проєкту. Не "запустіть тести", а буквально ./gradlew test чи npm run test:unit — модель не повинна вгадувати.
Головний тест для будь-якого рядка: чи можна це вивести з коду? Якщо так — це кандидат на видалення. Саме цю логіку використовує вбудований /doctor, і я раджу застосовувати її свідомо ще до того, як writing перетвориться на 300-рядковий файл, який доведеться урізати заднім числом.
Приклад хорошого CLAUDE.md
# Project overview
Backend API для системи бронювання приміщень. Spring Boot 3.5, Java 21, PostgreSQL.
# Architecture
Шарова архітектура: controller → service → repository.
DTO для вхідних/вихідних даних, entity не виходить за межі service-шару.
Бізнес-логіка тільки в service, контролери — тонкі.
# Coding conventions
- Named-параметри в конструкторах через Lombok @RequiredArgsConstructor
- Виключення — кастомні unchecked, наслідуються від ApiException
- DTO через record, не class
- Дати — тільки java.time, ніколи java.util.Date
# Directory structure
src/main/java/com/company/booking/
controller/ — REST-контролери, тільки delegation до service
service/ — бізнес-логіка
repository/ — Spring Data JPA
dto/ — record-класи для API
entity/ — JPA entities
config/ — Spring-конфігурація
# Commands
Build: ./gradlew build
Run tests: ./gradlew test
Run integration tests: ./gradlew integrationTest (потребує Docker для Testcontainers)
Local run: ./gradlew bootRun --args='--spring.profiles.active=local'
# Testing
JUnit 5 + Mockito для unit, Testcontainers + PostgreSQL для integration.
Кожен новий service-метод з бізнес-логікою — мінімум один unit-тест.
Не мокати те, що можна протестувати через Testcontainers.
# Security
Ніколи не логувати паролі, токени, персональні дані клієнтів.
Усі ендпоінти під /admin/** — тільки роль ADMIN, перевірка на рівні @PreAuthorize.
# Definition of Done
- Тести пройшли (./gradlew test)
- Немає нових warning від Checkstyle
- DTO задокументовані Javadoc, якщо публічний API
# Agent behaviour
Перед великим рефакторингом — спочатку план, без правок файлів.
Не видаляй існуючі тести без явного дозволу, навіть якщо вони "виглядають зайвими".
# Useful references
Архітектурні рішення: docs/adr/
Опис доменної моделі: docs/domain-model.md
Зверніть увагу: тут немає жодного шматка реального коду, немає копії README, немає changelog. Кожен розділ дає моделі те, чого вона не могла б впевнено вивести сама з коду — саме тому файл і працює.
Приклад поганого CLAUDE.md
# Про проєкт
Це наш чудовий проєкт, який ми почали розробляти в 2023 році.
Спочатку ми використовували Spring Boot 2, потім перейшли на 3.
У лютому 2025 ми переписали модуль оплат (див. PR #482).
У квітні додали Kafka, а в червні прибрали, бо не злетіло.
# Стиль коду
Пишіть чистий, читабельний код. Дотримуйтесь best practices.
Коментарі мають бути змістовними.
# Приклад контролера
```java
@RestController
@RequestMapping("/api/v1/bookings")
public class BookingController {
// ... 150 рядків реалізації контролера ...
}
```
# API документація
GET /api/v1/bookings — повертає список бронювань
Параметри: page, size, sort
Відповідь: { "content": [...], "totalElements": 42, ... }
[... ще 40 ендпоінтів з повним описом полів ...]
# Changelog
- v1.2.0: додано фільтрацію за датою
- v1.1.0: виправлено баг з таймзонами
- v1.0.0: перший реліз
Це майже підручникова колекція антипатернів: історія проєкту замість поточного стану, очевидні поради на кшталт "пишіть чистий код", вставлений код реалізації замість посилання на файл, повна копія API-документації, яка гарантовано розійдеться з реальним кодом за перший же спринт, і changelog, який не впливає на жодне рішення про новий код. Файл такого розміру й змісту буде з'їдати контекст щосесії, даючи моделі мінімум корисного сигналу.
CLAUDE.md для Spring Boot
Для Java/Spring-проєктів я б виділяв окремим блоком стек, специфічний саме для екосистеми:
Maven чи Gradle — і конкретні команди для збірки/тестів вашого варіанту, а не обидва "про всяк випадок".
Spring Boot версія і ключові стартери, які реально використовуються (web, data-jpa, security, actuator).
Spring AI, якщо проєкт з ним працює — окремо варто зазначити, який provider (Ollama, OpenAI, Anthropic) використовується за замовчуванням у dev-профілі.
Docker — команди для локального піднімання інфраструктури (docker-compose up -d), а не просто згадка, що Docker використовується.
PostgreSQL — версія, чи використовуються специфічні для Postgres типи (jsonb, arrays), які можуть не мати прямого аналога в інших СУБД.
Flyway — правило нумерації міграцій, чи можна редагувати вже застосовану міграцію (майже завжди — ні).
Testcontainers — які саме контейнери використовуються для інтеграційних тестів, щоб Claude не пропонував мокати те, що й так тестується через реальну БД.
CLAUDE.md для монорепозиторію
Для монорепо з декількома пакетами в одному репозиторії ("root", "frontend/", "backend/", "shared/") працює саме той механізм вкладених CLAUDE.md, описаний у розділі про технічне завантаження: кореневий файл несе спільне для всього репозиторію (загальні конвенції, команди CI), а кожна піддиректорія — свій CLAUDE.md з тим, що специфічне саме для неї.
Практична порада: не дублюйте в піддиректорії те, що вже є в кореневому файлі, — вкладений CLAUDE.md доповнює кореневий, а не замінює його повністю. І пам'ятайте про правило пріоритету: якщо кореневий файл каже одне, а frontend/CLAUDE.md — інше саме для frontend-коду, для роботи всередині frontend/ виграє більш специфічна інструкція.
CLAUDE.md для мікросервісів
Тут задача принципово інша, ніж у монорепо. У монорепо питання — "де зберігати вкладені файли всередині одного репозиторію". У мікросервісній архітектурі кожен сервіс живе у власному репозиторії з власним CLAUDE.md — і реальне питання не про вкладеність, а про синхронізацію спільних конвенцій між репозиторіями, які фізично не зв'язані одним деревом каталогів.
Два практичних підходи, які я бачив: перший — тримати спільні конвенції (стиль комітів, підхід до логування, спільні security-правила) в окремому внутрішньому репозиторії й підключати через @import у кожному сервісі (пам'ятайте — імпорт розгортається цілком, тож тримайте цей спільний файл компактним). Другий — прийняти, що невелике дублювання кількох ключових рядків у кожному сервісному CLAUDE.md дешевше, ніж інфраструктура для синхронізації, особливо якщо сервісів небагато й вони не змінюються щотижня.
CLAUDE.md vs AGENTS.md
Параметр
CLAUDE.md
AGENTS.md
Хто читає
Лише Claude Code
Codex, Cursor, Copilot, Gemini CLI, Windsurf та інші
Хто керує стандартом
Anthropic
Agentic AI Foundation (Linux Foundation)
Модель пам'яті
Багаторівнева: global / project / nested + rules з path-scoping
Простіша: файл у корені, override за глибиною директорії
Поширення
Специфічно для Claude Code
60 000+ публічних репозиторіїв станом на середину 2026
Ключовий факт, який плутають найчастіше: Claude Code не читає AGENTS.md нативно, а інші інструменти (Cursor, Copilot, Gemini CLI) не читають CLAUDE.md — це підтверджено прямим тестом на живому репозиторії: покласти CLAUDE.md у Cursor-проєкт, і Cursor його просто ігнорує (TECHSY). Якщо ваша команда використовує більше одного AI-інструменту, найпрактичніший підхід — тримати AGENTS.md як базовий крос-інструментальний файл і CLAUDE.md окремо для того, що специфічне саме для Claude Code (вкладена структура, path-scoped rules).
CLAUDE.md vs Cursor Rules
Параметр
CLAUDE.md
Cursor Rules
Формат
Один чи кілька .md файлів
.mdc файли в .cursor/rules/ з YAML frontmatter
Режими активації
Завжди при вході в область дії (global/project/nested)
Чотири режими: Always Apply, Apply Intelligently, Apply to Specific Files, і легасі .cursorrules
Path-scoping
Через окремі .claude/rules/ з paths: frontmatter
Вбудовано в сам формат через поле globs
Пріоритет при конфлікті
За глибиною директорії (специфічніше перебиває загальніше)
Team → Project → User, раніше джерело виграє
Об'єктивно кажучи, система активації правил у Cursor структурованіша "з коробки" — чотири явних режими проти простішої моделі Claude Code. Але глибша ієрархія Claude Code (global/project/nested + rules) дає більше гнучкості для великих монорепо. Якщо ваша команда працює виключно в Cursor, я б не намагався штучно відтворити систему Claude Code — просто використовуйте нативні можливості .mdc-файлів.
CLAUDE.md vs Codex Instructions
Тут варто одразу зняти неточність у самій назві порівняння: у OpenAI Codex немає окремого власного формату "Codex Instructions" — Codex CLI читає той самий відкритий AGENTS.md, який використовують і інші інструменти (The Prompt Shelf). Тобто порівняння "CLAUDE.md vs Codex" на практиці — це той самий кейс, що й "CLAUDE.md vs AGENTS.md" вище, з однією відмінністю: у Codex CLI є зручна діагностична команда --print-instructions, яка показує, який саме злитий AGENTS.md-контент реально завантажився в поточну сесію — корисно, коли підозрюєте, що якийсь файл обрізається чи пропускається.
Практичний висновок: якщо ваша команда використовує і Claude Code, і Codex, готуйтесь підтримувати два файли — CLAUDE.md для одного інструменту, AGENTS.md для іншого — і виносити справді спільне у формат, який можна імпортувати чи копіювати в обидва без розбіжностей.
Типові помилки розробників
Більшість пунктів у цьому розділі — не просто "погана практика", а конкретний ланцюжок причина-наслідок, який я вже спостерігав або на власних проєктах, або в описах спільноти. Розписую кожен так, щоб було видно не тільки "що не так", а що саме це викликає далі.
Файл на 1000 рядків. Класична помилка — намагання описати проєкт вичерпно замість того, щоб дати моделі лише те, чого вона не може вивести сама. Наслідок прямий і я вже пояснював механізм вище: модель надійно тримає в увазі приблизно 150-200 інструкцій одночасно, а системний промпт Claude Code вже займає близько 50 з них. Файл на 1000 рядків — це не "більше контексту про проєкт", це переповнений бюджет уваги, де важливе правило про Definition of Done губиться серед сотні очевидних тверджень, і модель фактично починає ігнорувати частину інструкцій не зі злого умислу, а тому, що фізично не може утримати їх усі з однаковою вагою.
Протирічні інструкції. Особливо часто трапляється між глобальним і проєктним файлом, коли особисті звички суперечать командним конвенціям. Наслідок тут не "модель плутається" абстрактно — оскільки діє правило специфічності (project перебиває global), модель фактично завжди виконає проєктне правило, а ваша особиста звичка з глобального файлу просто мовчки ігноруватиметься щоразу. Якщо ви не знаєте цього правила, виглядатиме так, ніби Claude "забуває" ваші налаштування — а насправді він коректно застосовує пріоритет, просто ви не усвідомлювали, що глобальний рядок ніколи не мав шансу спрацювати в цьому проєкті.
Застарілі команди. Файл, який ніхто не оновлював після переходу з npm на pnpm чи зміни CI-пайплайна. Наслідок конкретний: модель виконає саме ту команду, що написана у файлі, отримає помилку "command not found" чи конфлікт лок-файлів, і витратить крок на самостійне з'ясування, що пішло не так, замість того, щоб одразу запустити правильну команду. Це дрібниця, яка непомітно з'їдає час на кожній сесії, доки хтось не оновить один рядок.
Відсутність архітектури. Модель без опису шарів застосунку схильна створювати нові файли не там, де прийнято в проєкті. Причина проста: без явного правила модель орієнтується на найпростіший робочий шлях для конкретної задачі, а не на архітектурну домовленість команди — технічно код запрацює, навіть якщо бізнес-логіка опиниться прямо в контролері замість service-шару, і ви отримаєте технічно правильний, але архітектурно невірний код, який доведеться переносити на рев'ю.
Змішування документації та інструкцій. Коли CLAUDE.md намагається бути одночасно і README, і API-довідником, і файлом інструкцій — він погано виконує всі три ролі одразу. Причина та сама, що я вже пояснював у розділі "що ніколи не варто писати": документація і довідники змінюються з іншою частотою, ніж інструкції для моделі, і рано чи пізно розходяться з реальністю — тільки тут наслідок ширший, бо файл втрачає фокус одразу для трьох різних аудиторій (нових розробників, тих, хто шукає API, і самої моделі), не задовольняючи жодну з них повністю.
Задокументований баг: user-level rules з paths: frontmatter у ~/.claude/rules/ станом на початок 2026 не завантажуються, навіть якщо файл відповідає патерну — це підтверджений баг (GitHub issue #21858). Практичний наслідок: якщо ви написали особисте path-scoped правило на рівні свого профілю й воно тихо не спрацьовує, це виглядає точнісінько як помилка у вашому glob-патерні — і можна годинами шукати помилку там, де насправді баг у самому інструменті. Робочий обхідний шлях — переносити path-scoped правила на рівень проєкту, а не особистого профілю.
Заголовки з імпортованих файлів не понижуються автоматично. Якщо у головному файлі є \# Code conventions, а імпортований файл починається з власного \# Heading, результат — не підрозділ, а sibling того самого рівня заголовка. Наслідок непомітний, але реальний: структура файлу, яка виглядає логічною у вашому редакторі (імпорт нібито "вкладений" у розділ), насправді розгортається в моделі як два незалежних заголовки одного рівня — це плутає ієрархію важливості інструкцій, коли ви розраховували, що вкладеність сама по собі щось сигналізує моделі. GitHub issue щодо цього закрили як "not planned", тож фікса не варто очікувати — слідкуйте за рівнями заголовків вручну (HackerNoon).
Glob-патерни, що починаються з { або *, треба брати в лапки в YAML-frontmatter — без лапок це не обмеження Claude Code, а стандартна вимога синтаксису YAML, яка регулярно ловить розробників зненацька (Medium, Frontend Master). Наслідок тут найгрубіший з усього списку: це не тиха помилка поведінки, а синтаксична помилка парсингу — весь файл правил може не завантажитись узагалі, і ви втратите не одне правило, а весь набір path-scoped rules з цього файлу, доки не знайдете й не виправите лапки.
FAQ
Чи можна мати кілька CLAUDE.md?
Так, і я б навіть сказав, що для будь-якого проєкту більшого за один сервіс це не опція, а норма. У мене зазвичай в роботі три рівні одночасно: глобальний з особистими налаштуваннями, проєктний під git для всієї команди, і кілька вкладених у піддиректоріях зі специфікою конкретного модуля. Вони не конкурують — кожен рівень доповнює загальніший за правилом специфічності, яке я вже пояснював вище: більш локальна інструкція перебиває загальнішу там, де вони перетинаються.
Де краще зберігати файл?
Тут я дотримуюсь простого поділу за призначенням. Проєктний CLAUDE.md завжди кладу в корінь репозиторію й коммічу в git — інакше вся команда працює з різними інструкціями для однієї й тієї самої моделі, що зводить нанівець сенс файлу. Особистий файл (~/.claude/CLAUDE.md) навпаки — поза репозиторієм, бо це мої особисті звички роботи, які не мають нав'язуватись іншим учасникам команди.
Який оптимальний розмір?
Орієнтир, якого я сам тримаюсь, — до 200 рядків для проєктного файлу і до 30 рядків для особистого глобального. Це не довільна цифра для галочки: я вже пояснював у розділі про найкращі практики, що моделі надійно тримають у фокусі приблизно 150-200 інструкцій одночасно, а системний промпт самого Claude Code вже займає близько 50 із них. Тобто перевищення цієї межі — не естетична проблема, а пряма втрата ефективності: частина ваших інструкцій просто перестає надійно спрацьовувати.
Чи можна використовувати Markdown?
Так, це і є рідний формат файлу, і я б рекомендував не нехтувати структурою — заголовки та списки не просто "красиво виглядають", вони допомагають групувати пов'язані інструкції в логічні блоки, що полегшує читання як мені при рев'ю файлу, так і моделі при обробці контексту.
Чи працює CLAUDE.md у піддиректоріях?
Так, і саме тут я вважаю модель пам'яті Claude Code сильнішою за простіші альтернативи. Вкладений CLAUDE.md підвантажується не одразу при старті сесії, а on-demand — лише коли Claude реально звертається до файлів у відповідній піддиректорії. Для монорепо, з якими я регулярно працюю, це означає, що інструкції, специфічні для frontend-модуля, не займають контекст, коли Claude працює виключно з backend-кодом.
Чи потрібно зберігати його в Git?
Проєктний файл — обов'язково так, я на цьому наполягаю в кожній команді, з якою працюю: якщо CLAUDE.md не в git, кожен розробник накопичує власну, поступово розбіжну версію інструкцій, і ви втрачаєте головну цінність файлу — консистентність. А от особисті override-файли я, навпаки, завжди додаю в .gitignore — вони специфічні для мого робочого середовища, а не для проєкту.
Чим відрізняється від README?
Я формулюю цю різницю через аудиторію, а не формат. README пишеться для людини, яка вперше відкриває репозиторій і нічого не знає про проєкт, — це вітрина. CLAUDE.md пишеться для моделі, яка вже знає загальні патерни розробки й потребує лише того, чим саме ваш проєкт відрізняється від дефолтних припущень. Коли я намагався колись поєднати обидві ролі в одному файлі, страждали обидві аудиторії одразу — я детальніше писав про це в розділі про типові помилки вище.
Чи можна використовувати разом з AGENTS.md?
Так, і в моїй практиці це вже радше правило, ніж виняток — рідко яка команда сьогодні тримається виключно одного AI-інструменту. Claude Code читає лише CLAUDE.md, тоді як Cursor, Copilot чи Gemini CLI переважно орієнтуються на AGENTS.md. Якщо ваша команда змішана, я б одразу закладав підтримку обох файлів, а не намагався змусити один інструмент читати формат іншого — це просто не спрацює.
Чи справді @import зменшує контекст?
Ні, і це саме та помилкова інтуїція, яку я сам мав до того, як розібрався в механізмі детальніше. Імпорти завантажуються цілком одразу при старті сесії — розбиття файлу на кілька імпортованих частин полегшує вам підтримку коду, але не зменшує обсяг, який реально йде в модель. Якщо мета саме економія контексту, а не зручність редагування, працюють лише path-scoped rules у .claude/rules/, які я детально розібрав у розділі про технічне завантаження файлу вище.
Що відбувається з CLAUDE.md після /compact?
Кореневий файл переінжектиться заново з диска — це я перевіряв особисто, і поведінка стабільна. А от вкладені CLAUDE.md і rules після компакції автоматично не повертаються: вони підвантажуються знову лише тоді, коли Claude наступного разу звертається до відповідної піддиректорії чи файлу. Якщо ви розраховуєте, що вкладена інструкція "запам'яталась" на всю сесію після компакції, це небезпечне припущення — краще вважати, що вона довантажується лише за потреби.
Яка мінімальна версія Claude Code потрібна для /doctor-трімінгу?
v2.1.206 або новіша. Раджу перевірити вашу поточну версію перед тим, як покладатись на цю команду в описі найкращих практик вище, — на старіших версіях команда просто відсутня, і ви отримаєте помилку замість підказки щодо урізання файлу.
Висновки
Якщо винести з цієї статті одну думку, я б обрав таку: CLAUDE.md — це не документація і не конфіг, а текст, який щоразу конкурує за обмежену увагу моделі з усім іншим, що завантажено в контекст. Кожен зайвий рядок — це не безкоштовна страховка "про всяк випадок", а реальна ціна, яку модель платить щосесії.
Моя практична порада, з якою я підходжу до кожного нового CLAUDE.md: не намагайтесь написати ідеальний файл одразу. Почніть з базового мінімуму — стек, команди, ключові конвенції — і додавайте по одному рядку щоразу, коли Claude робить помилку, якої одне чітке правило могло б запобігти. І перш ніж додати новий рядок, застосуйте той самий тест, що лежить в основі /doctor: чи можна вивести це з коду? Якщо так — не пишіть, модель і сама розбереться.
