CLAUDE.md, якого Claude справді дотримується в кожній сесії

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

Де лежить файл

Покладіть його в кореневу теку проєкту, просто поруч із README:

my-project/
 - CLAUDE.md
 - README.md
 - package.json
 - src/
 - tests/

Закомітьте його в Git, щоб колеги отримували ті самі вказівки. Інше допустиме місце — .claude/CLAUDE.md.

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

my-project/
 - CLAUDE.md
 - src/
   - frontend/
     - CLAUDE.md
   - backend/
     - CLAUDE.md

Почніть з одного файлу в корені. Додавайте нові, лише коли якійсь частині кодової бази справді потрібні власні інструкції.

Замініть добрі наміри конкретикою

Інструкція, очевидна для вас, для агента може виявитися розмитою. Такі рядки звучать розумно:

• Пиши чистий код
• Дотримуйся найкращих практик
• Тестуй ретельно
• Зберігай однорідність архітектури

Але погляньте на них очима агента. Що означає «ретельно» в цьому репозиторії? Які саме найкращі практики? Ви знаєте, що мали на увазі, а агентові доводиться вгадувати, доки ви цього не скажете.

Ось як той самий намір виглядає для API на TypeScript:

• Обробники маршрутів лежать у src/routes/.
• Запити до бази даних живуть у src/repositories.
• Тіла запитів перевіряються вже наявними схемами Zod.
• Помилки надсилаються через src/lib/api-error.ts.
• Виправляючи баг, додавай регресійний тест, що відтворює описаний збій.

Це рішення, а не побажання, і агент може їх виконувати.

Перелічіть справжні команди

У проєкті можуть бути модульні, інтеграційні й браузерні тести та кілька способів запустити застосунок. Фраза «запускай тести після кожної правки» не каже агентові, які з них запускати. Уявіть проєкт на pnpm і Vitest. Можна написати розділ із командами й зазначити, що вони запускаються з кореня репозиторію:

• Встановлення залежностей: pnpm install.
• Запуск dev-сервера: pnpm dev.
• Перевірка типів: pnpm typecheck.
• Одноразовий прогін модульних тестів: pnpm exec vitest run.
• Прогін одного файлу: pnpm exec vitest run <test-file>.

Каталог, з якого запускається команда, і будь-які передумови важать не менше за саму команду. Запустіть кожну самі, перш ніж додавати. Скопійована команда, яка переходить у режим спостереження або потребує сервісу, про який ніхто не написав, лише підкине нову проблему.

І не змушуйте кожну дрібну правку запускати всі дорогі перевірки. Опишіть перевірки, доречні в щоденній роботі, а обов'язкові бар'єри хай забезпечує CI.

Запишіть особливості, схожі на помилки

Саме тут файл виправдовує своє місце. Скажімо, ваш API зберігає гроші в цілих центах, тож $19.99 проходить через систему як 1999. Без цього знання невинна на вигляд правка може призвести до неузгоджених значень. Добра нотатка описує і правило, і точку перевикористання:

• Суми в API та базі даних — цілі центи.
• Переводить у валюту для відображення тільки UI, і робити це треба через наявну formatMoney() у src/lib/money.ts.

Або, скажімо, старий мобільний клієнт залежить від дивної поведінки. Запис про сумісність може повідомляти, що POST /subscriptions повертає HTTP 200 на повторні запити, що старі мобільні клієнти на це покладаються і що так має лишитися, хіба що задача явно змінює контракт API. Останнє застереження важливе. Воно лишає місце для навмисних змін, щоб історична нотатка не перетворилася на незрозуміле правило, яке ніхто не може переглянути.

Один рядок про те, навіщо щось існує, може зупинити непотрібне «виправлення».

Перетворіть повторювані поправки на вказівки

Уявіть, що Claude підключає нову бібліотеку для дат, хоча в проєкті вже є спільний форматер. Можна сказати: «Не додавай зайвих залежностей». Біда в тому, що наступного разу ви сперечатиметеся, що вважати «зайвим».

Сильніша версія називає перевірку, вказує на код і пояснює шлях для винятків:

• Перш ніж додати залежність часу виконання, пошукай у package.json і src/lib/ те, що вже розв'язує задачу.
• Для дат використовуй src/lib/date.ts.
• Якщо новий пакет справді потрібен, поясни, з чим не дають ради наявні інструменти.

Але будьте вибагливі. Одна дивна задача не завжди виправдовує постійне правило. Непогана перевірка — чи матиме ця поправка значення за місяць.

Не тримайте там короткострокової роботи

Деякі нотатки застарівають того ж дня, коли їх написано:

Уявіть нотатку на кшталт «сьогодні займаємося багом в оформленні замовлення, зламаний акаунт — test-user-42, спершу збільш таймаут».

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

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

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

Project overview
 - Briefly explain what this project does and its main technologies.

Useful commands
 - Set up the project: [command]
 - Run locally: [command]
 - Run tests: [command]
 - Check formatting and linting: [command]

Mention where to run these commands and any required setup.

Where things live
 - Point to the main source code, tests, and important documentation.
 - Include locations that may be difficult to find or easy to confuse.

Project conventions
 - Describe the patterns to follow and existing helpers to reuse.
 - Focus on decisions that aren't obvious from reading the code.

Things to watch out for
 - Explain unusual behavior that must be preserved.
 - Identify generated files and how they should be updated.
 - Give a short reason for each restriction.

Checking changes
 - Explain how to choose and run the relevant checks.
 - Ask Claude to report what it checked and anything it couldn't verify.

Заповнювати кожен розділ не обов'язково. Якщо розділові нічого корисного сказати, видаліть його. Замініть заглушки справжніми командами й шляхами, перш ніж покладатися на файл.

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