A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
feat(uk): translate P3 examples for skills/refactor, subagents, checkpoints, advanced
Evgenij Ib56f1e111abb
diff --git a/uk/04-subagents/README.md b/uk/04-subagents/README.mdnew file mode 100644index 0000000..6786dc1--- /dev/null+++ b/uk/04-subagents/README.md@@ -0,0 +1,1118 @@+<!-- i18n-source: 04-subagents/README.md -->+<!-- i18n-source-sha: 63a1416 -->+<!-- i18n-date: 2026-04-09 -->++<picture>+ <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">+ <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">+</picture>++# Субагенти — повний довідник++Субагенти — це спеціалізовані 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/<n>/` | Персональні нотатки та налаштування для всіх проєктів |+| `project` | `.claude/agent-memory/<n>/` | Знання, специфічні для проєкту, спільні з командою |+| `local` | `.claude/agent-memory-local/<n>/` | Локальні знання проєкту, не комітяться у контроль версій |++### Як це працює++- Перші 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<br/>Session 1"] -->|writes| M["MEMORY.md<br/>(persistent)"]+ M -->|loads into| B["Subagent<br/>Session 2"]+ B -->|updates| M+ M -->|loads into| C["Subagent<br/>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<br/>Isolated Worktree"]+ Sub -->|makes changes in| WT["Separate Git<br/>Worktree + Branch"]+ WT -->|no changes| Clean["Auto-cleaned"]+ WT -->|has changes| Return["Returns worktree<br/>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<br/>(Coordinator)"]+ TaskList["Shared Task List<br/>(Dependencies)"]+ Mailbox["Mailbox<br/>(Messages)"]+ T1["Teammate 1<br/>(Own Context)"]+ T2["Teammate 2<br/>(Own Context)"]+ T3["Teammate 3<br/>(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<br/>(Coordinator)"]+ Reviewer["Code Reviewer<br/>Subagent"]+ Tester["Test Engineer<br/>Subagent"]+ Docs["Documentation<br/>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<br/>Subagent+ participant Context as Separate<br/>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<br/>50,000 tokens"]+ B["Subagent 1 Context<br/>20,000 tokens"]+ C["Subagent 2 Context<br/>20,000 tokens"]+ D["Subagent 3 Context<br/>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<br/>(Context)"]+ Main -->|Queries| MCP["MCP<br/>(Live Data)"]+ Main -->|Invokes| Skills["Skills<br/>(Auto Tools)"]+ Main -->|Delegates| Subagents["Subagents<br/>(Specialists)"]++ Subagents -->|Use| Memory+ Subagents -->|Query| MCP+ Subagents -->|Isolated| Context["Clean Context<br/>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.5diff --git a/uk/04-subagents/clean-code-reviewer.md b/uk/04-subagents/clean-code-reviewer.mdnew file mode 100644index 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 квітня 2026diff --git a/uk/04-subagents/code-reviewer.md b/uk/04-subagents/code-reviewer.mdnew file mode 100644index 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 квітня 2026diff --git a/uk/04-subagents/data-scientist.md b/uk/04-subagents/data-scientist.mdnew file mode 100644index 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 квітня 2026diff --git a/uk/04-subagents/debugger.md b/uk/04-subagents/debugger.mdnew file mode 100644index 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 квітня 2026diff --git a/uk/04-subagents/documentation-writer.md b/uk/04-subagents/documentation-writer.mdnew file mode 100644index 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": "[email protected]"+}+```++### Помилки++| Код | Опис |+|-----|------|+| 404 | Користувача не знайдено |+| 401 | Не авторизовано |++### Приклад++```bash+curl -X GET https://api.example.com/api/users/abc123 \+ -H "Authorization: Bearer <token>"+```+```++---+**Останнє оновлення**: 9 квітня 2026diff --git a/uk/04-subagents/implementation-agent.md b/uk/04-subagents/implementation-agent.mdnew file mode 100644index 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 квітня 2026diff --git a/uk/04-subagents/performance-optimizer.md b/uk/04-subagents/performance-optimizer.mdnew file mode 100644index 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 квітня 2026diff --git a/uk/04-subagents/secure-reviewer.md b/uk/04-subagents/secure-reviewer.mdnew file mode 100644index 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 квітня 2026diff --git a/uk/04-subagents/test-engineer.md b/uk/04-subagents/test-engineer.mdnew file mode 100644index 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 квітня 2026diff --git a/uk/08-checkpoints/checkpoint-examples.md b/uk/08-checkpoints/checkpoint-examples.mdnew file mode 100644index 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 квітня 2026diff --git a/uk/09-advanced-features/planning-mode-examples.md b/uk/09-advanced-features/planning-mode-examples.mdnew file mode 100644index 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