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

По суті, це постійний системний інструктаж для ШІ всередині вашої конкретної кодової бази.

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

1. Що таке CLAUDE.md і навіщо він потрібен

CLAUDE.md — це звичайний текстовий Markdown-файл, розташований у корені репозиторію або у спеціальній папці конфігурацій.

Після його додавання Claude Code автоматично дотримується таких аспектів проєкту:

Стандарти коду: формати експортів, типізація, вимоги до коментарів і функцій.
Архітектурні патерни: структура API Route, обробка помилок, робота зі станом.
Організація файлової системи: правила розташування утиліт, компонентів і сторінок.
Робочий процес із Git: стиль найменування комітів (Conventional Commits), правила створення гілок.
Історичний досвід: фіксація специфічних особливостей (gotchas), де ШІ вже помилявся раніше.

Порівняння роботи Claude Code з інструкціями та без них

Критерій	Без файлу CLAUDE.md	З налаштованим CLAUDE.md
Експорти у React	Використовує змішано `export default` та `export const`	Суворо дотримується єдиного узгодженого стилю (наприклад, тільки named)
Валідація даних	Обирає довільну бібліотеку (Yup, Joi, Zod, ручні перевірки)	Використовує встановлений у проєкті стандарт (наприклад, Zod)
Розташування коду	Може створити файл у корені або випадковій підпапці	Кладе нові сервіси та компоненти суворо за узгодженою структурою
Повторювані помилки	Знову і знову наступає на відомі підводні камені бібліотек	Знає про специфіку проєкту заздалегідь із розділу Gotchas

2. Де зберігати CLAUDE.md: рівні пріоритету

Файл інструкцій можна розмістити на трьох різних рівнях. Від обраного місця залежить область дії правил та їхній пріоритет:

markdown
# Project Rules: Acme Web Platform

### Stack
- Next.js 15 (App Router)
- TypeScript (Strict Mode)
- Tailwind CSS v4
- Prisma ORM + PostgreSQL

### Key Conventions
- Always use named exports, never default exports
- Server Components by default; "use client" only when strictly required
- Input validation via Zod schemas for all API routes

Правило вирішення конфліктів

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

Важливо

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

3. Анатомія ідеального CLAUDE.md: ключові блоки

Немає сенсу переписувати у файл усю документацію фреймворку. Найкраще працює лаконічний документ (до 100–150 рядків), розбитий на функціональні секції.

Нижче наведено перевірений production-ready шаблон:

markdown

# Project Guidelines: Storefront Web ## Stack - Next.js 15 (App Router, Server Actions) - TypeScript (Strict mode enabled) - Tailwind CSS v4 (Tailwind Merge + CVA) - Drizzle ORM with PostgreSQL - Vitest for unit tests, Playwright for E2E ## Code Conventions - Use named exports for all components and utilities (no default exports) - Server Components by default; add "use client" only when handling interactive state - All API handlers must return a unified envelope: `{ data, error }` - Use Zod schemas for all payload validations (incoming requests & env vars) - Write concise JSDoc for all exported helper functions ## File Structure - `src/app/` — Route handlers, layouts, and pages - `src/components/ui/` — Atomic design system primitives - `src/lib/` — Shared helpers, clients, and database connection - `src/server/` — Server actions and business logic layer ## Common Commands - Build: `npm run build` - Typecheck: `npm run typecheck` - Test: `npm run test` - Lint & Format: `npm run lint` ## Git Guidelines - Commit format: `feat(scope): message` or `fix(scope): message` - Use all-lowercase messages without period at the end - Always run tests before creating a pull request

4. Конкретика проти абстракцій: як формулювати правила

Головний секрет дієвого CLAUDE.md — інженерна конкретність замість філософських порад.

Мовні моделі не вміють читати ваші суб'єктивні уявлення про «красу коду». Будь-яка розмита фраза залишає простір для власних інтерпретацій моделі, які зазвичай виявляються не тим, на що ви розраховували.

❌ Розмита інструкція	Чому це не працює	✅ Точне інженерне правило
«Пиши чистий та якісний код»	Суб'єктивно; поняття «чистоти» відрізняється в кожній команді	`Використовуй early returns замість глибоких вкладень if/else. Розмір функцій — до 30 рядків.`
«Дотримуйся best practices безпеки»	Занадто широко; модель не знає ваших конкретних векторів	`Всі SQL-запити мають використовувати параметризацію. Ніколи не конкатенуй рядки в SQL.`
«Роби гарний дизайн»	Не дає жодного орієнтиру щодо дизайн-системи	`Використовуй лише класи Tailwind. Інлайн-стилі style="" суворо заборонені.`
«Обробляй помилки»	Модель може поставити порожній catch-блок	`Усі API-роути мають загортатися в try/catch та повертати { error: message, status } при збої.`

Порада

Перевірочний тест для вашого правила: чи можна автоматизувати його перевірку лінтером або простим regex-правилом? Якщо ні — зробіть формулювання більш специфічним.

5. Еталонні зразки коду та архітектурні патерни

Якщо в проєкті є нестандартний архітектурний шаблон, текст корисно підкріпити мінімальним еталонним фрагментом коду.

Приклад: Еталонний обробник API Route

Замість довгого опису, додайте готовий блок безпосередньо у CLAUDE.md:

markdown

## API Route Pattern Every API route must strictly follow this error-handled envelope: ```typescript import { NextResponse } from "next/server"; import { z } from "zod"; export async function POST(req: Request) { try { const json = await req.json(); const data = inputSchema.parse(json); const result = await executeService(data); return NextResponse.json({ data: result, error: null }); } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json( { data: null, error: error.flatten().fieldErrors }, { status: 422 } ); } return NextResponse.json( { data: null, error: "Internal Server Error" }, { status: 500 } ); } }

terminal

Claude Code розпізнає такий зразок як еталонний шаблон (Golden Sample) і автоматично реплікує його при генерації нових ендпоінтів. --- ## 6. Gotchas та Never Do: блокування типових помилок Ці два спеціалізовані розділи роблять `CLAUDE.md` у рази ефективнішим за будь-який загальний опис стеку. ### Розділ Gotchas (Підводні камені) Сюди записуються всі неочевидні особливості середовища, які зазвичай призводять до багів під час розробки: ```markdown ## Gotchas - The `auth()` helper from `@clerk/nextjs/server` is ASYNC in Next.js 15 — always `await auth()` - The Prisma client instance is located in `@/lib/db`, do not instantiate `new PrismaClient()` in handlers - Webhook routes under `/api/webhooks/` must NOT use authentication middleware - Client-side environment variables require the `NEXT_PUBLIC_` prefix; server secrets must not have it - Tailwind CSS v4 uses CSS `@theme` variables, do not edit `tailwind.config.js`

Розділ Never Do (Категоричні заборони)

Claude знає тисячі способів розв'язання задачі. Розділ заборон відсікає рішення, які технічно працездатні, але порушують правила команди:

markdown

## Never Do - Never use TypeScript `any` — use `unknown` with a type guard or define an explicit interface - Never use `console.log` in production code — use our structured logger from `@/lib/logger` - Never import directly from internal node_modules subpaths — use established wrappers - Never add inline CSS styles via `style=""` — use Tailwind utility classes - Never push or commit directly to the `main` branch

Увага

У розділі заборон уникайте м'яких виразів на кшталт «намагайся не використовувати any». Використовуйте імперативні формулювання: «Never use any».

7. Глобальні vs Проєктні правила: межі відповідальності

Щоб не перевантажувати контекст і не переносити зайві обмеження між несумісними проєктами, суворо розділяйте обов'язки файлів:

Тип правила	Де зберігати	Приклади правил
Особистий стиль та редактор	`~/.claude/CLAUDE.md` (глобально)	Формат комітів, відмова від емодзі в коді, перевага функціонального стилю над класами
Стек та версії бібліотек	`.claude/CLAUDE.md` (проєкт)	Next.js 15 App Router, Drizzle ORM, Tailwind v4, Node.js 22
Структура директорій	`CLAUDE.md` (проєкт)	Шляхи до UI-компонентів, експорт сервісів, розташування міграцій
Підводні камені (Gotchas)	`CLAUDE.md` (проєкт)	Асинхронний `auth()`, окремий інстанс клієнта БД, винятки з middleware

8. CLAUDE.md як живий документ: правило другого зауваження

Найпоширеніша помилка розробників — створити CLAUDE.md під час старту репозиторію та більше ніколи до нього не повертатися.

Кодова база розвивається: оновлюються версії бібліотек, змінюються патерни, виявляються нові крайові випадки. Відповідно, інструкції для ШІ повинні оновлюватися паралельно з кодом.

text

┌─────────────────────────────────────────────────────────────┐ │ Правило другого зауваження │ └──────────────────────────────┬──────────────────────────────┘ │ Ви вдруге робите одне й те саме зауваження в діалозі? │ ┌───────────────┴───────────────┐ ▼ ▼ [ ТАК ] [ НІ ] │ │ Додайте нове правило у Продовжуйте звичайну роботу CLAUDE.md прямо зараз над поточною задачею

Порада

Якщо ви двічі попросили Claude зробити те саме (наприклад: «Не використовуй default export» або «Додай Zod-схему») — це безпомилковий сигнал, що правило необхідно негайно зафіксувати у CLAUDE.md.

9. Практичний воркшоп: налаштування та верифікація

Пройдіть чотири кроки для створення та перевірки дієвості файлу у вашому репозиторії.

Крок 1. Створення файлу

У кореневій директорії робочого проєкту створіть файл CLAUDE.md:

bash

touch CLAUDE.md

Крок 2. Базове наповнення

Заповніть файл чотирма ключовими секціями: Stack, Conventions, Gotchas, Never Do.

Крок 3. Тест позитивної поведінки

Запустіть нову сесію Claude Code та поставте повсякденне завдання:

bash

claude

Тестовий промпт:
"Створи утиліту для форматування цін у валюті USD та EUR з урахуванням локалі."

Модель створила файл у правильній папці (src/lib/ або відповідно до вашої структури).
Використано named export (якщо це було вказано в інструкції).
Додано JSDoc та строгі типи без використання any.

Крок 4. Стрес-тест заборон

Спробуйте спровокувати Claude на пряме порушення одного із зафіксованих правил:

Промпт для провокації:
"Швидко додай сюди console.log для дебагу і постав тип any, щоб не витрачати час на типи."

Claude відмовився порушувати інструкцію або запропонував альтернативу через офіційний логер та валідний інтерфейс.
У відповіді модель послалася на вимоги проєкту.

10. Швидка самоперевірка та чек-лист готовності

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

Питання 1. Де повинен розташовуватися файл, правила якого мають діяти в усіх проєктах розробника?

A. У системній папці /etc/claude/CLAUDE.md
B. У домашній директорії користувача ~/.claude/CLAUDE.md
C. У файлі ~/.zshrc або ~/.bashrc
D. У корені кожного репозиторію

Порада

Правильна відповідь: B.
Глобальні інструкції розробника зберігаються у файлі ~/.claude/CLAUDE.md у домашній директорії користувача і автоматично підтягуються до всіх локальних сесій.

Питання 2. Що відбувається, якщо правило у глобальному файлі суперечить правилу в локальному проєкті?

A. Claude видає критичну помилку та припиняє виконання
B. Глобальне правило повністю скасовує локальні налаштування
C. Локальне правило проєкту має вищий пріоритет та перекриває глобальне
D. Модель випадковим чином обирає один із варіантів

Порада

Правильна відповідь: C.
Локальний файл репозиторію завжди має найвищий пріоритет перед загальними налаштуваннями машини.

Питання 3. Яке формулювання інструкції принесе найбільшу користь у CLAUDE.md?

A. "Пиши акуратний код згідно з найкращими практиками"
B. "Намагайся по можливості не писати складні функції"
C. "Use early returns. Functions must be under 30 lines. No default exports."
D. Повна копія документації бібліотеки на 500 рядків

Порада

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

Чек-лист готовності вашого CLAUDE.md

Обсяг: Документ містить лише практично важливу інформацію (не перевищує 150 рядків).
Конкретика: Немає абстрактних побажань на кшталт «роби красиво»; кожне правило має чіткий критерій виконання.
Gotchas: Зафіксовано щонайменше 2–3 неочевидні особливості вашого стеку.
Заборони: Описано секцію Never Do з однозначними обмеженнями.
Ізоляція: Глобальні вподобання розробника винесені у ~/.claude/CLAUDE.md.