# CLAUDE.md: як налаштувати інструкції для Claude Code

> Як правильно налаштувати файл CLAUDE.md для Claude Code: рівні конфігурації, стандарти коду, розділи Gotchas та Never Do, еталонні приклади та правило другого зауваження.

**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: рівні пріоритету

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

:::tabs
=== Проєктний корінь (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)
```markdown
# Scoped Project Rules

- Location: .claude/CLAUDE.md
- Applies to all contributors of this repository
- Versioned in Git alongside codebase
- Overrides any user-level global preferences
```
=== Глобальний файл (~/.claude/CLAUDE.md)
```markdown
# Global User Preferences

### Coding Style
- Prefer functional patterns over OOP classes
- Always write explicit error handling with typed errors
- Keep functions short (under 30 lines where possible)

### Git
- Use lowercase commit messages
- Conventional commits: feat:, fix:, chore:, docs:, refactor:
- Never push directly to main/master branch
```
:::

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

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

> [!IMPORTANT]
> **Пріоритет завжди на боці локального проєкту:** Якщо глобальне правило суперечить вимозі у файлі репозиторію, модель суворо дотримується локального `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 } при збої.` |

> [!TIP]
> Перевірочний тест для вашого правила: чи можна автоматизувати його перевірку лінтером або простим 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 }
    );
  }
}
```
```

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
```

> [!WARNING]
> У розділі заборон уникайте м'яких виразів на кшталт *«намагайся не використовувати 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 прямо зараз            над поточною задачею
```

> [!TIP]
> Якщо ви двічі попросили 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.** У корені кожного репозиторію

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

---

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

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

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

---

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

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

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

---

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

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