CLAUDE.md Best Practices: як правильно налаштувати Claude

Коротко:

• CLAUDE.md — markdown-файл, який Claude Code автоматично завантажує на старті кожної сесії. Він не виконується як конфіг, а вставляється в контекст як текст — тому це порада моделі, а не жорстке правило.
• Головна технічна помилка: розбивати файл на @imports заради економії контексту. Імпорти завантажуються цілком одразу. Реально економлять контекст лише path-scoped rules у .claude/rules/.
• Орієнтир розміру — до 200 рядків для project CLAUDE.md. Це не жорсткий ліміт: важливіша щільність корисних інструкцій, ніж кількість рядків.
• З версії 2.1.277 Claude Code читає й AGENTS.md, але за замовчуванням лише тоді, коли в проєкті немає CLAUDE.md. Cursor має власну систему .cursor/rules/.
• Коли CLAUDE.md стає замало — rules, skills, hooks і permissions: що куди класти.
• У статті — робочий приклад для Spring Boot, типові помилки і простий спосіб перевірити, чи файл узагалі впливає на результат.

Зміст

• Що таке CLAUDE.md і навіщо він потрібен
• Як Claude використовує CLAUDE.md
• Як Claude Code технічно завантажує CLAUDE.md: imports vs rules vs compaction
• Що обов'язково має бути в CLAUDE.md
• Що ніколи не варто писати в CLAUDE.md
• Оптимальна структура CLAUDE.md
• Найкращі практики написання CLAUDE.md
• CLAUDE.md vs rules vs skills vs hooks: що куди класти
• Приклад хорошого CLAUDE.md
• Приклад поганого CLAUDE.md
• CLAUDE.md для Spring Boot
• CLAUDE.md для монорепозиторію
• CLAUDE.md для мікросервісів
• CLAUDE.md vs AGENTS.md
• CLAUDE.md vs Cursor Rules
• CLAUDE.md vs Codex Instructions
• Типові помилки розробників
• FAQ
• Висновки

Що таке CLAUDE.md і навіщо він потрібен

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, OpenCode та інші. Claude Code з версії 2.1.277 теж його читає, але за замовчуванням лише як запасний варіант — коли в проєкті немає CLAUDE.md. Деталі й режими — у розділі порівняння.

Відмінність від 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 або ./.claude/CLAUDE.md) — головний файл, комітиться в git і працює для всієї команди.
• Локальний (./CLAUDE.local.md) — ваші особисті нотатки до цього проєкту (локальна URL, тестові акаунти). Додайте його в .gitignore.
• Вкладені CLAUDE.md у піддиректоріях — підвантажуються лише тоді, коли Claude читає файли з цієї піддиректорії. Монорепо з 50 модулями не роздуває контекст тим, що зараз не потрібно.
• Managed policy — файл, який адміністратор розкатує на всі машини організації. Для соло-розробника неактуально, але в компаніях важливо знати, що такий рівень існує.

Окремо від цих файлів працює auto memory — нотатки, які Claude веде сам у ~/.claude/projects/<проєкт>/memory/MEMORY.md. На старті завантажуються перші 200 рядків або 25 KB. Переглянути й відредагувати їх можна через /memory. CLAUDE.md пишете ви, MEMORY.md — Claude.

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

Як Claude Code технічно завантажує CLAUDE.md: imports vs rules vs compaction

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

@imports завантажуються одразу й цілком. Розбийте 500-рядковий CLAUDE.md на п'ять імпортів по 100 рядків — і отримаєте зручніші файли, але той самий обсяг контексту. Імпорт розгортається на старті сесії, ніби вміст вставили напряму. Вкладеність — до 5 рівнів. Усередині `код` і code-блоків @шлях не обробляється, тож шлях можна згадати, не імпортуючи файл.

Rules у .claude/rules/*.md поводяться по-різному:

⚠️ Особисті rules у ~/.claude/rules/ з paths: довго не працювали (issue #21858, закрите в березні 2026), і пізніші звіти показують, що проблема повертається. Path-scoped rules надійно працюють на рівні проєкту. Після змін перевіряйте через /memory, що файл справді підвантажився.

Що переживає /compact:

Практичний висновок: інструкція, дана лише в чаті, після компакції може зникнути. Якщо правило важливе — йому місце у файлі.

HTML-коментарі не коштують контексту. Блочні коментарі <!-- ... --> вирізаються перед завантаженням. Зручно для нотаток колегам: «чому тут це правило».

Вбудований трімінг. З v2.1.206 команда /doctor (аліас /checkup) аналізує закомічений CLAUDE.md і пропонує прибрати те, що модель може вивести з коду: структуру папок, список залежностей, загальний огляд. Залишає граблі, обґрунтування рішень і нестандартні конвенції. Також знаходить дублі між CLAUDE.md і CLAUDE.local.md і пропонує винести частину інструкцій у skills або вкладені CLAUDE.md. Критерій «чи можна це вивести з коду» — найкращий тест для будь-якого рядка.

Що обов'язково має бути в CLAUDE.md

Критерій той самий: лише те, чого модель не виведе з коду впевнено. Ось категорії, де без явної інструкції вона найчастіше вгадує неправильно:

• Стек і версії — особливо в перехідний період (частина модулів на Java 17, частина на 21). Інакше модель застосує API новішої версії, і збірка впаде.
• Архітектура — куди йде новий код. Без цього бізнес-логіка регулярно опиняється в контролері: працює, але ламає шари.
• Нестандартні правила іменування — наприклад, суфікс Dto замість Request/Response. Дефолти Java модель знає, ваші домовленості — ні.
• Команди збірки — буквально ./gradlew build, а не «зберіть проєкт». Інакше отримаєте mvn install у Gradle-проєкті.
• Тестування — фреймворк, команда запуску, коли писати тести. Від цього залежить, чи модель перевіряє свою роботу, перш ніж сказати «готово».
• Обмеження — що не чіпати без дозволу (наприклад, уже застосовані міграції). Важливо: текстова заборона — це прохання, а не замок. Для критичного використовуйте permissions і hooks (див. нижче).
• Definition of Done — тести пройшли, лінтер чистий, документація оновлена. Без цього «код написано» і «задачу виконано» — різні речі.

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

За кожним пунктом — конкретний механізм шкоди, а не «на смак»:

• Секрети, ключі, паролі. CLAUDE.md комітиться в git і потрапляє в контекст кожної сесії. Ключі — у змінних оточення або secret manager, а доступ до .env краще заборонити через permissions.
• Великі шматки коду. Вставлений приклад застаріває швидше за опис. Після рефакторингу модель орієнтуватиметься на старий приклад, а не на реальний код. Посилайтесь на файл.
• Документацію API. Застаріла копія гірша за відсутню: модель упевнено запропонує ендпоінт, якого вже немає. Вийде не помилка компіляції, а тиха логічна помилка.
• Копію README. README оновлюють при релізах, бо на нього дивляться люди. Копію в CLAUDE.md забувають, і файли розходяться.
• Changelog та історію рішень. «Раніше був Redux, тепер Zustand» — модель не відрізняє історію від актуального правила, читає все як рівнозначне.
• Інструкції на один раз. «Онови залежність X» — задача для чату. Забута в файлі, вона змусить модель повторювати або перевіряти вже виконане.
• Очевидні речі. «Пиши чистий код», «додавай коментарі» — модель і так це робить. Такі рядки лише розмивають ті, що реально впливають на результат.

Оптимальна структура CLAUDE.md

За результатами того, що я бачив у робочих production-файлах і в рекомендаціях спільноти, оптимальна структура виглядає так:

1. Project overview
2. Architecture
3. Coding conventions
4. Directory structure
5. Commands
6. Testing
7. Security
8. Definition of Done
9. Agent behaviour
10. Useful references

Порядок тут не випадковий: спочатку — контекст, у якому модель має розуміти, що взагалі за проєкт (overview, architecture), потім — правила, за якими писати код (conventions, structure), потім — як перевіряти власну роботу (commands, testing, security, DoD), і насамкінець — поведінкові інструкції та посилання на додаткові матеріали.

Найкращі практики написання CLAUDE.md

Тримайте файл коротким. Практичний орієнтир від Anthropic — до 200 рядків на один CLAUDE.md, для особистого ~/.claude/CLAUDE.md — кілька десятків. Це не жорсткий ліміт: кожен рядок займає контекст у кожній сесії, і що довший файл, то менш послідовно Claude його виконує. Важливіша щільність, ніж довжина.

Пишіть однозначно. «Використовуй named exports, не default» краще за «намагайся використовувати named exports».

Не залишайте протиріч. Виняток для модуля — у його вкладений CLAUDE.md або rule з paths:, а не друге правило поруч із першим.

Розділяйте рівні. Особисті вподобання — у ~/.claude/CLAUDE.md, особисте по проєкту — у CLAUDE.local.md, командні конвенції — у проєктний CLAUDE.md під git.

Тримайте лише поточний стан. Без історії, без застарілих команд. Файл, який не редагувався три місяці на живому проєкті, майже напевно бреше.

Посилайтесь, а не копіюйте. Один рядок з посиланням живе довше за скопійований параграф.

Додавайте правило після повторної помилки. Не намагайтесь передбачити все наперед. Модель двічі поклала логіку в контролер — це кандидат у CLAUDE.md. Гіпотетична проблема — ні.

Головний тест: чи можна це вивести з коду? Якщо так — видаляйте. Цю ж логіку використовує /doctor; застосовуйте її до того, як файл виросте до 300 рядків.

Як перевірити, що CLAUDE.md справді працює

1. Візьміть 3–5 типових задач проєкту (новий ендпоінт, фікс бага, тест).
2. Виконайте їх з CLAUDE.md і без нього (тимчасово перейменуйте файл).
3. Порівняйте, скільки правок довелося робити руками і чи дотримані архітектура та конвенції.
4. Правила, які не змінили результату, — на видалення.
5. Час від часу запускайте /doctor prompt-audit — він знаходить протиріччя між файлами інструкцій.

💡 Це не перестраховка. Дослідження ETH Zurich (138 репозиторіїв, 5 694 PR) показало, що файли інструкцій, написані як README, трохи погіршують результат агента і збільшують витрату токенів. Довгий файл ≠ корисний файл.

CLAUDE.md vs rules vs skills vs hooks: що куди класти

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

Ключова різниця: CLAUDE.md, rules і skills — це текст, який модель може порушити. Hooks і permissions — детерміновані: спрацьовують незалежно від того, що «вирішила» модель. Тому правило «ніколи не пушити в main» у CLAUDE.md — побажання, а deny у permissions — гарантія:

// .claude/settings.json
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(git push:*)"
    ]
  }
}

Просте правило вибору: якщо порушення інструкції — це незручність, пишіть у CLAUDE.md. Якщо порушення — це інцидент, використовуйте permissions або hook.

Приклад хорошого CLAUDE.md

# Project overview
Backend API для системи бронювання приміщень. Spring Boot 4, Java 21, PostgreSQL 17.

# Architecture
Шарова архітектура: controller → service → repository.
Entity не виходить за межі service-шару, назовні — тільки DTO.
Бізнес-логіка тільки в service, контролери — тонкі.

# Coding conventions
- Ін'єкція через конструктор (@RequiredArgsConstructor), без @Autowired на полях
- Винятки — кастомні unchecked, наслідуються від ApiException
- DTO — тільки record
- Дати — тільки java.time, ніколи java.util.Date
- JSON — Jackson 3 (пакет tools.jackson), не com.fasterxml.jackson

# Commands
Build: ./gradlew build
Unit tests: ./gradlew test
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 build проходить без нових warning від Checkstyle
- Публічні DTO мають Javadoc

# Agent behaviour
Перед великим рефакторингом — спочатку план, без правок файлів.
Не видаляй існуючі тести без явного дозволу.

# References
Архітектурні рішення: docs/adr/
Доменна модель: docs/domain-model.md

<!-- Правила для міграцій винесені в .claude/rules/migrations.md -->

Тут немає коду, копії README чи changelog — лише те, чого модель не виведе сама. Зверніть увагу на дві речі. Розділу Directory structure немає: стандартну структуру Spring-проєкту Claude бачить з коду, і саме такі блоки /doctor пропонує видаляти першими. А рядок про Jackson 3 — приклад ідеальної інструкції: у Spring Boot 4 змінився пакет, і без підказки модель за звичкою імпортуватиме старий com.fasterxml.

Приклад поганого 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, що не впливає на жодне рішення. Такий файл їсть контекст щосесії і майже нічого не дає. Порівняйте: «пишіть чистий код» → нуль ефекту; «entity не виходить за межі service-шару» → конкретна поведінка, яку легко перевірити.

CLAUDE.md для Spring Boot

Для Java/Spring-проєктів окремо варто зафіксувати те, що специфічне для екосистеми:

• Maven чи Gradle — і точні команди саме вашого варіанту, а не обидва «про всяк випадок».
• Версія Spring Boot і ключові стартери. Особливо важливо зараз: безкоштовна підтримка Boot 3.5 закінчилась у червні 2026, і багато проєктів у процесі переходу на Boot 4 (Jackson 3, Spring Framework 7). Модель має знати, на якій версії ви зараз.
• Spring AI — версія (1.x і 2.x суттєво відрізняються, 2.0 потребує Boot 4) і provider за замовчуванням у dev-профілі (Ollama, OpenAI, Anthropic).
• Docker — команда підняття інфраструктури (docker compose up -d), а не просто «використовуємо Docker».
• PostgreSQL — версія і специфічні типи (jsonb, arrays, pgvector), які не мають прямого аналога в інших СУБД.
• Flyway — нумерація міграцій і заборона редагувати застосовані.
• Testcontainers — які контейнери використовуються, щоб Claude не пропонував мокати те, що тестується на реальній БД.

Правила для міграцій — ідеальний кандидат на path-scoped rule: вони потрібні лише тоді, коли Claude торкається папки з міграціями.

# .claude/rules/migrations.md
---
paths:
  - "src/main/resources/db/migration/**"
---
- Нова міграція — новий файл V{N}__короткий_опис.sql, N = останній номер + 1
- Ніколи не редагуй уже існуючі міграції — вони застосовані на production
- Для зміни схеми — нова міграція з ALTER, не правка старої

А якщо помилка тут коштує інциденту — додайте ще й заборону на редагування через permissions (див. що куди класти).

CLAUDE.md для монорепозиторію

Для монорепо (frontend/, backend/, shared/) працює механізм вкладених CLAUDE.md: кореневий файл містить спільне (конвенції, команди CI), а кожна піддиректорія — лише своє. Вкладений файл доповнює кореневий, а не замінює, тому не дублюйте в ньому те, що вже є вище.

Дві практичні поради:

• Правила, прив'язані до типу файлів, а не до папки (наприклад, усі *.test.ts у будь-якому пакеті), зручніше тримати як rules з paths:, ніж розкидати по вкладених CLAUDE.md.
• У великих монорепо підтягуються CLAUDE.md інших команд, які вам не потрібні. Їх можна виключити налаштуванням claudeMdExcludes у .claude/settings.local.json.

CLAUDE.md для мікросервісів

Тут задача інша: кожен сервіс живе у власному репозиторії, і питання не у вкладеності, а в тому, як синхронізувати спільні конвенції між репозиторіями.

Для 3–5 сервісів я б обрав дублювання: кілька рядків дешевші за інфраструктуру. Коли сервісів більше десятка або конвенції часто змінюються — plugin. Імпорт із домашньої папки — проміжний варіант для особистих правил, але не для командних.

CLAUDE.md vs AGENTS.md

Довго Claude Code був винятком і читав лише CLAUDE.md. З версії 2.1.277 (18 вересня 2026) він читає й AGENTS.md, але за замовчуванням лише як запасний варіант.

⚠️ Важливо: якщо в робочій директорії або будь-якій директорії вище є CLAUDE.md, .claude/CLAUDE.md чи CLAUDE.local.md, Claude Code за замовчуванням ігнорує AGENTS.md. Помилки не буде — файл просто не потрапить у контекст.

Чотири режими «Project instructions»

Режим перемикається командою /config → Project instructions:

💡 Цей параметр персональний: у проєктних settings Claude Code його ігнорує, тому закомітити його не вийде. Щоб уся команда отримувала однакові інструкції, використовуйте імпорт.

Рекомендований підхід для команди

Спільні правила — в AGENTS.md. У CLAUDE.md першим рядком імпорт і лише специфіка Claude:

# CLAUDE.md
@AGENTS.md

## Тільки для Claude Code
- Для змін у src/billing/ використовуй plan mode
- Перед комітом запускай ./gradlew build

Рядок @AGENTS.md комітиться разом із репозиторієм і працює для всіх, незалежно від персонального режиму. Якщо хтось увімкне claude-md-and-agents-md, AGENTS.md не задублюється.

Як перевірити, що завантажилось

• /memory — показує завантажені файли (AGENTS.md там видно з версії 2.1.280).
• /doctor prompt-audit — знаходить суперечності між CLAUDE.md і AGENTS.md.
• Якщо пункту Project instructions немає в /config, підтримка AGENTS.md у цій сесії недоступна (стара версія, перша сесія після оновлення або вимкнений вбудований плагін agents-md). Тоді лишається імпорт @AGENTS.md.

CLAUDE.md vs Cursor Rules

Система активації в Cursor гнучкіша з коробки: режим «Apply Intelligently», де агент сам вирішує за описом, чи потрібне правило, у Claude Code найближче за суттю до skills, а не до rules. Старий файл .cursorrules застарів — у нових проєктах використовуйте лише .cursor/rules/.

⚠️ Якщо в Cursor-проєкті лежить великий CLAUDE.md, Cursor вантажить його в кожен чат цілком. Для змішаних команд це ще один аргумент тримати CLAUDE.md коротким, а спільне — в AGENTS.md.

CLAUDE.md vs Codex Instructions

Окремого формату «Codex Instructions» не існує: Codex CLI читає той самий AGENTS.md. Відмінності — у механіці:

• Глобальні інструкції — у ~/.codex/AGENTS.md (аналог ~/.claude/CLAUDE.md).
• AGENTS.override.md — якщо лежить поруч з AGENTS.md, Codex читає лише його. Зручно для тимчасових локальних змін, але це й часта причина, чому правки в AGENTS.md «не працюють».
• Порядок — Codex склеює файли від кореня до поточної директорії, ближчі до роботи йдуть останніми.

Практичний висновок змінився: раніше для Claude Code і Codex доводилося підтримувати два окремі файли. Тепер достатньо AGENTS.md як єдиного джерела правди і короткого CLAUDE.md з @AGENTS.md плюс специфікою Claude (див. вище). Для перевірки в Codex найпростіше додати в AGENTS.md унікальний маркер і попросити агента його повторити.

Типові помилки розробників

За кожним пунктом — конкретний ланцюжок «причина → наслідок», а не абстрактна «погана практика».

• Файл на 1000 рядків. Спроба описати проєкт вичерпно замість того, щоб дати лише те, чого модель не виведе сама. Кожен рядок займає контекст у кожній сесії, і важливе правило про Definition of Done губиться серед сотні очевидних тверджень. Модель не ігнорує його навмисно — просто чим довший файл, тим менш послідовно вона його виконує.
• Протирічні інструкції. Найчастіше — між глобальним і проєктним файлом. Модель бачить обидві версії одночасно і зазвичай обирає специфічнішу, але це не гарантовано: поведінка може «плавати» від сесії до сесії. Здається, що Claude «забуває» налаштування, хоча насправді йому дали дві взаємовиключні вказівки. Лікується /doctor prompt-audit і явним винятком на нижчому рівні.
• Застарілі команди. Перейшли з npm на pnpm чи змінили CI, а файл не оновили. Модель виконає написане, отримає «command not found» і витратить крок на з'ясування — на кожній сесії, доки хтось не виправить один рядок.
• Відсутність архітектури. Без опису шарів модель іде найпростішим робочим шляхом: код запрацює, але бізнес-логіка опиниться в контролері, і переносити її доведеться на рев'ю.
• Змішування документації та інструкцій. CLAUDE.md, який намагається бути одночасно README, API-довідником та інструкцією, погано виконує всі три ролі: документація змінюється з іншою частотою і розходиться з реальністю.
• І CLAUDE.md, і AGENTS.md — і очікування, що працюють обидва. За замовчуванням Claude Code читає лише CLAUDE.md, а AGENTS.md мовчки пропускає. Половина правил команди просто не доходить до моделі. Рішення — @AGENTS.md першим рядком CLAUDE.md (див. розділ порівняння).
• Заборони лише текстом. «Ніколи не пуш у main» у CLAUDE.md — побажання, яке модель може порушити. Для критичного — permissions.deny або hook (див. що куди класти).
• Важливі правила лише в чаті. Після /compact історія стискається, і сказане в розмові може зникнути. Якщо ви повторюєте одне й те саме вдруге — це рядок для файлу.
• Особисті path-scoped rules у ~/.claude/rules/. Правила з paths: на рівні профілю довго не завантажувались (GitHub issue #21858, закрите в березні 2026), і пізніші звіти показують, що проблема повертається. Це виглядає точно як помилка у вашому glob-патерні — можна годинами шукати не там. Тримайте path-scoped правила на рівні проєкту і перевіряйте через /memory.
• Заголовки з імпортованих файлів не понижуються. Якщо в головному файлі є # Code conventions, а імпортований починається з власного # Heading, у моделі вийде не підрозділ, а сусідній заголовок того самого рівня. Вкладеність, яку ви бачите в редакторі, моделі не передається — стежте за рівнями вручну (HackerNoon).
• Glob без лапок у YAML-frontmatter. Патерни, що починаються з * або {, треба брати в лапки — це вимога синтаксису YAML, а не Claude Code. Без лапок frontmatter не парситься, і може не завантажитись увесь файл правил, а не одне правило.

FAQ

Чи можна мати кілька CLAUDE.md?

Так, і для будь-якого проєкту більшого за один сервіс це норма. У мене зазвичай працюють три рівні: глобальний з особистими налаштуваннями, проєктний під git для команди і кілька вкладених у модулях. Вони доповнюють один одного; головне — не залишати між ними протиріч.

Де краще зберігати файл?

Проєктний CLAUDE.md — у корені репозиторію (або .claude/CLAUDE.md) під git. Особисті налаштування для всіх проєктів — у ~/.claude/CLAUDE.md. Особисте для конкретного проєкту (локальні URL, тестові акаунти) — у CLAUDE.local.md, доданому в .gitignore.

Який оптимальний розмір?

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

Чи можна використовувати Markdown?

Так, це рідний формат. Заголовки й списки групують пов'язані інструкції і полегшують рев'ю файлу. Блочні HTML-коментарі <!-- --> вирізаються перед завантаженням — ними зручно пояснювати колегам, навіщо потрібне правило, не витрачаючи контекст.

Чи працює CLAUDE.md у піддиректоріях?

Так. Вкладений CLAUDE.md підвантажується не на старті, а лише коли Claude читає файли з цієї піддиректорії. У монорепо інструкції для frontend не займають контекст, поки Claude працює з backend.

Чи потрібно зберігати його в Git?

Проєктний — обов'язково: інакше кожен розробник накопичує свою версію інструкцій, і зникає головна цінність файлу — консистентність. CLAUDE.local.md і особисті налаштування — навпаки, в .gitignore.

Чим відрізняється від README?

Аудиторією. README — для людини, яка вперше відкрила репозиторій. CLAUDE.md — для моделі, яка вже знає загальні патерни і потребує лише того, чим ваш проєкт відрізняється від дефолтних припущень. Поєднання обох ролей в одному файлі шкодить обом.

Чи читає Claude Code файл AGENTS.md?

Так, починаючи з версії 2.1.277 (вересень 2026). За замовчуванням — лише тоді, коли в проєкті немає CLAUDE.md, .claude/CLAUDE.md чи CLAUDE.local.md. Щоб завантажувались обидва, додайте @AGENTS.md першим рядком CLAUDE.md (працює для всієї команди) або оберіть режим claude-md-and-agents-md у /config → Project instructions (працює лише для вас).

Чи справді @import зменшує контекст?

Ні. Імпорти розгортаються цілком на старті сесії — розбиття на файли полегшує підтримку, але не зменшує обсяг контексту. Економлять лише rules у .claude/rules/ з paths:.

Що відбувається з CLAUDE.md після /compact?

Кореневий CLAUDE.md, rules без paths: і auto memory підвантажуються заново. Вкладені CLAUDE.md і rules з paths: повертаються лише тоді, коли Claude знову читає відповідні файли. Інструкції, дані тільки в чаті, після компакції можуть зникнути.

Чим CLAUDE.md відрізняється від MEMORY.md?

CLAUDE.md пишете ви — це інструкції. MEMORY.md (auto memory) веде сам Claude — це його нотатки з попередніх сесій; на старті завантажуються перші 200 рядків або 25 KB. Переглянути й виправити обидва можна через /memory.

Яка мінімальна версія Claude Code потрібна для /doctor-трімінгу?

v2.1.206 або новіша. На старіших версіях команда не пропонує урізання CLAUDE.md. Аліас — /checkup.

Висновки

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

Ось що я рекомендую, виходячи з власної роботи з Claude Code:

• Починайте з мінімуму. Стек, команди, архітектура, кілька нестандартних конвенцій — 30–50 рядків. Не намагайтесь написати ідеальний файл одразу.
• Додавайте рядок лише після повторної помилки. Claude двічі зробив те саме не так — це правило для файлу. Гіпотетична проблема — ні.
• Перед кожним новим рядком питайте: чи можна це вивести з коду? Якщо так — не пишіть. Раз на місяць проганяйте /doctor.
• Виносьте вузьке у rules з paths:, процедури — у skills. CLAUDE.md має містити тільки те, що потрібно в кожній сесії.
• Критичне закривайте permissions і hooks, а не текстом. Доступ до .env, push у main, production — це не те, що варто довіряти побажанню в markdown.
• Якщо в команді кілька AI-інструментів — одне джерело правди. Спільне в AGENTS.md, у CLAUDE.md — @AGENTS.md і специфіка Claude.
• Перевіряйте, а не вірте. Прогоніть 3–5 типових задач з файлом і без нього. Правила, які нічого не змінили, — видаляйте.