
Найкращі практики CLAUDE.md: 9 правил, які не дадуть Claude ігнорувати вас (2026)
Більшість публікацій про найкращі практики CLAUDE.md просто надають шаблон і вважають справу зробленою, але файл, який ви написали минулого тижня, ймовірно, вже ігнорується, і ви не знаєте чому. Рішення рідко полягає в тому, щоб «додати більше правил». Зазвичай все навпаки. Ми впровадили Claude Code у кожному недавньому клієнтському проекті, і саме ці 9 правил дійсно мають значення: ієрархія, що відповідає способу завантаження файлів Claude, незламний бюджет інструкцій, рішення щодо AGENTS.md та шість причин, чому Claude мовчки відкидає ваш файл посеред сесії.
Ключові висновки
- CLAUDE.md — це пам'ять проекту, яка завантажується в контекст Claude Code; тримайте її менше ніж 200 рядків, інакше правила почнуть відкидатися.
- Файли завантажуються зверху вниз: глобальні, корінь проекту, підкаталог (ліниве завантаження) та CLAUDE.local.md (особисті, ігноровані git).
- Використовуйте AGENTS.md, якщо ви також працюєте з Cursor або Copilot; створіть символічне посилання з CLAUDE.md на AGENTS.md для одночасного охоплення обох систем.
- Якщо Claude ігнорує ваш файл, у 90% випадків причина — довжина, невизначеність або відсутність пояснення «чому».
Що насправді робить CLAUDE.md (і чому це важливо)
Коротко: CLAUDE.md — це markdown-файл, який Claude Code читає як пам'ять проекту на початку кожної сесії. Це не системний промпт, не хук і не навичка, а рекомендаційний контекст, який спрямовує Claude до конвенцій вашої команди. Уявляйте його менше як документацію, а більше як конфігураційний файл, який ваш AI-парний програміст дійсно читає.
Багато команд пишуть CLAUDE.md так само, як README. Це перша помилка. README пояснює проект людям, які можуть пробігти очима й пропустити деталі. CLAUDE.md споживається Claude Code повністю на початку сесії, кожен рядок коштує токенів і впливає на дотримання інструкцій. Він набагато ближчий до конфігураційного файлу або набору тестових фіксатур, ніж до документації.
Це також не єдиний спосіб керувати Claude. Хуки виконують детерміновані дії (форматування, блокування комітів). Навички (Skills) об’єднують багаторазові робочі процеси. CLAUDE.md займає проміжне положення як рекомендаційний контекст: Claude оцінює його, іноді перевизначає й однозначно забуває частини, якщо ви напишете занадто багато. Це розрізнення є фундаментом для всього нижчезазначеного, і саме тому CLAUDE.md є одним із інструментів у більш широкій практиці інжинірингу контексту, а не срібною кулею.
Правило №1: Ставтеся до нього як до коду, а не як до документації. Версіонуйте його. Рецензуйте його в PR. Скорочуйте його так, ніби ви рефакторите роздутий модуль. Згідно з посібником Anthropic щодо CLAUDE.md, файл завантажується з тим самим пріоритетом, що й будь-яка системна інструкція, а це означає, що застаріле правило шестимісячної давнини все ще активно формує кожну відповідь сьогодні.
Як завантажується CLAUDE.md: 4-рівнева ієрархія
Коротко: Claude Code завантажує CLAUDE.md з чотирьох рівнів: глобальний (
~/.claude/CLAUDE.md), корінь проекту,CLAUDE.local.mdдля особистих перевизначень та файли в підкаталогах, які завантажуються ліниво лише тоді, коли Claude читає файли всередині цього каталогу. Сусідні підкаталоги ніколи не бачать CLAUDE.md один одного, що дозволяє тримати пам'ять claude code чітко обмеженою.

Ієрархія — це найбільш неправильно зрозуміла частина CLAUDE.md, і саме тут жоден із топ-5 результатів пошуку не заглиблюється достатньо. Ось що насправді відбувається під капотом:
| Рівень | Розташування | Завантажується коли | Область дії | Git |
|---|---|---|---|---|
| Глобальний | ~/.claude/CLAUDE.md | Початок сесії | Усі проекти на вашому комп'ютері | Особистий |
| Корінь проекту | ./CLAUDE.md | Початок сесії | Весь репозиторій | Закомічено |
| Локальний | ./CLAUDE.local.md | Початок сесії | Цей checkout, ваш комп'ютер | Ігнорується вручну |
| Підкаталог | ./frontend/CLAUDE.md тощо. | Ліниво, коли Claude читає файли в цьому каталозі | Це піддерево | Закомічено |
Два терміни, які варто зафіксувати: ліниве завантаження та ізоляція сусідів.
Ліниве завантаження означає, що CLAUDE.md підкаталогу не потрапляє в контекст Claude, доки Claude фактично не відкриє файл у цьому каталозі. Якщо ви запитаєте «виправ баг логіну», а Claude торкається лише backend/, ваш frontend/CLAUDE.md ніколи не завантажиться. Це добре, бо зберігає вікно контексту чистим, але це стає проблемою для команд, які розміщують критичні правила в підкаталогах, очікуючи, що вони завжди застосовуватимуться.
Ізоляція сусідів є наслідком цього: frontend/CLAUDE.md і backend/CLAUDE.md ніколи не завантажують один одного. Вони поділяють лише те, що є в корені проекту. Тож якщо ваші правила для фронтенду суперечать правилам для бекенду, це нормально. Якщо їм потрібно поділити конвенцію, винесіть її у кореневий файл.
CLAUDE.local.md — це аварійний люк. Він завантажується, але не комітиться, ідеально підходячи для перевизначень типу «я віддаю перевагу pnpm, але команда стандартизувала npm». Але є нюанс: він не ігнорується git автоматично. Ви повинні додати його самостійно. Забудьте про це, і ви закомітите свої особисті правила в репозиторій команди.
Правило №4: Узгоджуйте інструкції з тим, де Claude їх фактично читає. Правила стилю для компонентів React належать до frontend/CLAUDE.md, а не до кореня. Правила міграції бази даних належать до backend/. Документація Anthropic Memory (оновлена в листопаді 2025 року) підтверджує це: поведінка лінивого завантаження є навмисною та фундаментальною.
Що включати в CLAUDE.md (а що залишити поза ним)
Коротко: У CLAUDE.md включайте все, що Claude не може вивести з вашого коду: команди збірки, конвенції найменування, антипатерни, на яких ваша команда обпеклася, та причину кожного правила. Виключайте все, що є в README, у
package.json, і будь-яке правило, яке змінюється щотижня. Інструкції claude code мають бути перевірними та конкретними.
Ось мінімальний CLAUDE.md, який дійсно має вагу:
# Project: techsy-app
## Commands
- Build: `pnpm build` (Turbopack — Webpack flags don't apply)
- Test: `pnpm test --run` (we use Vitest, not Jest)
- Lint: `pnpm lint` (will fail CI on warnings, not just errors)
## Conventions
- Server components by default. Add `'use client'` only when truly needed.
Why: we hit 8s LCP last quarter from over-clienting.
- Database access only via `lib/db/` helpers — never raw SQL in routes.
Why: row-level security policies live in those helpers.
- Tests colocate as `*.test.ts` next to the file under test.
## Don'ts
- Don't add a new dependency without opening a PR comment first.
- Don't use `any` — use `unknown` and narrow.
## Where to look
- Schema: `db/schema.ts`
- Auth flow: `lib/auth/README.md`Тепер порівняйте це з версією-антипатерном, яку використовує більшість команд:
# Project Rules
- Write clean, maintainable code.
- Follow best practices.
- Use TypeScript properly.
- Make sure tests pass.
- Be consistent with existing patterns.
- Document complex logic.Другий файл не є неправильним. Він просто марний. Claude вже хоче писати чистий код. «Будьте послідовними» не каже Claude, який саме патерн має бути послідовним. Публічні приклади інженера Anthropic Бориса Черні сильно схиляються до першого стилю: конкретні команди, названі інструменти та причина рішень, які не очевидні лише з кодової бази.
Правило №2: Будьте конкретними, а не амбітними. «Пишіть чистий код» — це амбітно. «Серверні компоненти за замовчуванням; додавайте 'use client' лише коли це дійсно потрібно» — це можна перевірити. Та сама дисципліна лежить в основі хорошого інжинірингу промптів: конкретні, перевірені інструкції перемагають розмиті прагнення, чи то в промпті, чи в CLAUDE.md.
Правило №3: Пояснюйте, чому кожне правило важливе. «Чому» — це не вода, це те, як Claude приймає рішення в крайніх випадках. Правило з причиною («ми отримали 8 с LCP через надмірне використання клієнтських компонентів») узагальнюється на схожі ситуації. Правило без причини ігнорується, як тільки змінюється контекст. Цей патерн також документований у посібнику Builder.io щодо CLAUDE.md.
Чому Claude ігнорує ваш CLAUDE.md? Бюджет інструкцій
Коротко: Claude не діє зі зла, йому просто бракує уваги. Після приблизно 80 рядків ви помітите, що правила починають відкидатися; після 200 рядків великі блоки ігноруються повністю; після 500 слів щільних правил дотримання руйнується. Рішення — це бюджет інструкцій. Ставтеся до кожного рядка як до витрати пам'яті claude code та дотримання кожного правила.
Нещодавні дослідження підтверджують те, що постійно виявляють користувачі на продакшені: здатність слідувати інструкціям деградує нелінійно зі збільшенням кількості правил. Стаття arxiv 2507.11538 про ємність слідування інструкціям показує, що дотримання кожного правила падає, коли ви накопичуєте їх більше, а аналіз HumanLayer використання CLAUDE.md у продакшені повторює той самий висновок.
Переклад: кожне додане правило робить кожне інше правило трохи менш ймовірним для виконання. Тож CLAUDE.md на 400 рядків не є в 4 рази ефективнішим за файл на 100 рядків. Часто він менш ефективний, тому що правила, які вам дійсно важливі, розмиваються тими, які ви написали в п'ятницю три місяці тому й ніколи не видалили.
У наших файлах CLAUDE.md все, що після 150-го рядка, починає помітно втрачати дотримання. На 250-му рядку ми бачили, як Claude пропускав цілі розділи. Тому ми встановлюємо ліміт.
wc -l CLAUDE.mdЦе весь інструмент. Запустіть його. Якщо у вас більше 200, ви перевищили бюджет. Жорстке правило, яке ми надаємо клієнтам:
Ставтеся до CLAUDE.md як до бюджету в 200 рядків. Кожен рядок коштує дотримання. Витрачайте його там, де це важливо.
Правило №1 підсилене: Тримайте його коротким. Менше 200 рядків. Менше 500 слів щільних правил. Якщо ви ловите себе на бажанні додати правила автоматизації («завжди запускай prettier після редагувань»), вони, ймовірно, належать до хуків Claude Code, натомість хуки є детермінованими й не коштують токенів бюджету інструкцій.
Чи використовувати CLAUDE.md, AGENTS.md, .cursorrules або copilot-instructions?
Коротко: Якщо ви використовуєте лише Claude Code, CLAUDE.md підходить. Якщо ви використовуєте два або більше агентських CLI (Codex, Cursor, Copilot, Sourcegraph), перейдіть на AGENTS.md і створіть символічне посилання з CLAUDE.md на AGENTS.md. AGENTS.md з'явився наприкінці 2025 року як крос-інструментальний стандарт, більшість сучасних агентів повертаються до нього, тож один файл живить всю екосистему.
Це питання, на яке жоден із топ-5 результатів пошуку фактично не відповідає. Ось матриця:
| Файл | Інструмент | Область дії | Коли використовувати | Резервний варіант |
|---|---|---|---|---|
CLAUDE.md | Claude Code | Для кожного проекту + глобально | Команди, що використовують лише Claude Code | Claude читає лише це |
AGENTS.md | OpenAI Codex, Cursor, Sourcegraph, Factory, Google | Для кожного проекту | Ви використовуєте 2+ агентських CLI | Більшість агентів повертаються до нього |
.cursorrules | Cursor | Для кожного проекту | Лише Cursor або як додаток специфічний для Cursor | Лише Cursor |
.github/copilot-instructions.md | GitHub Copilot | Для кожного проекту | Лише Copilot | Лише Copilot |
Трюк з подвійним таргетингом — це один рядок:
ln -s AGENTS.md CLAUDE.mdОт і все. Тепер Claude Code, Codex і будь-який інструмент, що підтримує AGENTS.md, читають один і той самий файл. Оновіть один раз, і кожен агент підхопить зміни. Специфікація AGENTS.md є відкритою й навмисно мінімалістичною, це просто markdown із конвенційними розділами.
Два реальні нюанси. По-перше: якщо у вашій команді є потужний користувач Cursor, .cursorrules від Cursor використовує інший підхід: один файл, без ієрархії, більш жорсткий формат. Деякі команди тримають обидва: AGENTS.md для спільних правил, .cursorrules для специфічних особливостей Cursor. По-друге: .github/copilot-instructions.md від Copilot не повертається до AGENTS.md, тож командам, орієнтованим на Copilot, потрібен окремий файл.
Якщо ви обираєте стек агентів з нуля, наш огляд Claude Code проти Cursor проти Copilot охоплює компроміси на рівні використання. Коротка версія: ієрархія Claude Code є найпотужнішою для монорепозиторіїв, UX Cursor виграє для соло-роботи, інтеграція Copilot в IDE все ще є найплавнішою для поступового впровадження.
Правило №9: Використовуйте AGENTS.md, якщо ви запускаєте більше одного агентського CLI. Не підтримуйте два файли, які кажуть одне й те саме. Оберіть файл, який читає більшість вашого стеку, і створіть символічні посилання для решти.
CLAUDE.md проти Хуків проти Навичок: Трикутник рішень
Коротко: CLAUDE.md = рекомендаційний контекст. Хуки = детерміновані дії. Навички = об'єднані можливості. Оберіть неправильний варіант, і ви витратите бюджет інструкцій на те, що має обробляти хук, або напишете правило в CLAUDE.md для чогось, що може доставити лише навичка. Трикутник — це найдешевший спосіб зберегти CLAUDE.md легким.

Три інструменти, три завдання. Помилка, яку ми бачимо найчастіше: розміщення «завжди запускай prettier після редагування» в CLAUDE.md. Claude читає це. Claude іноді запускає prettier. Ви розчаровані. Рішення — перемістити цей рядок із CLAUDE.md у хук, тому що хуки спрацьовують детерміновано щоразу, без жодного рекомендаційного простору для маневрів.
| Варіант використання | Інструмент | Чому |
|---|---|---|
| Запуск prettier при збереженні | Хук | Детерміновано, має відбуватися завжди |
| Використовувати відступ у 2 пробіли | CLAUDE.md | Рекомендаційна перевага стилю |
| Запуск нашого тестового пайплайну з нашою конфігурацією | Навичка | Багаторазовий об'єднаний робочий процес |
| Блокування комітів у main | Хук | Жорстке правило, без переговорів |
| Віддавати перевагу функціональним компонентам перед класами | CLAUDE.md | Стильове керівництво, яке оцінює Claude |
| Генерація схеми Sanity | Навичка | Багатокрокова можливість з активами |
Якщо правило має спрацьовувати завжди, воно належить до хука. Якщо це стилістична перевага, яку Claude може оцінити щодо контексту, воно належить до CLAUDE.md. Якщо це багатокроковий робочий процес з об'єднаними активами (шаблони, скрипти, промпти), воно належить до навички.
Правило №8: Правильно обирайте між CLAUDE.md, хуками та навичками; розміщення хука в CLAUDE.md є найпоширенішою марною витратою бюджету інструкцій. Налаштовуйте детерміновані дії за допомогою хуків Claude Code та пакуйте багаторазові робочі процеси як навички Claude. Ваш CLAUDE.md стане коротшим, ваші обмежувачі стануть міцнішими, а Claude перестане «забувати» важливі правила.
Патерни монорепозиторію: Вкладені CLAUDE.md, @imports та .claude/rules/
Коротко: У монорепозиторії тримайте кореневий CLAUDE.md крихітним, лише покажчики та спільні конвенції. Винесіть специфіку в
apps/*/CLAUDE.md, щоб кожне піддерево мало обмежені правила. Використовуйте @imports для спільного використання модульних файлів правил через.claude/rules/. Це прогресивне розкриття, Claude витягує кожну частину лише коли вона релевантна.
Типове дерево CLAUDE.md монорепозиторію:
.
├── CLAUDE.md # 30 lines — points to subdirs and shared rules
├── .claude/
│ └── rules/
│ ├── style.md
│ ├── testing.md
│ └── security.md
├── apps/
│ ├── web/
│ │ └── CLAUDE.md # Next.js-specific rules
│ └── api/
│ └── CLAUDE.md # Fastify-specific rules
└── packages/
└── shared/
└── CLAUDE.md # Library author rulesСинтаксис @import дозволяє кореневому файлу підтягувати спільні фрагменти правил без їхнього повторного визначення:
# Root CLAUDE.md
This is a Turborepo. See subdir CLAUDE.md for app-specific rules.
@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md
## Top-level commands
- `pnpm dev` runs all apps in parallel
- `pnpm test` runs every workspace's test scriptЦе прогресивне розкриття на практиці. Кореневий файл — це покажчик на 30 рядків. Кожен CLAUDE.md підкаталогу додає 50–80 рядків сфокусованих правил. Файли .claude/rules/ містять фрагменти конвенцій, які можуть підтягувати кілька підкаталогів. Нічого не дублюється, нічого не пропускається, і жоден окремий файл не перевищує бюджет інструкцій.
Правило лінивого завантаження, згадане раніше, тут ще важливіше: коли Claude працює з apps/web/Button.tsx, він бачить кореневий файл плюс apps/web/CLAUDE.md плюс файли правил, імпортовані через @import. Він не бачить apps/api/CLAUDE.md. У цьому й суть: конвенції бекенду не забруднюють контекст фронтенду, і ваше вікно контексту залишається придатним для використання.
Правило №6: Використовуйте @imports, щоб тримати кореневий файл під 200 рядків. Посібник Anthropic Best Practices for Claude Code розглядає це як стандартний патерн монорепозиторію. Субагенти також успадковують контекст батьківського CLAUDE.md, про що варто знати, якщо ви вкладаєте робочі процеси; див. інжиніринг контексту, щоб зрозуміти, як це взаємодіє з дизайном субагентів.
6 причин, чому Claude ігнорує ваш файл (і виправлення для кожної)
Коротко: Коли Claude ігнорує CLAUDE.md, це майже завжди одна з шести причин: файл занадто довгий, розмите формулювання, відсутність «чому», стиснення контексту, конфліктуючий батьківський файл або неправильна назва файлу. Кожна має виправлення за 60 секунд. Тестуйте в новій сесії після кожної зміни, це Правило №7.
1. Файл занадто довгий (>200 рядків / >500 слів)
Запустіть wc -l CLAUDE.md. Якщо більше 200, агресивно скорочуйте. Перемістіть правила автоматизації в хуки. Перемістіть робочі процеси в навички. Розділіть спільні фрагменти на .claude/rules/ і підтягніть їх через @import. Найпоширеніша причина, чому Claude «перестав дотримуватися» ваших правил, полягає в тому, що файл з часом став занадто довгим, і дотримання тихо впало.
2. Розмите формулювання («пишіть чистий код»)
Замініть кожне амбітне правило на конкретне, яке можна перевірити. «Будьте послідовними» невидимі для Claude. «Використовуйте серверні компоненти за замовчуванням; додавайте 'use client' лише для форм або інтерактивного UI» — це те, що Claude дійсно може застосувати.
3. Відсутність «чому»
Правила без причин не узагальнюються. Claude не може зрозуміти, коли можна відхилитися від правила, бо не знає, від чого це правило захищає. Кожне неочевидне правило отримує один рядок: «ми використовуємо unknown, а не any, тому що минулого кварталу мали три краші runtime через API-відповіді, типізовані як any».
4. Стиснення контексту відкинуло його
Довгі сесії запускають стиснення, Claude підсумовує попередній контекст, щоб вміститися у вікно, і вміст CLAUDE.md іноді підсумовується до невбуття. Рішення: /clear після значних витрат контексту або повний перезапуск сесії. Саме це постійно спливає у GitHub Issue #17530.
5. Конфліктуючий батьківський CLAUDE.md
Глобальний каже «використовуй 4 пробіли». Корінь проекту каже «використовуй 2 пробіли». Підкаталог нічого не каже. Claude обирає один, іноді неправильний. Перевірте ~/.claude/CLAUDE.md і корінь проекту на наявність суперечностей. Той, що є більш специфічним, має перемагати, але лише якщо ви зробите це явним.
6. Неправильне розташування файлу або регістр назви
Claude.md і CLAUDE.md — це різні файли в Linux та macOS. Так само як claude.md і CLAUDE.md. Переконайтеся, що шлях точно ./CLAUDE.md (великими літерами), і переконайтеся, що Claude Code запускається з каталогу, де він міститься. GitHub Issue #668 повний випадків, коли файл існував, але Claude не бачив його через проблеми зі шляхами.
Правило №7: Тестуйте в новій сесії. Після будь-якої зміни в CLAUDE.md відкрийте нову сесію і попросіть Claude «підсумувати правила в CLAUDE.md». Якщо підсумок щось пропускає, файл не виконує свою роботу.
Ваш перший CLAUDE.md за 10 хвилин: Стартовий набір із 5 кроків
Коротко: Запустіть
/initдля створення чернетки, скоротіть її до 6–10 реальних правил з причинами, додайте 3 команди, які має знати Claude, додайте 2 антипатерни, з якими зіткнулася ваша команда, а потім протестуйте в новій сесії, попросивши Claude підсумувати файл. Загальний час: близько 10 хвилин. Рецепт із 5 кроків — це те, що ми використовуємо в день 1 кожного нового репозиторію.
-
Запустіть
/initдля створення чернетки. Команда/initу Claude Code сканує ваш репозиторій і пише стартовий CLAUDE.md. Не використовуйте те, що він напише, як фінальний варіант. Вивід/init— це відправна точка, а не готовий файл, і, чесно кажучи, більшу частину згенерованого можна видалити. -
Скоротіть його до 6–10 рядків реальних правил з причинами. Видаліть усе загальне. Видаліть усе, що є в README. Залиште лише ті правила, які Claude не може вивести з самого коду.
-
Додайте 3 команди, які має знати Claude. Збірка, тестування, лінтинг. Включіть точну команду та будь-які неочевидні прапорці. Якщо ви використовуєте Vitest, а не Jest, скажіть про це.
-
Додайте 2 антипатерни, з якими зіткнулася ця команда. Реальні. «Не використовуйте
any, тому що у нас було три краші runtime» завжди краще, ніж «використовуйте TypeScript правильно». -
Відкрийте нову сесію та перевірте. Попросіть Claude «підсумувати правила в CLAUDE.md». Якщо він щось пропускає, файл занадто довгий, занадто розмитий або йому бракує «чому». Виправте й повторіть.
Правило №5: Не генеруйте автоматично лише з /init. /init — це відправна точка, а не готовий файл. Цінність полягає в тих 8 хвилинах, які ви витрачаєте на його скорочення.
FAQ
Що таке файл CLAUDE.md?
Файл CLAUDE.md — це markdown-файл, який Claude Code читає як пам'ять проекту на початку кожної сесії. Він повідомляє Claude про ваші конвенції, команди та антипатерни, щоб йому не довелося здогадуватися. Він працює на чотирьох рівнях: глобальному, корені проекту, підкаталозі (з лінивим завантаженням) та особистому CLAUDE.local.md, який ви тримаєте ігнорованим git.
Якою має бути довжина файлу CLAUDE.md?
Менше 200 рядків і менше 500 слів щільних правил. Після цих порогів здатність Claude слідувати інструкціям погіршується, кожне додане правило робить кожне інше правило трохи менш ймовірним для виконання. Ставтеся до нього як до фіксованого бюджету. Якщо вам потрібно більше, розділіть на файли CLAUDE.md у підкаталогах і використовуйте @import для спільних фрагментів.
Куди мені помістити CLAUDE.md?
Основний розміщується в корені вашого проекту (./CLAUDE.md) і комітиться. Додайте файли CLAUDE.md у підкаталоги для правил, специфічних для додатків, у монорепозиторіях. Помістіть міжпроектні налаштування в ~/.claude/CLAUDE.md. Використовуйте CLAUDE.local.md для особистих перевизначень, які ви не хочете комітити, але не забудьте ігнорувати його в git вручну.
Чому Claude ігнорує мій CLAUDE.md?
У 90% випадків це одна з трьох речей: файл занадто довгий (понад 200 рядків), правила розмиті («пишіть чистий код») або правилам бракує «чому», яке Claude може використати для їх застосування. Запустіть wc -l CLAUDE.md, а потім перевірте на конкретність. Тестуйте зміни в новій сесії, попросивши Claude підсумувати файл.
Чи слід мені використовувати CLAUDE.md чи AGENTS.md?
Якщо ваша команда використовує лише Claude Code, дотримуйтесь CLAUDE.md. Якщо ви використовуєте два або більше агентських CLI (Codex, Cursor, Sourcegraph), перейдіть на AGENTS.md і створіть символічне посилання з CLAUDE.md на нього: ln -s AGENTS.md CLAUDE.md. Більшість сучасних агентських CLI повертаються до AGENTS.md, тож один файл живить усі інструменти.
Чи слід мені запускати /init для генерації CLAUDE.md?
Так, як чернетку. Ні, як готовий файл. /init сканує ваш репозиторій і створює стартовий варіант, але він багатослівний і загальний. Anthropic і HumanLayer обидва рекомендують агресивно скорочувати його після запуску /init. Цінність файлу реально проявляється в ті 8 хвилин, які ви витрачаєте на вирізання зайвого та додавання рядків «чому».
Як працюють файли CLAUDE.md у монорепозиторії?
Кореневий CLAUDE.md залишається крихітним, лише покажчики та спільні правила. Кожен додаток отримує власний apps/*/CLAUDE.md з обмеженими конвенціями. Файли підкаталогів завантажуються ліниво лише тоді, коли Claude читає файли всередині цього піддерева, тож сусіди залишаються ізольованими. Використовуйте @import .claude/rules/style.md для спільного використання модульних фрагментів правил без їхнього дублювання в додатках.
У чому різниця між CLAUDE.md, хуками та навичками?
CLAUDE.md — це рекомендаційний контекст, Claude читає його і зазвичай дотримується. Хуки — це детерміновані дії, які завжди спрацьовують (форматування, блокування комітів). Навички — це об'єднані можливості для багаторазових робочих процесів з активами. Використовуйте CLAUDE.md для стильових рекомендацій, хуки для жорстких правил, а навички для багатокрокових завдань, які ви повторюватимете в різних проектах.
Як Techsy підходить до цього
У Techsy кожен проект Claude Code, який ми поставляємо, має CLAUDE.md менше ніж на 150 рядків і символічне посилання на AGENTS.md. Ми ставимося до файлу як до коду, версіонуємо його, рецензуємо зміни в PR і повторно тестуємо в нових сесіях перед злиттям. Потрібна допомога з інтеграцією AI-агентів у ваш робочий процес розробки? Отримайте безкоштовну консультацію.