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

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

$ARGUMENTS

Ви ПОВИННІ врахувати введення користувача перед продовженням (якщо не порожнє). Користувач може вказати:

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

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 навколо трьох вимірів:

ЩО — Технологія та структура

ЧОМУ — Призначення та контекст

ЯК — Робочий процес та конвенції

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

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

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

У CLAUDE.md посилайтесь на ці файли інструкціями:

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 має включати:

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

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

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

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

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

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

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

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

НЕ включайте:

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

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

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

Для 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 визначає:

Застосовуйте аналогічні принципи:

Примітки