diff --git a/uk/03-skills/README.md b/uk/03-skills/README.md new file mode 100644 index 0000000..66127bc --- /dev/null +++ b/uk/03-skills/README.md @@ -0,0 +1,815 @@ + + + + + + + Claude How To + + +# Посібник з навичок агента + +Навички агента (Agent Skills) — це повторно використовувані, файлові можливості, які розширюють функціональність Claude. Вони пакують доменну експертизу, воркфлови та найкращі практики в компоненти, що автоматично виявляються, і Claude використовує їх, коли це доречно. + +## Огляд + +**Навички агента** — це модульні можливості, які перетворюють агентів загального призначення на спеціалістів. На відміну від промптів (інструкцій рівня розмови для одноразових завдань), навички завантажуються за потребою і усувають необхідність повторно надавати ті самі рекомендації в кількох розмовах. + +### Ключові переваги + +- **Спеціалізація Claude**: налаштування можливостей для доменних завдань +- **Зменшення повторень**: створити один раз, використовувати автоматично в усіх розмовах +- **Комбінування можливостей**: поєднання навичок для побудови складних воркфловів +- **Масштабування воркфловів**: повторне використання навичок у кількох проєктах і командах +- **Підтримка якості**: вбудовування найкращих практик безпосередньо у воркфлов + +Навички відповідають відкритому стандарту [Agent Skills](https://agentskills.io), який працює з кількома AI-інструментами. Claude Code розширює стандарт додатковими функціями: керування викликом, виконання в субагенті та динамічне впровадження контексту. + +> **Примітка**: Користувацькі слеш-команди об'єднано з навичками. Файли `.claude/commands/` все ще працюють і підтримують ті самі поля фронтматера. Навички рекомендовано для нової розробки. Коли обидва існують за одним шляхом (наприклад, `.claude/commands/review.md` та `.claude/skills/review/SKILL.md`), навичка має пріоритет. + +## Як працюють навички: прогресивне розкриття + +Навички використовують архітектуру **прогресивного розкриття** (progressive disclosure) — Claude завантажує інформацію поетапно за потребою, а не споживає весь контекст одразу. Це забезпечує ефективне управління контекстом із необмеженою масштабованістю. + +### Три рівні завантаження + +```mermaid +graph TB + subgraph "Level 1: Metadata (Always Loaded)" + A["YAML Frontmatter"] + A1["~100 tokens per skill"] + A2["name + description"] + end + + subgraph "Level 2: Instructions (When Triggered)" + B["SKILL.md Body"] + B1["Under 5k tokens"] + B2["Workflows & guidance"] + end + + subgraph "Level 3: Resources (As Needed)" + C["Bundled Files"] + C1["Effectively unlimited"] + C2["Scripts, templates, docs"] + end + + A --> B + B --> C +``` + +| Рівень | Коли завантажується | Вартість токенів | Вміст | +|--------|-------------------|-----------------|-------| +| **Рівень 1: Метадані** | Завжди (при запуску) | ~100 токенів на навичку | `name` та `description` з YAML-фронтматера | +| **Рівень 2: Інструкції** | Коли навичка активована | До 5k токенів | Тіло SKILL.md з інструкціями та рекомендаціями | +| **Рівень 3+: Ресурси** | За потребою | Фактично необмежено | Файли-пакети, що виконуються через bash без завантаження в контекст | + +Це означає, що ви можете встановити багато навичок без штрафу за контекст — Claude лише знає, що кожна навичка існує і коли її використовувати, доки вона фактично не активована. + +## Процес завантаження навички + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude + participant System as System + participant Skill as Skill + + User->>Claude: "Review this code for security issues" + Claude->>System: Check available skills (metadata) + System-->>Claude: Skill descriptions loaded at startup + Claude->>Claude: Match request to skill description + Claude->>Skill: bash: read code-review/SKILL.md + Skill-->>Claude: Instructions loaded into context + Claude->>Claude: Determine: Need templates? + Claude->>Skill: bash: read templates/checklist.md + Skill-->>Claude: Template loaded + Claude->>Claude: Execute skill instructions + Claude->>User: Comprehensive code review +``` + +## Типи та розташування навичок + +| Тип | Розташування | Область дії | Спільний | Найкраще для | +|-----|-------------|-------------|---------|-------------| +| **Enterprise** | Managed settings | Всі користувачі організації | Так | Загальноорганізаційні стандарти | +| **Personal** | `~/.claude/skills//SKILL.md` | Індивідуальний | Ні | Персональні воркфлови | +| **Project** | `.claude/skills//SKILL.md` | Команда | Так (через git) | Командні стандарти | +| **Plugin** | `/skills//SKILL.md` | Де увімкнено | Залежить | В складі плагінів | + +Коли навички мають однакову назву на різних рівнях, вищі пріоритетні розташування перемагають: **enterprise > personal > project**. Навички плагінів використовують простір імен `plugin-name:skill-name`, тому конфлікти неможливі. + +### Автоматичне виявлення + +**Вкладені каталоги**: коли ви працюєте з файлами в підкаталогах, Claude Code автоматично виявляє навички з вкладених каталогів `.claude/skills/`. Наприклад, якщо ви редагуєте файл у `packages/frontend/`, Claude Code також шукає навички в `packages/frontend/.claude/skills/`. Це підтримує конфігурації монорепо, де пакети мають власні навички. + +**Каталоги `--add-dir`**: навички з каталогів, доданих через `--add-dir`, завантажуються автоматично з виявленням змін у реальному часі. Будь-які зміни файлів навичок у цих каталогах набувають чинності негайно без перезапуску Claude Code. + +**Бюджет опису**: описи навичок (метадані рівня 1) обмежені **1% контекстного вікна** (резерв: **8 000 символів**). Якщо встановлено багато навичок, описи можуть бути скорочені. Назви всіх навичок завжди включаються, але описи обрізаються для вписування. Розміщуйте ключовий випадок використання на початку описів. Перевизначте бюджет змінною оточення `SLASH_COMMAND_TOOL_CHAR_BUDGET`. + +## Створення власних навичок + +### Базова структура каталогу + +``` +my-skill/ +├── SKILL.md # Головні інструкції (обов'язковий) +├── template.md # Шаблон для заповнення Claude +├── examples/ +│ └── sample.md # Приклад результату з очікуваним форматом +└── scripts/ + └── validate.sh # Скрипт, який Claude може виконати +``` + +### Формат SKILL.md + +```yaml +--- +name: your-skill-name +description: Brief description of what this Skill does and when to use it +--- + +# Your Skill Name + +## Instructions +Provide clear, step-by-step guidance for Claude. + +## Examples +Show concrete examples of using this Skill. +``` + +### Обов'язкові поля + +- **name**: тільки малі літери, цифри, дефіси (макс. 64 символи). Не може містити "anthropic" або "claude". +- **description**: що навичка робить І коли її використовувати (макс. 1024 символи). Це критично для того, щоб Claude знав, коли активувати навичку. + +### Додаткові поля фронтматера + +```yaml +--- +name: my-skill +description: What this skill does and when to use it +argument-hint: "[filename] [format]" # Підказка для автодоповнення +disable-model-invocation: true # Тільки користувач може викликати +user-invocable: false # Приховати з меню слеш-команд +allowed-tools: Read, Grep, Glob # Обмежити доступ до інструментів +model: opus # Конкретна модель +effort: high # Рівень зусиль (low, medium, high, max) +context: fork # Запуск в ізольованому субагенті +agent: Explore # Тип агента (з context: fork) +shell: bash # Оболонка: bash (за замовч.) або powershell +hooks: # Хуки, обмежені навичкою + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/validate.sh" +paths: "src/api/**/*.ts" # Glob-патерни, що обмежують активацію +--- +``` + +| Поле | Опис | +|------|------| +| `name` | Тільки малі літери, цифри, дефіси (макс. 64 символи). Не може містити "anthropic" або "claude". | +| `description` | Що навичка робить І коли її використовувати (макс. 1024 символи). Критично для автоматичного зіставлення. | +| `argument-hint` | Підказка в меню автодоповнення `/` (наприклад, `"[filename] [format]"`). | +| `disable-model-invocation` | `true` = тільки користувач може викликати через `/name`. Claude ніколи не викличе автоматично. | +| `user-invocable` | `false` = приховано з меню `/`. Тільки Claude може викликати автоматично. | +| `allowed-tools` | Список інструментів через кому, які навичка може використовувати без запитів дозволу. | +| `model` | Перевизначення моделі під час активності навички (наприклад, `opus`, `sonnet`). | +| `effort` | Перевизначення рівня зусиль: `low`, `medium`, `high` або `max`. | +| `context` | `fork` для запуску навички у відгалуженому контексті субагента з власним контекстним вікном. | +| `agent` | Тип субагента при `context: fork` (наприклад, `Explore`, `Plan`, `general-purpose`). | +| `shell` | Оболонка для підстановок `!`command`` та скриптів: `bash` (за замовч.) або `powershell`. | +| `hooks` | Хуки, обмежені життєвим циклом цієї навички (той самий формат, що й глобальні хуки). | +| `paths` | Glob-патерни, що обмежують автоактивацію. Рядок через кому або YAML-список. Формат як у правилах для конкретних шляхів. | + +## Типи вмісту навичок + +Навички можуть містити два типи вмісту, кожен для різних цілей: + +### Довідковий вміст + +Додає знання, які Claude застосовує до вашої поточної роботи — конвенції, патерни, стайлгайди, доменні знання. Виконується в контексті вашої розмови. + +```yaml +--- +name: api-conventions +description: API design patterns for this codebase +--- + +When writing API endpoints: +- Use RESTful naming conventions +- Return consistent error formats +- Include request validation +``` + +### Вміст завдань + +Покрокові інструкції для конкретних дій. Часто викликається безпосередньо через `/skill-name`. + +```yaml +--- +name: deploy +description: Deploy the application to production +context: fork +disable-model-invocation: true +--- + +Deploy the application: +1. Run the test suite +2. Build the application +3. Push to the deployment target +``` + +## Керування викликом навичок + +За замовчуванням і ви, і Claude можете викликати будь-яку навичку. Два поля фронтматера контролюють три режими виклику: + +| Фронтматер | Ви можете викликати | Claude може викликати | +|---|---|---| +| (за замовч.) | Так | Так | +| `disable-model-invocation: true` | Так | Ні | +| `user-invocable: false` | Ні | Так | + +**Використовуйте `disable-model-invocation: true`** для воркфловів з побічними ефектами: `/commit`, `/deploy`, `/send-slack-message`. Ви не хочете, щоб Claude вирішив задеплоїти, бо ваш код виглядає готовим. + +**Використовуйте `user-invocable: false`** для фонових знань, які не є дієвими як команда. Навичка `legacy-system-context` пояснює, як працює стара система — корисно для Claude, але не має сенсу як дія для користувачів. + +## Підстановки рядків + +Навички підтримують динамічні значення, які розв'язуються до того, як вміст навички потрапляє до Claude: + +| Змінна | Опис | +|--------|------| +| `$ARGUMENTS` | Всі аргументи, передані при виклику навички | +| `$ARGUMENTS[N]` або `$N` | Доступ до конкретного аргументу за індексом (починаючи з 0) | +| `${CLAUDE_SESSION_ID}` | ID поточної сесії | +| `${CLAUDE_SKILL_DIR}` | Каталог, що містить файл SKILL.md навички | +| `` !`command` `` | Динамічне впровадження контексту — виконує команду оболонки та вставляє результат | + +**Приклад:** + +```yaml +--- +name: fix-issue +description: Fix a GitHub issue +--- + +Fix GitHub issue $ARGUMENTS following our coding standards. +1. Read the issue description +2. Implement the fix +3. Write tests +4. Create a commit +``` + +Виконання `/fix-issue 123` замінює `$ARGUMENTS` на `123`. + +## Впровадження динамічного контексту + +Синтаксис `` !`command` `` виконує команди оболонки до того, як вміст навички відправляється до Claude: + +```yaml +--- +name: pr-summary +description: Summarize changes in a pull request +context: fork +agent: Explore +--- + +## Pull request context +- PR diff: !`gh pr diff` +- PR comments: !`gh pr view --comments` +- Changed files: !`gh pr diff --name-only` + +## Your task +Summarize this pull request... +``` + +Команди виконуються негайно; Claude бачить лише кінцевий результат. За замовчуванням команди виконуються в `bash`. Встановіть `shell: powershell` у фронтматері для використання PowerShell. + +## Запуск навичок у субагентах + +Додайте `context: fork` для запуску навички в ізольованому контексті субагента. Вміст навички стає завданням для виділеного субагента з власним контекстним вікном, зберігаючи основну розмову чистою. + +Поле `agent` вказує тип агента: + +| Тип агента | Найкраще для | +|---|---| +| `Explore` | Дослідження лише для читання, аналіз кодової бази | +| `Plan` | Створення планів реалізації | +| `general-purpose` | Широкі завдання, що потребують усіх інструментів | +| Custom agents | Спеціалізовані агенти, визначені у вашій конфігурації | + +**Приклад фронтматера:** + +```yaml +--- +context: fork +agent: Explore +--- +``` + +**Повний приклад навички:** + +```yaml +--- +name: deep-research +description: Research a topic thoroughly +context: fork +agent: Explore +--- + +Research $ARGUMENTS thoroughly: +1. Find relevant files using Glob and Grep +2. Read and analyze the code +3. Summarize findings with specific file references +``` + +## Практичні приклади + +### Приклад 1: Навичка код-рев'ю + +**Структура каталогу:** + +``` +~/.claude/skills/code-review/ +├── SKILL.md +├── templates/ +│ ├── review-checklist.md +│ └── finding-template.md +└── scripts/ + ├── analyze-metrics.py + └── compare-complexity.py +``` + +**Файл:** `~/.claude/skills/code-review/SKILL.md` + +```yaml +--- +name: code-review-specialist +description: Comprehensive code review with security, performance, and quality analysis. Use when users ask to review code, analyze code quality, evaluate pull requests, or mention code review, security analysis, or performance optimization. +--- + +# Code Review Skill + +This skill provides comprehensive code review capabilities focusing on: + +1. **Security Analysis** + - Authentication/authorization issues + - Data exposure risks + - Injection vulnerabilities + - Cryptographic weaknesses + +2. **Performance Review** + - Algorithm efficiency (Big O analysis) + - Memory optimization + - Database query optimization + - Caching opportunities + +3. **Code Quality** + - SOLID principles + - Design patterns + - Naming conventions + - Test coverage + +4. **Maintainability** + - Code readability + - Function size (should be < 50 lines) + - Cyclomatic complexity + - Type safety + +## Review Template + +For each piece of code reviewed, provide: + +### Summary +- Overall quality assessment (1-5) +- Key findings count +- Recommended priority areas + +### Critical Issues (if any) +- **Issue**: Clear description +- **Location**: File and line number +- **Impact**: Why this matters +- **Severity**: Critical/High/Medium +- **Fix**: Code example + +For detailed checklists, see [templates/review-checklist.md](templates/review-checklist.md). +``` + +### Приклад 2: Навичка візуалізації кодової бази + +Навичка, що генерує інтерактивні HTML-візуалізації: + +**Структура каталогу:** + +``` +~/.claude/skills/codebase-visualizer/ +├── SKILL.md +└── scripts/ + └── visualize.py +``` + +**Файл:** `~/.claude/skills/codebase-visualizer/SKILL.md` + +````yaml +--- +name: codebase-visualizer +description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files. +allowed-tools: Bash(python *) +--- + +# Codebase Visualizer + +Generate an interactive HTML tree view showing your project's file structure. + +## Usage + +Run the visualization script from your project root: + +```bash +python ~/.claude/skills/codebase-visualizer/scripts/visualize.py . +``` + +This creates `codebase-map.html` and opens it in your default browser. + +## What the visualization shows + +- **Collapsible directories**: Click folders to expand/collapse +- **File sizes**: Displayed next to each file +- **Colors**: Different colors for different file types +- **Directory totals**: Shows aggregate size of each folder +```` + +Python-скрипт у пакеті виконує важку роботу, а Claude займається оркестрацією. + +### Приклад 3: Навичка деплою (тільки виклик користувачем) + +```yaml +--- +name: deploy +description: Deploy the application to production +disable-model-invocation: true +allowed-tools: Bash(npm *), Bash(git *) +--- + +Deploy $ARGUMENTS to production: + +1. Run the test suite: `npm test` +2. Build the application: `npm run build` +3. Push to the deployment target +4. Verify the deployment succeeded +5. Report deployment status +``` + +### Приклад 4: Навичка голосу бренду (фонові знання) + +```yaml +--- +name: brand-voice +description: Ensure all communication matches brand voice and tone guidelines. Use when creating marketing copy, customer communications, or public-facing content. +user-invocable: false +--- + +## Tone of Voice +- **Friendly but professional** - approachable without being casual +- **Clear and concise** - avoid jargon +- **Confident** - we know what we're doing +- **Empathetic** - understand user needs + +## Writing Guidelines +- Use "you" when addressing readers +- Use active voice +- Keep sentences under 20 words +- Start with value proposition + +For templates, see [templates/](templates/). +``` + +### Приклад 5: Навичка генератора CLAUDE.md + +```yaml +--- +name: claude-md +description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding. Use when users mention CLAUDE.md, project documentation, or AI onboarding. +--- + +## Core Principles + +**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation. + +### The Golden Rules + +1. **Less is More**: Keep under 300 lines (ideally under 100) +2. **Universal Applicability**: Only include information relevant to EVERY session +3. **Don't Use Claude as a Linter**: Use deterministic tools instead +4. **Never Auto-Generate**: Craft it manually with careful consideration + +## Essential Sections + +- **Project Name**: Brief one-line description +- **Tech Stack**: Primary language, frameworks, database +- **Development Commands**: Install, test, build commands +- **Critical Conventions**: Only non-obvious, high-impact conventions +- **Known Issues / Gotchas**: Things that trip up developers +``` + +### Приклад 6: Навичка рефакторингу зі скриптами + +**Структура каталогу:** + +``` +refactor/ +├── SKILL.md +├── references/ +│ ├── code-smells.md +│ └── refactoring-catalog.md +├── templates/ +│ └── refactoring-plan.md +└── scripts/ + ├── analyze-complexity.py + └── detect-smells.py +``` + +**Файл:** `refactor/SKILL.md` + +```yaml +--- +name: code-refactor +description: Systematic code refactoring based on Martin Fowler's methodology. Use when users ask to refactor code, improve code structure, reduce technical debt, or eliminate code smells. +--- + +# Code Refactoring Skill + +A phased approach emphasizing safe, incremental changes backed by tests. + +## Workflow + +Phase 1: Research & Analysis → Phase 2: Test Coverage Assessment → +Phase 3: Code Smell Identification → Phase 4: Refactoring Plan Creation → +Phase 5: Incremental Implementation → Phase 6: Review & Iteration + +## Core Principles + +1. **Behavior Preservation**: External behavior must remain unchanged +2. **Small Steps**: Make tiny, testable changes +3. **Test-Driven**: Tests are the safety net +4. **Continuous**: Refactoring is ongoing, not a one-time event + +For code smell catalog, see [references/code-smells.md](references/code-smells.md). +For refactoring techniques, see [references/refactoring-catalog.md](references/refactoring-catalog.md). +``` + +## Допоміжні файли + +Навички можуть включати кілька файлів у каталозі крім `SKILL.md`. Ці допоміжні файли (шаблони, приклади, скрипти, довідкові документи) дозволяють тримати головний файл навички сфокусованим, надаючи Claude додаткові ресурси, які він завантажує за потребою. + +``` +my-skill/ +├── SKILL.md # Головні інструкції (обов'язковий, до 500 рядків) +├── templates/ # Шаблони для заповнення Claude +│ └── output-format.md +├── examples/ # Приклади результатів з очікуваним форматом +│ └── sample-output.md +├── references/ # Доменні знання та специфікації +│ └── api-spec.md +└── scripts/ # Скрипти, які Claude може виконати + └── validate.sh +``` + +Рекомендації щодо допоміжних файлів: + +- Тримайте `SKILL.md` до **500 рядків**. Переносіть детальний довідковий матеріал, великі приклади та специфікації в окремі файли. +- Посилайтесь на додаткові файли з `SKILL.md` за допомогою **відносних шляхів** (наприклад, `[API reference](references/api-spec.md)`). +- Допоміжні файли завантажуються на рівні 3 (за потребою), тому вони не споживають контекст, поки Claude фактично їх не прочитає. + +## Управління навичками + +### Перегляд доступних навичок + +Запитайте Claude безпосередньо: +``` +What Skills are available? +``` + +Або перевірте файлову систему: +```bash +# Список персональних навичок +ls ~/.claude/skills/ + +# Список навичок проєкту +ls .claude/skills/ +``` + +### Тестування навички + +Два способи тестування: + +**Дозвольте Claude викликати автоматично**, запитавши щось, що відповідає опису: +``` +Can you help me review this code for security issues? +``` + +**Або викличте безпосередньо** за назвою навички: +``` +/code-review src/auth/login.ts +``` + +### Оновлення навички + +Редагуйте файл `SKILL.md` безпосередньо. Зміни набувають чинності при наступному запуску Claude Code. + +```bash +# Персональна навичка +code ~/.claude/skills/my-skill/SKILL.md + +# Навичка проєкту +code .claude/skills/my-skill/SKILL.md +``` + +### Обмеження доступу Claude до навичок + +Три способи контролювати, які навички Claude може викликати: + +**Вимкнути всі навички** в `/permissions`: +``` +# Додати до правил заборони: +Skill +``` + +**Дозволити або заборонити конкретні навички**: +``` +# Дозволити лише конкретні навички +Skill(commit) +Skill(review-pr *) + +# Заборонити конкретні навички +Skill(deploy *) +``` + +**Приховати окремі навички**, додавши `disable-model-invocation: true` до їхнього фронтматера. + +## Найкращі практики + +### 1. Робіть описи конкретними + +- **Погано (розпливчасто)**: "Helps with documents" +- **Добре (конкретно)**: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction." + +### 2. Тримайте навички сфокусованими + +- Одна навичка = одна можливість +- ✅ "PDF form filling" +- ❌ "Document processing" (занадто широко) + +### 3. Включайте тригерні терміни + +Додавайте ключові слова в описи, що відповідають запитам користувачів: +```yaml +description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files. +``` + +### 4. Тримайте SKILL.md до 500 рядків + +Переносіть детальний довідковий матеріал в окремі файли, які Claude завантажує за потребою. + +### 5. Посилайтесь на допоміжні файли + +```markdown +## Additional resources + +- For complete API details, see [reference.md](reference.md) +- For usage examples, see [examples.md](examples.md) +``` + +### Рекомендовано + +- Використовуйте зрозумілі, описові назви +- Включайте вичерпні інструкції +- Додавайте конкретні приклади +- Пакуйте пов'язані скрипти та шаблони +- Тестуйте з реальними сценаріями +- Документуйте залежності + +### Не рекомендовано + +- Не створюйте навички для одноразових завдань +- Не дублюйте наявну функціональність +- Не робіть навички занадто широкими +- Не пропускайте поле description +- Не встановлюйте навички з ненадійних джерел без аудиту + +## Усунення несправностей + +### Короткий довідник + +| Проблема | Рішення | +|----------|---------| +| Claude не використовує навичку | Зробіть опис конкретнішим з тригерними термінами | +| Файл навички не знайдено | Перевірте шлях: `~/.claude/skills/name/SKILL.md` | +| Помилки YAML | Перевірте маркери `---`, відступи, відсутність табів | +| Конфлікт навичок | Використовуйте різні тригерні терміни в описах | +| Скрипти не запускаються | Перевірте дозволи: `chmod +x scripts/*.py` | +| Claude не бачить всі навички | Занадто багато навичок; перевірте `/context` на попередження | + +### Навичка не спрацьовує + +Якщо Claude не використовує навичку, коли очікується: + +1. Перевірте, що опис містить ключові слова, які користувачі природно вживають +2. Переконайтесь, що навичка відображається при запиті "What skills are available?" +3. Спробуйте переформулювати запит відповідно до опису +4. Викличте безпосередньо через `/skill-name` для тестування + +### Навичка спрацьовує занадто часто + +Якщо Claude використовує навичку, коли ви цього не хочете: + +1. Зробіть опис конкретнішим +2. Додайте `disable-model-invocation: true` для виклику лише вручну + +### Claude не бачить усі навички + +Описи навичок завантажуються з лімітом **1% контекстного вікна** (резерв: **8 000 символів**). Кожен запис обмежений 250 символами незалежно від бюджету. Запустіть `/context`, щоб перевірити попередження про виключені навички. Перевизначте бюджет змінною оточення `SLASH_COMMAND_TOOL_CHAR_BUDGET`. + +## Питання безпеки + +**Використовуйте навички лише з надійних джерел.** Навички надають Claude можливості через інструкції та код — шкідлива навичка може направити Claude на виклик інструментів або виконання коду небезпечними способами. + +**Ключові питання безпеки:** + +- **Ретельний аудит**: перевіряйте всі файли в каталозі навички +- **Зовнішні джерела ризиковані**: навички, що завантажують із зовнішніх URL, можуть бути скомпрометовані +- **Зловживання інструментами**: шкідливі навички можуть викликати інструменти небезпечними способами +- **Ставтесь як до встановлення ПЗ**: використовуйте навички лише з надійних джерел + +## Навички vs інші функції + +| Функція | Виклик | Найкраще для | +|---------|--------|-------------| +| **Навички** | Авто або `/name` | Повторно використовувана експертиза, воркфлови | +| **Слеш-команди** | Користувач через `/name` | Швидкі ярлики (об'єднано з навичками) | +| **Субагенти** | Автоделегування | Ізольоване виконання завдань | +| **Пам'ять (CLAUDE.md)** | Завжди завантажена | Постійний контекст проєкту | +| **MCP** | У реальному часі | Доступ до зовнішніх даних/сервісів | +| **Хуки** | За подіями | Автоматизовані побічні ефекти | + +## Вбудовані навички + +Claude Code постачається з кількома вбудованими навичками, доступними без встановлення: + +| Навичка | Опис | +|---------|------| +| `/simplify` | Перевірка змінених файлів на повторне використання, якість та ефективність; запускає 3 паралельних агенти рев'ю | +| `/batch ` | Оркестрація масштабних паралельних змін по кодовій базі з використанням git worktrees | +| `/debug [description]` | Усунення несправностей поточної сесії через читання журналу налагодження | +| `/loop [interval] ` | Циклічне виконання промпта з інтервалом (наприклад, `/loop 5m check the deploy`) | +| `/claude-api` | Завантаження довідника Claude API/SDK; автоактивується при імпортах `anthropic`/`@anthropic-ai/sdk` | + +Ці навички доступні одразу і не потребують встановлення чи конфігурації. Вони використовують той самий формат SKILL.md, що й власні навички. + +## Поширення навичок + +### Навички проєкту (командне поширення) + +1. Створіть навичку в `.claude/skills/` +2. Закомітьте в git +3. Члени команди витягують зміни — навички доступні одразу + +### Персональні навички + +```bash +# Копіювання в персональний каталог +cp -r my-skill ~/.claude/skills/ + +# Зробити скрипти виконуваними +chmod +x ~/.claude/skills/my-skill/scripts/*.py +``` + +### Дистрибуція через плагіни + +Пакуйте навички в каталог `skills/` плагіна для ширшої дистрибуції. + +## Далі: колекція навичок та менеджер навичок + +Коли ви починаєте серйозно створювати навички, дві речі стають необхідними: бібліотека перевірених навичок та інструмент для їх управління. + +**[luongnv89/skills](https://github.com/luongnv89/skills)** — колекція навичок, які автор використовує щодня майже у всіх проєктах. Серед цікавих: `logo-designer` (генерація логотипів проєктів на льоту) та `ollama-optimizer` (налаштування продуктивності локальних LLM під ваше обладнання). Хороша відправна точка для готових до використання навичок. + +**[luongnv89/asm](https://github.com/luongnv89/asm)** — Agent Skill Manager. Керує розробкою навичок, виявленням дублікатів та тестуванням. Команда `asm link` дозволяє тестувати навичку в будь-якому проєкті без копіювання файлів — це необхідно, коли навичок більше кількох. + +## Додаткові ресурси + +- [Офіційна документація навичок](https://code.claude.com/docs/en/skills) +- [Блог про архітектуру Agent Skills](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills) +- [Репозиторій навичок](https://github.com/luongnv89/skills) — колекція готових навичок +- [Посібник слеш-команд](../01-slash-commands/) — ярлики, ініційовані користувачем +- [Посібник субагентів](../04-subagents/) — делеговані AI-агенти +- [Посібник з пам'яті](../02-memory/) — постійний контекст +- [MCP (Model Context Protocol)](../05-mcp/) — зовнішні дані в реальному часі +- [Посібник хуків](../06-hooks/) — автоматизація за подіями + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/03-skills/blog-draft/SKILL.md b/uk/03-skills/blog-draft/SKILL.md new file mode 100644 index 0000000..71c5a6b --- /dev/null +++ b/uk/03-skills/blog-draft/SKILL.md @@ -0,0 +1,274 @@ +--- +name: blog-draft +description: Створення чернетки блог-посту з ідей та ресурсів. Використовуйте, коли користувачі хочуть написати блог-пост, створити контент з дослідження або підготувати статтю. Проводить через дослідження, мозковий штурм, складання плану та ітеративне написання з контролем версій. +--- + +## Введення користувача + +```text +$ARGUMENTS +``` + +Ви **ПОВИННІ** врахувати введення користувача перед продовженням. Користувач має надати: +- **Ідея/Тема**: Основна концепція або тематика блог-посту +- **Ресурси**: URL, файли або посилання на дослідження (необовʼязково, але рекомендовано) +- **Цільова аудиторія**: Для кого блог-пост (необовʼязково) +- **Тон/Стиль**: Формальний, невимушений, технічний тощо (необовʼязково) + +**ВАЖЛИВО**: Якщо користувач запитує оновлення **існуючого блог-посту**, пропустіть кроки 0-8 і починайте безпосередньо з **Кроку 9**. Спочатку прочитайте існуючий файл(и) чернетки, потім продовжуйте з процесом ітерації. + +## Потік виконання + +Виконуйте ці кроки послідовно. **Не пропускайте кроки та не продовжуйте без затвердження користувача, де це зазначено.** + +### Крок 0: Створення папки проєкту + +1. Згенерувати назву папки у форматі: `YYYY-MM-DD-short-topic-name` + - Використати сьогоднішню дату + - Створити короткий, URL-дружній slug з теми (малі літери, дефіси, макс. 5 слів) + +2. Створити структуру папок: + ``` + blog-posts/ + └── YYYY-MM-DD-short-topic-name/ + └── resources/ + ``` + +3. Підтвердити створення папки з користувачем перед продовженням. + +### Крок 1: Дослідження та збір ресурсів + +1. Створити підпапку `resources/` у каталозі блог-посту + +2. Для кожного наданого ресурсу: + - **URL-адреси**: Отримати та зберегти ключову інформацію до `resources/` як markdown-файли + - **Файли**: Прочитати та підсумувати в `resources/` + - **Теми**: Використати веб-пошук для збору актуальної інформації + +3. Для кожного ресурсу створити файл резюме в `resources/`: + - `resources/source-1-[short-name].md` + - `resources/source-2-[short-name].md` + - тощо + +4. Кожне резюме має включати: + ```markdown + # Джерело: [Назва/URL] + + ## Ключові тези + - Теза 1 + - Теза 2 + + ## Релевантні цитати/дані + - Цитата або статистика 1 + - Цитата або статистика 2 + + ## Як це стосується теми + Короткий опис релевантності + ``` + +5. Представити резюме дослідження користувачу. + +### Крок 2: Мозковий штурм та уточнення + +1. На основі ідеї та досліджених ресурсів представити: + - **Основні теми**, виявлені з дослідження + - **Потенційні ракурси** для блог-посту + - **Ключові тези**, які слід розкрити + - **Прогалини** в інформації, що потребують уточнення + +2. Поставити уточнюючі запитання: + - Який головний висновок ви хочете донести до читачів? + - Чи є конкретні тези з дослідження, які хочете виділити? + - Яка цільова довжина? (коротка: 500-800 слів, середня: 1000-1500, довга: 2000+) + - Щось хочете виключити? + +3. **Чекати відповідей користувача перед продовженням.** + +### Крок 3: Запропонувати план + +1. Створити структурований план, що включає: + + ```markdown + # План блог-посту: [Назва] + + ## Метаінформація + - **Цільова аудиторія**: [хто] + - **Тон**: [стиль] + - **Цільова довжина**: [кількість слів] + - **Головний висновок**: [ключове повідомлення] + + ## Запропонована структура + + ### Зачіпка/Вступ + - Ідея вступної зачіпки + - Встановлення контексту + - Теза + + ### Розділ 1: [Назва] + - Ключова теза A + - Ключова теза B + - Підтверджуючі докази з [джерела] + + ### Розділ 2: [Назва] + - Ключова теза A + - Ключова теза B + + [Продовжити для всіх розділів...] + + ### Висновок + - Резюме ключових тез + - Заклик до дії або завершальна думка + + ## Джерела для цитування + - Джерело 1 + - Джерело 2 + ``` + +2. Представити план користувачу та **запитати затвердження або модифікації**. + +### Крок 4: Зберегти затверджений план + +1. Після затвердження плану користувачем зберегти його як `OUTLINE.md` у папці блог-посту. + +2. Підтвердити збереження плану. + +### Крок 5: Закомітити план (якщо в git-репо) + +1. Перевірити, чи поточний каталог є git-репозиторієм. + +2. Якщо так: + - Додати нові файли до індексу: папку блог-посту, ресурси та OUTLINE.md + - Створити коміт з повідомленням: `docs: Add outline for blog post - [topic-name]` + - Відправити на віддалений сервер + +3. Якщо не git-репо, пропустити цей крок та повідомити користувача. + +### Крок 6: Написати чернетку + +1. На основі затвердженого плану написати повну чернетку блог-посту. + +2. Точно дотримуватися структури з OUTLINE.md. + +3. Включити: + - Захопливий вступ із зачіпкою + - Чіткі заголовки розділів + - Підтверджуючі докази та приклади з дослідження + - Плавні переходи між розділами + - Сильний висновок з головною тезою + - **Цитування**: Усі порівняння, статистика, дані та фактичні твердження ПОВИННІ цитувати оригінальне джерело + +4. Зберегти чернетку як `draft-v0.1.md` у папці блог-посту. + +5. Формат: + ```markdown + # [Назва блог-посту] + + *[Необовʼязково: підзаголовок або слоган]* + + [Повний вміст з інлайн-цитатами...] + + --- + + ## Список джерел + - [1] Назва джерела 1 - URL або цитата + - [2] Назва джерела 2 - URL або цитата + - [3] Назва джерела 3 - URL або цитата + ``` + +6. **Вимоги до цитування**: + - Кожна точка даних, статистика або порівняння ПОВИННІ мати інлайн-цитату + - Використовуйте нумеровані посилання [1], [2] тощо, або іменовані цитати [Назва джерела] + - Звʼязуйте цитати з розділом Список джерел наприкінці + - Приклад: «Дослідження показують, що 65% розробників віддають перевагу TypeScript [1]» + - Приклад: «React перевершує Vue за швидкістю рендерингу на 20% [React Benchmarks 2024]» + +### Крок 7: Закомітити чернетку (якщо в git-репо) + +1. Перевірити, чи в git-репозиторії. + +2. Якщо так: + - Додати файл чернетки до індексу + - Створити коміт з повідомленням: `docs: Add draft v0.1 for blog post - [topic-name]` + - Відправити на віддалений сервер + +3. Якщо не git-репо, пропустити та повідомити користувача. + +### Крок 8: Представити чернетку для перегляду + +1. Представити вміст чернетки користувачу. + +2. Запитати зворотний звʼязок: + - Загальне враження? + - Розділи, що потребують розширення або скорочення? + - Потрібні корекції тону? + - Відсутня інформація? + - Конкретні правки або переписування? + +3. **Чекати відповіді користувача.** + +### Крок 9: Ітерація або фіналізація + +**Якщо користувач запитує зміни:** +1. Зафіксувати всі запитані модифікації +2. Повернутися до Кроку 6 з такими змінами: + - Збільшити номер версії (v0.2, v0.3 тощо) + - Врахувати всі зауваження + - Зберегти як `draft-v[X.Y].md` + - Повторити Кроки 7-8 + +**Якщо користувач затверджує:** +1. Підтвердити фінальну версію чернетки +2. За бажанням перейменувати на `final.md` +3. Підсумувати процес створення блог-посту: + - Загальна кількість створених версій + - Ключові зміни між версіями + - Фінальна кількість слів + - Створені файли + +## Відстеження версій + +Усі чернетки зберігаються з інкрементальним версіонуванням: +- `draft-v0.1.md` — початкова чернетка +- `draft-v0.2.md` — після першого раунду зауважень +- `draft-v0.3.md` — після другого раунду зауважень +- тощо + +Це дозволяє відстежувати еволюцію блог-посту та повертатися до попередніх версій за потреби. + +## Структура вихідних файлів + +``` +blog-posts/ +└── YYYY-MM-DD-topic-name/ + ├── resources/ + │ ├── source-1-name.md + │ ├── source-2-name.md + │ └── ... + ├── OUTLINE.md + ├── draft-v0.1.md + ├── draft-v0.2.md (якщо ітерації) + └── draft-v0.3.md (якщо більше ітерацій) +``` + +## Поради щодо якості + +- **Зачіпка**: Починайте з питання, дивовижного факту або знайомого сценарію +- **Потік**: Кожен абзац має зʼєднуватися з наступним +- **Докази**: Підтверджуйте твердження даними з дослідження +- **Цитування**: ЗАВЖДИ цитуйте джерела для: + - Усіх статистик та даних (напр., «За даними [Джерело], 75%...») + - Порівнянь між продуктами, сервісами або підходами (напр., «X працює у 2 рази швидше за Y [Джерело]») + - Фактичних тверджень про ринкові тенденції, результати досліджень або бенчмарки + - Використовуйте інлайн-цитати у форматі: [Назва джерела] або [Автор, Рік] +- **Голос**: Підтримуйте послідовний тон протягом усього тексту +- **Довжина**: Дотримуйтесь цільової кількості слів +- **Читабельність**: Використовуйте короткі абзаци, маркери де доречно +- **CTA**: Завершуйте чітким закликом до дії або питанням, що провокує думки + +## Примітки + +- Завжди чекайте затвердження користувача у зазначених контрольних точках +- Зберігайте всі версії чернеток для історії +- Використовуйте веб-пошук для актуальної інформації, коли надані URL +- Якщо ресурсів недостатньо, попросіть користувача надати більше або запропонуйте додаткове дослідження +- Адаптуйте тон відповідно до цільової аудиторії (технічна, загальна, бізнес тощо) diff --git a/uk/03-skills/blog-draft/templates/draft-template.md b/uk/03-skills/blog-draft/templates/draft-template.md new file mode 100644 index 0000000..c03a5f9 --- /dev/null +++ b/uk/03-skills/blog-draft/templates/draft-template.md @@ -0,0 +1,67 @@ +# [Назва блог-посту] + +*[Підзаголовок або слоган — необовʼязково]* + +**[Імʼя автора]** | [Дата] + +--- + +[Вступна зачіпка — одразу захопити увагу] + +[Контекст та передісторія — чому це важливо] + +[Теза — що розкриє цей пост] + +--- + +## [Назва розділу 1] + +[Вміст розділу з чіткою, захопливою прозою] + +[Включити докази, приклади або дані для підтримки тез] + +> «Релевантна цитата з дослідження» — Джерело + +[Перехід до наступного розділу] + +--- + +## [Назва розділу 2] + +[Продовження основного контенту] + +**Ключовий висновок:** [Виділити важливі тези жирним або у виносках] + +[Ще підтверджуючий контент] + +--- + +## [Назва розділу 3] + +[Додаткові розділи за потреби] + +### Підрозділ (за потреби) + +[Вміст підрозділу] + +--- + +## Висновок + +[Підсумувати розкриті ключові тези] + +[Підкріпити головний висновок] + +[Заклик до дії або завершальне твердження, що провокує думки] + +--- + +## Список джерел + +1. [Назва джерела](#) +2. [Назва джерела](#) +3. [Назва джерела](#) + +--- + +*[Необовʼязково: біографія автора або пропозиція повʼязаних постів]* diff --git a/uk/03-skills/blog-draft/templates/outline-template.md b/uk/03-skills/blog-draft/templates/outline-template.md new file mode 100644 index 0000000..5660b01 --- /dev/null +++ b/uk/03-skills/blog-draft/templates/outline-template.md @@ -0,0 +1,97 @@ +# План блог-посту: [Назва] + +## Метаінформація + +| Атрибут | Значення | +|---------|----------| +| **Цільова аудиторія** | [Для кого це?] | +| **Тон** | [Формальний/Невимушений/Технічний/Розмовний] | +| **Цільова довжина** | [Діапазон кількості слів] | +| **Головний висновок** | [Одне речення: що мають запамʼятати читачі?] | +| **Ключові слова** | [SEO-ключові слова, якщо релевантно] | + +--- + +## Запропонована структура + +### 1. Вступ / Зачіпка + +**Варіанти вступної зачіпки:** +- [ ] Питання, що резонує з читачем +- [ ] Вражаюча статистика або факт +- [ ] Коротка історія або сценарій +- [ ] Сміливе твердження + +**Встановлення контексту:** +- Необхідна передісторія +- Чому ця тема важлива зараз + +**Теза:** +- Чітке твердження про те, що розкриє пост + +--- + +### 2. [Назва розділу] + +**Ключові тези:** +- Теза A: [опис] +- Теза B: [опис] + +**Підтверджуючі докази:** +- З [джерела]: [релевантні дані/цитата] + +**Перехід до наступного розділу:** +- [Як це повʼязується з наступним] + +--- + +### 3. [Назва розділу] + +**Ключові тези:** +- Теза A: [опис] +- Теза B: [опис] + +**Підтверджуючі докази:** +- З [джерела]: [релевантні дані/цитата] + +**Перехід до наступного розділу:** +- [Як це повʼязується з наступним] + +--- + +### 4. [Назва розділу] (додайте більше розділів за потреби) + +**Ключові тези:** +- Теза A: [опис] +- Теза B: [опис] + +**Підтверджуючі докази:** +- З [джерела]: [релевантні дані/цитата] + +--- + +### 5. Висновок + +**Резюме ключових тез:** +- Повторення тези 1 +- Повторення тези 2 +- Повторення тези 3 + +**Завершальна думка / Заклик до дії:** +- [Що мають зробити або обміркувати читачі далі?] + +--- + +## Джерела для цитування + +1. [Назва джерела](#) — використано для: [яка інформація] +2. [Назва джерела](#) — використано для: [яка інформація] +3. [Назва джерела](#) — використано для: [яка інформація] + +--- + +## Примітки для написання + +- [Будь-які конкретні вимоги або обмеження] +- [Що наголосити] +- [Чого уникати] diff --git a/uk/03-skills/brand-voice/SKILL.md b/uk/03-skills/brand-voice/SKILL.md new file mode 100644 index 0000000..b3e2cde --- /dev/null +++ b/uk/03-skills/brand-voice/SKILL.md @@ -0,0 +1,72 @@ +--- +name: brand-voice-consistency +description: Забезпечення відповідності всіх комунікацій голосу та тону бренду. Використовуйте при створенні маркетингових текстів, клієнтських комунікацій, публічного контенту, або коли користувачі згадують голос бренду, тон чи стиль написання. +--- + +# Навичка голосу бренду + +## Огляд +Ця навичка забезпечує послідовність голосу бренду, тону та повідомлень у всіх комунікаціях. + +## Ідентичність бренду + +### Місія +Допомогти командам автоматизувати робочі процеси розробки за допомогою AI + +### Цінності +- **Простота**: Робити складне простим +- **Надійність**: Непохитне виконання +- **Розширення можливостей**: Дати простір людській креативності + +### Тон голосу +- **Дружній, але професійний** — доступний, але не панібратський +- **Зрозумілий і лаконічний** — уникати жаргону, пояснювати технічні концепції просто +- **Впевнений** — ми знаємо, що робимо +- **Емпатичний** — розуміємо потреби та болі користувачів + +## Рекомендації щодо написання + +### Рекомендовано ✅ +- Використовуйте «ви» при зверненні до читачів +- Використовуйте активний стан: «Claude генерує звіти», а не «Звіти генеруються Claude» +- Починайте з ціннісної пропозиції +- Використовуйте конкретні приклади +- Тримайте речення до 20 слів +- Використовуйте списки для ясності +- Включайте заклики до дії + +### Не рекомендовано ❌ +- Не використовуйте корпоративний жаргон +- Не будьте поблажливими та не надмірно спрощуйте +- Не використовуйте «ми вважаємо» або «ми думаємо» +- Не використовуйте ВСІ ВЕЛИКІ ЛІТЕРИ, крім виділення +- Не створюйте стіни тексту +- Не припускайте наявність технічних знань + +## Словник + +### ✅ Бажані терміни +- Claude (не «AI Claude») +- Генерація коду (не «автокодування») +- Агент (не «бот») +- Оптимізувати (не «революціонізувати») +- Інтегрувати (не «синергізувати») + +### ❌ Уникати +- «Передовий» (заїжджено) +- «Проривний» (розмито) +- «Левериджити» (корпоративний жаргон) +- «Утилізувати» (використовуйте «використовувати») +- «Зміна парадигми» (незрозуміло) + +## Приклади + +### ✅ Вдалий приклад +«Claude автоматизує ваш процес код-рев'ю. Замість ручної перевірки кожного PR, Claude перевіряє безпеку, продуктивність та якість — заощаджуючи вашій команді години щотижня.» + +Чому працює: Зрозуміла цінність, конкретні переваги, орієнтація на дію + +### ❌ Невдалий приклад +«Claude левериджить передовий AI для надання комплексних рішень розробки програмного забезпечення.» + +Чому не працює: Розмито, корпоративний жаргон, немає конкретної цінності diff --git a/uk/03-skills/claude-md/SKILL.md b/uk/03-skills/claude-md/SKILL.md new file mode 100644 index 0000000..6e4b8b8 --- /dev/null +++ b/uk/03-skills/claude-md/SKILL.md @@ -0,0 +1,212 @@ +--- +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 для конкретних каталогів мають бути ще більш зосередженими diff --git a/uk/03-skills/code-review/SKILL.md b/uk/03-skills/code-review/SKILL.md new file mode 100644 index 0000000..d11b215 --- /dev/null +++ b/uk/03-skills/code-review/SKILL.md @@ -0,0 +1,70 @@ +--- +name: code-review-specialist +description: Комплексне код-рев'ю з аналізом безпеки, продуктивності та якості. Використовуйте, коли користувачі просять переглянути код, проаналізувати якість коду, оцінити pull request, або згадують код-рев'ю, аналіз безпеки чи оптимізацію продуктивності. +--- + +# Навичка код-рев'ю + +Ця навичка забезпечує комплексні можливості код-рев'ю з фокусом на: + +1. **Аналіз безпеки** + - Проблеми автентифікації/авторизації + - Ризики розкриття даних + - Вразливості інʼєкцій + - Криптографічні слабкості + - Логування чутливих даних + +2. **Аналіз продуктивності** + - Ефективність алгоритмів (аналіз Big O) + - Оптимізація памʼяті + - Оптимізація запитів до БД + - Можливості кешування + - Проблеми конкурентності + +3. **Якість коду** + - Принципи SOLID + - Патерни проєктування + - Конвенції іменування + - Документація + - Покриття тестами + +4. **Супровідність** + - Читабельність коду + - Розмір функцій (має бути < 50 рядків) + - Цикломатична складність + - Управління залежностями + - Безпека типів + +## Шаблон рев'ю + +Для кожного фрагмента перевіреного коду надати: + +### Резюме +- Загальна оцінка якості (1-5) +- Кількість виявлених проблем +- Рекомендовані пріоритетні зони + +### Критичні проблеми (якщо є) +- **Проблема**: Чіткий опис +- **Розташування**: Файл і номер рядка +- **Вплив**: Чому це важливо +- **Серйозність**: Критична/Висока/Середня +- **Виправлення**: Приклад коду + +### Знахідки за категоріями + +#### Безпека (якщо знайдено проблеми) +Перелік вразливостей безпеки з прикладами + +#### Продуктивність (якщо знайдено проблеми) +Перелік проблем продуктивності з аналізом складності + +#### Якість (якщо знайдено проблеми) +Перелік проблем якості коду з пропозиціями рефакторингу + +#### Супровідність (якщо знайдено проблеми) +Перелік проблем супровідності з покращеннями + +## Історія версій + +- v1.0.0 (2024-12-10): Початковий випуск з аналізом безпеки, продуктивності, якості та супровідності diff --git a/uk/03-skills/doc-generator/SKILL.md b/uk/03-skills/doc-generator/SKILL.md new file mode 100644 index 0000000..00c7103 --- /dev/null +++ b/uk/03-skills/doc-generator/SKILL.md @@ -0,0 +1,76 @@ +--- +name: api-documentation-generator +description: Генерація вичерпної, точної документації API з вихідного коду. Використовуйте при створенні або оновленні документації API, генерації специфікацій OpenAPI, або коли користувачі згадують документацію API, ендпоінти чи документацію. +--- + +# Навичка генерації документації API + +## Генерує + +- Специфікації OpenAPI/Swagger +- Документацію ендпоінтів API +- Приклади використання SDK +- Посібники з інтеграції +- Довідники кодів помилок +- Посібники з автентифікації + +## Структура документації + +### Для кожного ендпоінту + +```markdown +## GET /api/v1/users/:id + +### Опис +Короткий опис призначення цього ендпоінту + +### Параметри + +| Назва | Тип | Обовʼязковий | Опис | +|-------|-----|-------------|------| +| id | string | Так | ID користувача | + +### Відповідь + +**200 Успіх** +```json +{ + "id": "usr_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2025-01-15T10:30:00Z" +} +``` + +**404 Не знайдено** +```json +{ + "error": "USER_NOT_FOUND", + "message": "Користувач не існує" +} +``` + +### Приклади + +**cURL** +```bash +curl -X GET "https://api.example.com/api/v1/users/usr_123" \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +**JavaScript** +```javascript +const user = await fetch('/api/v1/users/usr_123', { + headers: { 'Authorization': 'Bearer token' } +}).then(r => r.json()); +``` + +**Python** +```python +response = requests.get( + 'https://api.example.com/api/v1/users/usr_123', + headers={'Authorization': 'Bearer token'} +) +user = response.json() +``` +``` diff --git a/uk/03-skills/refactor/SKILL.md b/uk/03-skills/refactor/SKILL.md new file mode 100644 index 0000000..ab50114 --- /dev/null +++ b/uk/03-skills/refactor/SKILL.md @@ -0,0 +1,426 @@ +--- +name: code-refactor +description: Систематичний рефакторинг коду на основі методології Мартіна Фаулера. Використовуйте, коли користувачі просять рефакторити код, покращити структуру коду, зменшити технічний борг, очистити застарілий код, усунути запахи коду (code smells) або покращити супровідність коду. Ця навичка проводить через поетапний підхід з дослідженням, плануванням та безпечною інкрементальною реалізацією. +--- + +# Навичка рефакторингу коду + +Систематичний підхід до рефакторингу коду на основі книги Мартіна Фаулера *Refactoring: Improving the Design of Existing Code* (2-ге видання). Ця навичка наголошує на безпечних, інкрементальних змінах, підкріплених тестами. + +> «Рефакторинг — це процес зміни програмної системи таким чином, що не змінює зовнішню поведінку коду, але покращує його внутрішню структуру.» — Мартін Фаулер + +## Основні принципи + +1. **Збереження поведінки**: Зовнішня поведінка повинна залишатися незмінною +2. **Малі кроки**: Робити крихітні, тестовані зміни +3. **Тест-орієнтованість**: Тести — це страхувальна сітка +4. **Безперервність**: Рефакторинг — постійний процес, а не одноразова подія +5. **Співпраця**: Затвердження користувача потрібне на кожній фазі + +## Огляд робочого процесу + +``` +Фаза 1: Дослідження та аналіз + ↓ +Фаза 2: Оцінка покриття тестами + ↓ +Фаза 3: Виявлення запахів коду + ↓ +Фаза 4: Створення плану рефакторингу + ↓ +Фаза 5: Інкрементальна реалізація + ↓ +Фаза 6: Перегляд та ітерація +``` + +--- + +## Фаза 1: Дослідження та аналіз + +### Цілі +- Зрозуміти структуру та призначення кодової бази +- Визначити обсяг рефакторингу +- Зібрати контекст про бізнес-вимоги + +### Запитання до користувача +Перед початком уточніть: + +1. **Обсяг**: Які файли/модулі/функції потребують рефакторингу? +2. **Цілі**: Які проблеми ви намагаєтесь вирішити? (читабельність, продуктивність, супровідність) +3. **Обмеження**: Чи є зони, які НЕ слід змінювати? +4. **Тиск термінів**: Чи блокує це іншу роботу? +5. **Стан тестів**: Чи існують тести? Чи проходять вони? + +### Дії +- [ ] Прочитати та зрозуміти цільовий код +- [ ] Виявити залежності та інтеграції +- [ ] Задокументувати поточну архітектуру +- [ ] Зафіксувати існуючі маркери технічного боргу (TODOs, FIXMEs) + +### Вивід +Представити знахідки користувачу: +- Резюме структури коду +- Виявлені проблемні зони +- Початкові рекомендації +- **Запросити затвердження для продовження** + +--- + +## Фаза 2: Оцінка покриття тестами + +### Чому тести важливі +> «Рефакторинг без тестів — як їзда без пасків безпеки.» — Мартін Фаулер + +Тести — **ключовий засіб** безпечного рефакторингу. Без них ви ризикуєте внести помилки. + +### Кроки оцінки + +1. **Перевірити наявні тести** + ```bash + # Пошук файлів тестів + find . -name "*test*" -o -name "*spec*" | head -20 + ``` + +2. **Запустити існуючі тести** + ```bash + # JavaScript/TypeScript + npm test + + # Python + pytest -v + + # Java + mvn test + ``` + +3. **Перевірити покриття (якщо доступно)** + ```bash + # JavaScript + npm run test:coverage + + # Python + pytest --cov=. + ``` + +### Точка рішення: Запитати користувача + +**Якщо тести існують та проходять:** +- Перейти до Фази 3 + +**Якщо тести відсутні або неповні:** +Представити варіанти: +1. Спочатку написати тести (рекомендовано) +2. Додавати тести інкрементально під час рефакторингу +3. Продовжити без тестів (ризиковано — потребує підтвердження користувача) + +**Якщо тести не проходять:** +- ЗУПИНИТИСЯ. Виправити тести перед рефакторингом +- Запитати користувача: Чи слід спочатку виправити тести? + +### Рекомендації щодо написання тестів (якщо потрібно) + +Для кожної функції, що рефакториться, забезпечити тести для: +- Успішний шлях (нормальна робота) +- Граничні випадки (порожні введення, null, межі) +- Сценарії помилок (невалідні введення, виключення) + +Використовуйте цикл «red-green-refactor»: +1. Написати тест, що не проходить (red) +2. Зробити так, щоб пройшов (green) +3. Рефакторити + +--- + +## Фаза 3: Виявлення запахів коду + +### Що таке запахи коду? +Симптоми глибших проблем у коді. Це не помилки, а індикатори того, що код можна покращити. + +### Типові запахи коду для перевірки + +Див. [references/code-smells.md](references/code-smells.md) для повного каталогу. + +#### Короткий довідник + +| Запах | Ознаки | Вплив | +|-------|--------|-------| +| **Довгий метод** | Методи > 30-50 рядків | Важко зрозуміти, тестувати, супроводжувати | +| **Дубльований код** | Та сама логіка в кількох місцях | Виправлення помилок потрібне в кількох місцях | +| **Великий клас** | Клас з занадто багатьма відповідальностями | Порушує принцип єдиної відповідальності | +| **Заздрість до функцій** | Метод використовує дані іншого класу більше | Погана інкапсуляція | +| **Одержимість примітивами** | Надмірне використання примітивів замість обʼєктів | Відсутні доменні концепції | +| **Довгий список параметрів** | Методи з 4+ параметрами | Складно викликати правильно | +| **Групи даних** | Ті самі елементи даних зʼявляються разом | Відсутня абстракція | +| **Оператори Switch** | Складні ланцюжки switch/if-else | Важко розширювати | +| **Спекулятивна загальність** | Код «на всякий випадок» | Зайва складність | +| **Мертвий код** | Невикористаний код | Плутанина, тягар супровідності | + +### Кроки аналізу + +1. **Автоматичний аналіз** (якщо скрипти доступні) + ```bash + python scripts/detect-smells.py + ``` + +2. **Ручний перегляд** + - Систематично пройти код + - Зафіксувати кожен запах з розташуванням та серйозністю + - Категоризувати за впливом (Критичний/Високий/Середній/Низький) + +3. **Пріоритезація** + Зосередитися на запахах, які: + - Блокують поточну розробку + - Спричиняють помилки або плутанину + - Впливають на найчастіше змінювані шляхи коду + +### Вивід: Звіт про запахи + +Представити користувачу: +- Список виявлених запахів з розташуванням +- Оцінку серйозності для кожного +- Рекомендований порядок пріоритету +- **Запросити затвердження пріоритетів** + +--- + +## Фаза 4: Створення плану рефакторингу + +### Вибір рефакторингів + +Для кожного запаху обрати відповідний рефакторинг з каталогу. + +Див. [references/refactoring-catalog.md](references/refactoring-catalog.md) для повного списку. + +#### Відповідність запахів рефакторингам + +| Запах коду | Рекомендований рефакторинг | +|------------|---------------------------| +| Long Method | Extract Method, Replace Temp with Query | +| Duplicated Code | Extract Method, Pull Up Method, Form Template Method | +| Large Class | Extract Class, Extract Subclass | +| Feature Envy | Move Method, Move Field | +| Primitive Obsession | Replace Primitive with Object, Replace Type Code with Class | +| Long Parameter List | Introduce Parameter Object, Preserve Whole Object | +| Data Clumps | Extract Class, Introduce Parameter Object | +| Switch Statements | Replace Conditional with Polymorphism | +| Speculative Generality | Collapse Hierarchy, Inline Class, Remove Dead Code | +| Dead Code | Remove Dead Code | + +### Структура плану + +Використовуйте шаблон [templates/refactoring-plan.md](templates/refactoring-plan.md). + +Для кожного рефакторингу: +1. **Ціль**: Який код зміниться +2. **Запах**: Яку проблему вирішує +3. **Рефакторинг**: Яку техніку застосувати +4. **Кроки**: Детальні мікрокроки +5. **Ризики**: Що може піти не так +6. **Відкат**: Як скасувати за потреби + +### Поетапний підхід + +**КРИТИЧНО**: Впроваджуйте рефакторинг поступово, фазами. + +**Фаза A: Швидкі перемоги** (Низький ризик, висока цінність) +- Перейменування змінних для ясності +- Витяг очевидного дубльованого коду +- Видалення мертвого коду + +**Фаза B: Структурні покращення** (Середній ризик) +- Витяг методів з довгих функцій +- Введення обʼєктів параметрів +- Переміщення методів до відповідних класів + +**Фаза C: Архітектурні зміни** (Вищий ризик) +- Заміна умовних конструкцій поліморфізмом +- Витяг класів +- Введення патернів проєктування + +### Точка рішення: Представити план користувачу + +Перед реалізацією: +- Показати повний план рефакторингу +- Пояснити кожну фазу та її ризики +- Отримати явне затвердження для кожної фази +- **Запитати**: «Чи продовжити з Фазою A?» + +--- + +## Фаза 5: Інкрементальна реалізація + +### Золоте правило +> «Зміна → Тест → Зелений? → Коміт → Наступний крок» + +### Ритм реалізації + +Для кожного кроку рефакторингу: + +1. **Попередня перевірка** + - Тести проходять (зелені) + - Код компілюється + +2. **Зробити ОДНУ малу зміну** + - Дотримуватися механіки з каталогу + - Тримати зміни мінімальними + +3. **Верифікація** + - Негайно запустити тести + - Перевірити на помилки компіляції + +4. **Якщо тести проходять (зелені)** + - Закомітити з описовим повідомленням + - Перейти до наступного кроку + +5. **Якщо тести не проходять (червоні)** + - ЗУПИНИТИСЯ негайно + - Скасувати зміну + - Проаналізувати, що пішло не так + - Запитати користувача, якщо незрозуміло + +### Стратегія комітів + +Кожен коміт має бути: +- **Атомарний**: Одна логічна зміна +- **Оборотний**: Легко відкатити +- **Описовий**: Зрозуміле повідомлення коміту + +Приклади повідомлень комітів: +``` +refactor: Extract calculateTotal() from processOrder() +refactor: Rename 'x' to 'customerCount' for clarity +refactor: Remove unused validateOldFormat() method +``` + +### Звіт про прогрес + +Після кожної підфази звітувати користувачу: +- Внесені зміни +- Тести досі проходять? +- Виявлені проблеми +- **Запитати**: «Продовжити з наступною порцією?» + +--- + +## Фаза 6: Перегляд та ітерація + +### Контрольний список після рефакторингу + +- [ ] Усі тести проходять +- [ ] Немає нових попереджень/помилок +- [ ] Код успішно компілюється +- [ ] Поведінка не змінилася (ручна верифікація) +- [ ] Документація оновлена за потреби +- [ ] Історія комітів чиста + +### Порівняння метрик + +Запустити аналіз складності до і після: +```bash +python scripts/analyze-complexity.py +``` + +Представити покращення: +- Зміна кількості рядків коду +- Зміна цикломатичної складності +- Зміна індексу супровідності + +### Перегляд користувачем + +Представити фінальні результати: +- Резюме всіх змін +- Порівняння коду до/після +- Покращення метрик +- Залишковий технічний борг +- **Запитати**: «Чи задоволені ви цими змінами?» + +### Наступні кроки + +Обговорити з користувачем: +- Додаткові запахи для усунення? +- Запланувати подальший рефакторинг? +- Застосувати аналогічні зміни в інших місцях? + +--- + +## Важливі рекомендації + +### Коли ЗУПИНИТИСЯ та запитати + +Завжди паузу та консультацію з користувачем, коли: +- Невпевненість щодо бізнес-логіки +- Зміна може вплинути на зовнішні API +- Покриття тестами недостатнє +- Потрібне значне архітектурне рішення +- Рівень ризику зростає +- Зустрічаєте неочікувану складність + +### Правила безпеки + +1. **Ніколи не рефакторити без тестів** (якщо користувач явно не підтвердив ризик) +2. **Ніколи не робити великих змін** — розбивати на крихітні кроки +3. **Ніколи не пропускати запуск тестів** після кожної зміни +4. **Ніколи не продовжувати, якщо тести не проходять** — виправити або відкатити +5. **Ніколи не припускати** — якщо сумніваєтесь, запитайте + +### Чого НЕ робити + +- Не поєднуйте рефакторинг з додаванням функцій +- Не рефакторте під час аварій на продакшні +- Не рефакторте код, який не розумієте +- Не переускладнюйте — тримайте просто +- Не рефакторте все одразу + +--- + +## Приклад швидкого старту + +### Сценарій: Довгий метод з дублюванням + +**До:** +```javascript +function processOrder(order) { + // 150 рядків коду з: + // - Дубльованою логікою валідації + // - Інлайн-обчисленнями + // - Змішаними відповідальностями +} +``` + +**Кроки рефакторингу:** + +1. **Переконатися, що тести існують** для processOrder() +2. **Витягти** валідацію у validateOrder() +3. **Тест** — має пройти +4. **Витягти** обчислення у calculateOrderTotal() +5. **Тест** — має пройти +6. **Витягти** сповіщення у notifyCustomer() +7. **Тест** — має пройти +8. **Перегляд** — processOrder() тепер оркеструє 3 чіткі функції + +**Після:** +```javascript +function processOrder(order) { + validateOrder(order); + const total = calculateOrderTotal(order); + notifyCustomer(order, total); + return { order, total }; +} +``` + +--- + +## Довідники + +- [Каталог запахів коду](references/code-smells.md) — повний список запахів коду +- [Каталог рефакторингів](references/refactoring-catalog.md) — техніки рефакторингу +- [Шаблон плану рефакторингу](templates/refactoring-plan.md) — шаблон планування + +## Скрипти + +- `scripts/analyze-complexity.py` — аналіз метрик складності коду +- `scripts/detect-smells.py` — автоматичне виявлення запахів + +## Історія версій + +- v1.0.0 (2025-01-15): Початковий випуск з методологією Фаулера, поетапним підходом, точками консультації з користувачем diff --git a/uk/03-skills/refactor/templates/refactoring-plan.md b/uk/03-skills/refactor/templates/refactoring-plan.md new file mode 100644 index 0000000..467cbda --- /dev/null +++ b/uk/03-skills/refactor/templates/refactoring-plan.md @@ -0,0 +1,284 @@ +# Шаблон плану рефакторингу + +Використовуйте цей шаблон для документування та відстеження вашого рефакторингу. + +--- + +## Інформація про проєкт + +| Поле | Значення | +|------|----------| +| **Проєкт/Модуль** | [Назва проєкту] | +| **Цільові файли** | [Список файлів для рефакторингу] | +| **Дата створення** | [Дата] | +| **Автор** | [Імʼя] | +| **Статус** | Чернетка / На перегляді / Затверджено / В роботі / Завершено | + +--- + +## Загальний опис + +### Цілі +- [ ] [Основна ціль: напр., Покращити читабельність обробки платежів] +- [ ] [Другорядна ціль: напр., Зменшити дублювання коду] +- [ ] [Третинна ціль: напр., Покращити тестовність] + +### Обмеження +- [ ] [Обмеження 1: напр., Не можна змінювати публічний API] +- [ ] [Обмеження 2: напр., Зберегти зворотну сумісність] +- [ ] [Обмеження 3: напр., Без змін схеми БД] + +### Рівень ризику +- [ ] Низький — незначні зміни, добре протестований код +- [ ] Середній — помірні зміни, деякий ризик +- [ ] Високий — значні зміни, потрібна ретельна увага + +--- + +## Контрольний список перед рефакторингом + +### Оцінка покриття тестами + +| Метрика | Поточне | Ціль | Статус | +|---------|---------|------|--------| +| Покриття юніт-тестами | __% | ≥80% | | +| Інтеграційні тести | Так/Ні | Так | | +| Усі тести проходять | Так/Ні | Так | | + +### Потрібно перед початком +- [ ] Усі тести проходять +- [ ] Код переглянутий та зрозумілий +- [ ] Резервне копіювання/контроль версій налаштовано +- [ ] Затвердження користувача отримано + +--- + +## Виявлені запахи коду + +### Резюме + +| # | Запах | Розташування | Серйозність | Пріоритет | +|---|-------|-------------|-------------|-----------| +| 1 | [напр., Long Method] | [файл:рядок] | Високий | P1 | +| 2 | [напр., Duplicate Code] | [файл:рядок] | Середній | P2 | +| 3 | [напр., Feature Envy] | [файл:рядок] | Низький | P3 | + +### Детальний аналіз + +#### Запах #1: [Назва] + +**Розташування**: `path/to/file.js:45-120` + +**Опис**: [Детальний опис проблеми] + +**Вплив**: +- [Вплив 1] +- [Вплив 2] + +**Запропоноване рішення**: [Короткий огляд виправлення] + +--- + +## Фази рефакторингу + +### Фаза A: Швидкі перемоги (Низький ризик) + +**Ціль**: Прості покращення з негайною цінністю + +**Орієнтовні зміни**: [X файлів, Y методів] + +**Потрібне затвердження користувача**: Так / Ні + +| # | Завдання | Файл | Рефакторинг | Статус | +|---|---------|------|-------------|--------| +| A1 | Перейменувати змінну `x` на `userCount` | utils.js:15 | Rename Variable | [ ] | +| A2 | Видалити невикористаний `oldHandler()` | api.js:89 | Remove Dead Code | [ ] | +| A3 | Витягти дубльовану валідацію | form.js:23,67 | Extract Method | [ ] | + +**План відкату**: Відкатити коміти A1-A3 + +--- + +### Фаза B: Структурні покращення (Середній ризик) + +**Ціль**: Покращити організацію та ясність коду + +**Орієнтовні зміни**: [X файлів, Y методів] + +**Потрібне затвердження користувача**: Так + +**Залежності**: Фаза A має бути завершена + +| # | Завдання | Файл | Рефакторинг | Статус | +|---|---------|------|-------------|--------| +| B1 | Витягти `calculatePrice()` з довгого методу | order.js:45 | Extract Method | [ ] | +| B2 | Ввести обʼєкт параметрів `OrderDetails` | order.js:12 | Introduce Parameter Object | [ ] | +| B3 | Перемістити `formatAddress()` до класу Address | customer.js:78 | Move Method | [ ] | + +**План відкату**: Відкатити до коміту після Фази A + +--- + +### Фаза C: Архітектурні зміни (Вищий ризик) + +**Ціль**: Усунути глибші структурні проблеми + +**Орієнтовні зміни**: [X файлів, Y методів] + +**Потрібне затвердження користувача**: Так + +**Залежності**: Фази A та B мають бути завершені + +| # | Завдання | Файл | Рефакторинг | Статус | +|---|---------|------|-------------|--------| +| C1 | Замінити switch цін на поліморфізм | pricing.js:30 | Replace Conditional with Polymorphism | [ ] | +| C2 | Витягти клас `NotificationService` | user.js:100 | Extract Class | [ ] | + +**План відкату**: Відкатити до коміту після Фази B + +--- + +## Детальні кроки рефакторингу + +### Завдання [ID]: [Назва завдання] + +**Усунений запах**: [Назва запаху] + +**Техніка рефакторингу**: [Назва техніки] + +**Рівень ризику**: Низький / Середній / Високий + +#### Контекст + +**До** (Поточний стан): +```javascript +// Вставте поточний код тут +``` + +**Після** (Очікуваний стан): +```javascript +// Вставте очікуваний код тут +``` + +#### Покрокова механіка + +1. [ ] **Крок 1**: [Опис] + - Тест: Запустити тести після цього кроку + - Очікувано: Усі тести проходять + +2. [ ] **Крок 2**: [Опис] + - Тест: Запустити тести після цього кроку + - Очікувано: Усі тести проходять + +3. [ ] **Крок 3**: [Опис] + - Тест: Запустити тести після цього кроку + - Очікувано: Усі тести проходять + +#### Верифікація + +- [ ] Усі тести проходять +- [ ] Поведінка не змінилася +- [ ] Код компілюється +- [ ] Немає нових попереджень + +#### Повідомлення коміту +``` +refactor: [Опишіть рефакторинг] +``` + +--- + +## Відстеження прогресу + +### Статус фаз + +| Фаза | Статус | Розпочато | Завершено | Тести проходять | +|------|--------|-----------|-----------|-----------------| +| A | Не розпочато / В роботі / Готово | | | | +| B | Не розпочато / В роботі / Готово | | | | +| C | Не розпочато / В роботі / Готово | | | | + +### Виявлені проблеми + +| # | Проблема | Рішення | Статус | +|---|---------|---------|--------| +| 1 | [Опис] | [Як вирішено] | Відкрито / Вирішено | + +--- + +## Порівняння метрик + +### До рефакторингу + +| Метрика | Файл 1 | Файл 2 | Загалом | +|---------|--------|--------|---------| +| Рядків коду | | | | +| Цикломатична складність | | | | +| Індекс супровідності | | | | +| Кількість методів | | | | +| Середня довжина методу | | | | + +### Після рефакторингу + +| Метрика | Файл 1 | Файл 2 | Загалом | Зміна | +|---------|--------|--------|---------|-------| +| Рядків коду | | | | | +| Цикломатична складність | | | | | +| Індекс супровідності | | | | | +| Кількість методів | | | | | +| Середня довжина методу | | | | | + +--- + +## Контрольний список після рефакторингу + +- [ ] Усі тести проходять +- [ ] Немає нових попереджень або помилок +- [ ] Код успішно компілюється +- [ ] Ручна верифікація завершена +- [ ] Документація оновлена (за потреби) +- [ ] Код переглянутий +- [ ] Метрики покращені +- [ ] Підпис користувача отриманий + +--- + +## Отримані уроки + +### Що пройшло добре +- [Пункт 1] +- [Пункт 2] + +### Що можна покращити +- [Пункт 1] +- [Пункт 2] + +### Рекомендації на майбутнє +- [Пункт 1] +- [Пункт 2] + +--- + +## Затвердження + +| Роль | Імʼя | Дата | Підпис | +|------|------|------|--------| +| Автор плану | | | | +| Технічний лід | | | | +| Власник продукту | | | | + +--- + +## Додатки + +### A. Повʼязана документація +- [Посилання на релевантні документи] + +### B. Довідкові матеріали +- [Посилання на каталог запахів коду] +- [Посилання на каталог рефакторингів] + +### C. Використані інструменти +- [Тестовий фреймворк] +- [Інструменти лінтингу] +- [Інструменти аналізу складності]