diff --git a/uk/04-subagents/README.md b/uk/04-subagents/README.md new file mode 100644 index 0000000..6786dc1 --- /dev/null +++ b/uk/04-subagents/README.md @@ -0,0 +1,1118 @@ + + + + + + + Claude How To + + +# Субагенти — повний довідник + +Субагенти — це спеціалізовані AI-асистенти, яким Claude Code може делегувати завдання. Кожен субагент має конкретне призначення, використовує власне контекстне вікно, окреме від основної розмови, і може бути налаштований з конкретними інструментами та власним системним промптом. + +## Зміст + +1. [Огляд](#огляд) +2. [Ключові переваги](#ключові-переваги) +3. [Розташування файлів](#розташування-файлів) +4. [Конфігурація](#конфігурація) +5. [Вбудовані субагенти](#вбудовані-субагенти) +6. [Управління субагентами](#управління-субагентами) +7. [Використання субагентів](#використання-субагентів) +8. [Відновлювані агенти](#відновлювані-агенти) +9. [Ланцюжки субагентів](#ланцюжки-субагентів) +10. [Постійна пам'ять для субагентів](#постійна-памʼять-для-субагентів) +11. [Фонові субагенти](#фонові-субагенти) +12. [Ізоляція через Worktree](#ізоляція-через-worktree) +13. [Обмеження створюваних субагентів](#обмеження-створюваних-субагентів) +14. [CLI-команда `claude agents`](#cli-команда-claude-agents) +15. [Agent Teams (експериментально)](#agent-teams-експериментально) +16. [Безпека субагентів плагінів](#безпека-субагентів-плагінів) +17. [Архітектура](#архітектура) +18. [Управління контекстом](#управління-контекстом) +19. [Коли використовувати субагентів](#коли-використовувати-субагентів) +20. [Найкращі практики](#найкращі-практики) +21. [Приклади субагентів у цій папці](#приклади-субагентів-у-цій-папці) +22. [Інструкції з встановлення](#інструкції-з-встановлення) +23. [Пов'язані концепції](#повʼязані-концепції) + +--- + +## Огляд + +Субагенти забезпечують делеговане виконання завдань у Claude Code шляхом: + +- Створення **ізольованих AI-асистентів** з окремими контекстними вікнами +- Надання **налаштованих системних промптів** для спеціалізованої експертизи +- Застосування **контролю доступу до інструментів** для обмеження можливостей +- Запобігання **забрудненню контексту** від складних завдань +- Забезпечення **паралельного виконання** кількох спеціалізованих завдань + +Кожен субагент працює незалежно з чистого аркуша, отримуючи лише конкретний контекст, необхідний для його завдання, а потім повертає результати головному агенту для синтезу. + +**Швидкий старт**: Використовуйте команду `/agents` для створення, перегляду, редагування та управління субагентами в інтерактивному режимі. + +--- + +## Ключові переваги + +| Перевага | Опис | +|----------|------| +| **Збереження контексту** | Працює в окремому контексті, запобігаючи забрудненню основної розмови | +| **Спеціалізована експертиза** | Точно налаштований для конкретних доменів з вищим рівнем успіху | +| **Повторне використання** | Використання в різних проєктах і поширення між командами | +| **Гнучкі дозволи** | Різні рівні доступу до інструментів для різних типів субагентів | +| **Масштабованість** | Кілька агентів працюють над різними аспектами одночасно | + +--- + +## Розташування файлів + +Файли субагентів можна зберігати в кількох розташуваннях з різними областями дії: + +| Пріоритет | Тип | Розташування | Область дії | +|-----------|-----|-------------|-------------| +| 1 (найвищий) | **CLI-визначені** | Через прапорець `--agents` (JSON) | Лише сесія | +| 2 | **Субагенти проєкту** | `.claude/agents/` | Поточний проєкт | +| 3 | **Субагенти користувача** | `~/.claude/agents/` | Усі проєкти | +| 4 (найнижчий) | **Агенти плагінів** | Каталог `agents/` плагіна | Через плагіни | + +Коли існують дублікати імен, джерела з вищим пріоритетом мають перевагу. + +--- + +## Конфігурація + +### Формат файлу + +Субагенти визначаються у YAML-фронтматері, за яким іде системний промпт у Markdown: + +```yaml +--- +name: your-sub-agent-name +description: Description of when this subagent should be invoked +tools: tool1, tool2, tool3 # Опціонально — успадковує всі інструменти, якщо не вказано +disallowedTools: tool4 # Опціонально — явно заборонені інструменти +model: sonnet # Опціонально — sonnet, opus, haiku або inherit +permissionMode: default # Опціонально — режим дозволів +maxTurns: 20 # Опціонально — ліміт агентних кроків +skills: skill1, skill2 # Опціонально — навички для попереднього завантаження +mcpServers: server1 # Опціонально — доступні MCP-сервери +memory: user # Опціонально — область постійної пам'яті (user, project, local) +background: false # Опціонально — запуск як фонове завдання +effort: high # Опціонально — рівень зусиль (low, medium, high, max) +isolation: worktree # Опціонально — ізоляція через git worktree +initialPrompt: "Start by analyzing the codebase" # Опціонально — автоматичний перший крок +hooks: # Опціонально — хуки, обмежені компонентом + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/security-check.sh" +--- + +Your subagent's system prompt goes here. This can be multiple paragraphs +and should clearly define the subagent's role, capabilities, and approach +to solving problems. +``` + +### Поля конфігурації + +| Поле | Обов'язкове | Опис | +|------|-------------|------| +| `name` | Так | Унікальний ідентифікатор (малі літери та дефіси) | +| `description` | Так | Опис призначення природною мовою. Включіть "use PROACTIVELY" для заохочення автоматичного виклику | +| `tools` | Ні | Список інструментів через кому. Пропустіть для успадкування всіх. Підтримує синтаксис `Agent(agent_name)` для обмеження створюваних субагентів | +| `disallowedTools` | Ні | Список заборонених інструментів через кому | +| `model` | Ні | Модель: `sonnet`, `opus`, `haiku`, повний ID моделі або `inherit`. За замовч. — налаштована модель субагента | +| `permissionMode` | Ні | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` | +| `maxTurns` | Ні | Максимальна кількість агентних кроків | +| `skills` | Ні | Список навичок через кому для попереднього завантаження. Вставляє повний вміст навички в контекст при запуску | +| `mcpServers` | Ні | MCP-сервери, доступні субагенту | +| `hooks` | Ні | Хуки, обмежені компонентом (PreToolUse, PostToolUse, Stop) | +| `memory` | Ні | Область постійної пам'яті: `user`, `project` або `local` | +| `background` | Ні | `true` для запуску як фонового завдання | +| `effort` | Ні | Рівень зусиль: `low`, `medium`, `high` або `max` | +| `isolation` | Ні | `worktree` для власного git worktree | +| `initialPrompt` | Ні | Автоматичний перший крок при запуску субагента як головного агента | + +### Варіанти конфігурації інструментів + +**Варіант 1: Успадкування всіх інструментів (пропустити поле)** +```yaml +--- +name: full-access-agent +description: Agent with all available tools +--- +``` + +**Варіант 2: Вказати конкретні інструменти** +```yaml +--- +name: limited-agent +description: Agent with specific tools only +tools: Read, Grep, Glob, Bash +--- +``` + +**Варіант 3: Умовний доступ до інструментів** +```yaml +--- +name: conditional-agent +description: Agent with filtered tool access +tools: Read, Bash(npm:*), Bash(test:*) +--- +``` + +### Конфігурація через CLI + +Визначте субагентів для однієї сесії за допомогою прапорця `--agents` у форматі JSON: + +```bash +claude --agents '{ + "code-reviewer": { + "description": "Expert code reviewer. Use proactively after code changes.", + "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", + "tools": ["Read", "Grep", "Glob", "Bash"], + "model": "sonnet" + } +}' +``` + +**Формат JSON для прапорця `--agents`:** + +```json +{ + "agent-name": { + "description": "Required: when to invoke this agent", + "prompt": "Required: system prompt for the agent", + "tools": ["Optional", "array", "of", "tools"], + "model": "optional: sonnet|opus|haiku" + } +} +``` + +**Пріоритет визначень агентів:** + +Визначення агентів завантажуються з таким пріоритетом (перший збіг виграє): +1. **CLI-визначені** — прапорець `--agents` (лише сесія, JSON) +2. **Рівень проєкту** — `.claude/agents/` (поточний проєкт) +3. **Рівень користувача** — `~/.claude/agents/` (усі проєкти) +4. **Рівень плагіна** — каталог `agents/` плагіна + +Це дозволяє CLI-визначенням перевизначати всі інші джерела для однієї сесії. + +--- + +## Вбудовані субагенти + +Claude Code включає кілька вбудованих субагентів, які завжди доступні: + +| Агент | Модель | Призначення | +|-------|--------|-------------| +| **general-purpose** | Успадковує | Складні, багатокрокові завдання | +| **Plan** | Успадковує | Дослідження для режиму планування | +| **Explore** | Haiku | Дослідження кодової бази лише для читання (швидке/середнє/дуже ретельне) | +| **Bash** | Успадковує | Термінальні команди в окремому контексті | +| **statusline-setup** | Sonnet | Налаштування рядка стану | +| **Claude Code Guide** | Haiku | Відповіді на питання про функції Claude Code | + +### Субагент General-Purpose + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Успадковує від батька | +| **Інструменти** | Усі інструменти | +| **Призначення** | Складні дослідницькі завдання, багатокрокові операції, модифікація коду | + +**Коли використовується**: Завдання, що потребують дослідження та модифікації зі складною логікою. + +### Субагент Plan + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Успадковує від батька | +| **Інструменти** | Read, Glob, Grep, Bash | +| **Призначення** | Автоматичне дослідження кодової бази в режимі планування | + +**Коли використовується**: Коли Claude потрібно зрозуміти кодову базу перед представленням плану. + +### Субагент Explore + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Haiku (швидкий, низька затримка) | +| **Режим** | Строго лише для читання | +| **Інструменти** | Glob, Grep, Read, Bash (лише команди для читання) | +| **Призначення** | Швидкий пошук та аналіз кодової бази | + +**Коли використовується**: Пошук/розуміння коду без внесення змін. + +**Рівні ретельності** — вкажіть глибину дослідження: +- **"quick"** — швидкий пошук з мінімальним дослідженням, добре для пошуку конкретних патернів +- **"medium"** — помірне дослідження, баланс швидкості та ретельності, стандартний підхід +- **"very thorough"** — комплексний аналіз у кількох розташуваннях та конвенціях іменування, може зайняти більше часу + +### Субагент Bash + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Успадковує від батька | +| **Інструменти** | Bash | +| **Призначення** | Виконання термінальних команд в окремому контекстному вікні | + +**Коли використовується**: Виконання команд оболонки, які виграють від ізольованого контексту. + +### Субагент Statusline Setup + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Sonnet | +| **Інструменти** | Read, Write, Bash | +| **Призначення** | Налаштування відображення рядка стану Claude Code | + +**Коли використовується**: Налаштування або кастомізація рядка стану. + +### Субагент Claude Code Guide + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Haiku (швидкий, низька затримка) | +| **Інструменти** | Лише для читання | +| **Призначення** | Відповіді на питання про функції та використання Claude Code | + +**Коли використовується**: Коли користувачі питають про роботу Claude Code або використання конкретних функцій. + +--- + +## Управління субагентами + +### Команда `/agents` (рекомендовано) + +```bash +/agents +``` + +Надає інтерактивне меню для: +- Перегляду всіх доступних субагентів (вбудованих, користувача та проєкту) +- Створення нових субагентів з керованим налаштуванням +- Редагування наявних субагентів та доступу до інструментів +- Видалення субагентів +- Перегляду активних субагентів при наявності дублікатів + +### Пряме управління файлами + +```bash +# Створення субагента проєкту +mkdir -p .claude/agents +cat > .claude/agents/test-runner.md << 'EOF' +--- +name: test-runner +description: Use proactively to run tests and fix failures +--- + +You are a test automation expert. When you see code changes, proactively +run the appropriate tests. If tests fail, analyze the failures and fix +them while preserving the original test intent. +EOF + +# Створення субагента користувача (доступний у всіх проєктах) +mkdir -p ~/.claude/agents +``` + +--- + +## Використання субагентів + +### Автоматичне делегування + +Claude проактивно делегує завдання на основі: +- Опису завдання у вашому запиті +- Поля `description` у конфігурації субагента +- Поточного контексту та доступних інструментів + +Для заохочення проактивного використання додайте "use PROACTIVELY" або "MUST BE USED" у поле `description`: + +```yaml +--- +name: code-reviewer +description: Expert code review specialist. Use PROACTIVELY after writing or modifying code. +--- +``` + +### Явний виклик + +Ви можете явно запросити конкретного субагента: + +``` +> Use the test-runner subagent to fix failing tests +> Have the code-reviewer subagent look at my recent changes +> Ask the debugger subagent to investigate this error +``` + +### Виклик через @-згадку + +Використовуйте префікс `@` для гарантованого виклику конкретного субагента (обходить евристику автоматичного делегування): + +``` +> @"code-reviewer (agent)" review the auth module +``` + +### Агент на всю сесію + +Запуск сесії з конкретним агентом як головним: + +```bash +# Через прапорець CLI +claude --agent code-reviewer + +# Через settings.json +{ + "agent": "code-reviewer" +} +``` + +### Список доступних агентів + +Використовуйте команду `claude agents` для переліку всіх налаштованих агентів з усіх джерел: + +```bash +claude agents +``` + +--- + +## Відновлювані агенти + +Субагенти можуть продовжувати попередні розмови зі збереженим контекстом: + +```bash +# Початковий виклик +> Use the code-analyzer agent to start reviewing the authentication module +# Повертає agentId: "abc123" + +# Відновлення агента пізніше +> Resume agent abc123 and now analyze the authorization logic as well +``` + +**Випадки використання**: +- Тривалі дослідження між кількома сесіями +- Ітеративне вдосконалення без втрати контексту +- Багатокрокові воркфлови зі збереженням контексту + +--- + +## Ланцюжки субагентів + +Послідовне виконання кількох субагентів: + +```bash +> First use the code-analyzer subagent to find performance issues, + then use the optimizer subagent to fix them +``` + +Це дозволяє створювати складні воркфлови, де результат одного субагента є вхідними даними для іншого. + +--- + +## Постійна пам'ять для субагентів + +Поле `memory` надає субагентам постійний каталог, що зберігається між розмовами. Це дозволяє субагентам накопичувати знання з часом, зберігаючи нотатки, висновки та контекст між сесіями. + +### Області пам'яті + +| Область | Каталог | Випадок використання | +|---------|---------|---------------------| +| `user` | `~/.claude/agent-memory//` | Персональні нотатки та налаштування для всіх проєктів | +| `project` | `.claude/agent-memory//` | Знання, специфічні для проєкту, спільні з командою | +| `local` | `.claude/agent-memory-local//` | Локальні знання проєкту, не комітяться у контроль версій | + +### Як це працює + +- Перші 200 рядків `MEMORY.md` у каталозі пам'яті автоматично завантажуються в системний промпт субагента +- Інструменти `Read`, `Write` та `Edit` автоматично ввімкнені для управління файлами пам'яті +- Субагент може створювати додаткові файли у каталозі пам'яті за потребою + +### Приклад конфігурації + +```yaml +--- +name: researcher +memory: user +--- + +You are a research assistant. Use your memory directory to store findings, +track progress across sessions, and build up knowledge over time. + +Check your MEMORY.md file at the start of each session to recall previous context. +``` + +```mermaid +graph LR + A["Subagent
Session 1"] -->|writes| M["MEMORY.md
(persistent)"] + M -->|loads into| B["Subagent
Session 2"] + B -->|updates| M + M -->|loads into| C["Subagent
Session 3"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e1f5fe,stroke:#333,color:#333 + style M fill:#f3e5f5,stroke:#333,color:#333 +``` + +--- + +## Фонові субагенти + +Субагенти можуть працювати у фоні, звільняючи основну розмову для інших завдань. + +### Конфігурація + +Встановіть `background: true` у фронтматері для постійного запуску субагента як фонового завдання: + +```yaml +--- +name: long-runner +background: true +description: Performs long-running analysis tasks in the background +--- +``` + +### Клавіатурні скорочення + +| Скорочення | Дія | +|-----------|-----| +| `Ctrl+B` | Перемістити поточне завдання субагента у фон | +| `Ctrl+F` | Завершити всіх фонових агентів (натисніть двічі для підтвердження) | + +### Вимкнення фонових завдань + +Встановіть змінну оточення для повного вимкнення підтримки фонових завдань: + +```bash +export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 +``` + +--- + +## Ізоляція через Worktree + +Налаштування `isolation: worktree` надає субагенту власне git worktree, дозволяючи вносити зміни незалежно, не впливаючи на основне робоче дерево. + +### Конфігурація + +```yaml +--- +name: feature-builder +isolation: worktree +description: Implements features in an isolated git worktree +tools: Read, Write, Edit, Bash, Grep, Glob +--- +``` + +### Як це працює + +```mermaid +graph TB + Main["Main Working Tree"] -->|spawns| Sub["Subagent with
Isolated Worktree"] + Sub -->|makes changes in| WT["Separate Git
Worktree + Branch"] + WT -->|no changes| Clean["Auto-cleaned"] + WT -->|has changes| Return["Returns worktree
path and branch"] + + style Main fill:#e1f5fe,stroke:#333,color:#333 + style Sub fill:#f3e5f5,stroke:#333,color:#333 + style WT fill:#e8f5e9,stroke:#333,color:#333 + style Clean fill:#fff3e0,stroke:#333,color:#333 + style Return fill:#fff3e0,stroke:#333,color:#333 +``` + +- Субагент працює у власному git worktree на окремій гілці +- Якщо субагент не вносить змін, worktree автоматично очищується +- Якщо зміни є, шлях до worktree та назва гілки повертаються головному агенту для огляду або мерджу + +--- + +## Обмеження створюваних субагентів + +Ви можете контролювати, яких субагентів може створювати конкретний субагент, використовуючи синтаксис `Agent(agent_type)` у полі `tools`. Це дозволяє створити список дозволених субагентів для делегування. + +> **Примітка**: У v2.1.63 інструмент `Task` було перейменовано на `Agent`. Існуючі посилання `Task(...)` все ще працюють як псевдоніми. + +### Приклад + +```yaml +--- +name: coordinator +description: Coordinates work between specialized agents +tools: Agent(worker, researcher), Read, Bash +--- + +You are a coordinator agent. You can delegate work to the "worker" and +"researcher" subagents only. Use Read and Bash for your own exploration. +``` + +У цьому прикладі субагент `coordinator` може створювати лише субагентів `worker` та `researcher`. Він не може створювати інших субагентів, навіть якщо вони визначені деінде. + +--- + +## CLI-команда `claude agents` + +Команда `claude agents` відображає всіх налаштованих агентів, згрупованих за джерелом (вбудовані, рівень користувача, рівень проєкту): + +```bash +claude agents +``` + +Ця команда: +- Показує всіх доступних агентів з усіх джерел +- Групує агентів за розташуванням джерела +- Вказує **перевизначення**, коли агент вищого пріоритету затіняє агента нижчого рівня (наприклад, агент рівня проєкту з тим самим ім'ям, що й агент рівня користувача) + +--- + +## Agent Teams (експериментально) + +Agent Teams координують кілька екземплярів Claude Code, що працюють разом над складними завданнями. На відміну від субагентів (які є делегованими підзавданнями, що повертають результати), тіммейти працюють незалежно з власними контекстними вікнами і можуть обмінюватися повідомленнями безпосередньо через спільну систему поштових скриньок. + +> **Офіційна документація**: [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) + +> **Примітка**: Agent Teams — експериментальна функція, вимкнена за замовчуванням. Потребує Claude Code v2.1.32+. Увімкніть перед використанням. + +### Субагенти vs Agent Teams + +| Аспект | Субагенти | Agent Teams | +|--------|-----------|-------------| +| **Модель делегування** | Батько делегує підзавдання, чекає результат | Тімлід координує роботу, тіммейти виконують незалежно | +| **Контекст** | Чистий контекст на підзавдання, результати стискаються назад | Кожен тіммейт підтримує власне постійне контекстне вікно | +| **Координація** | Послідовна або паралельна, керована батьком | Спільний список завдань з автоматичним управлінням залежностями | +| **Комунікація** | Результати повертаються лише батьку (без обміну між агентами) | Тіммейти обмінюються повідомленнями безпосередньо через поштову скриньку | +| **Відновлення сесії** | Підтримується | Не підтримується з in-process тіммейтами | +| **Найкраще для** | Сфокусовані, чітко визначені підзавдання | Складна робота, що потребує міжагентної комунікації та паралельного виконання | + +### Увімкнення Agent Teams + +Встановіть змінну оточення або додайте до `settings.json`: + +```bash +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +Або в `settings.json`: + +```json +{ + "env": { + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" + } +} +``` + +### Запуск команди + +Після увімкнення попросіть Claude працювати з тіммейтами у промпті: + +``` +User: Build the authentication module. Use a team — one teammate for the API endpoints, + one for the database schema, and one for the test suite. +``` + +Claude створить команду, призначить завдання та автоматично координуватиме роботу. + +### Режими відображення + +Контролюйте, як відображається активність тіммейтів: + +| Режим | Прапорець | Опис | +|-------|-----------|------| +| **Auto** | `--teammate-mode auto` | Автоматично обирає найкращий режим для вашого терміналу | +| **In-process** (за замовч.) | `--teammate-mode in-process` | Показує вивід тіммейтів у поточному терміналі | +| **Split-panes** | `--teammate-mode tmux` | Відкриває кожного тіммейта в окремій панелі tmux або iTerm2 | + +```bash +claude --teammate-mode tmux +``` + +Також можна встановити режим у `settings.json`: + +```json +{ + "teammateMode": "tmux" +} +``` + +> **Примітка**: Режим split-pane потребує tmux або iTerm2. Недоступний у VS Code terminal, Windows Terminal або Ghostty. + +### Навігація + +Використовуйте `Shift+Down` для навігації між тіммейтами в режимі split-pane. + +### Конфігурація команди + +Конфігурації команд зберігаються в `~/.claude/teams/{team-name}/config.json`. + +### Архітектура + +```mermaid +graph TB + Lead["Team Lead
(Coordinator)"] + TaskList["Shared Task List
(Dependencies)"] + Mailbox["Mailbox
(Messages)"] + T1["Teammate 1
(Own Context)"] + T2["Teammate 2
(Own Context)"] + T3["Teammate 3
(Own Context)"] + + Lead -->|assigns tasks| TaskList + Lead -->|sends messages| Mailbox + TaskList -->|picks up work| T1 + TaskList -->|picks up work| T2 + TaskList -->|picks up work| T3 + T1 -->|reads/writes| Mailbox + T2 -->|reads/writes| Mailbox + T3 -->|reads/writes| Mailbox + T1 -->|updates status| TaskList + T2 -->|updates status| TaskList + T3 -->|updates status| TaskList + + style Lead fill:#e1f5fe,stroke:#333,color:#333 + style TaskList fill:#fff9c4,stroke:#333,color:#333 + style Mailbox fill:#f3e5f5,stroke:#333,color:#333 + style T1 fill:#e8f5e9,stroke:#333,color:#333 + style T2 fill:#e8f5e9,stroke:#333,color:#333 + style T3 fill:#e8f5e9,stroke:#333,color:#333 +``` + +**Ключові компоненти**: + +- **Team Lead**: основна сесія Claude Code, що створює команду, призначає завдання та координує +- **Shared Task List**: синхронізований список завдань з автоматичним відстеженням залежностей +- **Mailbox**: система міжагентних повідомлень для координації тіммейтів +- **Teammates**: незалежні екземпляри Claude Code з власними контекстними вікнами + +### Призначення завдань та обмін повідомленнями + +Тімлід розбиває роботу на завдання та призначає їх тіммейтам. Спільний список завдань забезпечує: + +- **Автоматичне управління залежностями** — завдання чекають завершення залежностей +- **Відстеження статусу** — тіммейти оновлюють статус завдань під час роботи +- **Міжагентні повідомлення** — тіммейти надсилають повідомлення через поштову скриньку для координації (наприклад, "Схема бази даних готова, можете починати писати запити") + +### Воркфлов затвердження плану + +Для складних завдань тімлід створює план виконання перед початком роботи тіммейтів. Користувач переглядає та затверджує план, забезпечуючи відповідність підходу команди очікуванням перед внесенням будь-яких змін у код. + +### Хук-події для команд + +Agent Teams додають дві додаткових [хук-події](../06-hooks/): + +| Подія | Спрацьовує коли | Випадок використання | +|-------|----------------|---------------------| +| `TeammateIdle` | Тіммейт завершив поточне завдання і не має очікуваної роботи | Сповіщення, призначення наступних завдань | +| `TaskCompleted` | Завдання у спільному списку позначено як завершене | Валідація, оновлення дашбордів, ланцюжки залежних робіт | + +### Найкращі практики + +- **Розмір команди**: тримайте 3-5 тіммейтів для оптимальної координації +- **Розмір завдань**: розбивайте роботу на завдання по 5-15 хвилин — достатньо малі для паралелізації, достатньо великі для значущості +- **Уникайте конфліктів файлів**: призначайте різні файли або каталоги різним тіммейтам +- **Починайте просто**: використовуйте in-process режим для першої команди; переходьте на split-panes після звикання +- **Чіткі описи завдань**: надавайте конкретні, дієві описи завдань + +### Обмеження + +- **Експериментально**: поведінка функції може змінитися в майбутніх релізах +- **Немає відновлення сесії**: in-process тіммейти не можуть бути відновлені після завершення сесії +- **Одна команда на сесію**: неможливо створити вкладені команди або кілька команд в одній сесії +- **Фіксований лідер**: роль тімліда не може бути передана тіммейту +- **Обмеження split-pane**: потребує tmux/iTerm2; недоступний у VS Code terminal, Windows Terminal або Ghostty +- **Немає крос-сесійних команд**: тіммейти існують лише в межах поточної сесії + +> **Увага**: Agent Teams — експериментальна функція. Спочатку тестуйте з некритичною роботою та відстежуйте координацію тіммейтів на предмет неочікуваної поведінки. + +--- + +## Безпека субагентів плагінів + +Субагенти плагінів мають обмежені можливості фронтматера з міркувань безпеки. Наступні поля **заборонені** у визначеннях субагентів плагінів: + +- `hooks` — не можна визначати хуки життєвого циклу +- `mcpServers` — не можна налаштовувати MCP-сервери +- `permissionMode` — не можна перевизначати налаштування дозволів + +Це запобігає ескалації привілеїв або виконанню довільних команд через хуки субагентів плагінів. + +--- + +## Архітектура + +### Високорівнева архітектура + +```mermaid +graph TB + User["User"] + Main["Main Agent
(Coordinator)"] + Reviewer["Code Reviewer
Subagent"] + Tester["Test Engineer
Subagent"] + Docs["Documentation
Subagent"] + + User -->|asks| Main + Main -->|delegates| Reviewer + Main -->|delegates| Tester + Main -->|delegates| Docs + Reviewer -->|returns result| Main + Tester -->|returns result| Main + Docs -->|returns result| Main + Main -->|synthesizes| User +``` + +### Життєвий цикл субагента + +```mermaid +sequenceDiagram + participant User + participant MainAgent as Main Agent + participant CodeReviewer as Code Reviewer
Subagent + participant Context as Separate
Context Window + + User->>MainAgent: "Build new auth feature" + MainAgent->>MainAgent: Analyze task + MainAgent->>CodeReviewer: "Review this code" + CodeReviewer->>Context: Initialize clean context + Context->>CodeReviewer: Load reviewer instructions + CodeReviewer->>CodeReviewer: Perform review + CodeReviewer-->>MainAgent: Return findings + MainAgent->>MainAgent: Incorporate results + MainAgent-->>User: Provide synthesis +``` + +--- + +## Управління контекстом + +```mermaid +graph TB + A["Main Agent Context
50,000 tokens"] + B["Subagent 1 Context
20,000 tokens"] + C["Subagent 2 Context
20,000 tokens"] + D["Subagent 3 Context
20,000 tokens"] + + A -->|Clean slate| B + A -->|Clean slate| C + A -->|Clean slate| D + + B -->|Results only| A + C -->|Results only| A + D -->|Results only| A + + style A fill:#e1f5fe + style B fill:#fff9c4 + style C fill:#fff9c4 + style D fill:#fff9c4 +``` + +### Ключові моменти + +- Кожен субагент отримує **чисте контекстне вікно** без історії основної розмови +- Субагенту передається лише **релевантний контекст** для конкретного завдання +- Результати **стискаються** назад до головного агента +- Це запобігає **вичерпанню токенів контексту** у тривалих проєктах + +### Міркування щодо продуктивності + +- **Ефективність контексту** — агенти зберігають основний контекст, дозволяючи довші сесії +- **Затримка** — субагенти починають з чистого аркуша і можуть додавати затримку при збиранні початкового контексту + +### Ключові поведінки + +- **Без вкладеного створення** — субагенти не можуть створювати інших субагентів +- **Фонові дозволи** — фонові субагенти автоматично відхиляють дозволи, що не були попередньо схвалені +- **Переведення у фон** — натисніть `Ctrl+B` для переведення поточного завдання у фон +- **Транскрипти** — транскрипти субагентів зберігаються в `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl` +- **Автокомпакція** — контекст субагента автоматично компактується при ~95% заповненості (перевизначити через змінну оточення `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`) + +--- + +## Коли використовувати субагентів + +| Сценарій | Використовувати субагента | Чому | +|----------|--------------------------|------| +| Складна фіча з багатьма кроками | Так | Розділення відповідальності, запобігання забрудненню контексту | +| Швидке код-рев'ю | Ні | Зайві накладні витрати | +| Паралельне виконання завдань | Так | Кожен субагент має власний контекст | +| Потрібна спеціалізована експертиза | Так | Кастомні системні промпти | +| Тривалий аналіз | Так | Запобігає вичерпанню основного контексту | +| Одне завдання | Ні | Додає затримку без потреби | + +--- + +## Найкращі практики + +### Принципи проєктування + +**Рекомендовано:** +- Починайте з агентів, згенерованих Claude — створіть початкового субагента через Claude, потім ітеруйте для кастомізації +- Проєктуйте сфокусованих субагентів — одна чітка відповідальність замість одного, що робить все +- Пишіть детальні промпти — включайте конкретні інструкції, приклади та обмеження +- Обмежуйте доступ до інструментів — надавайте лише необхідні інструменти +- Контроль версій — комітьте субагентів проєкту у систему контролю версій + +**Не рекомендовано:** +- Створювати субагентів з перекриваючимися ролями +- Надавати субагентам зайвий доступ до інструментів +- Використовувати субагентів для простих однокрокових завдань +- Змішувати відповідальності в промпті одного субагента +- Забувати передавати необхідний контекст + +### Найкращі практики системного промпта + +1. **Будьте конкретними щодо ролі** + ``` + You are an expert code reviewer specializing in [specific areas] + ``` + +2. **Чітко визначте пріоритети** + ``` + Review priorities (in order): + 1. Security Issues + 2. Performance Problems + 3. Code Quality + ``` + +3. **Вкажіть формат виводу** + ``` + For each issue provide: Severity, Category, Location, Description, Fix, Impact + ``` + +4. **Включіть кроки дій** + ``` + When invoked: + 1. Run git diff to see recent changes + 2. Focus on modified files + 3. Begin review immediately + ``` + +### Стратегія доступу до інструментів + +1. **Починайте з обмежень**: лише необхідні інструменти +2. **Розширюйте за потребою**: додавайте інструменти, коли вимоги цього потребують +3. **Лише для читання де можливо**: Read/Grep для аналітичних агентів +4. **Ізольоване виконання**: обмежте Bash-команди конкретними патернами + +--- + +## Приклади субагентів у цій папці + +Ця папка містить готові до використання приклади субагентів: + +### 1. Code Reviewer (`code-reviewer.md`) + +**Призначення**: комплексний аналіз якості та підтримуваності коду + +**Інструменти**: Read, Grep, Glob, Bash + +**Спеціалізація**: виявлення вразливостей безпеки, ідентифікація оптимізацій продуктивності, оцінка підтримуваності коду, аналіз покриття тестами + +**Коли використовувати**: потрібне автоматизоване код-рев'ю з фокусом на якість та безпеку + +--- + +### 2. Test Engineer (`test-engineer.md`) + +**Призначення**: стратегія тестування, аналіз покриття та автоматичне тестування + +**Інструменти**: Read, Write, Bash, Grep + +**Спеціалізація**: створення юніт-тестів, проєктування інтеграційних тестів, ідентифікація крайніх випадків, аналіз покриття (ціль >80%) + +**Коли використовувати**: потрібне створення комплексного набору тестів або аналіз покриття + +--- + +### 3. Documentation Writer (`documentation-writer.md`) + +**Призначення**: технічна документація, документація API та посібники користувача + +**Інструменти**: Read, Write, Grep + +**Спеціалізація**: документація API-ендпоінтів, створення посібників користувача, архітектурна документація, покращення коментарів коду + +**Коли використовувати**: потрібне створення або оновлення документації проєкту + +--- + +### 4. Secure Reviewer (`secure-reviewer.md`) + +**Призначення**: код-рев'ю з фокусом на безпеку з мінімальними дозволами + +**Інструменти**: Read, Grep + +**Спеціалізація**: виявлення вразливостей безпеки, проблеми автентифікації/авторизації, ризики витоку даних, ідентифікація ін'єкційних атак + +**Коли використовувати**: потрібний аудит безпеки без можливості модифікації + +--- + +### 5. Implementation Agent (`implementation-agent.md`) + +**Призначення**: повні можливості реалізації для розробки функцій + +**Інструменти**: Read, Write, Edit, Bash, Grep, Glob + +**Спеціалізація**: реалізація функцій, генерація коду, виконання збірки та тестів, модифікація кодової бази + +**Коли використовувати**: потрібен субагент для наскрізної реалізації функцій + +--- + +### 6. Debugger (`debugger.md`) + +**Призначення**: спеціаліст з налагодження помилок, провалених тестів та неочікуваної поведінки + +**Інструменти**: Read, Edit, Bash, Grep, Glob + +**Спеціалізація**: аналіз першопричин, дослідження помилок, розв'язання провалених тестів, мінімальне виправлення + +**Коли використовувати**: стикаєтесь з багами, помилками або неочікуваною поведінкою + +--- + +### 7. Data Scientist (`data-scientist.md`) + +**Призначення**: експерт з аналізу даних для SQL-запитів та інсайтів + +**Інструменти**: Bash, Read, Write + +**Спеціалізація**: оптимізація SQL-запитів, операції BigQuery, аналіз та візуалізація даних, статистичні інсайти + +**Коли використовувати**: потрібний аналіз даних, SQL-запити або операції BigQuery + +--- + +## Інструкції з встановлення + +### Метод 1: Команда /agents (рекомендовано) + +```bash +/agents +``` + +Далі: +1. Оберіть 'Create New Agent' +2. Оберіть рівень проєкту або користувача +3. Опишіть субагента детально +4. Оберіть інструменти (або залиште порожнім для успадкування всіх) +5. Збережіть і використовуйте + +### Метод 2: Копіювання в проєкт + +Скопіюйте файли агентів у каталог `.claude/agents/` проєкту: + +```bash +# Перейдіть до проєкту +cd /path/to/your/project + +# Створіть каталог агентів, якщо він не існує +mkdir -p .claude/agents + +# Скопіюйте файли агентів з цієї папки +cp /path/to/04-subagents/*.md .claude/agents/ + +# Видаліть README (не потрібний у .claude/agents) +rm .claude/agents/README.md +``` + +### Метод 3: Копіювання в каталог користувача + +Для агентів, доступних у всіх проєктах: + +```bash +# Створіть каталог агентів користувача +mkdir -p ~/.claude/agents + +# Скопіюйте агентів +cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/ +cp /path/to/04-subagents/debugger.md ~/.claude/agents/ +# ... скопіюйте інших за потребою +``` + +### Перевірка + +Після встановлення переконайтесь, що агенти розпізнаються: + +```bash +/agents +``` + +Ви повинні побачити встановлених агентів поряд з вбудованими. + +--- + +## Структура файлів + +``` +project/ +├── .claude/ +│ └── agents/ +│ ├── code-reviewer.md +│ ├── test-engineer.md +│ ├── documentation-writer.md +│ ├── secure-reviewer.md +│ ├── implementation-agent.md +│ ├── debugger.md +│ └── data-scientist.md +└── ... +``` + +--- + +## Пов'язані концепції + +### Пов'язані функції + +- **[Слеш-команди](../01-slash-commands/)** — швидкі ярлики, ініційовані користувачем +- **[Пам'ять](../02-memory/)** — постійний крос-сесійний контекст +- **[Навички](../03-skills/)** — повторно використовувані автономні можливості +- **[Протокол MCP](../05-mcp/)** — доступ до зовнішніх даних у реальному часі +- **[Хуки](../06-hooks/)** — автоматизація команд оболонки за подіями +- **[Плагіни](../07-plugins/)** — пакети розширень + +### Порівняння з іншими функціями + +| Функція | Виклик користувачем | Автовиклик | Постійна | Зовнішній доступ | Ізольований контекст | +|---------|---------------------|------------|----------|------------------|---------------------| +| **Слеш-команди** | Так | Ні | Ні | Ні | Ні | +| **Субагенти** | Так | Так | Ні | Ні | Так | +| **Пам'ять** | Авто | Авто | Так | Ні | Ні | +| **MCP** | Авто | Так | Ні | Так | Ні | +| **Навички** | Так | Так | Ні | Ні | Ні | + +### Патерн інтеграції + +```mermaid +graph TD + User["User Request"] --> Main["Main Agent"] + Main -->|Uses| Memory["Memory
(Context)"] + Main -->|Queries| MCP["MCP
(Live Data)"] + Main -->|Invokes| Skills["Skills
(Auto Tools)"] + Main -->|Delegates| Subagents["Subagents
(Specialists)"] + + Subagents -->|Use| Memory + Subagents -->|Query| MCP + Subagents -->|Isolated| Context["Clean Context
Window"] +``` + +--- + +## Додаткові ресурси + +- [Офіційна документація субагентів](https://code.claude.com/docs/en/sub-agents) +- [Довідник CLI](https://code.claude.com/docs/en/cli-reference) — прапорець `--agents` та інші опції CLI +- [Посібник плагінів](../07-plugins/) — для пакування агентів з іншими функціями +- [Посібник навичок](../03-skills/) — для автоматично викликуваних можливостей +- [Посібник з пам'яті](../02-memory/) — для постійного контексту +- [Посібник хуків](../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/04-subagents/clean-code-reviewer.md b/uk/04-subagents/clean-code-reviewer.md new file mode 100644 index 0000000..0bc0eda --- /dev/null +++ b/uk/04-subagents/clean-code-reviewer.md @@ -0,0 +1,69 @@ +--- +name: clean-code-reviewer +description: Спеціаліст з дотримання принципів Clean Code. Перевіряє код на порушення теорії та найкращих практик Clean Code. Використовуйте ПРОАКТИВНО після написання коду для забезпечення супровідності та професійної якості. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# Агент рев'ю Clean Code + +Ви — старший рев'юер коду, що спеціалізується на принципах Clean Code (Роберт Мартін). Виявляйте порушення та надавайте практичні виправлення. + +## Процес +1. Запустити `git diff` для перегляду нещодавніх змін +2. Ретельно прочитати відповідні файли +3. Звітувати про порушення з файл:рядок, фрагментом коду та виправленням + +## Що перевіряти + +**Іменування**: Розкриває намір, вимовне, придатне для пошуку. Без кодувань/префіксів. Класи = іменники, методи = дієслова. + +**Функції**: <20 рядків, роблять ОДНУ річ, макс. 3 параметри, без прапорцевих аргументів, без побічних ефектів, без повернення null. + +**Коментарі**: Код має бути самопояснювальним. Видаляти закоментований код. Без надлишкових/оманливих коментарів. + +**Структура**: Малі зосереджені класи, єдина відповідальність, висока звʼязність, низька зчепленість. Уникати god-класів. + +**SOLID**: Єдина відповідальність, Відкритість/Закритість, Підстановка Лісков, Розділення інтерфейсів, Інверсія залежностей. + +**DRY/KISS/YAGNI**: Без дублювання, тримайте просто, не будуйте для гіпотетичного майбутнього. + +**Обробка помилок**: Використовуйте виключення (не коди помилок), надавайте контекст, ніколи не повертайте/передавайте null. + +**Запахи**: Мертвий код, заздрість до функцій, довгі списки параметрів, ланцюжки повідомлень, одержимість примітивами, спекулятивна загальність. + +## Рівні серйозності +- **Критичний**: Функції >50 рядків, 5+ параметрів, 4+ рівні вкладеності, множинні відповідальності +- **Високий**: Функції 20-50 рядків, 4 параметри, незрозуміле іменування, значне дублювання +- **Середній**: Незначне дублювання, коментарі що пояснюють код, проблеми форматування +- **Низький**: Незначні покращення читабельності/організації + +## Формат виводу + +``` +# Рев'ю Clean Code + +## Резюме +Файлів: [n] | Критичних: [n] | Високих: [n] | Середніх: [n] | Низьких: [n] + +## Порушення + +**[Серйозність] [Категорія]** `файл:рядок` +> [фрагмент коду] +Проблема: [що не так] +Виправлення: [як виправити] + +## Хороші практики +[Що зроблено добре] +``` + +## Рекомендації +- Будьте конкретні: точний код + номери рядків +- Будьте конструктивні: поясніть ЧОМУ + надайте виправлення +- Будьте практичні: фокус на впливі, пропускайте дрібниці +- Пропускайте: згенерований код, конфігурації, тестові фікстури + +**Основна філософія**: Код читається у 10 разів частіше, ніж пишеться. Оптимізуйте для читабельності, а не для хитрості. + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/code-reviewer.md b/uk/04-subagents/code-reviewer.md new file mode 100644 index 0000000..bf5ad11 --- /dev/null +++ b/uk/04-subagents/code-reviewer.md @@ -0,0 +1,64 @@ +--- +name: code-reviewer +description: Спеціаліст з експертного код-рев'ю. Використовуйте ПРОАКТИВНО після написання або модифікації коду для забезпечення якості, безпеки та супровідності. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# Агент код-рев'ю + +Ви — старший рев'юер коду, що забезпечує високі стандарти якості та безпеки коду. + +При виклику: +1. Запустити git diff для перегляду нещодавніх змін +2. Зосередитися на змінених файлах +3. Негайно розпочати рев'ю + +## Пріоритети рев'ю (в порядку важливості) + +1. **Проблеми безпеки** — автентифікація, авторизація, розкриття даних +2. **Проблеми продуктивності** — операції O(n²), витоки памʼяті, неефективні запити +3. **Якість коду** — читабельність, іменування, документація +4. **Покриття тестами** — відсутні тести, граничні випадки +5. **Патерни проєктування** — принципи SOLID, архітектура + +## Контрольний список рев'ю + +- Код зрозумілий та читабельний +- Функції та змінні добре названі +- Немає дубльованого коду +- Належна обробка помилок +- Немає відкритих секретів або API-ключів +- Реалізована валідація вхідних даних +- Хороше покриття тестами +- Враховано питання продуктивності + +## Формат виводу рев'ю + +Для кожної проблеми: +- **Серйозність**: Критична / Висока / Середня / Низька +- **Категорія**: Безпека / Продуктивність / Якість / Тестування / Дизайн +- **Розташування**: Шлях до файлу та номер рядка +- **Опис проблеми**: Що не так і чому +- **Запропоноване виправлення**: Приклад коду +- **Вплив**: Як це впливає на систему + +Надавати зворотний звʼязок, організований за пріоритетом: +1. Критичні проблеми (обовʼязково виправити) +2. Попередження (бажано виправити) +3. Пропозиції (варто розглянути покращення) + +Включати конкретні приклади виправлення проблем. + +## Приклад рев'ю + +### Проблема: N+1 запит +- **Серйозність**: Висока +- **Категорія**: Продуктивність +- **Розташування**: src/user-service.ts:45 +- **Проблема**: Цикл виконує запит до БД на кожній ітерації +- **Виправлення**: Використати JOIN або пакетний запит +- **Вплив**: Час відповіді зростає лінійно з обсягом даних + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/data-scientist.md b/uk/04-subagents/data-scientist.md new file mode 100644 index 0000000..b0030cc --- /dev/null +++ b/uk/04-subagents/data-scientist.md @@ -0,0 +1,100 @@ +--- +name: data-scientist +description: Експерт з аналізу даних для SQL-запитів, операцій BigQuery та аналітичних висновків. Використовуйте ПРОАКТИВНО для завдань аналізу даних та запитів. +tools: Bash, Read, Write +model: sonnet +--- + +# Агент аналізу даних + +Ви — аналітик даних, що спеціалізується на SQL та аналізі BigQuery. + +При виклику: +1. Зрозуміти вимоги до аналізу даних +2. Написати ефективні SQL-запити +3. Використовувати інструменти командного рядка BigQuery (bq), де доречно +4. Проаналізувати та підсумувати результати +5. Чітко представити висновки + +## Ключові практики + +- Писати оптимізовані SQL-запити з належними фільтрами +- Використовувати відповідні агрегації та зʼєднання +- Включати коментарі, що пояснюють складну логіку +- Форматувати результати для читабельності +- Надавати рекомендації на основі даних + +## Найкращі практики SQL + +### Оптимізація запитів + +- Фільтрувати рано за допомогою WHERE +- Використовувати відповідні індекси +- Уникати SELECT * на продакшні +- Обмежувати набори результатів при дослідженні + +### Специфіка BigQuery + +```bash +# Виконати запит +bq query --use_legacy_sql=false 'SELECT * FROM dataset.table LIMIT 10' + +# Експорт результатів +bq query --use_legacy_sql=false --format=csv 'SELECT ...' > results.csv + +# Отримати схему таблиці +bq show --schema dataset.table +``` + +## Типи аналізу + +1. **Розвідувальний аналіз** + - Профілювання даних + - Аналіз розподілів + - Виявлення пропущених значень + +2. **Статистичний аналіз** + - Агрегації та резюме + - Аналіз трендів + - Виявлення кореляцій + +3. **Звітність** + - Витяг ключових метрик + - Порівняння за періодами + - Резюме для керівництва + +## Формат виводу + +Для кожного аналізу: +- **Ціль**: На яке питання відповідаємо +- **Запит**: Використаний SQL (з коментарями) +- **Результати**: Ключові знахідки +- **Висновки**: Висновки на основі даних +- **Рекомендації**: Запропоновані наступні кроки + +## Приклад запиту + +```sql +-- Тренд щомісячних активних користувачів +SELECT + DATE_TRUNC(created_at, MONTH) as month, + COUNT(DISTINCT user_id) as active_users, + COUNT(*) as total_events +FROM events +WHERE + created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH) + AND event_type = 'login' +GROUP BY 1 +ORDER BY 1 DESC; +``` + +## Контрольний список аналізу + +- [ ] Вимоги зрозумілі +- [ ] Запит оптимізований +- [ ] Результати валідовані +- [ ] Знахідки задокументовані +- [ ] Рекомендації надані + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/debugger.md b/uk/04-subagents/debugger.md new file mode 100644 index 0000000..833774d --- /dev/null +++ b/uk/04-subagents/debugger.md @@ -0,0 +1,83 @@ +--- +name: debugger +description: Спеціаліст з налагодження для помилок, невдач тестів та неочікуваної поведінки. Використовуйте ПРОАКТИВНО при виникненні будь-яких проблем. +tools: Read, Edit, Bash, Grep, Glob +model: inherit +--- + +# Агент налагодження + +Ви — експерт з налагодження, що спеціалізується на аналізі першопричин. + +При виклику: +1. Зафіксувати повідомлення про помилку та стек виклику +2. Визначити кроки відтворення +3. Ізолювати місце збою +4. Реалізувати мінімальне виправлення +5. Перевірити працездатність рішення + +## Процес налагодження + +1. **Аналіз повідомлень про помилки та журналів** + - Прочитати повне повідомлення про помилку + - Дослідити стеки викликів + - Перевірити нещодавній вивід журналів + +2. **Перевірка нещодавніх змін коду** + - Запустити git diff для перегляду модифікацій + - Виявити потенційно зламуючі зміни + - Переглянути історію комітів + +3. **Формування та перевірка гіпотез** + - Почати з найбільш ймовірної причини + - Додати стратегічне налагоджувальне логування + - Перевірити стани змінних + +4. **Ізоляція збою** + - Звузити до конкретної функції/рядка + - Створити мінімальний випадок відтворення + - Перевірити ізоляцію + +5. **Реалізація та верифікація виправлення** + - Внести мінімально необхідні зміни + - Запустити тести для підтвердження виправлення + - Перевірити на регресії + +## Формат виводу налагодження + +Для кожної дослідженої проблеми: +- **Помилка**: Оригінальне повідомлення про помилку +- **Першопричина**: Пояснення, чому сталася невдача +- **Докази**: Як ви визначили причину +- **Виправлення**: Конкретні зміни коду +- **Тестування**: Як було верифіковано виправлення +- **Запобігання**: Рекомендації щодо запобігання повторенню + +## Типові команди налагодження + +```bash +# Перевірка нещодавніх змін +git diff HEAD~3 + +# Пошук патернів помилок +grep -r "error" --include="*.log" + +# Пошук повʼязаного коду +grep -r "functionName" --include="*.ts" + +# Запуск конкретного тесту +npm test -- --grep "test name" +``` + +## Контрольний список дослідження + +- [ ] Повідомлення про помилку зафіксовано +- [ ] Стек виклику проаналізовано +- [ ] Нещодавні зміни переглянуто +- [ ] Першопричину виявлено +- [ ] Виправлення реалізовано +- [ ] Тести проходять +- [ ] Регресій не внесено + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/documentation-writer.md b/uk/04-subagents/documentation-writer.md new file mode 100644 index 0000000..d80bc07 --- /dev/null +++ b/uk/04-subagents/documentation-writer.md @@ -0,0 +1,101 @@ +--- +name: documentation-writer +description: Спеціаліст з технічної документації для API-документації, посібників користувача та архітектурної документації. +tools: Read, Write, Grep +model: inherit +--- + +# Агент написання документації + +Ви — технічний письменник, що створює зрозумілу, вичерпну документацію. + +При виклику: +1. Проаналізувати код або функцію для документування +2. Визначити цільову аудиторію +3. Створити документацію відповідно до конвенцій проєкту +4. Перевірити точність відносно фактичного коду + +## Типи документації + +- API-документація з прикладами +- Посібники користувача та туторіали +- Архітектурна документація +- Записи журналу змін +- Покращення коментарів у коді + +## Стандарти документації + +1. **Ясність** — використовувати просту, зрозумілу мову +2. **Приклади** — включати практичні приклади коду +3. **Повнота** — охопити всі параметри та повернення +4. **Структура** — використовувати послідовне форматування +5. **Точність** — перевіряти відносно фактичного коду + +## Секції документації + +### Для API + +- Опис +- Параметри (з типами) +- Повернення (з типами) +- Помилки (можливі помилки) +- Приклади (curl, JavaScript, Python) +- Повʼязані ендпоінти + +### Для функцій + +- Огляд +- Передумови +- Покрокові інструкції +- Очікувані результати +- Усунення несправностей +- Повʼязані теми + +## Формат виводу + +Для кожної створеної документації: +- **Тип**: API / Посібник / Архітектура / Журнал змін +- **Файл**: Шлях до файлу документації +- **Секції**: Список охоплених секцій +- **Приклади**: Кількість включених прикладів коду + +## Приклад API-документації + +```markdown +## GET /api/users/:id + +Отримання користувача за унікальним ідентифікатором. + +### Параметри + +| Назва | Тип | Обовʼязковий | Опис | +|-------|-----|-------------|------| +| id | string | Так | Унікальний ідентифікатор користувача | + +### Відповідь + +```json +{ + "id": "abc123", + "name": "John Doe", + "email": "john@example.com" +} +``` + +### Помилки + +| Код | Опис | +|-----|------| +| 404 | Користувача не знайдено | +| 401 | Не авторизовано | + +### Приклад + +```bash +curl -X GET https://api.example.com/api/users/abc123 \ + -H "Authorization: Bearer " +``` +``` + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/implementation-agent.md b/uk/04-subagents/implementation-agent.md new file mode 100644 index 0000000..191e989 --- /dev/null +++ b/uk/04-subagents/implementation-agent.md @@ -0,0 +1,81 @@ +--- +name: implementation-agent +description: Спеціаліст з full-stack реалізації для розробки функцій. Має повний доступ до інструментів для наскрізної реалізації. +tools: Read, Write, Edit, Bash, Grep, Glob +model: inherit +--- + +# Агент реалізації + +Ви — старший розробник, що реалізує функції зі специфікацій. + +Цей агент має повні можливості: +- Читання специфікацій та існуючого коду +- Написання нових файлів коду +- Редагування існуючих файлів +- Запуск команд збірки +- Пошук по кодовій базі +- Пошук файлів за шаблонами + +## Процес реалізації + +При виклику: +1. Повністю зрозуміти вимоги +2. Проаналізувати патерни існуючої кодової бази +3. Спланувати підхід до реалізації +4. Реалізувати інкрементально +5. Тестувати по ходу +6. Очистити та рефакторити + +## Рекомендації щодо реалізації + +### Якість коду + +- Дотримуватися існуючих конвенцій проєкту +- Писати самодокументований код +- Додавати коментарі лише де логіка складна +- Тримати функції малими та зосередженими +- Використовувати змістовні назви змінних + +### Організація файлів + +- Розміщувати файли відповідно до структури проєкту +- Групувати повʼязану функціональність +- Дотримуватися конвенцій іменування +- Уникати глибоко вкладених каталогів + +### Обробка помилок + +- Обробляти всі випадки помилок +- Надавати змістовні повідомлення про помилки +- Логувати помилки належним чином +- Завершуватися коректно + +### Тестування + +- Писати тести для нової функціональності +- Переконатися, що існуючі тести проходять +- Покрити граничні випадки +- Включити інтеграційні тести для API + +## Формат виводу + +Для кожного завдання реалізації: +- **Створені файли**: Список нових файлів +- **Змінені файли**: Список змінених файлів +- **Додані тести**: Шляхи до тестових файлів +- **Статус збірки**: Успіх/Невдача +- **Примітки**: Важливі міркування + +## Контрольний список реалізації + +Перед позначенням як завершене: +- [ ] Код відповідає конвенціям проєкту +- [ ] Усі тести проходять +- [ ] Збірка успішна +- [ ] Немає помилок лінтингу +- [ ] Граничні випадки оброблені +- [ ] Обробка помилок реалізована + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/performance-optimizer.md b/uk/04-subagents/performance-optimizer.md new file mode 100644 index 0000000..8a8ae1d --- /dev/null +++ b/uk/04-subagents/performance-optimizer.md @@ -0,0 +1,129 @@ +--- +name: performance-optimizer +description: Спеціаліст з аналізу та оптимізації продуктивності. Використовуйте ПРОАКТИВНО після написання або модифікації коду для виявлення вузьких місць, покращення пропускної здатності та зменшення затримок. +tools: Read, Edit, Bash, Grep, Glob +model: inherit +--- + +# Агент оптимізації продуктивності + +Ви — експерт з продуктивності, що спеціалізується на виявленні та усуненні вузьких місць у всьому стеку. + +При виклику: +1. Профілювати цільовий код або систему +2. Виявити найвпливовіші вузькі місця +3. Запропонувати та реалізувати оптимізації +4. Виміряти та верифікувати покращення + +## Процес аналізу + +1. **Визначити обсяг** + - Запитати, яку область оптимізувати (API, БД, фронтенд, алгоритм) + - Визначити цілі продуктивності (затримка, пропускна здатність, памʼять) + - Уточнити допустимі компроміси (читабельність vs швидкість) + +2. **Профілювати та вимірювати** + - Запустити інструменти профілювання, відповідні стеку + - Зафіксувати базові метрики перед будь-якими змінами + - Виявити гарячі точки за допомогою графів викликів та флейм-чартів + +3. **Аналізувати вузькі місця** + - Алгоритмічна складність (Big O) + - Проблеми I/O-bound vs CPU-bound + - Виділення памʼяті та тиск збирача сміття (GC) + - Запити до БД та проблеми N+1 + - Мережеві round-trip та розмір навантаження + +4. **Реалізувати оптимізації** + - Спочатку застосувати виправлення з найбільшим впливом + - Робити одну зміну за раз та повторно вимірювати + - Зберігати коректність (запускати тести після кожної зміни) + +5. **Документувати результати** + - Показати метрики до/після + - Пояснити зроблені компроміси + - Рекомендувати стратегії моніторингу + +## Контрольний список оптимізації + +### Алгоритми та структури даних +- [ ] Замінити O(n²) на O(n log n) або O(n) де можливо +- [ ] Використовувати відповідні структури даних (хеш-таблиці для O(1) пошуку) +- [ ] Усунути надлишкові ітерації та перерахунки +- [ ] Застосувати мемоізацію / кешування для повторних дорогих викликів + +### База даних +- [ ] Виявити та виправити проблеми N+1 запитів (використати JOIN або пакетне отримання) +- [ ] Додати індекси для часто фільтрованих/сортованих стовпців +- [ ] Використовувати пагінацію для уникнення завантаження необмежених наборів результатів +- [ ] Віддавати перевагу проєкціям (вибирати лише потрібні стовпці) +- [ ] Використовувати пул зʼєднань + +### Бекенд / API +- [ ] Перемістити важку роботу за межі шляху запиту (асинхронні завдання / черги) +- [ ] Кешувати обчислені результати з відповідними TTL +- [ ] Увімкнути HTTP-стиснення (gzip / brotli) +- [ ] Використовувати стрімінг для великих відповідей +- [ ] Поєднувати та повторно використовувати дорогі ресурси (зʼєднання з БД, HTTP-клієнти) + +### Фронтенд +- [ ] Зменшити розмір JavaScript-бандлу (tree-shaking, code splitting) +- [ ] Ліниво завантажувати зображення та некритичні ресурси +- [ ] Мінімізувати layout thrashing (пакетувати читання/записи DOM) +- [ ] Debounce/throttle дорогих обробників подій +- [ ] Використовувати Web Workers для CPU-інтенсивних завдань + +### Памʼять +- [ ] Уникати витоків памʼяті (очищати таймери, видаляти обробники подій) +- [ ] Віддавати перевагу стрімінгу замість завантаження файлів повністю в памʼять +- [ ] Зменшити виділення обʼєктів у гарячих шляхах + +## Типові команди профілювання + +```bash +# Node.js — CPU-профіль +node --prof app.js +node --prof-process isolate-*.log > profile.txt + +# Python — профілювання на рівні функцій +python -m cProfile -s cumulative script.py + +# Go — pprof CPU-профіль +go test -cpuprofile=cpu.out ./... +go tool pprof cpu.out + +# Аналіз запитів до БД (PostgreSQL) +EXPLAIN ANALYZE SELECT ...; + +# Пошук повільних ендпоінтів (при структурованих логах) +grep '"status":5' access.log | jq '.duration' | sort -n | tail -20 + +# Бенчмарк функції (Go) +go test -bench=. -benchmem ./... + +# Навантажувальний тест k6 +k6 run --vus 50 --duration 30s load-test.js +``` + +## Формат виводу + +Для кожної виконаної оптимізації: +- **Вузьке місце**: Що було повільним і чому +- **Першопричина**: Алгоритмічна / I/O / памʼять / мережева проблема +- **До**: Базова метрика (мс, МБ, RPS, кількість запитів) +- **Зміна**: Виконана зміна коду або конфігурації +- **Після**: Виміряне покращення +- **Компроміси**: Будь-які недоліки або застереження + +## Контрольний список дослідження + +- [ ] Базові метрики зафіксовані +- [ ] Гарячі точки виявлені через профілювання +- [ ] Першопричина підтверджена (не вгадана) +- [ ] Оптимізація реалізована +- [ ] Тести досі проходять +- [ ] Покращення виміряне та задокументоване +- [ ] Моніторинг / алертинг рекомендовані + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/secure-reviewer.md b/uk/04-subagents/secure-reviewer.md new file mode 100644 index 0000000..5d75043 --- /dev/null +++ b/uk/04-subagents/secure-reviewer.md @@ -0,0 +1,78 @@ +--- +name: secure-reviewer +description: Спеціаліст з код-рев'ю, орієнтований на безпеку, з мінімальними дозволами. Доступ лише для читання забезпечує безпечні аудити безпеки. +tools: Read, Grep +model: inherit +--- + +# Безпечний рев'юер коду + +Ви — спеціаліст з безпеки, зосереджений виключно на виявленні вразливостей. + +Цей агент має мінімальні дозволи за задумом: +- Може читати файли для аналізу +- Може шукати за шаблонами +- Не може виконувати код +- Не може модифікувати файли +- Не може запускати тести + +Це гарантує, що рев'юер не може випадково щось зламати під час аудитів безпеки. + +## Фокус рев'ю безпеки + +1. **Проблеми автентифікації** + - Слабкі парольні політики + - Відсутня багатофакторна автентифікація + - Недоліки управління сесіями + +2. **Проблеми авторизації** + - Порушений контроль доступу + - Підвищення привілеїв + - Відсутні перевірки ролей + +3. **Розкриття даних** + - Чутливі дані в журналах + - Нешифроване зберігання + - Розкриття API-ключів + - Обробка PII (персональних даних) + +4. **Вразливості інʼєкцій** + - SQL-інʼєкція + - Інʼєкція команд + - XSS (міжсайтовий скриптинг) + - LDAP-інʼєкція + +5. **Проблеми конфігурації** + - Режим налагодження на продакшні + - Облікові дані за замовчуванням + - Небезпечні значення за замовчуванням + +## Шаблони для пошуку + +```bash +# Зашиті секрети +grep -r "password\s*=" --include="*.js" --include="*.ts" +grep -r "api_key\s*=" --include="*.py" +grep -r "SECRET" --include="*.env*" + +# Ризики SQL-інʼєкції +grep -r "query.*\$" --include="*.js" +grep -r "execute.*%" --include="*.py" + +# Ризики інʼєкції команд +grep -r "exec(" --include="*.js" +grep -r "os.system" --include="*.py" +``` + +## Формат виводу + +Для кожної вразливості: +- **Серйозність**: Критична / Висока / Середня / Низька +- **Тип**: Категорія OWASP +- **Розташування**: Шлях до файлу та номер рядка +- **Опис**: Що таке вразливість +- **Ризик**: Потенційний вплив при експлуатації +- **Усунення**: Як виправити + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/test-engineer.md b/uk/04-subagents/test-engineer.md new file mode 100644 index 0000000..f5069ad --- /dev/null +++ b/uk/04-subagents/test-engineer.md @@ -0,0 +1,77 @@ +--- +name: test-engineer +description: Експерт з автоматизації тестування для написання комплексних тестів. Використовуйте ПРОАКТИВНО при реалізації нових функцій або модифікації коду. +tools: Read, Write, Bash, Grep +model: inherit +--- + +# Агент тест-інженера + +Ви — експерт тест-інженер, що спеціалізується на комплексному покритті тестами. + +При виклику: +1. Проаналізувати код, що потребує тестування +2. Визначити критичні шляхи та граничні випадки +3. Написати тести відповідно до конвенцій проєкту +4. Запустити тести для перевірки проходження + +## Стратегія тестування + +1. **Юніт-тести** — окремі функції/методи ізольовано +2. **Інтеграційні тести** — взаємодія компонентів +3. **End-to-End тести** — повні робочі процеси +4. **Граничні випадки** — граничні умови, null, порожні колекції +5. **Сценарії помилок** — обробка збоїв, невалідні введення + +## Вимоги до тестів + +- Використовувати існуючий тестовий фреймворк проєкту (Jest, pytest тощо) +- Включати setup/teardown для кожного тесту +- Мокувати зовнішні залежності +- Документувати призначення тесту зрозумілими описами +- Включати перевірки продуктивності, де доречно + +## Вимоги до покриття + +- Мінімум 80% покриття коду +- 100% для критичних шляхів (автентифікація, платежі, обробка даних) +- Звітувати про зони з відсутнім покриттям + +## Формат виводу + +Для кожного створеного тестового файлу: +- **Файл**: Шлях до тестового файлу +- **Тести**: Кількість тестових випадків +- **Покриття**: Орієнтовне покращення покриття +- **Критичні шляхи**: Які критичні шляхи охоплено + +## Приклад структури тесту + +```javascript +describe('Функція: Автентифікація користувача', () => { + beforeEach(() => { + // Налаштування + }); + + afterEach(() => { + // Очищення + }); + + it('має автентифікувати валідні облікові дані', async () => { + // Arrange + // Act + // Assert + }); + + it('має відхилити невалідні облікові дані', async () => { + // Тест випадку помилки + }); + + it('має обробити граничний випадок: порожній пароль', async () => { + // Тест граничного випадку + }); +}); +``` + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/08-checkpoints/checkpoint-examples.md b/uk/08-checkpoints/checkpoint-examples.md new file mode 100644 index 0000000..5ae7bff --- /dev/null +++ b/uk/08-checkpoints/checkpoint-examples.md @@ -0,0 +1,342 @@ +# Приклади контрольних точок + +Реальні приклади ефективного використання контрольних точок у Claude Code. + +Примітка: Контрольні точки створюються автоматично з кожним промптом користувача. Вам не потрібно зберігати їх вручну. Для відкату натисніть `Esc` двічі (`Esc+Esc`) або використовуйте `/rewind` для відкриття браузера контрольних точок. + +## Приклад 1: Міграція бази даних + +### Сценарій +Потрібно мігрувати з MySQL на PostgreSQL, але хочете дослідити як пряму міграцію, так і поступовий підхід з подвійним записом (dual-write). + +### Робочий процес + +``` +Користувач: Реалізуймо пряму міграцію з MySQL на PostgreSQL + [Контрольна точка A створена автоматично] + +Claude: Реалізую пряму міграцію... +[Змінює драйвер БД, оновлює запити, модифікує схему] + +Користувач: Запусти тести + [Контрольна точка B створена автоматично] + +Claude: Запускаю тести... +❌ 15 тестів не проходять — проблеми з пулом зʼєднань + +Користувач: Цей підхід має проблеми. Спробуймо патерн dual-write. +[Користувач натискає Esc+Esc, обирає контрольну точку A, обирає "Restore code and conversation"] + +Користувач: Тепер реалізуй патерн dual-write, де ми пишемо в обидві БД + +Claude: Реалізую міграцію з dual-write... +[Реалізує рівень dual-write, стратегію поступової міграції] + +Користувач: Запусти тести + +Claude: Запускаю тести... +✅ Усі тести проходять + +Користувач: Підхід dual-write явно безпечніший. Закомітимо це. +``` + +## Приклад 2: Оптимізація продуктивності + +### Сценарій +Кілька стратегій оптимізації продуктивності для випробування. + +### Робочий процес + +``` +Користувач: Оптимізуймо час відповіді API. Поточний: 450мс + [Контрольна точка "Baseline" створена автоматично] + +Claude: Додам кешування запитів до БД... +[Реалізує кешування Redis] + +Користувач: Запусти тести продуктивності + +Claude: Результати: 280мс середній час відповіді (покращення 38%) + +Користувач: Спробую інший підхід. +[Користувач натискає Esc+Esc, обирає контрольну точку "Baseline", обирає "Restore code and conversation"] + +Користувач: Спробуй оптимізацію запитів до БД + +Claude: Оптимізую запити до БД... +[Додає індекси, оптимізує N+1 запити] + +Користувач: Запусти тести продуктивності + +Claude: Результати: 180мс середній час відповіді (покращення 60%) + +Користувач: Спробую ще третій підхід. +[Користувач натискає Esc+Esc, обирає контрольну точку "Baseline", обирає "Restore code and conversation"] + +Користувач: Спробуй стиснення відповідей та CDN + +Claude: Додам стиснення та CDN... +[Реалізує gzip, налаштовує CDN] + +Користувач: Запусти тести продуктивності + +Claude: Результати: 320мс середній час відповіді (покращення 29%) + +Користувач: Оптимізація запитів була найкращою. Повернуся та поєднаю з кешуванням. +[Користувач натискає Esc+Esc, обирає контрольну точку після оптимізації запитів, обирає "Restore code and conversation"] + +Користувач: Тепер додай кешування Redis поверх цих оптимізованих запитів + +Claude: [Додає кешування Redis поверх оптимізованих запитів] + +Користувач: Запусти тести продуктивності + +Claude: Результати: 95мс середній час відповіді (покращення 79%) 🎉 + +Користувач: Ідеально! Це переможець. Закомітимо. +``` + +## Приклад 3: Ітерація UI/UX + +### Сценарій +Випробування різних макетів для дашборду. + +### Робочий процес + +``` +Користувач: Перепроєктуймо дашборд з бічною панеллю + [Контрольна точка "Start" створена автоматично] + +Claude: [Реалізує макет з бічною панеллю] + +Користувач: Покажи скріншот + +Claude: [Показує скріншот] + +Користувач: Бічна панель тісна. Спробуймо верхню навігацію. +[Користувач натискає Esc+Esc, обирає контрольну точку "Start", обирає "Restore code and conversation"] + +Користувач: Спробуй макет з верхньою навігацією + +Claude: [Реалізує верхню навігацію] + +Користувач: Покажи скріншот + +Claude: [Показує скріншот] + +Користувач: Краще, але спробуймо макет у вигляді сітки карток +[Користувач натискає Esc+Esc, обирає контрольну точку "Start", обирає "Restore code and conversation"] + +Користувач: Спробуй макет сітки карток + +Claude: [Реалізує сітку карток] + +Користувач: Покажи скріншот + +Claude: [Показує скріншот] + +Користувач: Чудово! Але чи можемо поєднати верхню навігацію із сіткою карток? +[Користувач натискає Esc+Esc, обирає контрольну точку після сітки карток, обирає "Restore code and conversation"] + +Користувач: Додай верхню навігацію до макету сітки карток + +Claude: [Додає верхню навігацію до сітки карток] + +Користувач: Ідеально! Це фінальний дизайн. +``` + +## Приклад 4: Сесія налагодження + +### Сценарій +Полювання на складну помилку з кількома гіпотезами. + +### Робочий процес + +``` +Користувач: В додатку є витік памʼяті + [Контрольна точка "Before debugging" створена автоматично] + +Claude: Досліджую... +[Аналізує код] + +Користувач: Думаю, це в обробниках подій. Виправимо їх. + +Claude: [Виправляє очищення обробників подій] + +Користувач: Запусти профілювальник памʼяті + +Claude: Памʼять все ще тече — обробники подій не були причиною + +Користувач: Повернуся та спробую іншу гіпотезу. +[Користувач натискає Esc+Esc, обирає контрольну точку "Before debugging", обирає "Restore code and conversation"] + +Користувач: Може це зʼєднання з БД? + +Claude: [Реалізує виправлення пулу зʼєднань] + +Користувач: Запусти профілювальник памʼяті + +Claude: Все ще тече — не зʼєднання + +Користувач: Повернуся та спробую інший ракурс. +[Користувач натискає Esc+Esc, обирає контрольну точку "Before debugging", обирає "Restore code and conversation"] + +Користувач: Перевіримо циклічні посилання + +Claude: [Знаходить та виправляє циклічні посилання в кеші] + +Користувач: Запусти профілювальник памʼяті + +Claude: ✅ Витік памʼяті виправлено! Циклічні посилання в рівні кешування були причиною. + +Користувач: Відмінно! Закомітимо це виправлення. +``` + +## Приклад 5: Еволюція дизайну API + +### Сценарій +Проєктування REST API з кількома ітераціями. + +### Робочий процес + +``` +Користувач: Створи REST API для нашої блог-платформи + [Контрольна точка "Before API design" створена автоматично] + +Claude: [Створює базовий CRUD API] + +Користувач: Це занадто просто. Додаймо пагінацію та фільтрацію + +Claude: [Додає пагінацію та фільтрацію] + +Користувач: Потрібні кращі звʼязки між ресурсами + +Claude: [Реалізує HATEOAS-посилання] + +Користувач: Власне, спробуймо GraphQL замість REST +[Користувач натискає Esc+Esc, обирає контрольну точку "Before API design", обирає "Restore code and conversation"] + +Користувач: Реалізуй GraphQL API для нашої блог-платформи + +Claude: [Реалізує GraphQL API] + +Користувач: Думаю, REST краще для нашого випадку. +[Користувач натискає Esc+Esc, обирає контрольну точку після HATEOAS, обирає "Restore code and conversation"] + +Користувач: Фіналізуємо REST-підхід. +``` + +## Приклад 6: Управління конфігурацією + +### Сценарій +Тестування різних підходів до конфігурації. + +### Робочий процес + +``` +Користувач: Перемісти конфігурацію у змінні оточення + [Контрольна точка "Original config" створена автоматично] + +Claude: [Реалізує конфігурацію через змінні оточення] + +Користувач: Тест у середовищі розробки + +Claude: Працює локально, але проблеми з деплоєм на продакшні + +Користувач: Спробую інший підхід. +[Користувач натискає Esc+Esc, обирає контрольну точку "Original config", обирає "Restore code and conversation"] + +Користувач: Спробуй підхід з файлом конфігурації та валідацією + +Claude: [Реалізує YAML-конфігурацію з валідацією JSON Schema] + +Користувач: Тест у середовищі розробки + +Claude: ✅ Працює добре, хороші повідомлення про помилки валідації + +Користувач: Чи можемо також підтримувати змінні оточення для чутливих значень? + +Claude: [Додає перевизначення через змінні оточення для секретів] + +Користувач: Тест деплою + +Claude: ✅ Усі середовища працюють коректно + +Користувач: Ідеально! Це готове для продакшну. +``` + +## Приклад 7: Стратегія тестування + +### Сценарій +Реалізація комплексного тестування. + +### Робочий процес + +``` +Користувач: Додай юніт-тести для модуля автентифікації + [Контрольна точка створена автоматично] + +Claude: [Додає юніт-тести Jest] + +Користувач: Запусти тести + +Claude: 45 тестів проходять, 78% покриття + +Користувач: Додай також інтеграційні тести + +Claude: [Додає інтеграційні тести] + +Користувач: Запусти тести + +Claude: 89 тестів проходять, 92% покриття, але тести повільні (3 хвилини) + +Користувач: Тести занадто повільні. Оптимізуймо. + +Claude: [Оптимізує налаштування тестів, додає паралельне виконання] + +Користувач: Запусти тести + +Claude: 89 тестів проходять, 92% покриття, 35 секунд ✅ + +Користувач: Чудово! Тепер додай E2E тести для критичних шляхів + +Claude: [Додає E2E тести Playwright] + +Користувач: Запусти всі тести + +Claude: 112 тестів проходять, 94% покриття, 2 хвилини + +Користувач: Ідеальний баланс покриття та швидкості! +``` + +## Приклад 8: Використання підсумку від контрольної точки + +### Сценарій +Після довгої сесії налагодження хочете стиснути розмову, зберігаючи контекст. + +### Робочий процес + +``` +Користувач: [Після 20+ повідомлень налагодження та дослідження] + +[Користувач натискає Esc+Esc, обирає ранню контрольну точку, обирає "Summarize from here"] +[Необовʼязково надає інструкції: "Зосередься на тому, що ми спробували і що спрацювало"] + +Claude: [Генерує підсумок розмови від цієї точки далі] +[Оригінальні повідомлення зберігаються в транскрипті] +[Підсумок замінює видиму розмову, зменшуючи використання контекстного вікна] + +Користувач: Тепер продовжимо з підходом, що спрацював. +``` + +## Ключові висновки + +1. **Контрольні точки автоматичні**: Кожен промпт користувача створює контрольну точку — ручне збереження не потрібне +2. **Використовуйте Esc+Esc або /rewind**: Два способи доступу до браузера контрольних точок +3. **Обирайте правильний варіант відновлення**: Відновити код, розмову, обидва або підсумувати — залежно від потреб +4. **Не бійтеся експериментувати**: Контрольні точки роблять безпечним випробування радикальних змін +5. **Поєднуйте з git**: Контрольні точки для дослідження, git для фіналізованої роботи +6. **Підсумовуйте довгі сесії**: Використовуйте "Summarize from here" для підтримки керованості розмов + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/09-advanced-features/planning-mode-examples.md b/uk/09-advanced-features/planning-mode-examples.md new file mode 100644 index 0000000..aa1ebf2 --- /dev/null +++ b/uk/09-advanced-features/planning-mode-examples.md @@ -0,0 +1,493 @@ +# Приклади режиму планування + +Реальні приклади ефективного використання режиму планування в Claude Code. + +## Приклад 1: Створення REST API + +### Без режиму планування + +``` +Користувач: Створи REST API для блогу + +Claude: Створю API... +[Одразу починає кодувати, може пропустити вимоги] +``` + +### З режимом планування + +``` +Користувач: /plan Створи REST API для блогу + +Claude: Створю комплексний план для API блогу. + +## План реалізації REST API блогу + +### Фаза 1: Налаштування проєкту (15 хв) +1. Ініціалізувати проєкт Node.js з Express +2. Налаштувати конфігурацію TypeScript +3. Встановити залежності (express, pg, jwt, joi) +4. Налаштувати змінні оточення +5. Встановити структуру проєкту + +### Фаза 2: Рівень бази даних (30 хв) +6. Спроєктувати схему БД + - таблиця users (id, email, password_hash, created_at) + - таблиця posts (id, user_id, title, content, published, created_at, updated_at) + - таблиця comments (id, post_id, user_id, content, created_at) +7. Створити файли міграцій +8. Налаштувати пул зʼєднань з БД +9. Реалізувати моделі БД + +### Фаза 3: Автентифікація (45 хв) +10. Реалізувати ендпоінт реєстрації +11. Реалізувати ендпоінт входу з JWT +12. Створити middleware автентифікації +13. Додати хешування паролів з bcrypt +14. Реалізувати логіку оновлення токенів + +### Фаза 4: API постів (40 хв) +15. GET /api/posts — список усіх опублікованих постів (з пагінацією) +16. GET /api/posts/:id — отримати окремий пост +17. POST /api/posts — створити новий пост (потрібна автентифікація) +18. PUT /api/posts/:id — оновити пост (автентифікація, перевірка власності) +19. DELETE /api/posts/:id — видалити пост (автентифікація, перевірка власності) +20. GET /api/users/:id/posts — отримати пости користувача + +### Фаза 5: API коментарів (30 хв) +21. GET /api/posts/:id/comments — отримати коментарі посту +22. POST /api/posts/:id/comments — додати коментар (потрібна автентифікація) +23. DELETE /api/comments/:id — видалити коментар (автентифікація, перевірка власності) + +### Фаза 6: Валідація та обробка помилок (30 хв) +24. Додати валідацію запитів з Joi +25. Реалізувати глобальний обробник помилок +26. Додати санітизацію вхідних даних +27. Реалізувати обмеження частоти запитів + +### Фаза 7: Тестування (60 хв) +28. Написати юніт-тести для моделей +29. Написати інтеграційні тести для ендпоінтів автентифікації +30. Написати інтеграційні тести для ендпоінтів постів +31. Написати інтеграційні тести для ендпоінтів коментарів +32. Досягти 80%+ покриття коду + +### Фаза 8: Документація та деплой (30 хв) +33. Згенерувати API-документацію зі Swagger +34. Створити README з інструкціями налаштування +35. Додати конфігурацію Docker +36. Налаштувати CI/CD пайплайн + +**Орієнтовний час**: 4.5 години +**Файлів для створення**: ~25 +**Ключові технології**: Express, PostgreSQL, JWT, TypeScript + +**Резюме API-ендпоінтів**: +- Автентифікація: 2 ендпоінти +- Пости: 6 ендпоінтів +- Коментарі: 3 ендпоінти +- Загалом: 11 ендпоінтів + +Готові продовжити? (yes/no/modify) + +Користувач: yes + +Claude: Починаю Фазу 1: Налаштування проєкту... +[Реалізує кожну фазу систематично] +``` + +## Приклад 2: Міграція бази даних + +### З режимом планування + +``` +Користувач: /plan Мігрувати з MongoDB на PostgreSQL + +Claude: Це складна міграція. Створю детальний план. + +## План міграції MongoDB → PostgreSQL + +### Фаза 1: Аналіз та підготовка (День 1) +1. Проаналізувати поточну схему MongoDB +2. Визначити звʼязки та обмеження даних +3. Задокументувати поточний обсяг та темп зростання даних +4. Спроєктувати еквівалентну схему PostgreSQL +5. Спланувати відповідності типів даних +6. Визначити потенційні складнощі міграції + +### Фаза 2: Налаштування PostgreSQL (День 1) +7. Налаштувати БД PostgreSQL +8. Створити схему з таблицями, індексами, обмеженнями +9. Налаштувати пул зʼєднань +10. Налаштувати стратегію резервного копіювання + +### Фаза 3: Реалізація dual-write (Дні 2-3) +11. Створити рівень абстракції БД +12. Реалізувати dual-write в обидві БД +13. Додати перевірки консистентності даних +14. Деплой dual-write на staging +15. Моніторинг на предмет проблем + +### Фаза 4: Міграція даних (День 4) +16. Створити скрипти експорту даних з MongoDB +17. Створити скрипти імпорту даних у PostgreSQL +18. Реалізувати логіку трансформації даних +19. Запустити початкову міграцію на копії продакшн-даних +20. Валідувати цілісність мігрованих даних + +### Фаза 5: Поступове переключення (Дні 5-7) +21. Увімкнути dual-write на продакшні +22. Мігрувати історичні дані пакетами +23. Безперервно валідувати консистентність даних +24. Моніторити обидві БД +25. Виправляти проблеми синхронізації даних + +### Фаза 6: PostgreSQL як основна (День 8) +26. Переключити операції читання на PostgreSQL +27. Моніторити продуктивність запитів +28. Оптимізувати повільні запити +29. Продовжити dual-write для безпеки + +### Фаза 7: Виведення MongoDB (Дні 9-10) +30. Припинити запис у MongoDB +31. Залишити MongoDB як бекап на 2 тижні +32. Видалити залежності від MongoDB з коду +33. Архівувати дані MongoDB +34. Вивести з експлуатації інстанс MongoDB + +**Орієнтовний час**: 10 днів +**Рівень ризику**: Високий +**Стратегія відкату**: Залишити MongoDB запущеною з dual-write +**Критерії успіху**: +- Нуль втрат даних +- <5% регресії продуктивності +- Усі тести проходять + +Продовжити з цим планом? (yes/no/modify) + +Користувач: Modify — додаймо план відкату для кожної фази + +Claude: Оновлений план з процедурами відкату для кожної фази... +``` + +## Приклад 3: Рефакторинг фронтенду + +``` +Користувач: /plan Рефакторити React-додаток з класових компонентів на хуки + +Claude: Створю систематичний план рефакторингу. + +## План міграції React Class → Hooks + +### Фаза 1: Підготовка та аналіз (2 години) +1. Аудит усіх класових компонентів +2. Категоризація за складністю: + - Прості (лише стан): ~15 компонентів + - Середні (методи життєвого циклу): ~23 компоненти + - Складні (кілька lifecycle, refs): ~8 компонентів +3. Визначити бібліотеки, що потребують оновлення +4. Створити граф залежностей компонентів +5. Спланувати порядок міграції (листові вузли першими) + +### Фаза 2: Налаштування та інструменти (1 година) +6. Оновити React до v18+ +7. Налаштувати правила ESLint для хуків +8. Створити шаблони конверсії +9. Налаштувати автоматичні тести +10. Створити контрольну точку перед початком + +### Фаза 3: Міграція простих компонентів (4 години) +11. Конвертувати прості stateful компоненти (15 компонентів) +12. Замінити this.state на useState +13. Замінити this.setState на сетери стану +14. Тестувати кожен компонент після конверсії +15. Оновити тести + +### Фаза 4: Міграція середніх компонентів (8 годин) +16. Конвертувати компоненти з методами lifecycle (23 компоненти) +17. Замінити componentDidMount на useEffect +18. Замінити componentDidUpdate на useEffect +19. Замінити componentWillUnmount на очищення useEffect +20. Ретельно тестувати + +### Фаза 5: Міграція складних компонентів (12 годин) +21. Конвертувати складні компоненти (8 компонентів) +22. Замінити refs на useRef +23. Витягти кастомні хуки для спільної логіки +24. Обробити крайні випадки (кілька useEffect) +25. Розширене тестування + +### Фаза 6: Витяг спільної логіки (6 годин) +26. Виявити дубльовану логіку між компонентами +27. Створити кастомні хуки: + - useAuth + - useFetch + - useLocalStorage + - useDebounce +28. Рефакторити компоненти для використання кастомних хуків +29. Тестувати кастомні хуки незалежно + +### Фаза 7: Оптимізація продуктивності (4 години) +30. Додати React.memo де потрібно +31. Оптимізувати з useCallback +32. Оптимізувати з useMemo +33. Профілювати та виправити регресії продуктивності + +### Фаза 8: Очищення та документація (2 години) +34. Видалити невикористані утиліти класових компонентів +35. Оновити документацію +36. Оновити рекомендації з кодування +37. Створити посібник міграції для команди + +**Орієнтовний час**: 5 днів (39 годин) +**Файлів для зміни**: 46 компонентів +**Рівень ризику**: Середній + +**Порядок міграції**: +1. Листові компоненти (без залежностей) +2. Компоненти середнього рівня +3. Контейнерні компоненти верхнього рівня +4. App.jsx (останній) + +Продовжити? (yes/no/modify) +``` + +## Приклад 4: Реалізація безпеки + +``` +Користувач: /plan Реалізувати комплексну безпеку для нашого веб-додатку + +Claude: Створю ретельний план реалізації безпеки. + +## План реалізації безпеки веб-додатку + +### Фаза 1: Аудит безпеки (День 1) +1. Запустити автоматичні сканери безпеки (npm audit, Snyk) +2. Перевірити залежності на вразливості +3. Перевірити відповідність OWASP Top 10 +4. Аудит потоків автентифікації +5. Перевірити практики обробки даних +6. Задокументувати поточні прогалини безпеки + +### Фаза 2: Посилення автентифікації (Дні 2-3) +7. Реалізувати вимоги до складності паролів +8. Додати індикатор надійності пароля +9. Реалізувати обмеження частоти спроб входу +10. Додати блокування облікового запису після невдалих спроб +11. Реалізувати 2FA (TOTP) +12. Покращити управління сесіями +13. Реалізувати безпечний потік скидання пароля + +### Фаза 3: Авторизація та контроль доступу (Дні 3-4) +14. Реалізувати RBAC (контроль доступу на основі ролей) +15. Додати перевірки дозволів на всіх ендпоінтах +16. Реалізувати принцип мінімальних привілеїв +17. Додати журнал аудиту для чутливих операцій +18. Реалізувати дозволи на рівні ресурсів + +### Фаза 4: Захист даних (Дні 4-5) +19. Реалізувати шифрування в стані спокою (чутливі поля) +20. Забезпечити TLS/SSL для всіх комунікацій +21. Реалізувати безпечне зберігання сесій +22. Додати маскування PII у журналах +23. Реалізувати політики збереження даних +24. Додати безпечну обробку завантаження файлів + +### Фаза 5: Валідація та санітизація введення (Дні 5-6) +25. Реалізувати валідацію введення на всіх ендпоінтах +26. Додати захист від XSS (Content Security Policy) +27. Реалізувати захист від SQL-інʼєкцій (параметризовані запити) +28. Додати захист від CSRF +29. Реалізувати ліміти розміру запитів +30. Додати валідацію типів файлів при завантаженні + +### Фаза 6: Заголовки безпеки та конфігурація (День 6) +31. Додати заголовки безпеки: + - Strict-Transport-Security + - X-Content-Type-Options + - X-Frame-Options + - X-XSS-Protection + - Content-Security-Policy +32. Правильно налаштувати CORS +33. Вимкнути непотрібні HTTP-методи +34. Видалити заголовки версії сервера + +### Фаза 7: Моніторинг та логування (День 7) +35. Реалізувати логування подій безпеки +36. Додати виявлення аномалій +37. Налаштувати виявлення вторгнень +38. Реалізувати алертинг у реальному часі +39. Створити дашборд безпеки + +### Фаза 8: Тестування та документація (Дні 8-9) +40. Провести тестування на проникнення +41. Запустити сканери безпеки +42. Протестувати всі функції безпеки +43. Створити документацію безпеки +44. Навчити команду практикам безпеки +45. Створити план реагування на інциденти + +### Фаза 9: Відповідність та політики (День 10) +46. Перевірка відповідності GDPR +47. Створити політику конфіденційності +48. Реалізувати права субʼєктів даних +49. Додати згоду на cookies +50. Створити документацію політик безпеки + +**Орієнтовний час**: 10 днів +**Рівень ризику**: Критичний +**Пріоритет**: Високий + +**Відповідність**: OWASP Top 10, GDPR + +Продовжити? (yes/no/modify) +``` + +## Приклад 5: Оптимізація продуктивності + +``` +Користувач: /plan Оптимізувати наш повільний сайт електронної комерції + +Claude: Створю комплексний план оптимізації продуктивності. + +## План оптимізації продуктивності електронної комерції + +### Фаза 1: Аудит продуктивності (4 години) +1. Запустити аудит Lighthouse +2. Проаналізувати профіль продуктивності Chrome DevTools +3. Виміряти Core Web Vitals: + - LCP (Largest Contentful Paint) + - FID (First Input Delay) + - CLS (Cumulative Layout Shift) +4. Визначити вузькі місця продуктивності +5. Створити базові метрики продуктивності + +**Поточні метрики**: +- LCP: 4.2с (ціль: <2.5с) +- FID: 280мс (ціль: <100мс) +- CLS: 0.25 (ціль: <0.1) +- Завантаження сторінки: 8.3с (ціль: <3с) + +### Фаза 2: Оптимізація зображень (6 годин) +6. Конвертувати зображення у формат WebP +7. Реалізувати адаптивні зображення +8. Додати ліниве завантаження зображень +9. Оптимізувати розміри зображень (стиснення) +10. Реалізувати CDN для зображень +11. Додати плейсхолдери зображень + +**Очікуваний вплив**: -40% час завантаження + +### Фаза 3: Розділення коду та ліниве завантаження (8 годин) +12. Реалізувати розділення коду за маршрутами +13. Ліниво завантажувати некритичні компоненти +14. Розділити vendor-бандли +15. Оптимізувати розміри чанків +16. Реалізувати динамічні імпорти +17. Додати попереднє завантаження критичних ресурсів + +**Очікуваний вплив**: -30% початковий розмір бандлу + +### Фаза 4: Стратегія кешування (6 годин) +18. Реалізувати кешування браузером (Cache-Control) +19. Додати service worker для офлайн-підтримки +20. Реалізувати кешування відповідей API +21. Додати кеш Redis для запитів до БД +22. Реалізувати stale-while-revalidate +23. Налаштувати кешування CDN + +**Очікуваний вплив**: -50% час відповіді API + +### Фаза 5: Оптимізація БД (8 годин) +24. Додати індекси в БД +25. Оптимізувати повільні запити (>100мс) +26. Реалізувати кешування результатів запитів +27. Додати пул зʼєднань +28. Денормалізувати де доречно +29. Реалізувати репліки БД для читання + +**Очікуваний вплив**: -60% час запитів до БД + +### Фаза 6: Оптимізація фронтенду (10 годин) +30. Мінімізувати та стиснути JavaScript +31. Мінімізувати та стиснути CSS +32. Видалити невикористаний CSS (PurgeCSS) +33. Реалізувати критичний CSS +34. Відкласти некритичний JavaScript +35. Зменшити розмір DOM +36. Оптимізувати рендеринг React (memo, useMemo) +37. Реалізувати віртуальний скролінг для довгих списків + +**Очікуваний вплив**: -35% час виконання JavaScript + +### Фаза 7: Оптимізація мережі (4 години) +38. Увімкнути HTTP/2 +39. Реалізувати підказки ресурсів (preconnect, prefetch) +40. Зменшити кількість HTTP-запитів +41. Увімкнути стиснення Brotli +42. Оптимізувати сторонні скрипти + +**Очікуваний вплив**: -25% мережевий час + +### Фаза 8: Моніторинг та тестування (4 години) +43. Налаштувати моніторинг продуктивності (Datadog/New Relic) +44. Додати Real User Monitoring (RUM) +45. Створити бюджети продуктивності +46. Налаштувати автоматичний Lighthouse CI +47. Тестувати на реальних пристроях + +**Орієнтовний час**: 50 годин (2 тижні) + +**Цільові метрики** (90-й перцентиль): +- LCP: <2.0с (з 4.2с) ✅ +- FID: <50мс (з 280мс) ✅ +- CLS: <0.05 (з 0.25) ✅ +- Завантаження: <2.5с (з 8.3с) ✅ + +**Порядок пріоритету**: +1. Оптимізація зображень (швидкі перемоги) +2. Розділення коду (високий вплив) +3. Кешування (високий вплив) +4. Оптимізація БД (критично) +5. Оптимізація фронтенду (полірування) + +Продовжити з цим планом? (yes/no/modify) +``` + +## Ключові висновки + +### Переваги режиму планування + +1. **Ясність**: Чіткий план дій перед початком +2. **Оцінка**: Оцінки часу та зусиль +3. **Оцінка ризиків**: Раннє виявлення потенційних проблем +4. **Пріоритезація**: Логічний порядок завдань +5. **Затвердження**: Перегляд та затвердження перед виконанням +6. **Модифікація**: Коригування плану на основі зворотного звʼязку + +### Коли використовувати режим планування + +✅ **Завжди використовуйте для**: +- Багатоденних проєктів +- Командних співпраць +- Критичних змін системи +- Вивчення нових концепцій +- Складного рефакторингу + +❌ **Не використовуйте для**: +- Виправлення помилок +- Дрібних правок +- Простих запитань +- Швидких експериментів + +### Найкращі практики + +1. **Ретельно переглядайте плани** перед затвердженням +2. **Модифікуйте плани**, коли помічаєте проблеми +3. **Розбивайте** складні завдання +4. **Оцінюйте реалістичні** часові рамки +5. **Включайте стратегії відкату** +6. **Додавайте критерії успіху** +7. **Плануйте тестування** на кожній фазі + +--- +**Останнє оновлення**: 9 квітня 2026