CLAUDE.md
Файли конфігурації проєкту — як структурувати CLAUDE.md для ефективної роботи агента
📎ОФІЦІЙНА ДОКУМЕНТАЦІЯ
Що таке CLAUDE.md?
CLAUDE.md — це спеціальний файл, який надає Claude Code контекст про ваш проєкт. Він автоматично завантажується при запуску і допомагає агенту розуміти архітектуру, стандарти коду та робочі процеси вашої команди.
CLAUDE.md — це аналог системного промпту, але специфічний для кожного проєкту. Він значно покращує якість відповідей агента.
Рівні CLAUDE.md
Claude Code шукає файли CLAUDE.md на кількох рівнях, і кожен має свій пріоритет:
1. Користувацький рівень
~/.claude/CLAUDE.md
Глобальні інструкції, що застосовуються до всіх проєктів. Наприклад, ваші преференції щодо стилю коду.
2. Кореневий рівень проєкту
./CLAUDE.md # у корені проєкту
./.claude/CLAUDE.md # альтернативне розташування
Основний файл конфігурації проєкту. Комітиться в репозиторій і поширюється на всю команду.
3. Рівень піддиректорії
./src/CLAUDE.md
./src/components/CLAUDE.md
Специфічні інструкції для окремих частин проєкту. Завантажуються, коли Claude Code працює з файлами у цій директорії.
Порядок завантаження
~/.claude/CLAUDE.md ← глобальний (найнижчий пріоритет)
└── ./CLAUDE.md ← проєктний
└── ./src/CLAUDE.md ← піддиректорія (найвищий пріоритет)
Структура CLAUDE.md
Рекомендований шаблон
# Назва проєкту
## Огляд
Короткий опис проєкту, його мета та основні функції.
## Технічний стек
- Frontend: React 19, TypeScript, Tailwind CSS
- Backend: Node.js, Express, PostgreSQL
- Тестування: Vitest, Playwright
## Структура проєкту
src/ components/ — React компоненти hooks/ — кастомні хуки lib/ — утиліти та хелпери api/ — API-ендпоінти types/ — TypeScript типи
## Команди
- `npm run dev` — запуск dev-серверу
- `npm run test` — запуск тестів
- `npm run build` — збірка проєкту
- `npm run lint` — перевірка лінтером
## Стандарти коду
- Використовуй функціональні компоненти з hooks
- Всі нові файли повинні мати TypeScript типи
- Тести обов'язкові для бізнес-логіки
- Іменування: camelCase для змінних, PascalCase для компонентів
## Важливі правила
- НЕ видаляй існуючі тести
- НЕ змінюй конфігурацію CI/CD без узгодження
- Завжди запускай тести перед комітом
Приклади для різних типів проєктів
Next.js проєкт
# My Next.js App
## Стек
Next.js 15 (App Router), TypeScript, Prisma, PostgreSQL
## Важливо
- Використовуй Server Components за замовчуванням
- Client Components позначай "use client" лише коли потрібно
- API routes у app/api/ використовують Route Handlers
- Prisma schema знаходиться у prisma/schema.prisma
- Після зміни schema запускай: npx prisma generate
## Структура
- app/ — сторінки та layouts (App Router)
- components/ — UI компоненти
- lib/ — серверні утиліти
- prisma/ — схема бази даних
Python проєкт
# ML Pipeline
## Стек
Python 3.12, FastAPI, SQLAlchemy, PyTorch
## Середовище
- Використовуй uv для менеджменту залежностей
- Активація: source .venv/bin/activate
- Тести: pytest tests/
## Стандарти
- Type hints обов'язкові
- Docstrings у Google-стилі
- Black для форматування, ruff для лінтингу
Поширені помилки
Уникайте цих помилок при створенні CLAUDE.md:
Занадто довгий файл
CLAUDE.md завантажується в контекстне вікно при кожному запиті. Тримайте його стислим — 50-200 рядків достатньо.
Суперечливі інструкції
Якщо глобальний та проєктний CLAUDE.md суперечать один одному, проєктний має пріоритет, але це може створити плутанину.
Застаріла інформація
Регулярно оновлюйте CLAUDE.md при зміні стеку, структури або процесів.
Найкращі практики
- Комітьте CLAUDE.md у репозиторій — це частина документації проєкту
- Починайте з малого — додавайте інструкції поступово
- Будьте конкретними — "Використовуй Vitest" краще ніж "Пиши тести"
- Вказуйте команди — точні команди для збірки, тестів, деплою
- Оновлюйте регулярно — CLAUDE.md має відображати поточний стан проєкту
Детальніше про ефективну роботу з Claude Code
Загальні принципи інженерії контексту для AI-агентів