claude-md

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

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

$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 посилайтесь на ці файли інструкціями:

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. Антипатерни, яких слід уникати

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

• Рекомендації зі стилю коду (використовуйте лінтери)
• Документацію щодо використання 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:

Claude Code не читає AGENTS.md напряму. Щоб файл почав діяти, імпортуйте його з CLAUDE.md через @AGENTS.md або зробіть CLAUDE.md символічним посиланням на нього. Це найпоширеніше непорозуміння щодо цього файлу.

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

• Команди збірки, тестування та лінтингу
• Стиль коду та архітектурні конвенції
• Структура репозиторію та розташування компонентів

Субагенти визначаються окремо — у .claude/agents/*.md, а не в AGENTS.md.

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

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

Примітки

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