claude-md

---
name: claude-md
description: Створення або оновлення файлів CLAUDE.md відповідно до найкращих практик для оптимального онбордингу AI-агента
---

## Введення користувача

```text
$ARGUMENTS
```

Ви **ПОВИННІ** врахувати введення користувача перед продовженням (якщо не порожнє). Користувач може вказати:
- `create` — створити новий CLAUDE.md з нуля
- `update` — покращити існуючий CLAUDE.md
- `audit` — проаналізувати та звітувати про якість поточного CLAUDE.md
- Конкретний шлях для створення/оновлення (напр., `src/api/CLAUDE.md` для інструкцій, специфічних для каталогу)

## Основні принципи

**LLM не мають стану**: CLAUDE.md — єдиний файл, що автоматично включається в кожну розмову. Він слугує головним документом онбордингу AI-агентів у вашу кодову базу.

### Золоті правила

1. **Менше — краще**: Найсучасніші LLM можуть дотримуватись ~150-200 інструкцій. Системний промпт Claude Code вже використовує ~50. Тримайте CLAUDE.md зосередженим та лаконічним.

2. **Універсальна застосовність**: Включайте лише інформацію, релевантну для КОЖНОЇ сесії. Інструкції для конкретних завдань належать до окремих файлів.

3. **Не використовуйте Claude як лінтер**: Рекомендації зі стилю роздувають контекст та погіршують дотримання інструкцій. Використовуйте натомість детерміністичні інструменти (prettier, eslint тощо).

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

## Потік виконання

### 1. Аналіз проєкту

Спочатку проаналізуйте поточний стан проєкту:

1. Перевірити наявні файли CLAUDE.md:
   - Кореневий рівень: `./CLAUDE.md` або `.claude/CLAUDE.md`
   - Специфічні для каталогу: `**/CLAUDE.md`
   - Глобальний конфіг користувача: `~/.claude/CLAUDE.md`

2. Визначити структуру проєкту:
   - Технологічний стек (мови, фреймворки)
   - Тип проєкту (монорепо, окремий додаток, бібліотека)
   - Інструменти розробки (пакетний менеджер, система збірки, тест-раннер)

3. Переглянути існуючу документацію:
   - README.md
   - CONTRIBUTING.md
   - package.json, pyproject.toml, Cargo.toml тощо

### 2. Стратегія контенту (ЩО, ЧОМУ, ЯК)

Структуруйте CLAUDE.md навколо трьох вимірів:

#### ЩО — Технологія та структура
- Огляд технологічного стеку
- Організація проєкту (особливо важливо для монорепо)
- Ключові каталоги та їхнє призначення

#### ЧОМУ — Призначення та контекст
- Що робить проєкт
- Чому були прийняті певні архітектурні рішення
- За що відповідає кожен основний компонент

#### ЯК — Робочий процес та конвенції
- Робочий процес розробки (bun vs node, pip vs uv тощо)
- Процедури та команди тестування
- Методи верифікації та збірки
- Критичні «підводні камені» або неочевидні вимоги

### 3. Стратегія поступового розкриття

Для великих проєктів рекомендуйте створити папку `agent_docs/`:

```
agent_docs/
  |- building_the_project.md
  |- running_tests.md
  |- code_conventions.md
  |- architecture_decisions.md
```

У CLAUDE.md посилайтесь на ці файли інструкціями:
```markdown
For detailed build instructions, refer to `agent_docs/building_the_project.md`
```

**Важливо**: Використовуйте посилання `файл:рядок` замість фрагментів коду, щоб уникнути застарілого контексту.

### 4. Обмеження якості

При створенні або оновленні CLAUDE.md:

1. **Цільова довжина**: Менше 300 рядків (ідеально — менше 100)
2. **Без правил стилю**: Видалити будь-які інструкції лінтингу/форматування
3. **Без інструкцій для конкретних завдань**: Перемістити до окремих файлів
4. **Без фрагментів коду**: Використовувати посилання на файли замість цього
5. **Без надлишкової інформації**: Не повторювати те, що є в package.json або README

### 5. Обовʼязкові секції

Добре структурований CLAUDE.md має включати:

```markdown
# Назва проєкту

Короткий однорядковий опис.

## Технологічний стек
- Основна мова та версія
- Ключові фреймворки/бібліотеки
- База даних/сховище (якщо є)

## Структура проєкту
[Лише для монорепо або складних структур]
- `apps/` - Точки входу додатків
- `packages/` - Спільні бібліотеки

## Команди розробки
- Встановлення: `команда`
- Тестування: `команда`
- Збірка: `команда`

## Критичні конвенції
[Лише неочевидні, високовпливові конвенції]
- Конвенція 1 з коротким поясненням
- Конвенція 2 з коротким поясненням

## Відомі проблеми / Підводні камені
[Речі, що постійно створюють труднощі розробникам]
- Проблема 1
- Проблема 2
```

### 6. Антипатерни, яких слід уникати

**НЕ включайте:**
- Рекомендації зі стилю коду (використовуйте лінтери)
- Документацію щодо використання Claude
- Довгі пояснення очевидних патернів
- Скопійовані приклади коду
- Загальні найкращі практики («пишіть чистий код»)
- Інструкції для конкретних завдань
- Автозгенерований контент
- Розлогі списки TODO

### 7. Контрольний список валідації

Перед фіналізацією перевірте:

- [ ] Менше 300 рядків (бажано менше 100)
- [ ] Кожен рядок застосовний до ВСІХ сесій
- [ ] Без правил стилю/форматування
- [ ] Без фрагментів коду (використані посилання на файли)
- [ ] Команди перевірені на працездатність
- [ ] Поступове розкриття використано для складних проєктів
- [ ] Критичні підводні камені задокументовані
- [ ] Немає надлишковості з README.md

## Формат виводу

### Для `create` або за замовчуванням:

1. Проаналізувати проєкт
2. Створити чернетку CLAUDE.md за структурою вище
3. Представити чернетку для перегляду
4. Записати у відповідне місце після затвердження

### Для `update`:

1. Прочитати існуючий CLAUDE.md
2. Аудит за найкращими практиками
3. Визначити:
   - Контент для видалення (правила стилю, фрагменти коду, специфічне для завдань)
   - Контент для скорочення
   - Відсутню важливу інформацію
4. Представити зміни для перегляду
5. Застосувати зміни після затвердження

### Для `audit`:

1. Прочитати існуючий CLAUDE.md
2. Згенерувати звіт з:
   - Поточна кількість рядків vs ціль
   - Відсоток універсально застосовного контенту
   - Список знайдених антипатернів
   - Рекомендації для покращення
3. НЕ модифікувати файл, лише звітувати

## Обробка AGENTS.md

Якщо користувач запитує створення/оновлення AGENTS.md:

AGENTS.md використовується для визначення спеціалізованої поведінки агентів. На відміну від CLAUDE.md (який для контексту проєкту), AGENTS.md визначає:
- Кастомні ролі та можливості агентів
- Інструкції та обмеження для конкретних агентів
- Визначення робочих процесів для мультиагентних сценаріїв

Застосовуйте аналогічні принципи:
- Тримайте зосередженим та лаконічним
- Використовуйте поступове розкриття
- Посилайтесь на зовнішні документи замість вбудовування контенту

## Примітки

- Завжди перевіряйте працездатність команд перед їх включенням
- Якщо сумніваєтесь — не включайте; менше — краще
- Системне нагадування повідомляє Claude, що CLAUDE.md «може бути або не бути релевантним» — чим більше шуму, тим більше він ігнорується
- Монорепо найбільше виграють від чіткої структури ЩО/ЧОМУ/ЯК
- Файли CLAUDE.md для конкретних каталогів мають бути ще більш зосередженими