Команди та Агенти у Claude Code

Проблема: неструктурована робота з AI

Коли розробник просто спілкується з Claude чат-інтерфейсом або напряму через API без структури, він стикається з проблемами:

1. Повторення контексту — кожен запит вимагає повного пояснення контексту проєкту
2. Неконсистентність — один запит виконується інакше, ніж інший
3. Плутанина у моделях — невідомо, яка саме модель оптимальна для конкретного завдання
4. Витрата токенів — відсутність фокусування призводить до надлишкових запитів

Рішення: команди, скіли та субагенти

Команди/Скіли — це структуровані інструкції у вигляді Markdown-файлів у каталозі .claude/. Станом на 2026 рік команди (commands) та скіли (skills) об’єднані в єдину систему: файл .claude/commands/deploy.md і скіл .claude/skills/deploy/SKILL.md рівнозначно створюють команду /deploy. Скіли — це більш потужний формат, що підтримує папку з допоміжними файлами, YAML frontmatter для керування запуском, і можливість автоматичного завантаження за контекстом.

Субагенти — це спеціалізовані AI-асистенти з власним контекстним вікном, системним промптом і правами доступу до інструментів. Кожен субагент:

• Виконується в ізольованому контексті, не засмічуючи основну розмову
• Може використовувати конкретний набір інструментів (наприклад, лише read-only)
• Може бути налаштований на конкретну модель (наприклад, Haiku для дешевих задач)
• Повертає лише стислий результат до основної сесії (але власні запити субагента теж рахуються у ваші витрати — див. розділ про витрати)

Актуальна структура проєкту (2026)

проєкт/
├── .claude/
│   ├── CLAUDE.md               # Пам'ять проєкту (або ./CLAUDE.md у корені)
│   ├── settings.json           # Спільні налаштування (комітити)
│   ├── settings.local.json     # Локальні override (gitignore)
│   ├── agents/                 # Субагенти (Markdown + YAML frontmatter)
│   │   ├── feature-agent.md
│   │   ├── bugfix-agent.md
│   │   ├── code-reviewer.md
│   │   └── commit-agent.md
│   ├── commands/               # Slash-команди (legacy, сумісні зі skills)
│   │   └── optimize.md         # → /optimize
│   ├── skills/                 # Скіли (сучасний формат)
│   │   ├── new-feature/
│   │   │   └── SKILL.md
│   │   ├── fix-bug/
│   │   │   └── SKILL.md
│   │   └── code-review/
│   │       └── SKILL.md
│   ├── rules/                  # Модульні правила (*.md); з paths: у frontmatter вантажаться лише для потрібних файлів
│   ├── workflows/              # Збережені dynamic workflows
│   └── hooks/                  # Скрипти, що викликаються з hooks у settings.json
├── CLAUDE.local.md             # Особисті нотатки проєкту (у корені, не в .claude/; додати в .gitignore)
├── src/
├── tests/
└── package.json

Приклад скілу: розробка нової фічі

---
name: new-feature
description: >
  Запускай цей скіл, коли потрібно реалізувати нову функціональність.
  Отримує опис фічі і веде розробку від планування до PR.
disable-model-invocation: true   # лише ручний виклик /new-feature
---

## Розробка нової фічі

### Процес виконання

1. Аналіз вимог — розбери вимоги, визнач область змін
2. Архітектурне планування — список файлів для змін
3. Реалізація — написати код відповідно до плану
4. Тести — написати юніт-тести для нової логіки
5. Документація — оновити коментарі та README
6. Підготовка коміту — Conventional Commits

Приклад скілу: виправлення бага

---
name: fix-bug
description: >
  Запускай цей скіл для виправлення багів.
  Вимагає опис проблеми та кроки для відтворення.
disable-model-invocation: true
---

### Процес виконання

1. Відтворення — зрозуміти де і чому виникає проблема
2. Root cause analysis — знайти першопричину
3. Фікс — написати мінімальний, цільовий код
4. Регресійний тест — тест, який покриває баг
5. Коміт — Conventional Commits з типом fix:

Актуальні моделі (жовтень 2026)

Усі чотири актуальні моделі мають контекст 1M токенів і до 128K вихідних. Legacy (ще доступні через API): Fable 5, Opus 5, Sonnet 5, Opus 4.8 / 4.7 / 4.6 / 4.5, Sonnet 4.6, Haiku 4.5 (виведення — не раніше 15.10.2026). Sonnet 4.5 — deprecated, вимикається 30.11.2026.

Аліаси моделей

Скрізь, де приймається модель (--model, /model, model у settings і frontmatter, ANTHROPIC_MODEL), можна писати як повний ID, так і аліас:

Як аліаси розв’язуються залежно від провайдера

Тобто на Bedrock model: sonnet у frontmatter дасть Sonnet 4.5, а не Sonnet 5.5. Якщо потрібна конкретна версія — задай її через ANTHROPIC_DEFAULT_SONNET_MODEL (див. таблицю змінних нижче) або повним ID.

Це ж мінімальні версії Claude Code, які підтримують відповідні моделі: Fable 5.1 — v2.1.257+, Opus 5.5 — v2.1.280+, Sonnet 5.5 — v2.1.284+, Haiku 5.5 — v2.1.293+.

Модель за замовчуванням

• Opus 5.5 — Pro, Max, Team, Enterprise, API, Claude Platform on AWS, Bedrock, Agent Platform.
• Sonnet 4.5 — Foundry.
• Fable ніколи не є default: його треба вибрати явно. Використання Fable може тарифікуватися з usage credits — Claude Code спершу показує запит на згоду.

Пріоритет вибору моделі

Від найвищого до найнижчого:

1. /model під час сесії
2. --model при запуску
3. ANTHROPIC_MODEL
4. ключ model у settings
5. ANTHROPIC_DEFAULT_MODEL (з v2.1.236)

У пікері /model клавіша s перемикає модель лише для поточної сесії (без збереження в settings).

Логіка вибору моделей

Effort Levels (адаптивне мислення)

Effort керує глибиною міркувань моделі. Рівні: low, medium, high, xhigh, max. Задається на рівні сесії, у settings.json або — з 2026 року — прямо у frontmatter субагента чи скілу:

# Усі 5 рівнів: Fable 5.x, Opus 5.5 / 5 / 4.8 / 4.7, Sonnet 5.5 / 5, Haiku 5.5
# Opus 4.6 / Sonnet 4.6 — без xhigh (непідтримуваний рівень «опускається» нижче)
# Haiku 4.5 effort не підтримує взагалі
claude --effort low     # Швидко, дешево — для простих задач
claude --effort medium  # Default для Opus 5.5 / Sonnet 5.5 / Haiku 5.5
claude --effort high    # Default для більшості моделей (крім 5.5-моделей — medium, і Opus 4.7 — xhigh)
claude --effort xhigh   # Глибоке міркування для складних задач
claude --effort max     # Коли коректність важливіша за вартість (діє лише на поточну сесію)

# Всередині сесії: /effort high
# /effort зберігає рівень для поточної моделі в modelSettings (user settings)
# max у settings не приймається — його зберігає лише CLAUDE_CODE_EFFORT_LEVEL
# Env: CLAUDE_CODE_EFFORT_LEVEL=auto|low|...|max — найвищий пріоритет

Effort: рівні та значення за замовчуванням по моделях

Для Sonnet 5.5 дефолт на рівні API — high, але Claude Code свідомо стартує з medium. Організація також може задати власний default effort для своєї моделі за замовчуванням. Шкала effort відкалібрована окремо для кожної моделі: Opus 5.5 на medium приблизно відповідає Opus 5 на high, тому при міграції починай із medium. max схильний до «передумування» — вмикай його точково.

Як визначається рівень effort

1. Явний вибір: змінна CLAUDE_CODE_EFFORT_LEVEL, прапор --effort або команда /effort
2. Settings: збережений рівень у modelSettings або ключ effortLevel
3. Default моделі (таблиця вище)

Значення CLAUDE_CODE_EFFORT_LEVEL (auto = default моделі) перебиває навіть effort у frontmatter субагента. Верхню межу задають managed-ключ maxEffortLevel та (на Enterprise) ліміти effort по ролях.

modelSettings проти effortLevel

{
  "modelSettings": {
    "claude-opus-5-5": { "effortLevel": "high" }
  }
}

• /effort low|medium|high|xhigh і слайдер у /model зберігають рівень по моделях у modelSettings user settings (з v2.1.251). Запис іде під канонічним іменем моделі, а аліаси та [1m]-варіанти відображаються на той самий запис.
• Верхньорівневий effortLevel у user settings — старий формат: він працює для Opus 5, Fable 5.1 і старіших моделей, але ігнорується для Opus 5.5 і новіших.
• Верхньорівневий effortLevel у project / local / managed settings або через --settings діє для всіх моделей. В одному файлі запис modelSettings має перевагу над верхньорівневим ключем.
• max не приймається ні в effortLevel, ні в modelSettings. --effort max та /effort max діють лише на поточну сесію; зберегти max можна тільки через CLAUDE_CODE_EFFORT_LEVEL.
• /effort auto очищає збережений рівень для поточної моделі; у слайдері клавіша s застосовує рівень лише на сесію (з v2.1.257).

ultrathink та ultracode

• ultrathink у тексті промпту — глибше міркування лише на цей хід. Effort, який іде в API, не змінюється. Фрази «think hard», «think more» ключовими словами не є.
• Ultracode — це налаштування Claude Code (автоматична оркестрація workflows), а не рівень effort моделі. --effort ultracode ставить xhigh + ultracode (з v2.1.203); /effort ultracode лишає рівень effort без змін (з v2.1.284); постійно — ключ "ultracode": true. Недоступний, якщо workflows вимкнені або модель не підтримує xhigh. Деталі — у розділі «Dynamic workflows».

Thinking

• На Opus 5.5, Sonnet 5.5, Haiku 5.5 та Fable thinking вимкнути не можна — лише змінювати effort.
• Option+T / Alt+T перемикає thinking там, де це можливо; ключі alwaysThinkingEnabled, showThinkingSummaries, змінна MAX_THINKING_TOKENS.
• CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING працює лише на моделях 4.6.
• Токени thinking тарифікуються як вихідні (output).
• Субагенти успадковують увімкнено/вимкнено extended thinking головної сесії; окремого налаштування thinking для субагента немає (з v2.1.198).

Fast mode

Fast mode — режим «до 2,5x швидше за вищу ціну за токен». Та сама модель і та сама якість, лише швидше інференс; функція — research preview.

Контекст 1M

• Надбавки за довгий контекст немає, окрім Haiku 5.5 понад 100K ($0.50 / $2.50).
• Auto-compact спрацьовує приблизно на 967K токенів.
• Керування: CLAUDE_CODE_DISABLE_1M_CONTEXT=1, команда /autocompact, ключ autoCompactWindow, змінна CLAUDE_CODE_AUTO_COMPACT_WINDOW.
• Вікно контексту субагента визначається його власною моделлю.

Fallback-моделі

• --fallback-model sonnet,haiku або ключ fallbackModel — ланцюжок до 3 моделей, на які Claude Code переходить при недоступності основної. Для субагентів ланцюжки теж діють (з v2.1.247).
• Автоматичний safety-fallback: Fable та Opus 5.5 за bio-тематикою переходять на Opus 5, за cyber — на Opus 4.8; Sonnet 5.5 за cyber — на Sonnet 5, а bio-запити відхиляє. Ключ switchModelsOnFlag визначає, чи питати перед перемиканням.

Змінні оточення для моделей

Для адміністраторів: обмежити вибір моделей можна ключами availableModels (allowlist; при блокуванні підставляється найновіша дозволена модель того ж сімейства) та enforceAvailableModels, а також deniedModels / availableModelsMatch (v2.1.283+) і modelOverrides.

Кеш та знижки

• Читання з кешу коштує 0.05x від базової ціни на Opus 5.5 і Sonnet 5.5, та 0.025x на Fable 5.1. Batch API — знижка 50%.
• Виведення з обігу — не раніше ніж: Fable 5.1 — 01.09.2027, Opus 5.5 — 22.09.2027, Sonnet 5.5 — 28.09.2027, Haiku 5.5 — 07.10.2027.

Субагенти — це Markdown-файли з YAML frontmatter у каталозі .claude/agents/ (проєктні) або ~/.claude/agents/ (особисті). Для разових сесій їх також можна передати JSON-ом через прапор --agents. Команда /agents більше не є інтерактивним редактором — файли створюються та редагуються вручну.

Тіло файлу стає системним промптом субагента. Субагент не отримує системний промпт Claude Code — лише свій плюс базові відомості про оточення (наприклад, робочий каталог).

Feature Agent

---
name: feature-agent
description: >
  Спеціаліст з реалізації нових функцій. Делегуй цьому агенту, коли
  потрібно реалізувати нову фічу від планування до готового коду.
model: sonnet            # аліас сімейства Sonnet (див. «Як визначається модель»)
effort: high
tools: Read, Write, Edit, Bash, Glob, Grep
---

Ти — досвідчений fullstack-розробник.

Твій процес роботи:
1. Аналізуй вимоги і визнач мінімальний набір змін
2. Переглянь існуючий код для розуміння контексту
3. Напиши реалізацію відповідно до існуючих патернів
4. Додай юніт-тести
5. Поверни стислий звіт: що зроблено, які файли змінено

Bugfix Agent

---
name: bugfix-agent
description: >
  Спеціаліст з виправлення багів. Делегуй коли є конкретна
  проблема з описом та кроками відтворення.
model: sonnet
tools: Read, Write, Edit, Bash, Glob, Grep
permissionMode: acceptEdits   # діє лише коли головна сесія в default/dontAsk/plan
---

Ти — досвідчений debugger. Твій пріоритет — мінімальний, цільовий фікс.

Твій процес:
1. Відтвори проблему, знайди root cause
2. Напиши мінімальний фікс (не рефакторинг!)
3. Додай регресійний тест
4. Поверни звіт: причина та що змінено

Code Reviewer

---
name: code-reviewer
description: >
  Code review спеціаліст. Використовуй для перевірки PR або
  окремих файлів перед мержем. Код проєкту не змінює.
model: sonnet
tools: Read, Glob, Grep
permissionMode: plan         # діє лише якщо головна сесія НЕ в acceptEdits/auto/bypass
memory: project              # пам’ять між сесіями; автоматично вмикає Read/Write/Edit для файлів пам’яті
---

Ти — senior code reviewer. Перевіряй на:
- Коректність логіки та edge cases
- Потенційні security вразливості
- Продуктивність (лише суттєві проблеми)
- Відповідність існуючим патернам проєкту

Формат: APPROVE / REQUEST CHANGES / COMMENT
+ список зауважень з рівнем (critical/major/minor)

Commit Agent

---
name: commit-agent
description: >
  Генератор commit messages. Використовуй після завершення
  роботи для якісного Conventional Commits повідомлення.
model: haiku              # аліас сімейства Haiku
effort: low
tools: Read, Bash
---

Аналізуй `git diff --staged` та генеруй Conventional Commits.

Формат:
type(scope): short description

- Деталь 1
- Деталь 2

BREAKING CHANGE: ... (якщо є)

Приклад: Vue test writer в ізольованому worktree

---
name: vue-test-writer
description: >
  Пише Vitest-тести для Vue 3 компонентів. Використовуй проактивно
  після змін у frontend/src/components/.
model: sonnet
effort: medium
tools: Read, Write, Edit, Bash, Glob, Grep
disallowedTools: WebFetch, WebSearch
skills:
  - vue-testing-conventions
isolation: worktree
maxTurns: 30
color: green
experimental:
  cacheTtl: 5m
---

Ти пишеш Vitest + @vue/test-utils тести. Не чіпай код компонентів.
Після роботи запусти `npm run test:unit -- --run` і поверни список
створених файлів та результат запуску.

Де зберігаються субагенти і хто виграє

• Каталоги скануються рекурсивно; підпапки не впливають на ідентичність агента. У плагінах підпапки, навпаки, входять в ID: my-plugin:review:security.
• Проєктні агенти шукаються вгору до кореня репозиторію; перемагає найближчий. Каталоги з --add-dir також завантажуються.
• Зміни підхоплюються watcher-ом «за кілька секунд». Перезапуск потрібен, якщо створено новий каталог agents, для каталогів --add-dir та з --disable-slash-commands.
• Дублікати імен в одному каталозі: переможець залежить від порядку файлової системи; /doctor повідомляє про дублікати.
• Попередження при старті з’являється, якщо сумарні description кастомних агентів перевищують 15 000 токенів — довгі описи «з’їдають» контекст кожної сесії.

Довідник полів frontmatter

Обов’язкові — лише name і description. Імена полів — camelCase і точні; невідомі поля мовчки ігноруються.

Прапор --agents: субагенти як JSON

Для разових сесій, CI або тестів. Кожен ключ верхнього рівня — ім’я агента, поле prompt — системний промпт (може бути порожнім, з v2.1.281).

claude --agents '{
  "django-migration-reviewer": {
    "description": "Перевіряє Django-міграції на небезпечні операції. Використовуй проактивно перед MR.",
    "prompt": "Ти рев’юер міграцій Django. Шукай RunPython без reverse, видалення колонок, NOT NULL без default.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet",
    "maxTurns": 15
  }
}'

# Додатковий системний промпт для субагентів у -p (v2.1.205+; з файлу — v2.1.261+)
claude -p --append-subagent-system-prompt "Відповідай українською" "..."

• Приймаються поля: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, omitClaudeMd, isolation.
• color та experimental у JSON ігноруються.
• У режимі -p замість JSON-рядка можна передати шлях до JSON-файлу (v2.1.281+).

Субагенти з плагінів

Плагінні субагенти лежать у каталозі agents/ плагіна, мають ID виду plugin:name. З міркувань безпеки поля hooks, mcpServers і permissionMode у них ігноруються; так само ігнорується initialPrompt. Потрібен такий агент з hooks чи MCP — скопіюй його у .claude/agents/ або ~/.claude/agents/.

Як викликати субагента

Як визначається модель субагента

Від найвищого пріоритету:

1. Параметр model окремого виклику. Mod-hook agent.spawn може його замінити.
2. Поле model з frontmatter (inherit = модель головної сесії).
3. Змінна CLAUDE_CODE_SUBAGENT_MODEL.
4. Модель головної сесії.

• До v2.1.251 змінна оточення стояла першою. CLAUDE_CODE_SUBAGENT_MODEL=inherit = «не задано» (до v2.1.196 вона примусово ставила inherit).
• Сама по собі CLAUDE_CODE_SUBAGENT_MODEL не змінює Explore і Plan.
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (v2.1.257+) примусово ставить одну модель усім субагентам, teammate-ам і workflow-агентам і ігнорує model з frontmatter. Fork-и та context: fork скіли з model: inherit усе одно йдуть на модель головної сесії.
• Підстановка availableModels діє й на субагентів: береться найновіша дозволена версія сімейства (з v2.1.222).
• Модель окремого виклику зберігається при resume (v2.1.211+). Перемикання через /model доходить і до субагентів, що наслідують модель.
• /tasks показує модель та effort кожного субагента (v2.1.242+).

Вбудовані субагенти

Як вимкнути вбудованих:

• permissions.deny: ["Agent(Explore)"] або --disallowedTools "Agent(Explore)" — конкретний тип; deny на Agent — будь-яке делегування.
• CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 (v2.1.198+) — прибрати Explore і Plan.
• CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 — для режимів -p/SDK.
• Інструмент Task перейменовано на Agent у v2.1.63; запис Task(...) досі працює як alias.

Foreground і background

• В інтерактивних сесіях fork-режим увімкнено за замовчуванням (з v2.1.232): усі запущені субагенти працюють у фоні, і Claude не може попросити foreground.
• У режимах -p/SDK субагенти за замовчуванням у фоні; foreground — коли Claude потрібен результат для продовження.
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 примусово переводить усе у foreground.
• Ctrl+B відправляє запущену задачу у фон.
• Поле background: true у frontmatter тримає конкретного агента у фоні, навіть якщо Claude просить foreground.
• Запити дозволів від background-субагентів з’являються в головній сесії.
• Для швидких побічних питань використовуй /btw — це краще, ніж запускати для цього субагента.

Які інструменти бачить субагент

Незалежно від tools, з субагента завжди прибираються:

• Agent — на межі ліміту глибини;
• AskUserQuestion, EndConversation, EnterPlanMode, ScheduleWakeup, WaitForMcpServers, Workflow;
• ExitPlanMode — крім випадку, коли permissionMode: plan.

Background-субагенти (а це дефолт) зберігають лише такі вбудовані інструменти:

Ліміти конкурентності та глибини

Відновлення субагента (resume)

Claude повертається до вже запущеного субагента через SendMessage, вказуючи його ID або ім’я — тобто субагент продовжує з накопиченим контекстом, а не стартує заново. Agent teams для цього не потрібні. Explore і Plan відновити не можна — вони одноразові. Якщо агент зупинився через maxTurns, його результат позначено як partial, і Claude може відновити агента, щоб той завершив роботу.

Транскрипти та очищення

~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl

• Транскрипти видаляються через cleanupPeriodDays (за замовчуванням 30 днів).
• Субагенти автоматично компактують свій контекст (діє CLAUDE_AUTOCOMPACT_PCT_OVERRIDE).
• З v2.1.210 вивід субагентів сканується перед поверненням у головну сесію.

Форки та /subtask

Fork — це субагент, що успадковує всю розмову головної сесії, її системний промпт, інструменти та модель. Оскільки префікс однаковий, форк ділить prompt cache з батьком і тому дешевший за свіжого субагента, якому треба все пояснювати з нуля.

/subtask Перевір, чи всі ендпоїнти apps/orders/api/ мають permission_classes

# До v2.1.212 (з v2.1.161) команда називалась /fork

• Форк не може породжувати інші форки.
• CLAUDE_CODE_FORK_SUBAGENT=0 вимикає fork-режим (Claude більше не створює форки сам, а субагенти знову можуть працювати у foreground); /subtask працює незалежно від fork-режиму. Заборонити Claude створювати форки, не вимикаючи режим, — правилом Agent(fork) у deny.
• Панель форків: ↑/↓ вибір, Enter відкрити транскрипт, x зупинити (або прибрати рядок завершеного), Esc повернутися до поля вводу.
• Коли використовувати: побічне дослідження, яке потребує контексту поточної розмови (наприклад, «знайди всіх споживачів цього Vue-composable»), але не має засмічувати основну сесію. Якщо контекст не потрібен — краще окремий субагент з вузьким промптом.

Концепція: Головна сесія як менеджер

Замість жорсткої ролі "Opus = оркестратор", сучасний підхід виглядає так:

• Головна сесія (Opus 5.5 за замовчуванням) розуміє задачу і делегує роботу
• Субагенти виконують спеціалізовані завдання в ізольованих контекстах — паралельно (до 20 одночасно) і за замовчуванням у фоні
• Вбудований Explore агент виконує read-only дослідження кодової бази. Увага: тепер він працює на моделі головної сесії, а не на Haiku

Claude Code автоматично делегує задачі субагентам на основі їхніх description. Також можна явно викликати субагента:

# Явний виклик субагента природною мовою
claude "Use the code-reviewer agent to review auth/ directory"

# @-згадка у промпті (гарантований виклик саме цього агента)
@agent-code-reviewer перевір auth/

# Вся сесія як конкретний агент
claude --agent code-reviewer

# Виклик через скіл
/fix-bug "В фільтрі дат краш при виборі однакових дат"

# Нова фіча через скіл
/new-feature "Додати фільтрацію по датах. Критерії: діапазон дат"

Схема делегування

Режим opusplan (для складних задач)

claude --model opusplan "Redesign the authentication system to support OAuth2 + API keys"

# plan mode   → Opus 5.5 для глибокого архітектурного аналізу
# exec mode   → автоматично Sonnet 5.5 для генерації коду
# На Anthropic API обидві фази вже мають нативний 1M, тож opusplan[1m] не потрібен;
# він має сенс лише там, де opus/sonnet не мають нативного 1M (задавати через /model — v2.1.265+)

Вкладені субагенти

Субагенти можуть породжувати власних субагентів — за замовчуванням до 3 рівнів вкладеності (обмежується CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH; щоб заборонити конкретному агенту, прибери Agent з його tools).

---
name: lead
description: Тімлід, що делегує лише перевіреним агентам
tools: Agent(code-reviewer, django-migration-reviewer, vue-test-writer), Read, Bash
---

Розбий задачу на підзадачі й делегуй їх лише дозволеним агентам.
Сам код не пиши.

Запуск: claude --agent lead.

Для масштабних задач (міграції, аудит усього репозиторію, deep research) є dynamic workflows — скрипт, що у фоні оркеструє десятки–сотні субагентів. Детально — у розділі Dynamic workflows.

Деталі opusplan

• Plan mode використовує аліас opus, виконання — sonnet. Фази керуються змінними ANTHROPIC_DEFAULT_OPUS_MODEL та ANTHROPIC_DEFAULT_SONNET_MODEL.
• Якщо задано allowlist availableModels, підставляється найновіший дозволений Opus.
• Альтернатива: інструмент advisor.

Який механізм обрати

Приклад: паралельний review MR

Переглянь MR !482 у GitLab. Паралельно запусти:
1) code-reviewer на backend-змінах (Django, apps/orders/) — безпека і N+1 запити;
2) vue-test-writer на змінених Vue-компонентах (frontend/src/components/);
3) django-migration-reviewer на нових міграціях.
Зведи результати в один коментар для MR, не публікуй його без мого підтвердження.

Вартість делегування

• Запити субагентів рахуються в ті ж ліміти використання, що й основна сесія. /usage показує, скільки пішло на субагентів, скіли, плагіни та MCP.
• Подешевшати: model: haiku для механічних агентів або CLAUDE_CODE_SUBAGENT_MODEL разом з _FORCE для всіх одразу.
• Орієнтир: у середньому по Enterprise ≈ $13 на розробника за активний день, $150–250 на місяць; у 90% користувачів — менше $30 за активний день. Фонове використання зазвичай менше $0.04 за сесію.
• Тримай CLAUDE.md коротшим за 200 рядків; процедури виносять у скіли.
• Thinking-токени тарифікуються як output. Ultracode змушує кожен запит використовувати більше токенів, тому ліміти плану вичерпуються швидше.

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Увімкнути можна й без export — через env у settings:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Для задач, де потрібні декілька агентів одночасно, Claude Code підтримує agent teams — окремі сесії, що координуються між собою. Team lead (головна сесія) створює teammates — окремі інстанси Claude зі спільним списком задач (з залежностями та блокуванням) і поштовою скринькою для обміну повідомленнями.

Режим відображення задається налаштуванням teammateMode або прапором --teammate-mode: in-process (default), auto, tmux, iterm2 (split-панелі). Для контролю якості є hooks TeammateIdle, TaskCreated, TaskCompleted.

Архітектура

Проєктного конфігу команди немає: файл .claude/teams/teams.json не розпізнається.

Керування у режимі in-process

Коли всі агенти в панелі простоюють, idle-рядки ховаються через 30 секунд (teammate при цьому працює далі й доступний за іменем). Якщо idle-teammate-ів більше трьох, рядки понад перші три згортаються в один рядок «N idle agents».

Режими відображення: нюанси

• Прапор --teammate-mode експериментальний і не показується у claude --help.
• iterm2 потребує CLI it2 та ввімкненого Python API (iTerm2 → Settings → General → Magic). Для iTerm2 також радять tmux -CC.
• Split-панелі не підтримуються у терміналі VS Code, Windows Terminal і Ghostty; для них використовуй in-process.

Модель і дозволи teammate-ів

Модель teammate-а визначається за порядком:

1. модель, названа в spawn-промпті;
2. model з визначення субагента;
3. CLAUDE_CODE_SUBAGENT_MODEL;
4. модель лідера.

• Ключ teammateDefaultModel прибрано у v2.1.234. Teammate-и успадковують effort лідера.
• Режим дозволів — як у лідера, окрім dontAsk; --dangerously-skip-permissions поширюється на всіх. Режим окремого teammate-а можна змінити після spawn, але не задати при spawn. Запити дозволів з’являються в лідера.
• Якщо лідер у plan mode, teammate-и, запущені в цей час, спершу планують, а лідер автоматично схвалює їхні плани.

Визначення субагентів як teammate-ів

Обмеження

• /resume та /rewind не відновлюють in-process teammate-ів.
• Статус задач може запізнюватись; завершення teammate-а повільне.
• Лідер фіксований; одна команда на сесію, вкладених команд немає.
• In-process teammate-и не можуть запускати background-субагентів.
• Дозволи задаються при spawn.
• Split-панелі потребують tmux або iTerm2; фіча працює лише в інтерактивних сесіях (без -p та SDK).

Вартість і розмір команди

• Agent Teams використовують значно більше токенів; ≈ 7x порівняно зі звичайною сесією, коли teammate-и працюють у plan mode.
• Для teammate-ів бери Sonnet. Починай із 3–5 teammate-ів і 5–6 задач на кожного. Завершуй teammate-ів, коли вони закінчили.
• Кеш in-process teammate-а живе 5 хвилин за замовчуванням; для 1 години — subagentPromptCacheTtl: "1h" (запис у кеш на 1 годину тарифікується дорожче).

Коли команда виправдана, а коли ні

Почни з не-кодових задач: review MR, дослідження. Приклад spawn-промпту:

Create an agent team to review MR !482 in GitLab:
- one teammate on Django API security (permissions, serializers),
- one on Vue 3 component accessibility,
- one on test coverage gaps.
Use Sonnet for each teammate. Ask them to report findings, not to edit code.

Альтернатива, коли окремі сесії треба лише зв’язати між собою, — cross-session messaging.

Dynamic workflow — це JavaScript-скрипт, який пише Claude, а окремий runtime виконує його у фоні: скрипт розкладає велику задачу на фази й запускає десятки–сотні агентів. Проміжні результати лишаються у змінних скрипта, а не в контексті розмови — ти отримуєш один підсумок замість покрокового транскрипту.

Доступність

• Усі платні плани, API, Bedrock, Agent Platform та Foundry.
• На Pro вмикається в /config — рядок Dynamic workflows.
• Вбудований workflow: /deep-research <питання> — веб-пошук з кількох кутів, перехресна перевірка джерел, голосування за кожне твердження і звіт з цитатами (потрібен інструмент WebSearch). Запускається лише на твій виклик.

Як запустити

ultracode: проаудитуй усі DRF-в’юхи в apps/ на відсутні permission_classes і перевір кожну знахідку скептично

• Ключове слово підсвічується у полі вводу. Option+W / Alt+W знімає підсвітку для цього промпта; постійно вимкнути — перемикач «Ultracode keyword trigger» у /config.
• Ключове слово спрацьовує лише у промпті, який друкуєш ти сам (інтерактив, IDE, Remote Control, SDK з людським origin). Воно не запускає workflow з -p, з SDK-вводу без позначки людського введення, зі scheduled tasks, з webhook-ів і коментарів до PR (з v2.1.210; раніше спрацьовувало й звідти).
• Ultracode — налаштування Claude Code (ключ "ultracode": true для постійного вмикання), а не рівень effort моделі. Коли воно увімкнене: немає попередження «Large workflow», не діє ліміт одночасних субагентів для Agent tool, а в auto-режимі не питають підтвердження першого запуску.

Підтвердження плану

Перед запуском CLI показує заплановані фази і варіанти: Yes, run it · Yes, and don’t ask again (лише для вбудованих, збережених і плагінних workflow, не для одноразового скрипта) · View raw script · No. Ctrl+G відкриває скрипт у редакторі.

Субагенти workflow працюють за твоїми правилами дозволів. Щоб довгий запуск не зупинявся на промптах, додай потрібні інструменти в allow ще до старту.

Керування запуском: /workflows

Деталі агента показують його промпт, останні виклики інструментів, результат і власний task list; також видно токени кожного агента. Запуск можна відновити (resume) у межах тієї ж сесії; скрипт кожного запуску лежить у ~/.claude/projects/.

Збереження і повторне використання

• У /workflows вибери запуск і натисни s; Tab перемикає місце: .claude/workflows/ проєкту (ділиться з командою через git) або ~/.claude/workflows/ (лише ти, усі проєкти). Workflow далі запускається як /<name>.
• Проєктний workflow перемагає особистий з тим же іменем. У монорепо береться найближчий каталог .claude/workflows/ до робочого каталогу.
• У плагіні — каталог workflows/ у корені; ім’я з простором: /acme-tools:release-audit.
• Вхідні дані: «Run /triage-issues on issues 1024, 1025» — Claude передає список як структуровані дані в глобальну змінну args.

Скрипт: огляд API

export const meta = {
  name: 'drf-permission-audit',
  description: 'Аудит DRF-в’юх на відсутні permission_classes',
  phases: [
    { title: 'Discover', detail: 'знайти файли з в’юхами' },
    { title: 'Audit', detail: 'по одному агенту на файл' },
    { title: 'Verify', detail: 'скептична перевірка знахідок' },
  ],
}

const FILES = {
  type: 'object',
  required: ['files'],
  properties: { files: { type: 'array', items: { type: 'string' } } },
}
const FINDINGS = {
  type: 'object',
  required: ['findings'],
  properties: { findings: { type: 'array', items: { type: 'string' } } },
}
const VERDICT = {
  type: 'object',
  required: ['real'],
  properties: { real: { type: 'boolean' }, why: { type: 'string' } },
}

phase('Discover')
const found = await agent(`List every views.py and viewsets.py under ${args.dir}.`, {
  schema: FILES, label: 'discover',
})

// pipeline: кожен файл проходить Audit -> Verify незалежно, без бар’єра
const results = await pipeline(
  found.files,
  file => agent(`Find DRF views in ${file} without permission_classes.`, {
    phase: 'Audit', label: file, schema: FINDINGS,
  }),
  (audit, file) => audit && audit.findings.length
    ? agent(`Try to refute these findings for ${file}: ${audit.findings.join('; ')}`, {
        phase: 'Verify', label: `verify ${file}`, schema: VERDICT,
      }).then(v => ({ file, findings: audit.findings, confirmed: v && v.real }))
    : null,
)

return results.filter(Boolean).filter(r => r.confirmed)

• Скрипт — звичайний JavaScript (не TypeScript). Date.now(), Math.random() та new Date() без аргументів кидають помилку (інакше resume не відтворив би виклики); import() заборонено; прямого доступу до файлів чи shell у скрипта немає — це роблять агенти.
• Якщо вивід агента не проходить валідацію за schema після 5 спроб, виклик падає з помилкою; кількість спроб змінює MAX_STRUCTURED_OUTPUT_RETRIES.
• Перед редагуванням збереженого скрипта запусти скіл /workflow-authoring (v2.1.248+) — він підвантажує довідник із написання скриптів; після змін виконай /reload-skills.

Ліміти та змінні

Вартість і розмір

• Один запуск може коштувати суттєво більше токенів, ніж та ж задача в розмові; запуски рахуються в ліміти плану. Спершу проганяй на малому зрізі (один каталог замість усього репо).
• Попередження Large workflow з’являється при понад 25 агентах або понад 1,5 млн прогнозованих токенів. Воно дорадче — запуск не зупиняє.
• Модель агента workflow вибирається за тим же порядком, що й для субагентів; модель, названа скриптом для стадії, — це «модель окремого виклику».

Змінити guideline: рядок Dynamic workflow size у /config, команда /config workflowSizeGuideline=small або ключ у будь-якому settings-файлі (v2.1.219+; має пріоритет над /config). Це порада для Claude, а не жорсткий ліміт.

Як вимкнути

• Перемикач Dynamic workflows у /config.
• "disableWorkflows": true у settings або CLAUDE_CODE_DISABLE_WORKFLOWS=1 (читається при старті).
• Для організації — "disableWorkflows": true у managed settings.
• Наслідки: зникають /workflows, workflow-команди, скіл /workflow-authoring, ключове слово ultracode та перемикач Ultracode в /effort. Запуск, що вже йде, продовжується.

Кожна сесія Claude Code починається з порожнього контекстного вікна. Знання між сесіями переносять два механізми: CLAUDE.md — інструкції, які пишете ви, і auto memory — нотатки, які Claude веде собі сам. Обидва вантажаться на початку розмови.

Де лежить CLAUDE.md і в якому порядку вантажиться

Таблиця подана в порядку завантаження: від найширшого охоплення до найвужчого, тож проєктна інструкція стоїть у контексті після користувацької.

Замість окремого файлу організація може покласти текст у ключ claudeMd в managed-settings.json (діє лише в managed/policy settings). Керувати технічним примусом (deny, sandbox, env) треба через managed settings, а CLAUDE.md лишається для поведінкових настанов.

Правила завантаження

• Claude Code вантажить CLAUDE.md і CLAUDE.local.md з поточного каталогу й усіх каталогів над ним при старті. Файли конкатенуються, а не перекривають одне одного; порядок — від кореня файлової системи до робочого каталогу, у кожному каталозі CLAUDE.local.md стоїть після CLAUDE.md. Найближчі до вас інструкції читаються останніми.
• CLAUDE.md у підкаталогах вантажаться лише коли Claude читає, пише чи редагує файл у цьому підкаталозі (у тому числі cat/head одного файлу). Для monorepo Django + Vue це природне місце для backend/CLAUDE.md і frontend/CLAUDE.md.
• Файли з --add-dir за замовчуванням не вантажаться; увімкніть CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.
• У великому monorepo пропускайте чужі файли через claudeMdExcludes (масив glob-шляхів, зливається між шарами; managed-файли виключити не можна).
• Блокові HTML-коментарі <!-- нотатки для супровідників --> вилучаються до потрапляння в контекст, тож не коштують токенів. У блоках коду коментарі зберігаються.
• CLAUDE.md до 4 MiB вантажиться повністю, більший файл пропускається.

@-імпорти

У CLAUDE.md можна імпортувати файли синтаксисом @шлях/до/файлу. Імпортовані файли розгортаються й вантажаться при старті поруч із файлом-джерелом.

• Шляхи відносні (до файлу з імпортом, а не до робочого каталогу) або абсолютні; рекурсивні імпорти — максимум чотири переходи.
• Імпорти пропускають code spans і fenced-блоки: `@README` у бектиках лишається текстом.
• Шлях з пробілами — з бекслешем перед кожним пробілом; у лапках шлях не імпортується.
• Імпорти допомагають організувати довгий файл, але не зменшують вартість контексту: імпортоване теж вантажиться при старті.
• Імпорт, що виходить за межі робочого каталогу (наприклад, з домашнього), спершу викликає діалог підтвердження в проєктних файлах; користувацькі файли довіряються без діалогу.

Огляд проєкту — @README.md, команди npm — @frontend/package.json

# Індивідуальні вподобання
- @~/.claude/my-project-instructions.md

.claude/rules/: модульні правила

Для великих проєктів інструкції розбивають на теми у .claude/rules/ (testing.md, api-design.md…). Усі .md знаходяться рекурсивно, тож можна робити підкаталоги backend/ і frontend/. Правила без paths вантажаться при старті з тим самим пріоритетом, що й .claude/CLAUDE.md.

Єдине поле frontmatter, яке Claude Code читає з правила, — paths (YAML-список або рядок через кому; решта полів ігнорується). Правило з paths вантажиться, коли Claude використовує Read/Write/Edit на відповідному файлі (або переглядає його через cat/head).

• Бюджет розгортання фігурних дужок: 1 000 шаблонів і 4 MiB на весь список paths правила (шаблони без дужок не враховуються).
• Правила з paths підтягуються в історію розмови, тож компактизація їх вимиває до наступного збігу. Якщо правило має жити завжди — приберіть paths.
• Підтримуються symlink-и (спільні правила для кількох проєктів: ln -s ~/shared-claude-rules .claude/rules/shared); цілі поза робочим каталогом працюють як зовнішні імпорти й потребують підтвердження.
• Користувацькі правила — ~/.claude/rules/, діють у всіх проєктах і вантажаться перед проєктними; при конфлікті Claude може піти за будь-яким, тож тримайте їх узгодженими.

AGENTS.md

З v2.1.277 Claude Code вміє читати AGENTS.md як проєктні інструкції (корисно, якщо репозиторій спільний з іншими агентами). За замовчуванням його читають лише тоді, коли в робочому каталозі й вище немає жодного CLAUDE.md, .claude/CLAUDE.md чи CLAUDE.local.md. Файли ~/.claude/CLAUDE.md, managed CLAUDE.md та .claude/rules/ на це не впливають. Увага: створення CLAUDE.local.md вимикає читання AGENTS.md.

@AGENTS.md

## Claude Code

Для змін у `backend/billing/` спершу використовуй plan mode.

Альтернатива — symlink ln -s AGENTS.md CLAUDE.md, але на Windows краще імпорт (symlink потребує прав, а git може віддати текстовий файл).

Auto memory

Claude сам веде нотатки чотирьох типів (поле type у frontmatter): user (роль, досвід, вподобання), feedback (виправлення й підтверджені підходи), project (поточна робота, дедлайни, рішення, яких не видно з коду) і reference (де шукати зовнішню інформацію: трекер, дашборд). Він пропускає те, що виводиться з коду чи вже є в CLAUDE.md, і не зберігає нічого кожну сесію.

Коли ви кажете «запам’ятай, що API-тести потребують локального Redis», Claude зберігає це в auto memory. Щоб записати в CLAUDE.md, скажіть прямо: «додай це в CLAUDE.md».

Пам’ять субагента: поле memory

У frontmatter субагента memory дає йому власний каталог, що переживає розмови. Перші 200 рядків або 25 KB його MEMORY.md додаються в system prompt, а Read/Write/Edit вмикаються автоматично. Якщо auto memory вимкнено, поле нічого не робить.

---
name: code-reviewer
description: Рев’ю Django/Vue коду за конвенціями команди
memory: project
---
Перед рев’ю прочитай свою пам’ять: які патерни й помилки траплялися раніше.
Після рев’ю збережи в пам’ять нові повторювані зауваження.

Команди: /memory, /init, /context, /doctor

Що писати і який розмір

Ключова перевірка для кожного рядка: «Чи призведе до помилок Claude, якщо це прибрати?» Якщо ні — вилучайте.

• Розмір: цільове значення — менше 200 рядків на файл CLAUDE.md. Довші споживають контекст і знижують виконання. Вузькі інструкції переносьте в path-scoped rules або скіли. Для файлів, що перевищують рекомендовану довжину (чи разом переходять сукупний ліміт), є попередження при старті та в /status; кожен CLAUDE.md, rule і @-імпорт рахується окремо.
• Конкретність: «Використовуй відступ у 2 пробіли», а не «форматуй акуратно»; «Запускай pytest backend/…::test перед комітом», а не «тестуй зміни».
• Структура: заголовки й марковані списки. Суперечливі інструкції Claude може обрати довільно, тож періодично чистіть CLAUDE.md, вкладені файли й rules.
• Акцент: якщо Claude ігнорує одне правило, додайте «IMPORTANT» лише до цього рядка; якщо виділити багато — не виділиться жодне.
• Коли додавати: Claude вдруге робить ту саму помилку; рев’ю виявило те, що він мав би знати; ви набираєте те саме виправлення, що й минулої сесії.
• Якщо дія має виконуватись у певний момент (перед кожним комітом) — це hook, не рядок у CLAUDE.md.

Приклад для Django + Vue 3 проєкту

проєкт/
├── CLAUDE.md                  # короткий корінь (комітити)
├── CLAUDE.local.md            # особисте (в .gitignore)
├── backend/
│   └── CLAUDE.md              # завантажиться при роботі з файлами backend/
├── frontend/
│   └── CLAUDE.md
└── .claude/
    ├── rules/
    │   ├── backend-python.md  # paths: backend/**/*.py
    │   └── frontend-vue.md    # paths: frontend/**/*.{vue,ts}
    └── agent-memory/          # пам’ять субагентів memory: project (комітити)

# Проєкт: Shop (Django 5 + DRF, Vue 3 + Vite)

## Команди
- Backend dev: `python manage.py runserver`
- Один тест: `pytest backend/apps/orders/tests/test_api.py::test_create_order -x`
- Усі тести бекенду: `pytest backend/`
- Міграції: `python manage.py makemigrations && python manage.py migrate`
- Frontend dev: `cd frontend && npm run dev`; перевірка: `npm run lint && npm run type-check`

## Конвенції
- Python: ruff + black, типізація обов’язкова для нових функцій
- Vue: Composition API з `<script setup lang="ts">`, стан у Pinia
- API: DRF ViewSet-и, серіалізатори в `serializers.py`, URL у kebab-case

## Робочий процес
- Гілки: `feature/<ticket>-<slug>`, коміти за Conventional Commits
- MR у GitLab: заголовок з номером задачі, обов’язково зелений пайплайн
- IMPORTANT: не змінюйте застосовані міграції, лише створюйте нові

## Середовище
- Потрібні змінні: `DATABASE_URL`, `REDIS_URL` (див. `.env.example`)
- Тести API вимагають локального Redis

<!-- Для супровідників: розширену інструкцію деплою тримати в скілі /deploy, не тут -->

---
paths:
  - "backend/**/*.py"
---

# Правила для Python-коду

- Усі ендпоінти валідують вхід через DRF-серіалізатори
- Запити з join-ами — через `select_related` / `prefetch_related`, без N+1
- Нові моделі: міграція + фабрика в `tests/factories.py`
- Тести: pytest-django, без реальних зовнішніх викликів

---
paths:
  - "frontend/**/*.{vue,ts}"
---

# Правила для Vue/TypeScript

- Компоненти: `<script setup lang="ts">`, props типізовані через `defineProps<…>()`
- HTTP-виклики лише через `frontend/src/api/`, не напряму з компонентів
- Стилі: scoped, без глобальних селекторів

Діагностика: Claude не дотримується CLAUDE.md

Головне обмеження роботи з Claude Code — контекстне вікно: у ньому всі повідомлення, кожен прочитаний файл і вивід кожної команди. Чим воно повніше, тим гірше працює модель: може «забувати» ранні інструкції й частіше помилятись. Тож контекст — найважливіший ресурс, яким треба керувати.

Подивитись, що в контексті: /context

/context (з аргументом all — докладніше) малює кольорову сітку використання контексту, показує розбивку за категоріями, підказки з оптимізації та список завантажених Memory files і auto memory. Перед початком сесії вантажаться CLAUDE.md, auto memory, назви MCP-інструментів (схеми відкладені), описи скілів та, за потреби, output style.

Автоматична компактизація

Коли контекст наближається до межі, Claude Code компактує розмову сам: спершу очищає старі виводи інструментів, а якщо цього мало — підсумовує розмову. Повне вікно не завершує сесію.

Якщо один завеликий файл чи вивід інструмента заповнює контекст одразу після кожного підсумку, Claude Code припиняє автокомпактизацію після кількох спроб і показує помилку — це сигнал, що пора зробити /clear або делегувати читання субагентам.

/compact із фокусом

/compact [інструкції] стискає розмову вручну й каже, що зберегти: /compact Focus on code samples and API usage, /compact фокус на виправленні помилки в авторизації. Робіть це перед довгою новою задачею, а не коли контекст уже переповнений. Ті самі настанови можна закласти в CLAUDE.md — вони діятимуть і для автокомпактизації:

# Compact instructions

При компактизації зберігай повний список змінених файлів, команди запуску тестів
та результати останніх прогонів pytest.

Для часткового стиснення відкрийте /rewind (або Esc Esc), оберіть повідомлення й виберіть Summarize from here (стиснути від цього місця вперед) або Summarize up to here (стиснути все до цього місця, пізніші повідомлення лишаються повними). Можна додати побажання у рядку «add context (optional)». Файли на диску не змінюються, а оригінальні повідомлення лишаються в транскрипті.

Що переживає компактизацію

З v2.1.198 запит на підсумок успадковує налаштування extended thinking сесії. Інструкції, що були лише в розмові, після компактизації можуть пропасти — важливе фіксуйте в CLAUDE.md. Хочете гарантовано повертати нагадування після стиснення — використайте hook:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Нагадування: міграції не редагувати, тести — pytest backend/, гілка feature/<ticket>-<slug>'"
          }
        ]
      }
    ]
  }
}

/clear, /btw і субагенти

Що ще займає контекст

• Скіли: описи завантажуються при старті; disable-model-invocation: true тримає скіл поза контекстом до виклику. Опис + when_to_use обрізаються до 1 536 символів. Для сторонніх скілів є skillOverrides.
• MCP: визначення інструментів за замовчуванням відкладені (tool search) — у контексті лише назви. Вимикайте невикористані сервери через /mcp.
• Вивід команд: довгі логи й тести з’їдають контекст — фільтруйте hook-ом (див. розділ про витрати) або делегуйте субагентам.
• Вікно 1M: Fable, Sonnet 5+, Haiku 5.5 та Opus 4.7+ працюють з 1M за замовчуванням без суфікса [1m]. Більше вікно не скасовує потреби чистити контекст.

Типові антипатерни

Claude Code автоматично знімає знімок файлів перед кожним промптом, що починає хід, тож змінений Claude код можна швидко відкотити. Це страховка рівня сесії, не заміна git.

Як відкрити меню відкату

• Esc Esc (подвійний Escape) на порожньому полі вводу, або команда /rewind (аліаси /checkpoint, /undo).
• Якщо в полі є текст, подвійний Esc лише очищає його (текст зберігається в історії вводу — повернути можна клавішею «вгору»).
• Меню показує промпти сесії; виберіть точку, потім дію.

Дії з кодом з’являються лише якщо після цієї точки були відстежені зміни файлів. Після відновлення розмови чи Summarize from here оригінальний промпт повертається в поле вводу, щоб його можна було повторити або відредагувати. Summarize не змінює файли, а оригінальні повідомлення лишаються в транскрипті.

Скільки зберігається

• Кожен промпт, що починає хід, створює checkpoint. Знімки файлів тримаються для 100 останніх checkpoint-ів сесії.
• Checkpoint-и зберігаються разом з розмовою, тож /rewind працює і після відновлення сесії.
• Знімки видаляються при очищенні приблизно через 30 днів після останнього збереження в сесії (cleanupPeriodDays); якщо їх уже немає, відкат може завершитись помилкою No files were restored.
• Після /clear у тому ж процесі в меню з’являється запис /resume <session-id> (previous session) для повернення до розмови до очищення.

Що НЕ відкочується

/rewind проти /branch

Summarize тримає вас у тій самій сесії й діє як цілеспрямований /compact. Щоб випробувати інший підхід, зберігши оригінальну сесію неторканою, використайте /branch [name] або claude --continue --fork-session.

• Дослідження варіантів: спробуйте два підходи, не втрачаючи початкової точки.
• Відновлення після помилки: швидко скасуйте зміни, що зламали код.
• Звільнення контексту: стисніть вербозну сесію налагодження від середини, залишивши початкові інструкції.

Claude Code тарифікується за токенами (на підписці — за ліміти плану). Вартість росте разом з розміром контексту, тому майже всі прийоми економії зводяться до двох речей: тримати контекст малим і не ламати prompt cache. Нижче — реальні цифри з документації, інструменти вимірювання, повний перелік того, що інвалідує кеш, налаштування TTL, керування моделями субагентів і поради для команди.

Скільки це коштує насправді

Ціни моделей (за 1 млн токенів)

Множники кешу відносно базової ціни входу: запис на 5 хвилин — 1.25x, запис на 1 годину — 2x, читання — 0.1x (0.05x для Opus 5.5 і Sonnet 5.5, 0.025x для Fable 5.1). Кеш окупається вже після одного читання для 5-хвилинного запису або двох читань для годинного.

Як виміряти: /usage, /cost, /stats

/usage (аліаси /cost і /stats) показує блок Session: вартість, тривалість, токени по кожній моделі (вхід, вихід, читання й запис кешу). Суму Claude Code рахує локально за прейскурантом — це оцінка, а не рахунок; точні цифри дивіться в Claude Console. На Pro/Max вартість сесії для білінгу не важлива — там замість неї смуги використання плану. Підсумки скидаються після /clear (з v2.1.211).

Total cost:            $0.55
Total duration (API):  6m 20s
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · warm (1h TTL, last activity 40s ago)

Як працює prompt cache

Кожне повідомлення — новий API-запит, і Claude Code знову надсилає весь контекст. API кешує префікс запиту; збіг має бути точним, тому зміна будь-де в префіксі перераховує все після неї. Порядок шарів — від найстабільнішого до найрухливішого:

Окрім шарів, у ключ кешу входять модель (у кожної свій кеш) і — на більшості моделей — рівень effort. Кеш живе на боці сервера й, за документацією, фактично прив’язаний до однієї машини й каталогу: сесії в різних каталогах будують різні префікси; паралельні сесії в одному каталозі читають кеш одна одної.

Що ламає кеш

Після такої дії наступний запит один раз читає всю історію без попадань у кеш: повільніше й дорожче, далі новий префікс знову кешується.

Що кеш не ламає

Час життя кешу (TTL)

Кеш спливає після періоду бездіяльності; кожне попадання скидає таймер. Claude Code вирішує TTL для кожного запиту окремо, і запити діляться на два фіксовані «відра»: головна розмова (інтерактив, -p, Agent SDK та допоміжні запити поруч) і все інше (субагенти, workflows, teammates, форки, компактизація, назви сесій).

Коли ви виходите за ліміт плану й витрачаєте usage credits, головна розмова падає до 5 хвилин. Годинний TTL має дорожчий запис кешу (2x проти 1.25x): він окупається при простоях, але коштує більше на коротких серіях роботи.

Пріоритет, коли застосовується кілька: FORCE_PROMPT_CACHING_5M → змінна відра → налаштування відра → experimental.cacheTtl субагента → ENABLE_PROMPT_CACHING_1H → значення за замовчуванням. Перевірити, який TTL реально використаний: claude -p "hello" --output-format json і поле usage.cache_creation (ephemeral_1h_input_tokens проти ephemeral_5m_input_tokens). Через LLM-шлюз потрібно, щоб він пересилав заголовок anthropic-beta без змін.

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "5m"
}

Субагенти й кеш

• Субагент починає власну розмову з власним system prompt і набором інструментів, тому його перший запит не читає кеш батька і прогріває свій. Кеш батька при цьому не страждає.
• Субагенти поза відром головної розмови: навіть на підписці вони отримують 5 хвилин, поки не задасте TTL самі.
• Форк успадковує system prompt, інструменти й історію батька точно, тож його перший запит читає кеш батька.
• Продовжений (resumed) субагент може прочитати кеш свого першого запуску; у workflow fan-out Claude Code затримує всіх, крім першого агента, до 5 секунд за замовчуванням (CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS), щоб їхні перші запити прочитали префікс першого.
• Власні запити субагента все одно рахуються у ваші витрати.

---
name: repo-auditor
description: Аудит великого репозиторію та звіт про знахідки
experimental:
  cacheTtl: 1h
---
Ти аудитор репозиторію. Повертай лише стислий звіт.

Модель для всіх субагентів: CLAUDE_CODE_SUBAGENT_MODEL

Порядок вибору моделі субагента: (1) параметр model у конкретному виклику, (2) model у frontmatter (inherit = модель розмови), (3) змінна CLAUDE_CODE_SUBAGENT_MODEL (аліас або повний ID), (4) модель головної розмови. Тобто сама змінна — лише значення за замовчуванням.

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Винятки при FORCE: форк і скіл у субагенті з model: inherit лишаються на моделі головної розмови. Перевірити модель працюючого субагента можна в /tasks (з v2.1.242). Значення, заборонене організаційним availableModels, підміняється іншою моделлю з попередженням.

Thinking та effort

Thinking-токени тарифікуються як вихідні, а дефолтний бюджет може сягати десятків тисяч токенів на запит. Вимкнути thinking на Opus 5.5, Sonnet 5.5, Haiku 5.5 та моделях Fable не можна — знижуйте /effort (або effort: low у frontmatter механічних агентів). MAX_THINKING_TOKENS працює лише для моделей з фіксованим бюджетом; адаптивні моделі ігнорують ненульові значення.

Умовна ілюстрація: що потрапляє в основний контекст

Правила для економії токенів

1. Мінімальний контекст — кожен субагент отримує лише потрібні інструменти; CLAUDE.md тримайте до 200 рядків, процедури виносьте в скіли.
2. Правильна модель — не давати Opus задачі, що добре виконує Sonnet; не давати Sonnet те, з чим справляється Haiku. Пам’ятайте про поріг 100K токенів у Haiku 5.5.
3. Правильний effort — effort: low у frontmatter для механічних агентів (коміти, пошук).
4. Правило скілів — довгі інструкції завантажуються лише за потреби, не в кожну сесію. disable-model-invocation: true тримає скіл поза контекстом до виклику.
5. Ізольований контекст — вербозні операції (тести, логи, документація) делегуйте субагентам: у розмову повертається лише підсумок.
6. Очищайте між задачами — /clear нічого не коштує, а застарілий контекст дорожчає з кожним повідомленням. Перед цим /rename, щоб потім /resume.
7. Конкретні запити — «додай валідацію в login-функцію у auth.py» замість «покращ проєкт»: менше зайвих читань файлів.
8. Plan mode для складного, перервати помилковий напрям Esc одразу, /rewind — щоб відкотитись.
9. Дайте перевірку — тести, очікуваний вивід, скріншот: Claude сам ловить помилки без зайвих ітерацій.
10. MCP та LSP — визначення MCP-інструментів за замовчуванням відкладені (tool search), але вимикайте невикористані сервери через /mcp; CLI на зразок gh/glab економніші за MCP. Плагіни code intelligence (Python, TypeScript) зменшують зайві читання файлів.

function selectSubagentModel(task) {
  if (task.isLongHorizonAutonomous) {
    return 'fable';   // Fable 5.1 — багатогодинні автономні сесії
  } else if (task.requiresDeepArchitecture || task.codebaseSize > 'large') {
    return 'opus';    // Opus 5.5 — складна архітектура
  } else if (task.requiresCodeGeneration || task.requiresAnalysis) {
    return 'sonnet';  // Sonnet 5.5 — основна робота з кодом
  } else {
    return 'haiku';   // Haiku 5.5 — прості задачі (стежте за порогом 100K токенів промпта)
  }
}

Hook, що фільтрує вивід тестів

Hook може обробити дані до того, як їх побачить Claude: замість 10 000 рядків логу — лише рядки з помилками, тобто сотні токенів замість десятків тисяч. Офіційний приклад — PreToolUse hook, який переписує команди тестів через updatedInput.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/filter-test-output.sh" }
        ]
      }
    ]
  }
}

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# Для тестових команд залишаємо лише збої
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "$input" | jq --arg filtered "$filtered_cmd" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

• Зробіть скрипт виконуваним: chmod +x .claude/hooks/filter-test-output.sh. Перевірка: /hooks або claude --debug-file ./claude-debug.txt (рядок modified tool input keys).
• Приклад повертає permissionDecision: "allow" для переписаної команди, тобто вона виконується без запиту дозволу. Для всіх інших команд повертається {}.
• Після | head код завершення команди — це код head, а не pytest. Для Django додайте у regex python manage.py test і ./manage.py test, якщо запускаєте тести так.

Чому використання росте в довгій сесії

• Довгий контекст — повна розмова йде з кожним запитом (за ціною читання кешу), тож одне коротке запитання у сесії, відкритій цілий день, ще й оплачує весь контекст.
• Промахи кешу — перше повідомлення після перерви довшої за TTL перераховує все. На Pro/Max при поверненні до великої сесії Claude Code пропонує відновити з підсумку.
• Заплановані задачі й /loop, субагенти, workflows і teammates — кожен робить власні запити.
• Компактизація — /compact читає розмову, яку стискає (дорогий після простою); /clear нічого не коштує.
• Фонові процеси (підсумки для --resume тощо) зазвичай коштують менше $0.04 на сесію; підказки наступного промпта додають короткі запити, які в основному читають кеш, і їх можна вимкнути.

Витрати команди

Для API-організацій Console автоматично створює workspace «Claude Code» (ключів для нього створити не можна). На ньому ставлять ліміт витрат і, за потреби, ліміт швидкості, щоб Claude Code не з’їв квоту інших сервісів.

Рекомендовані ліміти TPM/RPM на користувача

Приклад: 200 користувачів по 20k TPM — це 4 млн TPM загалом. Ліміти діють на рівні організації, тож хтось може тимчасово перевищувати свою «частку». Для заходів з високою одночасністю (навчання з великою групою) потрібен запас. Agent teams вмикаються через CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; щоб стримати витрати — Sonnet для teammates, малі команди, сфокусовані spawn-промпти, зупиняти teammates після роботи.

Status line: витрати й кеш перед очима

Налаштуйте /statusline (або ключ statusLine у settings.json), щоб постійно бачити контекст і вартість. Скрипт отримує JSON зі stdin; корисні поля:

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '(.context_window.used_percentage // 0) | floor')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
HIT=$(echo "$input" | jq -r '((.prompt_cache.hit_ratio // 0) * 100) | floor')
printf '[%s] ctx %s%% | cache %s%% | $%.2f' "$MODEL" "$PCT" "$HIT" "$COST"

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}

Необов’язкове поле refreshInterval (мінімум 1 с) перезапускає скрипт за таймером, а не лише за подіями.

Hooks — детерміновані обробники, що запускаються на події життєвого циклу (зазвичай shell-команди; також доступні типи http, mcp_tool, prompt та експериментальний agent). Дані події hook отримує як JSON у stdin — наприклад, шлях до файлу лежить у .tool_input.file_path. Повний довідник (усі події, поля, формати відповіді) — на сторінці Налаштування → hooks; тут лише рецепти автоматизації саме для роботи з агентами.

Рецепт 1: форматування після кожної правки

Для Django + Vue потрібні різні форматери, тому фільтр за розширенням краще винести в скрипт. Hook спрацьовує на Edit і Write без поля if — про причину нижче.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# PostToolUse: форматуємо файл, який щойно змінив Claude
f=$(jq -r '.tool_input.file_path // empty')
[ -z "$f" ] && exit 0
case "$f" in
  *.py)            ruff format "$f" >/dev/null 2>&1 ;;
  *.vue|*.ts|*.js) npx prettier --write "$f" >/dev/null 2>&1 ;;
esac
exit 0

Рецепт 2: захист файлів (PreToolUse)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -qE '\\.(env|lock)$' && { echo 'Захищений файл' >&2; exit 2; } || exit 0"
          }
        ]
      }
    ]
  }
}

Рецепт 3: Stop-hook як ворота перед завершенням ходу

Hook на Stop може не пустити Claude закінчити, повернувши {"decision": "block", "reason": "…"} — Claude отримає причину й продовжить роботу. Оскільки такий hook працює раз за хід і бачить дерево цілком, він ловить і зміни, зроблені через Bash.

#!/bin/bash
INPUT=$(cat)
# Не зациклюватися: якщо ми вже продовжуємо через Stop-hook — дозволити зупинку
[ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ] && exit 0

# cwd з події, а не $CLAUDE_PROJECT_DIR: у worktree це різні каталоги
cd "$(echo "$INPUT" | jq -r '.cwd')" || exit 0

changed=$(git status --porcelain | awk '{print $NF}' | grep -E '\.py$' \
  | while read -r f; do [ -f "$f" ] && echo "$f"; done)
[ -z "$changed" ] && exit 0

if ! out=$(echo "$changed" | xargs ruff check 2>&1); then
  jq -n --arg r "ruff check знайшов проблеми, виправ їх: $out" '{decision: "block", reason: $r}'
fi
exit 0

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-gate.sh" }
        ]
      }
    ]
  }
}

Рецепт 4: повернути важливе після компакції

Компакція стискає розмову й може «з’їсти» домовленості. Hook SessionStart з матчером compact додає stdout у контекст щоразу після неї:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Нагадування: тести — pytest, фронтенд — npm run test:unit; коміти — Conventional Commits; git push не виконувати.'"
          }
        ]
      }
    ]
  }
}

Замість echo може бути будь-яка команда з динамічним виводом, наприклад git log --oneline -5. Для інструкцій, потрібних на кожному старті, краще CLAUDE.md. Якщо потрібно перезавантажувати середовище (direnv) при зміні каталогу, є події CwdChanged/SessionStart і файл $CLAUDE_ENV_FILE.

Рецепт 5: скоротити вивід тестів (PreToolUse + updatedInput)

Офіційний приклад з документації щодо витрат: hook переписує команду тестів, лишаючи у виводі тільки збої, — менше токенів у контексті. Він напряму підходить для pytest.

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# Якщо це запуск тестів — залишаємо лише збої
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "$input" | jq --arg filtered "$filtered_cmd" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/filter-test-output.sh" }
        ]
      }
    ]
  }
}

Події, корисні для роботи з агентами

Типи hooks і таймаути

Тут зібрано все, що стосується git у роботі з агентами: власний skill для комітів, керування вбудованими git-інструкціями й атрибуцією, зв’язок сесій із merge request у GitLab та вбудовані команди рев’ю. Паралельні гілки через worktrees — у розділі «Паралельна робота», запуск у CI — у «Headless і GitLab CI».

Skill smart-commit (виправлена версія)

---
name: smart-commit
description: >
  Аналізує staged зміни і створює коміт у форматі Conventional Commits.
  Запускай після git add.
disable-model-invocation: true
context: fork
model: haiku
allowed-tools: Bash(git diff *) Bash(git log *) Bash(git status *) Bash(git commit *)
---

Ти не бачиш попередньої розмови — працюй тільки зі staged змінами.

1. Виконай `git status --short` і `git diff --staged`. Якщо нічого не staged — зупинись і скажи про це.
2. Подивись `git log --oneline -5`, щоб підхопити стиль scope у проєкті.
3. Створи коміт (`git commit -m`) у форматі Conventional Commits:

type(scope): короткий опис (не більше 72 символів)

- Деталь 1: що і чому
- Деталь 2

BREAKING CHANGE: ... (тільки якщо є)
Refs: номер задачі GitLab (якщо відомий)

Типи: feat, fix, docs, style, refactor, perf, test, chore, ci.
Не виконуй `git push` і не змінюй файли.

Що змінено порівняно зі «спрощеною» версією і чому:

Атрибуція та вбудовані git-інструкції

Claude Code додає Claude власні інструкції про те, як писати коміти й pull/merge request (в описі Bash-інструмента), а також знімок git-стану (поточна гілка, головна гілка, вивід git status, останні коміти), зчитаний на початку розмови. До коміту додається трейлер Co-Authored-By, до опису PR — рядок про генерацію. Якщо у вас свій формат комітів (skill, CLAUDE.md), ці налаштування варто узгодити.

{
  "includeGitInstructions": false,
  "attribution": {
    "commit": "",
    "pr": "",
    "sessionUrl": false
  }
}

Власні інструкції про атрибуцію (CLAUDE.md, пам’ять) Claude Code ставить вище за ці рядки — крім значень, заданих у managed settings.

Merge request у GitLab: glab, значок і --from-pr

• Сесія зв’язується з PR/MR, коли Claude виконує gh pr create або glab mr create. Потім сесію можна знайти: claude --from-pr 123 або за URL merge request.
• Значок MR !N у футері (v2.1.234+): зелене підкреслення — GitLab вважає MR придатним до злиття, жовте — інший відкритий стан, сіре — draft. Потрібні remote на ваш GitLab (gitlab.com чи self-managed) і glab у PATH з виконаним glab auth login. Змінні токена на кшталт GITLAB_TOKEN Claude Code для цієї перевірки ігнорує, а наявність glab перевіряє раз за сесію — після встановлення перезапусти Claude Code. Значок оновлюється після успішних git push та glab mr create/glab mr merge.
• claude --worktree "https://gitlab.com/group/repo/-/merge_requests/123" (або "#123") створює worktree pr-123 з head цього MR (v2.1.233+). Докладніше — у розділі «Паралельна робота».

# знайти сесію, що створила MR
claude --from-pr https://gitlab.example.com/group/repo/-/merge_requests/123

# попросити Claude відкрити MR (дозволи нижче)
claude "Створи MR у main через glab mr create --fill з описом змін"

{
  "permissions": {
    "allow": [
      "Bash(glab mr view *)",
      "Bash(glab mr diff *)",
      "Bash(glab mr create *)"
    ],
    "deny": ["Bash(git push --force *)"]
  }
}

Рев’ю: /code-review, /security-review, /simplify

/code-review high --comment !123
/code-review https://gitlab.example.com/group/repo/-/merge_requests/123 --comment
/security-review
/simplify

Паралельна робота потребує двох речей: щоб агенти не псували файли один одного і щоб ти не сидів і не чекав. Перше вирішують git worktrees, друге — фонові команди та фонові сесії.

Worktrees: claude --worktree

Git worktree — окрема робоча тека з власними файлами й гілкою, але з тією самою історією та remote. --worktree (-w) створює її й запускає в ній Claude. Без імені назву генерує сам Claude.

claude --worktree feature-export     # .claude/worktrees/feature-export/, гілка worktree-feature-export
claude -w fix-login                  # друга ізольована сесія в іншому терміналі

# гілка з head існуючого MR (GitLab) або PR
claude --worktree "https://gitlab.com/group/repo/-/merge_requests/123"
claude --worktree "#123"             # лапки обов’язкові: # інакше початок коментаря в shell

• Додай .claude/worktrees/ у .gitignore, щоб вміст worktree не світився як untracked.
• Worktree — свіжий checkout: залежності треба поставити (pip install, npm install) — попроси Claude або зроби сам.
• Інтерактивний запуск вимагає workspace trust: у новій теці спершу запусти звичайний claude.
• Для MR URL Claude Code читає лише номер і завжди тягне з remote origin: на gitlab.com — merge-requests/<n>/head, на self-managed GitLab та інших хостах пробує pull/<n>/head, потім merge-requests/<n>/head. Теку названо pr-<номер>. Запит пароля чи passphrase не чекається — завантаж ключ у ssh-agent і раз виконай git fetch вручну.
• Можна й попросити Claude посеред сесії: «працюй у worktree» (інструмент EnterWorktree).

.worktreeinclude: перенести .env у нові worktree

Файл у корені проєкту з синтаксисом .gitignore. Копіюються лише файли, що і збігаються з патерном, і ігноруються git, тож відслідковувані файли не дублюються. Діє для --worktree, worktrees субагентів і паралельних сесій desktop-застосунку.

.env
.env.local
config/secrets.json

Налаштування worktree

{
  "worktree": {
    "baseRef": "head"
  }
}

Прибирання та повторне використання

• При виході з неіменованої чистої сесії worktree і його гілка видаляються автоматично; для іменованої Claude спитає. Якщо там є зміни чи нові коміти — запропонує залишити або видалити. Залишене можна відновити командою claude --worktree <name> --resume, яку Claude Code друкує при виході.
• Запуски з -p нічого не прибирають: видали вручну git worktree remove (якщо заблоковано — спершу git worktree unlock).
• Якщо передати ім’я вже існуючого worktree, відкриється він же. Чистий worktree на своїй гілці без власних комітів (або чий MR злито, а remote-гілку видалено) при "fresh" скидається на актуальну головну гілку.
• Worktrees субагентів і фонових сесій періодично прибирає sweep за терміном cleanupPeriodDays, але не чіпає ті, де лишилися зміни чи ненапушені коміти.

Що worktree ділить з основним checkout

• Каталог .git (тому git commit працює й із ввімкненим sandbox).
• Плагіни рівня проєкту (v2.1.200+).
• Схвалення «більше не питати» зберігаються в settings.local.json основного checkout і діють в усіх worktrees (v2.1.211+).
• Невідслідковувані skills, agents і commands: якщо у worktree немає власного .claude/skills, підхоплюється каталог основного checkout (для skills — v2.1.277+).

Субагент у власному worktree

---
name: refactorer
description: Робить механічні рефакторинги на багатьох файлах. Використовуй для масових змін.
isolation: worktree
model: sonnet
---

Застосуй запитаний рефакторинг до всіх потрібних файлів, потім запусти тести й повідом результат.

Субагент отримує тимчасовий worktree, який Claude Code прибирає, якщо змін немає; якщо зміни є — залишає. Гілка береться за тими самими правилами worktree.baseRef. Субагент у worktree бере стартові інструкції з головної розмови, а не зі свого worktree: CLAUDE.md і .claude/rules/ із кореня такого worktree він не підвантажує. Можна й просто попросити: «використай worktrees для агентів».

/batch: масові правки з ізоляцією

/batch <інструкція> розбиває роботу на 5–30 незалежних частин і запускає по одному фоновому субагенту в ізольованому worktree на кожну. Підходить для однотипних міграцій (наприклад, оновити виклики застарілого API у всьому Django-проєкті). Поза git-репозиторієм працює, якщо налаштований hook WorktreeCreate (v2.1.281+).

Фонові задачі: Ctrl+B, /tasks

• Ctrl+B переносить запущену Bash-команду чи агента у фон (у tmux — двічі). Просто сказати Claude «запусти у фоні» теж можна.
• Команда, що досягла таймауту, автоматично йде у фон (крім команд, що починаються з sleep); вивід — у файл, керування — /tasks (псевдонім /bashes). Задачі вбиваються при 5 ГБ виводу й прибираються при виході.
• Субагент у фоні: поле background: true у frontmatter. Його запити дозволів з’являються в головній сесії. Ctrl+X Ctrl+K (двічі за 3 с) зупиняє всіх фонових субагентів сесії.
• Вимкнути фонові задачі: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1. У режимі --bare їх теж немає.
• Ctrl+T показує чекліст задач Claude (це не фонові задачі), Ctrl+O — transcript viewer.

Фонові сесії: --bg і claude agents

Agent view (дослідницький preview) — один екран для багатьох фонових сесій: що робить кожна, кому потрібен твій ввід, що завершилось. Сесії працюють на твоїй машині, витрачають квоту підписки незалежно й зупиняються при вимкненні комп’ютера (сон переживають).

claude agents                              # відкрити agent view
claude agents --cwd ~/projects/my-app      # лише сесії з цього каталогу
claude --bg "розберися з нестабільним тестом test_export"
claude --bg --name flaky-fix "розберися з нестабільним тестом"
claude --agent code-reviewer --bg "відреагуй на коментарі до MR 123"
claude --resume <session-id> --bg "продовж з того місця"
claude --bg --exec 'pytest -x'             # shell-команда як фонова робота

• --bg не поєднується з -p/--print.
• Усередині сесії: /background (/bg) переносить розмову у фон; /fork копіює розмову у нову фонову сесію, а оригінал продовжує працювати (v2.1.212+); на порожньому промпті ← теж відправляє у фон.
• Перед правками диспатчена сесія переходить у власний worktree в .claude/worktrees/ — крім випадків, коли її винесено у фон вже відкритою, вона вже у worktree або каталог не git-репозиторій без WorktreeCreate. Вимкнути: "worktree": {"bgIsolation": "none"}.
• Видалення сесії в agent view прибирає її worktree разом з незакоміченими змінами; claude rm зберігає worktree зі змінами і відмовляє, якщо є ненапушені коміти (без --discard-unpushed). Транскрипти лишаються — claude --resume.
• Вимкнути: disableAgentView: true або CLAUDE_CODE_DISABLE_AGENT_VIEW; відкривати agent view за замовчуванням: /config defaultToAgentsView=true.

У agent view: Space — peek (швидка відповідь без входу), Enter/→ — під’єднатися, ← на порожньому промпті — від’єднатися, Ctrl+X — зупинити (повторно протягом 2 с — видалити), Ctrl+T — закріпити, Ctrl+R — перейменувати, ? — усі комбінації. Задати значення за замовчуванням для сесій, запущених з agent view, можна прапорами: claude agents --permission-mode plan --model opus --effort high.

Патерн Writer/Reviewer

Свіжий контекст рев’юера не упереджений до коду, який він сам щойно написав. Тому писати й перевіряти варто в різних сесіях.

# термінал A: пише код
claude -w feature-export

# термінал B (основний checkout): окрема сесія з агентом-рев’юером
claude --agent code-reviewer \
  "Перевір git diff main...worktree-feature-export: коректність, тести, безпека. Звітуй лише про те, що впливає на правильність."

Гілку, на якій працює worktree, не можна одночасно відкрити в основному checkout, тому рев’юер читає diff, а не перемикається на цю гілку. Інший варіант: після пушу запустити /code-review high --comment !<номер> із нової сесії.

claude -p "…" запускає Claude Code без інтерактивного інтерфейсу: результат іде в stdout, код виходу 0 означає успіх, ненульовий — помилку (при SIGTERM — 143). Так Claude вбудовується в скрипти, git-hooks і CI. Це та сама агентна петля й ті самі інструменти, що й у терміналі (Agent SDK у режимі CLI).

Прапори claude -p

Корисні рецепти

# повідомлення коміту (офіційний приклад)
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

# лог збірки в аналіз причини
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

# diff у рев’ю безпеки; для GitLab замість gh pr diff підставте glab mr diff (адаптація, у документації приклад для gh)
glab mr diff 123 | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json | jq -r '.result'

# структурований вивід
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

# цикл по файлах (fan-out) без жодних запитів
for f in $(cat files.txt); do
  claude -p "Migrate $f to the new API" --allowedTools "Edit,Bash(git commit *)" --permission-mode dontAsk
done

• Вхід через pipe (stdin) обмежений 10 МБ; більші дані клади у файл і давай шлях у промпті.
• Користувацькі skills працюють: /skill-name у рядку промпта розгортається перед запуском. Вбудовані термінальні команди (/login) недоступні. /model sonnet, /effort, /config key=value і /output-style <style> приймають значення аргументом.
• Після завершення ходу -p може чекати фонову роботу (фонові команди, субагенти, Monitor): ліміт простою — 10 хв, змінюється CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS (0 — без ліміту). Досягнутий --max-budget-usd зупиняє залишок фонової роботи.
• Мережеві помилки API з повтором видають події system/api_retry; system/init у stream-json повідомляє про MCP-сервери (mcp_server_errors) і плагіни (plugin_errors) — по них CI може впасти, якщо щось не завантажилось.

Дозволи в CI

GitLab CI/CD: інтеграція від GitLab

Офіційна сторінка інтеграції — у бета-статусі, її підтримує GitLab. Основа — те саме CLI та Agent SDK, що запускається в джобі на ваших runner’ах; усі зміни проходять через MR, тож діють branch protection і approvals. Мінімальний офіційний джоб:

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    GIT_STRATEGY: fetch
  before_script:
    - apk update
    - apk add --no-cache git curl bash
    - curl -fsSL https://claude.ai/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    # необов’язково: GitLab MCP-сервер, якщо ваш runner його має
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug

Повний приклад: рев’ю MR з публікацією нотатки

Джоб нижче запускається на кожну подію merge request, дає Claude лише читання коду, повертає знахідки за JSON-схемою і публікує їх в MR однією приміткою. Публікацію виконує окремий curl, тому Claude токена GitLab API не отримує.

stages:
  - review

claude-mr-review:
  stage: review
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  allow_failure: true            # рев’ю не блокує злиття
  timeout: 15m
  variables:
    GIT_DEPTH: "0"               # повна історія — потрібна для diff проти цільової гілки
    REVIEW_SCHEMA: '{"type":"object","properties":{"summary":{"type":"string"},"findings":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"severity":{"type":"string","enum":["high","medium","low"]},"message":{"type":"string"}},"required":["file","severity","message"]}}},"required":["summary","findings"]}'
  before_script:
    - apk add --no-cache git curl bash jq
    - curl -fsSL https://claude.ai/install.sh | bash
    # інсталятор кладе claude у ~/.local/bin, якого немає в PATH цього образу
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
    - git diff "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD" > mr.diff
    # конвенції беремо з ЦІЛЬОВОЇ гілки, а не з MR: автор MR не може підмінити інструкції рев’юера
    - git show "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME:CLAUDE.md" > /tmp/conventions.md || echo "" > /tmp/conventions.md
    # env -u: токен GitLab API не потрапляє в оточення Claude;
    # --tools без Bash + blockReadsOutsideWorkingDirectories: читання лише в теці проєкту
    - |
      env -u GITLAB_ACCESS_TOKEN claude --bare -p "Review the merge request diff in mr.diff. Report only bugs, security issues and missing tests. No style nitpicks. Answer in Ukrainian." \
        --append-system-prompt-file /tmp/conventions.md \
        --tools "Read,Grep,Glob" \
        --settings '{"permissions":{"blockReadsOutsideWorkingDirectories":true}}' \
        --permission-mode dontAsk \
        --max-turns 15 \
        --max-budget-usd 2.00 \
        --no-session-persistence \
        --output-format json \
        --json-schema "$REVIEW_SCHEMA" > review.json
    - jq -e '.structured_output' review.json > findings.json
    - |
      jq -r '"## Claude review\n\n" + .summary + "\n\n" + ([.findings[] | "- **" + .severity + "** `" + .file + (if .line then ":" + (.line | tostring) else "" end) + "` — " + .message] | join("\n"))' findings.json > note.md
    # публікує окремий curl: токен GitLab API у Claude не передається
    - |
      curl --fail --silent --request POST \
        --header "PRIVATE-TOKEN: $GITLAB_ACCESS_TOKEN" \
        --data-urlencode "body@note.md" \
        "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
  artifacts:
    when: always
    expire_in: 1 week
    paths:
      - review.json

• GITLAB_ACCESS_TOKEN — Project Access Token зі scope api, masked. ANTHROPIC_API_KEY також masked. Protected-змінні недоступні на незахищених гілках MR — якщо рев’ю потрібне на всіх гілках, змінні мають бути не protected.
• У mr.diff лежить diff цільової гілки та HEAD; Claude читає його інструментом Read і за потреби відкриває файли через Read/Grep/Glob. --tools обмежує набір інструментів, тож Bash у сесії немає взагалі (а саме --allowedTools лише попередньо схвалює, і в dontAsk read-only команди Bash на кшталт cat усе одно виконувалися б). На Linux Grep і Glob за замовчуванням відсутні — їх повертає саме згадка в --tools. permissions.blockReadsOutsideWorkingDirectories (v2.1.257+) не дає файловим інструментам читати поза текою проєкту, а env -u прибирає GITLAB_ACCESS_TOKEN з оточення процесу Claude — prompt injection у diff не зможе витягти токен у нотатку.
• Для проєктів із .claude/CLAUDE.md змініть шлях у git show. --bare CLAUDE.md не читає, тому конвенції передані через --append-system-prompt-file.
• Альтернатива: вбудоване /code-review … --comment теж вміє публікувати нотатку в GitLab MR через glab (v2.1.257+); без glab знахідки лише друкуються. Документація описує це як команду сесії й окремого рецепта для CI не дає — запуск у джобі (авторизований glab, ширші права, токен у оточенні Claude) є нашою адаптацією: перевір на тестовому MR, перш ніж робити обов’язковим.

Безпека CI-джобів

Ставтеся до MR від Claude як до MR від будь-якого іншого учасника: рев’ю, approvals і branch protection мають лишатися. Документація наголошує: інтеграція працює на ваших runner’ах із вашими правилами захисту гілок.

Output style — набір інструкцій, що задає роль, тон і формат відповідей на всю сесію. Це інструкція, яку Claude виконує, а не гарантія: для того, що має відбуватися завжди, потрібен hook, для знань про проєкт — CLAUDE.md.

Вбудовані стилі

Як перемкнути

• /output-style concise (v2.1.269+; без аргументу — список). Працює й у -p.
• /config → Output style, або поле outputStyle у settings: значення чутливе до регістру ("Explanatory"); неправильне дає Default. Команда і меню зберігають вибір у .claude/settings.local.json.
• Стиль за замовчуванням для всіх проєктів — outputStyle у ~/.claude/settings.json; налаштування проєкту мають пріоритет.
• Зміна посеред сесії діє з наступного повідомлення (до v2.1.251 — лише після /clear).

Власний стиль для команди

Markdown-файл у ~/.claude/output-styles/ або .claude/output-styles/ (також у каталозі managed settings і в плагінах). Назва файлу стає назвою стилю, якщо не задано name. Файли читаються при старті — після створення перезапусти Claude Code.

---
name: MR review
description: Рев’ю у форматі, зручному для коментаря в GitLab MR
keep-coding-instructions: true
---

Відповідай українською. Структура відповіді завжди така:

## Висновок
Одне речення: можна зливати чи ні.

## Критичне
Помилки коректності та безпеки: файл:рядок і що не так. Якщо нічого немає — так і напиши.

## Рекомендації
Не більше трьох пунктів, за пріоритетом.

• Стилі діють на головну розмову та на fork; інші субагенти мають власний системний промпт, тож стиль на них не впливає.
• Помилка написання поля у frontmatter мовчки ігнорується; якщо YAML не розбирається, стиль завантажується під іменем файлу без полів — шукай причину у claude --debug.

Стиль, CLAUDE.md, skill, hook чи субагент?

Status line: контекст і вартість завжди на виду

Status line — рядок унизу інтерфейсу, що виконує ваш shell-скрипт: він отримує JSON сесії в stdin і друкує те, що треба показати. Налаштувати можна командою /statusline (опиши, що хочеш, і Claude напише скрипт) або вручну:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2,
    "refreshInterval": 30
  }
}

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
BRANCH=$(git branch --show-current 2>/dev/null)
printf '[%s] ctx %s%% | $%.2f | %s\n' "$MODEL" "$PCT" "$COST" "$BRANCH"

• Скрипт запускається подіями (нове повідомлення, зміна команди тощо); refreshInterval (мінімум 1 с) додає періодичний запуск — корисно для годинника чи коли фонові субагенти змінюють git, поки основна сесія простоює.
• padding додає горизонтальний відступ у символах. Видалити: /statusline delete або прибрати поле statusLine.
• Status line не замінює вбудований футер, але при власному рядку Claude Code ховає більшість підказок на клавіші.
• Це найдешевший спосіб бачити заповненість контексту й вартість без окремих команд — доповнення до /context і /usage.

Що робити

Чого уникати

Що комітити, що ні

проєкт/
├── CLAUDE.md                 ← комітити (або .claude/CLAUDE.md); цільовий розмір до 200 рядків
├── CLAUDE.local.md           ← НЕ комітити: у корені проєкту, додай у .gitignore вручну
├── .worktreeinclude          ← комітити (які ігноровані файли копіювати у worktrees)
└── .claude/
    ├── settings.json         ← комітити (спільні налаштування команди)
    ├── settings.local.json   ← НЕ комітити (Claude Code сам додає у глобальні git excludes при першому записі)
    ├── agents/              ← комітити
    ├── agent-memory/        ← комітити (memory: project)
    ├── agent-memory-local/  ← НЕ комітити (memory: local)
    ├── skills/              ← комітити
    ├── commands/            ← комітити (legacy, сумісні)
    ├── rules/               ← комітити
    ├── output-styles/       ← комітити
    ├── workflows/           ← комітити
    ├── hooks/               ← комітити (скрипти для settings.json)
    └── worktrees/           ← НЕ комітити (додай у .gitignore)

CLAUDE.md (приклад для Django + Vue 3 проєкту)

# Project: My Web App

## Stack
- Backend: Django 4.2, DRF, PostgreSQL, Redis
- Frontend: Vue 3, Pinia, Vite, TypeScript
- Infra: Docker, nginx

## Commands
- `make dev`  — запустити локально
- `make test` — усі тести
- `make lint` — перевірка якості коду
- `pytest path/to/test_file.py::test_name` — один тест (швидше за весь набір)
- `npm run test:unit -- path/to/file.spec.ts` — один фронтенд-тест
- `python manage.py makemigrations --check` — перевірити, що міграції актуальні

## Environment
- Скопіюй `.env.example` у `.env`; без `DATABASE_URL` і `REDIS_URL` тести не стартують

## Conventions
- Conventional Commits обов’язково; гілки `feature/<тема>`, `fix/<тема>`
- MR у `main` через GitLab; перед MR — `make lint && make test`
- Тести обов’язкові для нової бізнес-логіки
- API endpoints мають вхідну валідацію через DRF serializers
- Vue компоненти — Composition API з <script setup>

IMPORTANT: ніколи не редагуй застосовані міграції — створюй нову.

Тримай такий файл у межах 200 рядків. Включай те, чого Claude не вгадає з коду: команди (зокрема запуск одного тесту), нюанси середовища, правила гілок і MR, архітектурні рішення. Не пиши очевидного й загальноприйнятого — мірило: «чи помилиться Claude без цього рядка?». Слово IMPORTANT ставлять в окремому рядку.

settings.json

{
  "permissions": {
    "allow": [
      "Bash(make *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git add *)",
      "Bash(pytest *)",
      "Bash(npm run *)",
      "Bash(glab mr view *)",
      "Bash(glab mr diff *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}

Hook викликає скрипт format.sh із розділу Hooks (ruff для .py, prettier для .vue/.ts/.js). Фільтр за розширенням винесено в скрипт, бо поле if приймає лише одне правило й гарантовано працює для Edit, а не обов’язково для Write. git push заборонено дозволами — тому MR створюйте самі або додайте окреме правило для glab mr create (див. «Git і GitLab»).

Найкорисніше для роботи з агентами на одному екрані. Повний список — /help і довідник команд.

Slash-команди

/ultraplan видалено — використовуй режим планування.

Прапори CLI

Підкоманди

Гарячі клавіші

Написання власних скілів та субагентів у .claude/ — це стратегічна переорієнтація розробки.

Крок за кроком

1. Почніть з CLAUDE.md — зафіксуйте конвенції проєкту (найбільший leverage)
2. Додайте 2–3 скіли — fix-bug, new-feature, code-review
3. Визначте субагентів — reviewer, commit-agent як мінімум
4. Налаштуйте hooks — форматування, блокування небезпечних операцій, Stop-перевірки
5. Винесіть рутину в CI — рев’ю MR у GitLab CI через claude -p з обмеженими інструментами й бюджетом
6. Розпаралелюйте — worktrees та фонові сесії для незалежних задач
7. Розширюйте поступово — додавайте нових агентів за реальною потребою

Актуальні ресурси