`CLAUDE.md`, rules і auto memory

1. CLAUDE.md зʼявляється саме зараз

CLAUDE.md починає працювати лише тоді, коли довкола вже є порядок: безпечний старт, зрозумілий робочий каталог, виразна позиція щодо прав доступу. Напишете проєктні інструкції раніше — при брудному working tree, без окремої гілки і з режимом доступу «на авось» жоден markdown не врятує.

Думайте про CLAUDE.md як про коротку записку поруч із кодовою базою. Це не документація і не заміна README.md. README відповідає людині: «як підняти проєкт і що це таке». CLAUDE.md відповідає Claude: «як працювати тут, щоб не накоїти зайвого».

Фраза «проєкт на Spring Boot і Next.js» у CLAUDE.md марна — це видно з репозиторію. А «історичні міграції в db/migration/ не переписуємо, нові зміни лише новим файлом» — корисна: це домовленість команди, з коду вона неочевидна.

У Commerce OS такий файл виглядав би так:

# CLAUDE.md

## Команди проєкту
- run: `docker compose up`
- test: `./gradlew test`
- check: `./gradlew check`

## Домовленості
- не змінювати `/api/v1/**` без явного підтвердження
- не переписувати наявні файли в `db/migration/`
- у відповіді завжди перелічувати змінені файли і запущені перевірки

Файл добрий тим, що короткий. Жодної екскурсії архітектурою магазину — три речі, які Claude справді використовує: як запускати проєкт, де небезпечні зони і в якому вигляді звітувати. Живе в репозиторії, сприймається як частина проєкту.

2. Корисне наповнення CLAUDE.md

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

Робоча таблиця для наповнення:

Особливо корисні команди. Claude дуже охоче вгадує, чим запускати проєкт, і іноді вгадує не туди. Якщо у вас справді прийнято підіймати Commerce OS через docker compose up, а перевірки запускати через ./gradlew check, краще записати це явно. Один точний рядок економить багато зайвих спроб.

Не менш корисні приховані особливості проєкту. Якщо в сервісі оплати всі суми зберігаються в копійках, а не в рублях чи доларах, це потрібно записати. Якщо видалення замовлення означає не фізичне видалення рядка з бази, а soft delete, це теж варто записати. Якщо локально застосунок нормально працює лише за піднятого worker, а по одному npm run dev або bootRun усе виглядає живим, але частина логіки мовчки не працює, це теж хороший кандидат для CLAUDE.md.

Окремо корисно записувати очікування до формату відповіді. Наприклад, не просто «зроби правку», а «після змін переліч, які файли ти міняв, які перевірки запускав і що залишилося ризикованим». Це вже не про запуск проєкту, а про якість вашої повсякденної роботи. І такі рядки дуже швидко окуповуються: ви менше граєте в археолога за diff’ами і рідше ловите сюрпризи.

3. Зайве в CLAUDE.md

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

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

Друга часта помилка — записувати очевидне. Рядок «проєкт на Next.js» зазвичай нічого не дає, якщо в репозиторії вже лежать package.json, next.config.* і папка app/. А ось рядок «не пропонуй масовий рефакторинг форматування в одному diff із фічею» — дає, бо це не про стек, а про робочий режим команди.

Третя помилка — писати абстрактні моральні гасла. Фрази на кшталт «пиши хороший код», «будь обережним», «не ламай нічого» звучать дуже виховано, але користі дають мало. Що конкретніше правило, то краще воно працює.

Порівняйте такі пари:

Погано: «Роби все охайно і сучасно».
Добре: «Не змінюй сигнатури публічних методів у src/api/** без явного підтвердження».

Погано: «Дотримуйся стилю проєкту».
Добре: «Не пропонуй форматувальні правки поза поточним обсягом задачі».

Погано: «Слідкуй за безпекою».
Добре: «Не читай і не редагуй .env* без прямого запиту».

І ще одна дуже важлива думка: CLAUDE.md — це context, not enforcement.

Якщо ви написали у файлі «не чіпати .env», це корисна інструкція. Але це не жорстка заборона. Якщо у вас є справді небезпечна зона, яку не можна випадково чіпати, захищати її потрібно не лише словами в markdown, а ще й іншими механізмами: Git baseline, permissions, .gitignore, захищені шляхи, додаткові перевірки. Інакше ви будете чекати від пам’ятки поведінки сейфа. Пам’ятка так не вміє.

4. CLAUDE.local.md — локальні нотатки

У будь-якого розробника є локальні особливості середовища. У когось база працює на нестандартному порту, у когось свій шлях до мок-даних, хтось любить, щоб Claude показував зміни маленькими порціями, а не одним великим шматком. Ці речі нормальні. Проблема починається, коли вони непомітно переповзають у спільний CLAUDE.md і починають виглядати як правила всієї команди.

Саме для цього корисний CLAUDE.local.md. Це ваш локальний файл для нотаток про цей проєкт. Його не слід комітити в репозиторій, і він не має підміняти загальні домовленості проєкту. Якщо CLAUDE.md — це табличка на дверях майстерні, то CLAUDE.local.md — це ваш стікер на ноутбуці.

Ось типовий локальний приклад:

# CLAUDE.local.md

## Нотатки про workspace
- локальна БД працює на порту 5454
- тестові CSV для імпорту лежать у `~/projects/data/subscriptions/`

## Особисті вподобання
- пропонуй зміни невеликими diff-блоками
- якщо зачеплено більше двох файлів, спочатку коротко опиши план

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

CLAUDE.local.md не комітиться, і це добре. Але Claude все одно може читати його у вашому локальному середовищі. Отже, класти туди реальні токени, паролі і чутливі дані все одно не слід. Локальність рятує від випадкового коміту, але не перетворює файл на сейф.

Різницю між двома файлами зручно бачити так:

CLAUDE.md

CLAUDE.local.md

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

5. Різниця CLAUDE.md, rules і auto memory

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

Зручно тримати в голові таку схему:

flowchart TD
    A[Зʼявилася нова інструкція або нотатка] --> B{Вона потрібна всій команді і майже всім сесіям?}
    B -->|Так| C[Покласти в CLAUDE.md]
    B -->|Ні| D{Вона потрібна лише вам у цьому проєкті?}
    D -->|Так| E[Покласти в CLAUDE.local.md]
    D -->|Ні| F{Вона стосується лише однієї папки або типу файлів?}
    F -->|Так| G[Це кандидат на окреме rule]
    F -->|Ні| H{Це тимчасовий або нещодавно дізнаний факт?}
    H -->|Так| I[Нехай живе в auto memory до перевірки]
    H -->|Ні| J[Ймовірно, записувати взагалі не треба]

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

При цьому сьогодні вам важлива саме логіка розділення, а не формат rules за файлами і синтаксисом. Досить запам’ятати ідею: загальне і стабільне — в загальний файл, вузьке і специфічне — в окреме правило, особисте — в локальний файл.

6. auto memory потребує переперевірки

auto memory зручна саме тому, що не потребує вашої постійної участі. Claude помітив щось у процесі роботи, запам’ятав це і в наступній сесії вже поводиться так, ніби знав цю деталь завжди. Звучить приємно. Але є нюанс, і він дуже людський: помічник теж може запам’ятати нісенітницю, застарілий факт або тимчасове рішення так, ніби це вічна істина проєкту.

Уявіть простий сценарій. Тиждень тому ви тимчасово тримали старий шлях /api/v0/refunds, бо міграція маршрутів ще не завершилася. Claude це запам’ятав. Через тиждень ви маршрут виправили, а пам’ять не переглянули. І ось у новій сесії Claude впевнено тягнеться до вже неактуального шляху, бо колись чесно це вивчив. Помилка не в тому, що пам’ять погана. Помилка в тому, що її ніхто не перевірив.

Тому корисно тримати дуже простий рефлекс перевірки пам’яті:

Точна slash-команда для перегляду або очищення пам’яті залежить від версії Claude Code, тому тут правильна звичка дуже проста: заглянути в /help і знайти актуальну команду у вашому середовищі. Нам важливий не конкретний синтаксис, а сам робочий ритуал.

І є одне дуже корисне правило, яке варто запам’ятати майже дослівно: якщо факт настільки важливий, що ви засмутитеся при його порушенні, не тримайте його лише в auto memory. Виносьте його рівнем вище — у CLAUDE.md або в окреме правило. Пам’ять добра для допоміжних речей. Основа проєкту має жити у явному файлі.

7. Короткий baseline для pet-проєкту

Найкращий перший CLAUDE.md — не той, який «ідеально покриває все», а той, який ви справді відкриватимете і підтримуватимете. Для pet-проєкту краще почати з маленького baseline: команди, дві-три неочевидні домовленості, одна-дві небезпечні зони і зрозумілий формат відповіді Claude. Цього вже досить, щоб перестати повторювати одні й ті самі інструкції з сесії в сесію.

Наприклад, для маленького проєкту з обліку підписок такий baseline міг би виглядати так:

# CLAUDE.md

## Команди
- run: `npm run dev`
- test: `npm test`

## Домовленості проєкту
- усі суми зберігаємо в копійках
- не вимикати TypeScript strict mode
- у відповіді перелічуй змінені файли і запущені перевірки

## Не робити
- не чіпати `.env*` без прямого запиту
- не робити масовий рефакторинг поза межами поточного запиту

Якщо ваш pet-проєкт на Java і Gradle, файл залишиться таким самим за змістом, зміняться лише команди. Наприклад, run стане ./gradlew bootRun, а test — ./gradlew test. Логіка не змінюється: ви не описуєте весь світ, ви кладете на стіл коротку робочу пам’ятку.

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

Саме тому короткий baseline майже завжди перемагає «розумний», але роздутий файл. Коли ви завтра відкриєте проєкт, Claude вже знатиме, чим запускати код, які зони у вас чутливі і у якому вигляді ви хочете бачити результат. А ви не писатимете в чат учетверте те саме. Для робочого процесу це дуже приємне відчуття: ніби в майстерні нарешті зʼявилися підписані шухляди, і молоток більше не зберігається в холодильнику.