Notatky logo
Published on

Як зробити, щоб Claude Code доводив задачу до кінця

Як зробити, щоб Claude Code доводив задачу до кінця
Автори
  • avatar
    Name
    Екклезіаст
    github

Ви просите додати форму на сторінку налаштувань. Через десять хвилин Claude Code повертає правку в пʼяти файлах: новий маршрут в app/api, власну схему валідації і рефакторинг сусіднього компонента. /context показує, що вікно зайняте на 78%, і більша частина цього обсягу — читання файлів, якого ви не замовляли.

Модель тут не помилилась. Промпт «додай форму на сторінку налаштувань» не містить умови, за якою можна сказати, що робота закінчена, тому цикл зупинився на першій правдоподібній правці, а до неї встиг обійти половину репозиторію.

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

Агентний цикл зупиняється на умові, яку видно в diff

Агентний цикл (agentic loop) — послідовність «промпт → виклик інструмента → дія → перевірка», яка повторюється, доки результат не збігається з метою. Збіг зупиняє цикл, розбіжність запускає ще один прохід. Поки цикл іде, можна додати контекст, перервати крок або спрямувати модель.

Інструмент (tool) — дія, яку модель запитує посеред роботи: прочитати файл, виконати команду оболонки, пошукати в мережі. Claude Code сам обирає момент виклику за змістом задачі і підставляє результат у наступний крок.

Агентний цикл Claude Code
Агентний цикл Claude Code

Критичний крок тут — перевірка. Вона працює, лише якщо умова перевірна: її можна побачити в diff або отримати з команди. «Зроби форму кращою» такого критерію не дає. Корисна умова виглядає так:

Додай на /settings форму зміни email.
Відправляй через наявний server action у src/app/settings/actions.ts.
Нових маршрутів в app/api не створюй.
Валідацію візьми з тієї самої схеми, що на /signup.
Готово, коли email зберігається і проходить npm run lint && npm run build.

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

Контекстне вікно — бюджет сесії

Контекстне вікно (context window) вміщує системний промпт, вашу розмову, вміст прочитаних файлів, вивід команд і описи доступних інструментів. Кожен промпт і кожен результат інструмента додають до нього обсяг. Коли місця не лишається, Claude Code стискає розмову сам: лишає те, без чого не продовжити, решту зводить до переказу.

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

Команда або файлЩо робитьКоли застосовувати
/contextПоказує, чим вікно зайняте заразПеред довгим кроком і коли відповіді «плавають»
/compactСтискає розмову до вижимки, лишає місцеФіча не дороблена, а вікно близько до межі
/clearВідкриває сесію з порожнім вікномПочинається нова фіча
CLAUDE.mdІнструкції, які читаються на старті сесіїПравило потрібне в кожній сесії проєкту
/initЗбирає CLAUDE.md за проєктомСписок повторюваних правил уже усталився
@шлях/до/файлаВкладає конкретний файл у промптПотрібен саме цей документ, а не пошук по проєкту

/compact і /clear вирішують різні задачі. Перша лишає контекст поточної роботи, друга його прибирає навмисне, щоб рішення попередньої фічі не підсовувались як уже ухвалені.

Те, що має пережити сесію, живе у CLAUDE.md: стек, команди збірки й тестів, уподобання на кшталт «у цьому проєкті лише server actions». Файл краще збирати з реальних повторень: почніть без нього, позначайте, де доводиться повертати модель, і коли список усталився, викличте /init. Так у файлі лишається тільки те, без чого сесія справді збивається, — а кожен зайвий рядок CLAUDE.md теж витрачає вікно.

Велике вікно не скасовує це правило. Чому модель гірше тримає середину довгого контексту, розібрано в статті про чотири властивості мовних моделей.

Режим дозволів визначає, що виконається без вас

Цикл править файли і запускає команди у вашому репозиторії, тому другий рівень керування — дозволи. Режим задають прапорцем --permission-mode на запуск або ключем permissions.defaultMode у налаштуваннях.

default питає підтвердження перед правкою файлів і перед командою оболонки. acceptEdits (той самий auto-accept) знімає питання лише з файлів: команда все одно чекає на вас. plan працює інструментами читання і спочатку збирає план, не змінюючи код. Саме цей план потім стає міркою, з якою цикл звіряє результат. bypassPermissions не питає нічого; його не варто тримати як стандартний режим, і з файлу налаштувань проєкту він не застосовується.

Замість того щоб знімати підтвердження повністю, точкові правила описують у .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

allow перелічує те, що можна виконувати без питання: ідемпотентні команди, помилку яких легко відкотити. deny закриває доступ назовсім — секрети, прод-конфіг. Файл лежить у репозиторії, тому правила ті самі в усієї команди.

На цих режимах тримається звичний прохід Explore → Plan → Code → Commit. Розвідка в plan-режимі дає контекст проєкту. План фіксує, як виглядає готове. Далі йде обмін правками, поки результат збігається з планом. Коміт — це перегляд diff і відправка; наступна фіча починається після /clear.

Оболонок у Claude Code кілька, цикл один: термінал, розширення в редакторі, десктопна програма для фонової роботи і браузерна версія для репозиторію на GitHub. Налаштування з .claude/settings.json і CLAUDE.md працюють однаково в усіх.

Гачок виконує правило без винятків

Рядок у CLAUDE.md на кшталт «після кожної правки запусти Prettier» здебільшого спрацює. Здебільшого — не те саме, що завжди: це інструкція моделі, а не гарантія.

Гачок (hook) — команда, яку Claude Code виконує в заданий момент життєвого циклу незалежно від рішення моделі. Описують його в settings.json або через /hooks: подія, матчер інструментів і сам обробник. Подій багато, у щоденній роботі потрібні кілька.

ПодіяКоли спрацьовуєТипове застосування
UserPromptSubmitПромпт надіслано, до обробкиДодати контекст, відкинути промпт
PreToolUseПеред викликом інструментаЗаблокувати небезпечну дію
PostToolUseПісля успішного викликуФорматування, лінт, типи
StopВідповідь завершеноСповіщення, фінальна перевірка
PreCompactПеред стисканням контекстуЗберегти те, що не має зникнути

Форматування садять на PostToolUse з матчером правок:

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

${CLAUDE_PROJECT_DIR} — корінь проєкту, у якому стартувала сесія. Шлях до скриптів беруть саме з нього, щоб гачок не залежав від поточної теки Claude.

PreToolUse відрізняється тим, що вміє зупинити виклик. На stdin обробник отримує JSON із назвою інструмента і його входом, а далі вирішує код виходу: 0 пропускає дію, 2 блокує її і повертає моделі текст зі stderr як пояснення, будь-який інший код показує вам помилку, але дія все одно виконується. Так закріплюють заборони, які не повинні залежати від настрою сесії:

#!/bin/bash
# .claude/hooks/no-main-commit.sh
command=$(jq -r '.tool_input.command')

if [[ "$command" == *"git commit"* && "$(git branch --show-current)" == "main" ]]; then
  echo "Коміт у main заборонено: створіть гілку" >&2
  exit 2
fi

Замість коду виходу 2 обробник може вивести JSON із hookSpecificOutput.permissionDecision: "deny" і причиною — результат той самий, але відповідь структурована. Гачки з .claude/settings.json комітять у репозиторій, і їх отримує вся команда.

Субагент, CLI і MCP: три різні ціни в контексті

Розвідка забиває вікно дужче за саму фічу: довгі читання файлів, пошук, логи. Субагент (subagent) виконує таку задачу у власному контекстному вікні й повертає в основну сесію лише підсумок. Список прочитаних файлів лишається в його вікні, не у вашому.

Описують субагента Markdown-файлом із YAML у шапці: .claude/agents/ для проєкту, ~/.claude/agents/ для всіх ваших проєктів. Обовʼязкові поля — name і description; за описом Claude вирішує, коли агента кликати. Створити файл можна командою /agents.

---
name: diff-reviewer
description: Рецензує diff перед пушем. Викликати після завершення фічі.
tools: Read, Grep, Glob, Bash
model: inherit
---

Ти рецензент. Перевір diff на помилки, безпеку і відхилення від конвенцій проєкту.
Файли не змінюй, лише перелічи знайдене з посиланням на рядки.

Це корисний випадок сам собою: субагент бачить diff у чистому вікні й оцінює його окремо від рішень, які основна сесія щойно ухвалила, тобто без історії написання. Інструменти йому лишають тільки читальні. Поле memory: user зберігає нотатки агента між розмовами, а skills вкладає названі навички повним текстом.

MCP (Model Context Protocol) підключає те, що лежить поза репозиторієм: сервер Linear приносить тікети, сервер на кшталт Context7 — свіжу документацію залежності. Сервер додають командою claude mcp add з однією з трьох областей: local — тільки поточний проєкт і тільки для вас, user — усі ваші проєкти, project — список у .mcp.json, який після коміту отримує команда.

Ціна в MCP постійна: описи інструментів сидять у вікні, навіть коли ви їх не кличете. Звідси порядок вибору. Якщо в сервісу є CLI, як gh або aws, він ощадніший: опис не висить у контексті, а Claude викликає команду через Bash. Навичка (Skill) тримає у вікні лише назву і короткий опис, повний текст читається в момент потреби. Зайві сервери вимикають у /mcp. А сервер, потрібний одному субагентові, описують прямо в його шапці через mcpServers — тоді основна сесія його описів не бачить взагалі.

Коли описи MCP займають понад десяту частину вікна, Claude Code переходить на пошук інструментів за потребою. Місце економиться, але влучність вибору нижча, ніж у короткого явного списку.

Збої живуть на перетині цих налаштувань

Кожне з цих налаштувань окремо зрозуміле. Реальні збої живуть там, де вони перетинаються.

Найчастіший — acceptEdits на повному вікні. Автоматичне стискання викидає з контексту план і початкові обмеження, а правки файлів далі йдуть без підтвердження. Формально цикл працює, фактично він звіряє код із переказом, у якому вашої умови вже немає. Тому перед довгим кроком варто подивитись /context і стиснути розмову самому, поки вижимку ще формує повний контекст.

Другий — правило, яке живе не там, де має. Умову цієї фічі тримають у промпті, бо вона одноразова. Уподобання проєкту — у CLAUDE.md, бо воно потрібне щосесії. Інваріант, який не має винятків, — у гачку, бо гачок не залежить ні від того, що лишилось у вікні, ні від того, як модель прочитала інструкцію. Інваріант, залишений у промпті, зникає першим під час стискання.

Третій — розвідка в основному вікні. Пошук по незнайомому репозиторію коштує стільки, що на саму фічу місця вже не лишається. Це робота субагента, і виносити її варто до того, як /context покаже 70%, а не після.

Що зробити наступного разу

Наступну фічу почніть із /clear і з промпту, в якому є перевірна умова: що має зʼявитись у diff, чого там бути не повинно і яка команда підтверджує результат. Увімкніть plan-режим, прочитайте план і лише тоді дозволяйте правки.

Далі розкладіть умови по рівнях. Повторюване вподобання — у CLAUDE.md. Заборону без винятків — у гачок PreToolUse. Безпечні команди — у permissions.allow, щоб підтвердження лишились тільки там, де вони справді потрібні. Розвідку по репозиторію віддайте субагентові. Тоді вікно залишиться під поточну роботу, а цикл перевірятиме код проти умови, яку ви сформулювали, а не проти її переказу.

Джерела

Підпишіться на нові статті
Про що надсилати листи:

Уже підписані? Повторна підписка лише додає теми. Щоб відписатися, натисніть «Відписатися» в будь-якому листі.