CLAUDE.md: як написати пам'ять проєкту для Claude Code — шаблон і приклади
Кожна нова сесія Claude Code починається «з чистого аркуша»: агент не пам'ятає, що вчора ви домовилися запускати тести через pytest -q, а нові ендпоінти класти в src/api. CLAUDE.md — це файл, який Claude Code автоматично читає на старті кожної сесії, щоб ці домовленості не доводилося повторювати. Добре написаний CLAUDE.md економить час, токени й нерви; погано написаний — тихо погіршує кожну відповідь.
У статті — де лежить цей файл, що в нього писати, як підключати додаткові інструкції, і готовий шаблон, з якого можна почати. Усе звірено з документацією Anthropic станом на листопад 2026 року.
Головне за 30 секунд
./CLAUDE.mdу корені проєкту — пам'ять для всієї команди, комітиться в Git./initстворює заготовку,/memoryпоказує й відкриває всі файли пам'яті.- Пишіть конкретно: команди, структура, правила. Тримайте файл коротшим за 200 рядків.
- Деталі виносьте в окремі файли: імпорт
@docs/api.mdабо правила в.claude/rules/. - CLAUDE.md — контекст, а не замок: заборони задавайте в налаштуваннях дозволів і хуках.
Де лежить CLAUDE.md і в якому порядку читається
Файлів пам'яті може бути кілька — від загальних до конкретних:
| Рівень | Розташування | Для чого |
|---|---|---|
| Організація (managed) | Системна тека, наприклад /etc/claude-code/CLAUDE.md у Linux | Політики компанії, задає адміністратор |
| Користувач | ~/.claude/CLAUDE.md | Ваші особисті звички для всіх проєктів |
| Проєкт | ./CLAUDE.md або ./.claude/CLAUDE.md | Спільні правила команди, комітяться в Git |
| Локальний | ./CLAUDE.local.md | Ваші особисті нотатки до цього проєкту; додайте в .gitignore |
Під час запуску Claude Code завантажує файли з робочої теки й усіх тек вище, об'єднуючи їх від кореня до поточної теки. CLAUDE.md у вкладених теках (наприклад, frontend/CLAUDE.md) підвантажуються, коли агент починає працювати з файлами в них. Побачити, що саме завантажено, можна командою /memory: вона показує файли пам'яті й відкриває їх у редакторі.
Найшвидший старт — команда /init: Claude прочитає проєкт і запропонує початковий CLAUDE.md. Згенерований файл майже завжди варто скоротити: агент схильний описувати очевидне.
Що писати, а що ні
Добре правило: у CLAUDE.md потрапляє те, що новий колега мав би знати в перший день і що неможливо швидко зрозуміти з коду.
| Варто писати | Не варто писати |
|---|---|
| Команди збірки, тестів, лінтера — точно, як їх запускати | Опис мови чи фреймворку загалом («React — це бібліотека…») |
Де що лежить: «API-обробники — у src/api/handlers/» | Повний перелік файлів — агент і так бачить дерево |
| Неочевидні домовленості: стиль, назви гілок, формат комітів | Загальні побажання: «пиши гарний код», «будь уважним» |
| Пастки проєкту: «міграції не редагувати, лише нові файли» | Секрети, паролі, токени — файл комітиться в Git |
| Як перевірити результат перед завершенням задачі | Те, що швидко застаріває: статуси задач, дати релізів |
Документація Anthropic наводить приклади конкретних інструкцій: «Use 2-space indentation», «Run npm test before committing», «API handlers live in src/api/handlers/». Порівняйте з розмитим «дотримуйся стилю проєкту»: першу інструкцію можна виконати й перевірити, другу — ні.
Шаблон CLAUDE.md
Шаблон для невеликого вебпроєкту. Замініть команди й шляхи на свої, видаліть розділи, які вам не потрібні.
# Проєкт: трекер завдань (Node.js + React)
## Команди
- Встановлення: `npm ci`
- Dev-сервер: `npm run dev` (http://localhost:5173)
- Тести: `npm test` — запускай після кожної зміни коду
- Лінтер: `npm run lint` — має проходити без помилок перед комітом
## Структура
- `src/api/` — REST-ендпоінти (Express), один файл на ресурс
- `src/web/` — React-застосунок
- `db/migrations/` — міграції; існуючі НЕ редагувати, лише додавати нові
## Домовленості
- TypeScript strict, відступ 2 пробіли
- Назви гілок: `feature/коротка-назва`, `fix/коротка-назва`
- Коміти: англійською, в наказовому способі ("Add task filter")
- Тексти інтерфейсу — лише через `src/web/i18n/`, не хардкодити
## Перед завершенням задачі
1. `npm run lint && npm test` проходять
2. Нові ендпоінти мають тест у `src/api/__tests__/`
3. Коротко опиши, що змінено і як це перевірити
## Додатково
- Опис API: @docs/api.md
Зверніть увагу на три речі. Команди записано точно, а не «запусти тести». Пастки названо прямо (міграції не редагувати). Великий опис API винесено в окремий файл через імпорт — він не роздуває основний CLAUDE.md.
Написання CLAUDE.md під реальний проєкт — тема окремого розділу практичного курсу Claude Code: ви пишете пам'ять для власного проєкту, а система перевіряє, чи інструкції конкретні й виконувані.
Імпорти, .claude/rules і CLAUDE.local.md
Імпорти. Рядок з @шлях/до/файлу підключає інший файл: See @README for project overview. Шлях рахується відносно файлу, у якому стоїть імпорт; глибина вкладених імпортів — до чотирьох рівнів. Для файлів поза проєктом Claude Code попросить підтвердження.
Правила в .claude/rules/. Окремі markdown-файли з інструкціями, які можна прив'язати до частини проєкту через поле paths у заголовку. Тоді правило діє лише тоді, коли агент працює з відповідними файлами:
---
paths:
- "src/api/**/*.ts"
---
# Правила для API
- Кожен ендпоінт валідує вхідні дані через zod
- Помилки повертаються у форматі { error: { code, message } }
Особисті правила для всіх проєктів можна класти в ~/.claude/rules/.
CLAUDE.local.md. Ваші особисті нотатки до конкретного проєкту — наприклад, адреса вашої тестової бази або улюблений спосіб запуску. Файл додається після CLAUDE.md і не має потрапляти в Git — додайте його в .gitignore.
Автопам'ять і AGENTS.md
Окрім CLAUDE.md, у Claude Code є автопам'ять: агент сам записує корисні спостереження про проєкт у ~/.claude/projects/<проєкт>/memory/MEMORY.md. На початку сесії завантажуються перші 200 рядків (або 25 КБ) цього файлу. Автопам'ять увімкнена за замовчуванням; вимкнути її можна в /memory або налаштуванням autoMemoryEnabled. Різниця проста: CLAUDE.md пишете ви і він спільний для команди, автопам'ять веде агент і вона лише ваша.
AGENTS.md — формат інструкцій, який використовують різні AI-агенти. Claude Code читає його, якщо в проєкті немає CLAUDE.md чи CLAUDE.local.md, а також його можна явно підключити: @AGENTS.md у вашому CLAUDE.md. Схожа ідея лежить в основі Agent Skills — про них ми писали в статті про відкритий стандарт навичок: навичка завантажується лише тоді, коли потрібна, тож туди варто виносити довгі інструкції для окремих задач.
Навчіть Claude Code працювати за вашими правилами
У курсі Claude Code для початківців пам'ять проєкту — окремий розділ, а далі — дозволи, Git, MCP, навички, хуки, субагенти й фінальний мультиагентний проєкт. Практика з автоматичною перевіркою. Курс входить у підписку Prog Academy разом із курсами Claude Chat, Claude Cowork і Claude in Chrome.
Типові помилки
- Файл на 600 рядків. Він з'їдає контекст у кожній сесії, а важливі правила губляться серед другорядних. Ціль — до 200 рядків; решту — в імпорти й правила.
- Розмиті інструкції. «Пиши якісний код» нічого не змінює. «Кожна нова функція в
src/apiмає unit-тест» — змінює. - Суперечності. У кореневому файлі «відступ 4 пробіли», у вкладеному — «2 пробіли». Агент обере одне з двох, і не обов'язково те, що ви чекаєте.
- Віра в CLAUDE.md як у захист. Рядок «ніколи не читай .env» — лише прохання. Щоб справді заборонити, використовуйте правила deny, sandbox і хуки — як це зробити, ми розібрали в статті про безпечну роботу з Claude Code.
- «Написав і забув». Якщо агент двічі зробив ту саму помилку, це сигнал додати правило. Якщо правило застаріло — видаліть його. Можна просто попросити Claude: «додай це в CLAUDE.md».
Якщо ви ще не пробували Claude Code на власному проєкті, почніть з нашої статті про перший проєкт з Claude Code, а потім додайте до нього CLAUDE.md за шаблоном вище.
Часті питання
Що таке CLAUDE.md?
Це markdown-файл з інструкціями для Claude Code, який автоматично завантажується на початку кожної сесії. У ньому зберігають те, що інакше доводилося б пояснювати щоразу: команди збірки й тестів, структуру проєкту, домовленості щодо коду й правила роботи. Документація Anthropic називає це контекстом, а не примусовою конфігурацією.
Де має лежати CLAUDE.md?
Для проєкту — у корені репозиторію (./CLAUDE.md) або в ./.claude/CLAUDE.md. Особисті інструкції для всіх проєктів — у ~/.claude/CLAUDE.md. Особисті інструкції лише для одного проєкту — у ./CLAUDE.local.md, який варто додати в .gitignore.
Як створити CLAUDE.md автоматично?
Запустіть Claude Code у теці проєкту і виконайте команду /init. Claude проаналізує проєкт і запропонує початковий CLAUDE.md; якщо файл уже існує, він запропонує покращення. Згенерований файл варто переглянути й скоротити вручну.
Якого розміру має бути CLAUDE.md?
Документація радить тримати кожен CLAUDE.md коротшим за 200 рядків. Довгий файл займає контекст у кожній сесії і гірше виконується. Великі теми краще винести в окремі файли й підключити через імпорт @ або правила в .claude/rules.
Чи читає Claude Code файл AGENTS.md?
Так, якщо в проєкті немає CLAUDE.md чи CLAUDE.local.md (у версіях 2.1.277 і новіших). Також AGENTS.md можна явно підключити з CLAUDE.md через імпорт @AGENTS.md — зручно, якщо команда використовує кілька AI-агентів.
Джерела
CLAUDE.md — найпростіший спосіб зробити Claude Code передбачуваним: десять хвилин на файл економлять години пояснень. Наступні кроки — дозволи, навички, хуки й субагенти. Їх системно, з практикою на власному проєкті, розбираємо в курсі Claude Code для початківців. Курс входить у підписку: за 29 $ на місяць відкриваються всі курси за підпискою, а перші 7 днів можна спробувати за 1 $.
Читайте також
- Як безпечно працювати з Claude Code: режими дозволів, auto mode, sandbox і хуки
- Claude Code: повне керівництво у 2026 році — що це, як працює і як використовувати
- Agent Skills стали відкритим стандартом: як написати свій перший SKILL.md
- Вайб-кодинг із Claude Code: перший проєкт з нуля — покрокова інструкція для початківців
