CLAUDE.md, rules і auto memory · Claude Code Guide

CLAUDE.md — коротка інструкція для агента

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

Перед написанням інструкцій перевірте Git-стан, окрему гілку, права доступу та правильність робочого каталогу.

Блок	Що в ньому зафіксувати
Команди	Запуск, тести, перевірки та збірка
Конвенції	Неочевидні правила коду або workflow
Приховані властивості	Наприклад, суми в копійках або soft delete
Формат звіту	Змінені файли, перевірки та залишкові ризики
Заборонені дії	Чутливі шляхи, API, міграції та конфігурації

Еталонний мінімум CLAUDE.md

# CLAUDE.md

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

## Правила
- не змінювати публічний API без підтвердження
- не робити масове форматування разом із функціональною зміною
- у підсумку перелічувати файли та перевірки

## Не робити
- не читати й не редагувати .env* без прямого запиту
- не виконувати широкий рефакторинг поза scope

CLAUDE.local.md для локальних деталей

`CLAUDE.local.md` підходить для машинозалежних параметрів і особистих вподобань, які не потрібні всій команді. Такий файл зазвичай виключають із Git, але він не повинен містити секрети.

Стабільне командне правило не варто ховати в локальному файлі: інші сесії та колеги його не побачать.

Приклад локальних нотаток без секретів

# CLAUDE.local.md

## Локальне середовище
- база даних працює на порту `5454`
- тестові CSV лежать у `~/projects/data/subscriptions/`

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

Куди покласти конкретне правило

Якщо правило потрібне всій команді та більшості сесій — додайте його до CLAUDE.md.
Якщо воно потрібне лише вам — використайте CLAUDE.local.md або user-рівень.
Якщо воно стосується конкретної папки чи типу файлів — винесіть його в окреме rule.
Якщо це тимчасове спостереження або новий факт — розгляньте auto memory.
Якщо запис не є стабільним і корисним, не додавайте його лише «про всяк випадок».

Rules і auto memory не замінюють захист

Rules допомагають звузити контекст для окремої області, а auto memory може зберегти тимчасове рішення чи спостереження. Памʼять може бути неповною, помилковою або застарілою, тому критично важливу домовленість не можна зберігати лише там.

Інструкції Markdown не є механізмом примусу. Для захисту потрібні також Git-права, permissions, `.gitignore`, секрет-менеджмент, тести та людська перевірка.

Регулярно переглядайте auto memory.
Видаляйте випадкові та неактуальні записи.
Стабільні правила переносіть до спільного CLAUDE.md або вузького rule.
Не перетворюйте CLAUDE.md на енциклопедію всього проєкту.