cea0a7d4ef
6 SKILL.md files + 3 templates translated. Remaining: references/code-smells.md and references/refactoring-catalog.md Ref: luongnv89/claude-howto#63
213 lines
11 KiB
Markdown
213 lines
11 KiB
Markdown
---
|
||
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 для конкретних каталогів мають бути ще більш зосередженими
|