Два курси по годині й два короткі матеріали закривають основні прогалини

Урок 1. Керування довгими сесіями (Steering long sessions)

Короткі задачі прості: попросив, перевірив. Довгі (рефакторинг на десяток файлів, нова фіча на кілька годин) затягуються тим більше, чим частіше доводиться виправляти курс. Дві базові звички: спершу окреслити обсяг роботи, а потім керувати нею під час виконання.

Спершу окресліть роботу в plan mode

• У plan mode Claude досліджує код, не редагуючи вихідні файли: читає, визначає, що треба змінити, і віддає план на перевірку.
• План треба саме прочитати, а не проглянути: що ретельніший план, то менше сюрпризів під час виконання.
• Якщо чогось бракує або щось не так, попросіть Claude дописати це в план. Ітерувати план значно швидше, ніж запустити роботу навмання й потім розгрібати наслідки.

Керуйте, поки Claude працює: compact

/compact підсумовує розмову, робить цей підсумок новим контекстом і видаляє старі повідомлення, звільняючи context window. Ризик: у підсумку може загубитися щось важливе, і Claude почне відхилятися від курсу.

• Не запускайте /compact «голим». Дописуйте після команди інструкцію, що саме зберегти. Наприклад, якщо налагодження давно завершене, а зараз важливі лише зміни API:

/compact Focus on the --version flag implementation

Усе, що написано після команди, визначає зміст підсумку. Це ваш інструмент керування контекстом.

Rewind

Коли Claude пішов не туди, не треба «випрошувати» повернення новими промптами. Rewind повертає до checkpoint: кожен ваш промпт створює checkpoint. Меню відкривається подвійним натисканням Esc на порожньому рядку вводу. Варіанти:

• Restore code and conversation — відкотити і код, і розмову разом.
• Restore conversation — відкотити лише чат.
• Restore code — відкотити лише файли.
• Summarize from here — стиснути все після checkpoint; зручно, якщо була побічна розмова і треба звільнити місце.
• Summarize up to here — стиснути все до checkpoint; зручно, коли була довга фаза підготовки, а частину з реалізацією хочеться зберегти повністю.

Автономніша робота: goal

/goal задає умову завершення: ви описуєте, як виглядає «готово», і Claude працює через кілька ходів, доки швидкий evaluator не підтвердить виконання умов. Він не зупиниться просто тому, що вперше вирішив, що закінчив.

/goal all tests in src/billing pass, and the type checker reports zero errors

• Скасування: /goal clear.
• Важливе обмеження: evaluator читає лише transcript. Умова має бути перевірною з того, що Claude реально виводить (наприклад, результат прогону тестів).

Автономніша робота: loop

• /loop запускає промпт з інтервалом між ходами: фіксованим або self-paced (Claude сам обирає темп).
• Призначення: опитувати щось зовнішнє (CI-прогін, деплой) і діяти, коли стан змінився.
• Self-paced loop зупиняється натисканням Esc, поки він чекає наступного запуску. Loop із фіксованим інтервалом працює, доки ви не попросите Claude його скасувати, або максимум сім днів.

Паралельна робота у worktrees

• Дві сесії Claude, що редагують ті самі файли, конфліктують. Worktree дає кожній сесії власне незалежне дерево файлів, тож агенти не затирають зміни один одного.
• Коли сесія завершується, чистий worktree видаляється автоматично.
• Файл .worktreeinclude у корені репозиторію перелічує git-ignored файли, які треба копіювати в кожен worktree: наприклад, файл зі змінними середовища чи локальний конфіг, які потрібні всюди, але не комітяться.

Підсумок уроку

• Спочатку окреслити роботу, потім керувати.
• Спрямовувати compaction інструкцією, щоб підсумок зберіг важливе.
• Виправляти дрейф через меню rewind.
• Ставити goal, коли «готово» описати легше, ніж кроки.
• Паралельну роботу запускати у worktrees.

Головне: довгу сесію робить надійною не постійний нагляд, а план на старті плюс точкові інструменти керування (спрямований compact, rewind, goal/loop, worktrees).

Урок 2. CLAUDE.md, якого Claude дотримується (A CLAUDE.md that follows)

Типова пастка: на кожну проблему в CLAUDE.md додається нове правило, файл розростається, і Claude починає ігнорувати його частини. Це не баг, а природа файлу: CLAUDE.md — не примусова конфігурація, а настанови. Кожен рядок конкурує з усіма іншими за увагу моделі, тож що довший файл, то менш надійно виконується кожне окреме правило. Мета — не записати все, а тримати файл стислим.

Спершу перевірте, чи CLAUDE.md взагалі правильний інструмент

• Є м'які настанови, а є жорсткі межі, які не можна перетинати ніколи. Це різні задачі.
• Приклад: «never push to main». У CLAUDE.md ви лише сподіваєтеся, що Claude послухає; «здебільшого» для такого ризику недостатньо.
• Жорсткі правила переносьте в PreToolUse hook: це код, який виконується перед дією і може її заблокувати навіть тоді, коли Claude спробує її виконати. CLAUDE.md лишається для м'якших конвенцій.

Чотири розташування CLAUDE.md

Claude завантажує всі чотири одночасно при запуску; вони складаються, нічого не відкидається:

• Managed policy — рівень організації, контролює платформна команда; виключити його не можна, тож політика організації діє завжди.
• User — особисті вподобання, що діють у всіх проєктах на вашій машині.
• Project — спільний з командою файл, закомічений у репозиторій.
• Local — ігнорується git; ваші особисті нотатки лише для цього репозиторію. Наприклад, архітектурні рішення для вашого рефакторингу в окремій гілці, які не мають впливати на всю команду.

Розбиття великого файлу через imports

Довгий project-файл можна розкласти на частини синтаксисом імпорту за шляхом:

@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md

Застереження: при запуску імпортовані файли розгортаються inline у місці посилання. Імпорти допомагають упорядкувати, але все одно завантажуються одразу й обсяг контексту не зменшують.

Формулювання вирішує, чи правило спрацює

• Конкретно й перевірно. Якщо ви самі не можете перевірити виконання, Claude теж не може. Погано: «Follow best practices for API routes». Добре: «Put new API routes in src/api/handlers, one per file» — результат одразу видно.
• Називайте заміну, а не лише забороняйте. «Don't use default exports» лишає простір для здогадок; «Use named exports, not default exports» його закриває.
• Наголос — це бюджет. «IMPORTANT», «YOU MUST» підвищують пріоритет лише відносно тихіших правил. Якщо кричить усе, не виділяється ніщо. Витрачайте наголос на два-три правила, порушення яких справді болить.

Файл постійно редагується

• CLAUDE.md ніколи не «готовий»; ставтеся до нього як до живого коду.
• Коли Claude помиляється, сприймайте це як bug report на CLAUDE.md, а не виправляйте мовчки вручну. Можна прямо сказати Claude «add that to the CLAUDE.md file», і він сам запише правило.

Підсумок уроку

• Ставтеся до CLAUDE.md як до production-коду: рядок, який не можете обґрунтувати, видаляйте.
• Жорсткі правила — у hooks, де вони справді примусові.
• Довгі файли впорядковуйте імпортами (контекст вони не зменшують).
• Кожне правило — конкретне, перевірне, з названою заміною.
• Наголос — лише на найважливіших правилах.
• Переглядайте файл щоразу, коли Claude помиляється.

Головне: що стисліший CLAUDE.md, то більшу його частину Claude виконує; усе, що має бути гарантованим, належить hooks, а не CLAUDE.md.

Урок 3. Skills для перевірки (Verification skills)

Коли проєкт росте, одна й та сама робота повторюється, і skills її автоматизують. Урок про конкретне застосування: перевірку власної роботи. Якщо будувати лише один skill першим, то цей.

Чому verification skill варто створити першим

Зазвичай перевірка залежить від того, чи ви не забули попросити прогнати тести або прочитати diff. Пропустили раз — поганий код проходить. Verification skill прибирає цю залежність: коли Claude завершує, наприклад, рефакторинг, зміна відповідає опису skill, і він спрацьовує сам. Далі він:

• запускає набір тестів;
• читає diff;
• перевіряє, що жоден тест не послабили заради проходження;
• звітує pass або fail із доказами.

Спрацювання визначає опис (description) skill, а після запуску він щоразу проходить ті самі кроки. Остання перевірка критична: зелені тести нічого не гарантують, якщо тест тихо послабили. «Готово» означає не «код виглядає правильно в diff», а «гейти запущено, результати побачено й явно зафіксовано».

Така ж форма підходить для будь-якої процедури, яку команда повторює: release checklist, рецепт міграції, перевірка перед PR. Емпіричне правило: якщо ви двічі набрали ту саму багатокрокову інструкцію, це кандидат на skill.

Папка skill може містити більше, ніж інструкції

• Skill — це не лише SKILL.md, а вся папка навколо нього.
• Поруч можна покласти reference.md з детальним матеріалом і послатися на нього з SKILL.md; Claude читає його лише тоді, коли потрібна така глибина.
• Можна класти й скрипти: Claude їх виконує, а не завантажує вміст у контекст. Отже skill може мати власний інструментарій, наприклад check.sh, що запускає всі гейти.
• Висновок: SKILL.md тримайте стислим (що робити), а важкий матеріал — довгі пояснення та виконувані скрипти — виносьте в супутні файли.

Яка поверхня інструкцій відповідає за яке правило

• CLAUDE.md — конвенції, що діють завжди: правила іменування, де лежать файли.
• Skill — процедури й довідковий матеріал для певного типу задач.
• Hook — правило, яке Claude не може пропустити. CLAUDE.md і skills — інструкції, яких Claude дотримується; hook — код, який реально виконується. Якщо пропуск неприйнятний, не покладайтеся на виконання інструкцій.

Підсумок уроку

• Skill — це папка з SKILL.md: назва, description (тригер) і сама процедура.
• Доки skill не потрібен, у контекст завантажуються лише descriptions, тож пакувати кожну повторювану процедуру майже нічого не коштує.
• Почніть із verification: створіть skill, закомітьте його в .claude/skills проєкту — і вся команда автоматично перевіряє роботу однаково, без нагадувань.

Головне: перший skill, який варто зробити, — автоматична перевірка (тести, diff, контроль послаблених тестів, звіт із доказами), закомічена в .claude/skills для всієї команди.

Урок 4. Режими дозволів (Permission modes)

Permission modes дозволяють один раз вирішити, що Claude може виконувати без запиту, замість підтверджувати кожну дію окремо. Shift+Tab перемикає режими для щоденної роботи (manual, accept edits, plan); для роботи без нагляду основний режим — auto.

Шість режимів

• Manual — без запиту лише читання; усе інше питає.
• Accept edits — без запиту читання, редагування файлів і поширені bash-команди файлової системи. Для ітерацій над кодом, який ви переглядаєте постфактум.
• Plan — досліджує й пропонує зміни, нічого не редагуючи. Читання вільне; якщо auto mode доступний, classifier auto переглядає команди, які Claude запускає для дослідження, і схвалені виконуються без запиту.
• Auto — приймає все, але окрема classifier-модель переглядає більшість дій перед виконанням.
• Don't ask — дозволяє читання файлів у робочих каталогах і заздалегідь схвалені інструменти; усе, що мало б викликати запит, автоматично відхиляється.
• Bypass permissions — пропускає всі перевірки; еквівалент прапорця --dangerously-skip-permissions. Лише в ізольованому контейнері або VM.

Перемикання через Shift+Tab

Shift+Tab циклічно перемикає manual, accept edits, plan і auto. Поточний режим завжди видно в status bar унизу.

Як працює auto mode

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

• production-деплої та міграції;
• force push, а також передавання завантаженого коду прямо в shell;
• надсилання чутливих даних на зовнішні endpoints;
• незворотне знищення файлів, що існували до початку сесії.

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

Чого classifier не робить

• Він перевіряє намір, а не коректність. Якщо Claude напише зламану автентифікацію під час рефакторингу, classifier її пропустить: зламане не означає небезпечне.
• Тому auto mode поєднують зі Stop hook, що запускає тести: auto стежить за діями під час роботи, Stop hook підтверджує, що код працює після завершення.
• Guardrails auto mode ще розвиваються; актуальні списки блокувань і дозволів дивіться в документації.

Don't ask для запусків без нагляду

Підходить, коли поруч немає людини для підтверджень: CI-пайплайни, заплановані задачі, нічні batch-запуски. Виконується те, що й у Manual не потребує підтвердження (читання файлів у робочих каталогах), плюс заздалегідь схвалені інструменти; решта автоматично відхиляється. Пайплайн не зависає в очікуванні підтвердження, яке нікому дати.

Підбирайте режим під задачу

• Auto — режим без нагляду: classifier перевіряє намір перед більшістю дій, Stop hook — коректність після.
• Don't ask — для пайплайнів без людини.
• Bypass permissions — лише в ізольованих контейнерах і VM.

Головне: для роботи без нагляду беріть auto (з тестами у Stop hook), для CI — don't ask, а bypass permissions — тільки в ізоляції.

Урок 5. Hooks (Hooks)

Інструкція в CLAUDE.md («завжди форматуй після редагування») — прохання, а не гарантія; на довгому запуску без нагляду «зазвичай» недостатньо. Hook — детермінований код, що виконується у фіксованій точці агентного циклу, тож поведінка гарантується: правило переходить зі стану «Claude зазвичай слухається» у «Claude не може це пропустити».

Події hooks

За сесію Claude Code генерує близько 30 подій hooks, але регулярно потрібні кілька, прив'язані до точок циклу (старт сесії, надходження промпту, виклик інструментів, завершення ходу):

• PreToolUse — перед викликом інструмента; основний примітив примусу, може зупинити дію заздалегідь.
• PostToolUse — після успішного виклику; типове місце для автоформатування чи автолінту.
• Stop — коли Claude хоче завершити хід; можна відмовити («ти ще не закінчив»), якщо умова не виконана. Парний SubagentStop — для завершення subagent.
• PreCompact і PostCompact — до й після compaction.
• InstructionsLoaded — коли завантажується CLAUDE.md або файл правил; корисно для аудиту того, що реально потрапило в контекст.
• SessionStart — на старті, готує середовище. Source startup — якщо потрібно лише на свіжих стартах.

Часта помилка: щоб повторно вставити контекст після compaction, використовуйте не PostCompact, а SessionStart з matcher compact — саме його вивід повертається в розмову.

PreToolUse: рішення у форматі JSON

Hook відповідає Claude, друкуючи JSON і завершуючись з кодом 0. Ключове поле — permissionDecision:

• allow — пропустити виклик;
• deny — зупинити;
• ask — передати рішення користувачу.
• Є ще defer, але лише для неінтерактивних запусків -p, де зовнішній процес призупиняє інструмент і пізніше відновлює; потрібен рідко.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "...",
    "updatedInput": { "command": "..." }
  }
}

updatedInput дозволяє не блокувати, а переписати виклик (наприклад, вирізати секрет із bash-команди й виконати її). Застереження: updatedInput замінює весь об'єкт input, тож поля, які ви не змінюєте, треба повернути як є, інакше вони зникнуть.

Exit codes для hooks без JSON

• 0 — успіх. Якщо stdout містить JSON, Claude його розбирає. Звичайний текст на більшості подій ігнорується, але на SessionStart, UserPromptSubmit і UserPromptExpansion додається в контекст — на цьому й тримається hook збереження стану.
• 2 — блокувальна помилка; stderr передається Claude як контекст. Майже всюди це і є код блокування.
• Будь-який інший — неблокувальний: stderr логується, Claude продовжує.

Пастка: exit code 1 виглядає як помилка, але нічого не блокує — команда все одно виконується. Щоб зупинити дію, повертайте 2, а не 1.

• Exit 2 може блокувати навіть Stop — так Claude отримує сигнал, що робота не завершена.
• PostToolUse спрацьовує після виконання інструмента, тож блокувати вже пізно, але текст назад Claude передати можна.
• Деякі події блокування ігнорують, наприклад Notification і SessionStart: SessionStart показує stderr лише вам, Notification його ігнорує, і обидві продовжують роботу.

Реальний guardrail: редагувати замість блокувати

• PreToolUse на інструменті Bash: matcher обирає інструмент, необов'язкова умова if звужує до конкретної команди.
• Очевидний крок — повернути deny для небезпечного виклику. Менш відомий і цікавіший — повернути updatedInput і переписати виклик.
• Приклад: команда містить секрет, схожий на бойовий; hook помічає шаблон sk_live_ і замінює його на placeholder ще до виконання. Команда виконалась, робота зроблена, а секрет нікуди не потрапив — і так щоразу.

Збереження стану через compact

Compaction відкидає багато деталей. SessionStart hook з matcher compact запускається одразу після compaction; нехай він друкує короткий перелік файлів, з якими ви працювали. Цей вивід повертається в контекст, і Claude продовжує з того ж місця, а не починає з нуля.

Підсумок уроку

Hooks роблять правило, яке Claude виконує зазвичай, правилом, яке він виконує завжди. Не обмежуйтеся автоформатуванням: захищайте інструменти через PreToolUse, контролюйте завершення ходу через Stop, зберігайте стан через compact. Налаштування потребує трохи зусиль, але окупається першого ж разу, коли hook ловить проблему на запуску, за яким ви не стежили.

Головне: hook — єдиний спосіб гарантувати поведінку; блокуйте через exit 2 або permissionDecision (не exit 1), а updatedInput дає змогу виправити виклик замість заборони.

Урок 6. Routines і headless (Routines and headless)

Коли задачі вже довіряєте, наступний крок — перестати запускати її вручну. Варіанти утворюють спектр: на одному кінці routines на керованій інфраструктурі Anthropic (нічого не будуєте), на іншому — headless mode та Agent SDK, що запускають Claude Code з вашого коду (повний контроль).

Routines: збережений промпт, що виконується в хмарі

• Routine поєднує промпт, репозиторій, з яким він працює, і потрібні connectors, та запускає цей набір у хмарі за тригером. Без скриптів і серверів.
• Інфраструктура — Anthropic: ваша машина не мусить працювати вночі, workflow-файл підтримувати не треба.
• Тригери: cron-розклад (наприклад, щоранку о 9:00); HTTP POST на API endpoint routine (запуск із вашого коду); подія GitHub (наприклад, новий pull request).
• Підходить усе, що є тим самим промптом на повторюваному тригері: ранковий аудит залежностей, тріаж нових PR, щоденний розбір тікетів Sentry для визначення найтерміновіших.

Два способи створити routine

• У вебі: claude.ai/code/routines — назва, інструкції для кожної сесії, репозиторій, тригер.
• З терміналу: команда /schedule з описом звичайною мовою, наприклад /schedule daily dependency audit at 9am.

Три обмеження routines

• Це research preview: поведінка й ліміти змінюватимуться.
• Повторюваний розклад — не частіше ніж раз на годину. Потрібно частіше — routines не підходять.
• Запуск починається зі свіжого клону default branch і пушить у гілку claude/, якщо промпт не називає іншу. Якщо запуск ініційований подією GitHub pull request, репозиторій PR стартує з head-коміту PR — за умови, що це перший репозиторій у routine. Щоб обмежити гілки для push, використовуйте branch protection rules або rulesets на GitHub; вони застосовуються до підключеного вами доступу GitHub, тож правило, яке ваш доступ може обійти, push не зупинить.

Headless mode: коли потрібне ваше середовище

Якщо задача потребує вашого середовища або логіки навколо запуску, використовуйте headless mode (у документації тепер — non-interactive mode). Основа — прапорець -p (--print): одноразовий запуск без інтерактивного UI, читає stdin, пише stdout і вбудовується в pipe, як будь-яка shell-утиліта.

claude -p "summarize the changes in this diff"

Сам по собі -p завантажує той самий контекст, що й інтерактивна сесія: hooks, skills, plugins, MCP servers, CLAUDE.md. Щоб усе це пропустити, додайте --bare.

Структурований вивід

Поєднайте JSON schema з форматом виводу JSON — Claude обмежить відповідь схемою. Об'єкт, що відповідає схемі, лежить у полі structured_output; його можна витягти через jq і передати в базу даних чи інший скрипт:

claude -p "Extract the exported function names from src/core/style.js" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output.functions'

Багатокрокова автоматизація через сесії

Не обов'язково вміщати все в одну команду: збережіть session ID з JSON-виводу й відновіть сесію пізніше з повним контекстом. Зручно, коли перший прохід складає план, а другий його виконує.

claude --resume "$(jq -r .session_id /tmp/plan.json)"

Однакові запуски в CI

• --bare пропускає автовиявлення hooks, skills, plugins, MCP servers і CLAUDE.md.
• Лишаються інструменти Bash, читання й редагування файлів плюс те, що передано прапорцями на кшталт --settings або --mcp-config.
• Кожна машина стартує з однакового налаштування, запуск швидший.
• Bare mode не використовує логін підписки — спершу задайте ANTHROPIC_API_KEY.

Agent SDK: Claude Code у вашому застосунку

• Бібліотека для вбудовування Claude Code у застосунки на TypeScript або Python.
• Обидві мови надають функцію query і ті самі примітиви, що й CLI: передаєте промпт та опції — allowedTools (що Claude може робити), system prompt, permission mode.
• Далі ітеруєте по повідомленнях, які Claude стрімить, і обробляєте їх як потрібно. Той самий рушій, що й у CLI.

Що обрати

• Routines — варіант за замовчуванням для повторюваної роботи; нічого не треба хостити.
• Headless -p — коли задача потребує вашого пайплайну і даних через скрипт.
• --bare — коли CI потребує однакового налаштування на кожній машині.
• Agent SDK — коли робота має жити всередині вашого продукту.

Головне: починайте з routines і спускайтеся спектром (-p → --bare → Agent SDK) лише тоді, коли задача справді потребує більшого контролю.

Урок 7. GitHub Actions і Code Review (GitHub Actions and Code Review)

Найкраще місце для передачі рутини — pull request: там відбувається рев'ю і потрапляють зміни. Є два шляхи з різними задачами: керований сервіс, який просто вмикаєте, і GitHub Action, який налаштовуєте самі.

Керований шлях: Code Review

• Сервіс на інфраструктурі Anthropic, що рев'юїть PR через Claude GitHub app і публікує знахідки inline-коментарями на відповідних рядках. Нічого будувати чи хостити не треба.
• Вмикає Owner організації Claude в адмін-налаштуваннях Claude Code: розділ Code review, перемикач Allow code review.
• Далі Owner встановлює Claude GitHub app, обирає репозиторії й час запуску. Якщо Owner не є власником організації GitHub, спочатку застосунок має встановити й прив'язати власник GitHub-організації.
• Варіанти запуску: один раз при відкритті PR; на кожен push у PR; лише за коментарем @claude review.
• Набір review-агентів аналізує diff на тлі всієї кодової бази, а не лише змінені рядки ізольовано. Знахідки — inline-коментарі з позначкою severity, плюс зведена таблиця в check run. Кожен коментар містить пояснення і запропоноване виправлення.
• Знахідки дедуплікуються й ранжуються: замість стіни дрібниць — кілька справжніх проблем.

Що Code Review робить і чого ні

• Ніколи не схвалює й не блокує PR — рішення лишається за людиною.
• Не пушить виправлення, лише публікує знахідки.
• Доступний на планах Team та Enterprise.
• Реагувати на знахідку — ваша справа: виправити код і запушити. Перевірити виправлення до push можна командою /code-review у своєму терміналі: вона робить власне рев'ю вашого diff, а прапорець --fix застосовує його знахідки до робочого дерева.

Шлях «зроби сам»: GitHub Action

Коли задача виходить за межі рев'ю — кастомний CI: реалізація змін за коментарем, звіти за розкладом, усе, для чого зазвичай пишуть workflow. Action запускає агента на коментарях у PR, за розкладом і на будь-якій події GitHub.

• Налаштування: команда /install-github-app у Claude Code (потрібні права repo admin). Вона проводить через встановлення GitHub app і додавання секрету з Anthropic API key у репозиторій.
• Сам action: anthropics/claude-code-action@v1.

Основні inputs:

• anthropic_api_key — потрібен, коли запуск викликає Claude API, якщо не використовується claude_code_oauth_token (з підписки Claude) або workload identity federation (через service account у Claude Console, без збереженого секрету). З хмарними провайдерами нижче не використовується.
• github_token — необов'язковий; без нього action автентифікується як встановлений Claude GitHub app. Передавайте лише для перевизначення.
• trigger_phrase — що action слухає в коментарях; за замовчуванням @claude.
• use_bedrock / use_vertex / use_foundry — маршрутизація через Amazon Bedrock, Google Cloud Agent Platform або Microsoft Foundry замість Claude API, з входом через ваш хмарний акаунт замість API key.
• prompt — інструкція для автоматичного запуску: якщо задано, Claude працює на подію без згадки; якщо ні — чекає trigger phrase.
• claude_args — рядок CLI-аргументів, що передаються напряму в Claude Code.

Workflow, що реагує на @claude

Файл .github/workflows/claude.yaml слухає @claude у коментарях до PR та issues. У permissions job треба надати id-token: write, щоб action міг увійти як Claude GitHub app. Основний крок:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    trigger_phrase: "@claude"
    claude_args: "--max-turns 5 --model claude-sonnet-5"

Коли хтось пише в PR, наприклад, @claude implement the spec in the linked Linear issue, action підхоплює задачу: Claude пушить коміти й коментує, що зробив.

Workflow за розкладом

• Той самий action для щоденного зведення: cron-тригер, скажімо, о 9:00 UTC, action виконує ваш промпт, зведення читаєте в лозі цього запуску. Запуск за розкладом сам коментар не публікує.
• Можна додати тригер workflow_dispatch, щоб запускати вручну з вкладки Actions.
• Хід виконання видно у вкладці Actions, як для будь-якого workflow.

Тонке налаштування через claude_args

• --max-turns 5 — жорстка межа агентного циклу, щоб він не працював нескінченно.
• Permission mode — для запуску без нагляду такий, що не зупиняється з питаннями: відповідати нікому.
• Allowed tools — рівно те, що потрібно задачі; для звіту — лише читання.

Що обрати

• Для рев'ю PR — керований Code Review: GitHub app публікує inline-знахідки, ви виправляєте й пушите.
• Action — коли потрібно більше, ніж рев'ю: /install-github-app для налаштування, один workflow для згадок @claude, один для cron, усе тонке налаштування — в claude_args.

Головне: починайте з керованого Code Review, а на GitHub Action переходьте, щойно Claude має щось робити в CI, а не лише коментувати.

Урок 8. Довіряй, але перевіряй: запуски без нагляду (Trust it: Verifying unsupervised runs)

Claude працював без вашого нагляду й каже, що закінчив. Перед відвантаженням треба перевірити те, чого ви не бачили. Принцип: перевіряйте пропорційно до свободи, яку дали запуску. Короткій сесії, яку ви читали в процесі, вистачить погляду; запуск без нагляду чи job у CI потребує справжньої перевірки з відновленням подій постфактум. Що менше ви бачили, то більше перевіряєте.

Запуски без нагляду — в auto mode

• На роботі тримайте такі запуски в auto mode, а не в bypass permissions: classifier усе ще перевіряє більшість дій на небезпечність.
• Але classifier не оцінює коректність коду, лише позначає небезпечні дії. Планка перевірки не знижується і визначається тим, наскільки запуск був без нагляду.

Починайте з diff, а не з підсумку

• Запустіть /code-review, щоб пройтися змінами й позначити проблеми.
• Потім самі перегляньте git diff.
• Пастка: охайний підсумок, тоді як diff зачепив файл, якого ви не очікували. Підсумок цього не скаже, diff — скаже.
• Спершу читайте файли з плану, потім шукайте все поза ним. Чистий опис не доводить чистоти коду.

Тести — це гейт, а не обіцянка

Головне питання: чи пройшли тести і чи Claude справді їх запускав, а не лише стверджує. Не покладайтеся на довіру — зробіть hook, який неможливо пропустити:

• Stop hook, що запускає тести й не дає завершити хід при падінні.
• PostToolUse hook, що робить lint і type check після кожного редагування.

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

Холодна друга думка

Рев'ю силами subagent, яке ви робили б перед PR, застосовне й тут. Відкрийте нову сесію або subagent і попросіть переглянути змінений код без пам'яті про те, як його створювали. Не маючи прив'язаності до підходу, такий рецензент помічає те, що автор собі «пояснив» і пропустив.

Підсумок уроку

• Самі читайте diff.
• Тести — у hook, що контролює завершення ходу.
• Headless-запуски перевіряйте за їхнім JSON-результатом і exit code.
• Для всього важливого — холодна друга думка.

Головне: серйозність перевірки має відповідати мірі відсутності нагляду: diff замість підсумку, тести як hook-гейт, незалежне рев'ю свіжою сесією.

Урок 9. Plugins (Plugins)

Налаштування, якому ви довіряєте, цінніше, коли ним користується вся команда. Проблема — перенесення: копіювати .claude зі skills, subagents і hooks між машинами й сподіватися на синхронність ненадійно. Plugin — спосіб, яким Claude Code пакує налаштування й передає його іншим. Дві сторони: використання чужих plugins і пакування власних.

Що таке plugin

• Одна встановлювана одиниця: skills, subagents, hooks, конфіги MCP servers, а також LSP-сервери, фонові монітори, теми й частина settings.json. Одна версія — одне встановлення.
• Спосіб встановлення залежить від того, де plugin розміщено. У сесії можна встановити за назвою:

/plugin install github@claude-plugins-official

• Команда спершу показує деталі plugin, щоб ви переглянули їх і обрали scope; потім встановлює й друкує короткий підсумок: або plugin вже активний у сесії, або згадує /reload-plugins і Claude Code сам виконує reload.
• Втручатися треба лише тоді, коли reload попереджає, що наступне повідомлення перечитає всю розмову: тоді виконайте /reload-plugins --force, щоб усе одно активувати plugin.

Marketplace для команди

• Для команди краще один раз додати приватний marketplace — спільне джерело, через яке резолвляться plugins:

/plugin marketplace add your-org/claude-plugins

• Після цього всі встановлення йдуть через нього: централізований пошук, відстеження версій та оновлення в одному місці, а не на ноутбуках кожного.
• Вкладка Discover показує plugins з ваших marketplaces для пошуку й вибору.

Читайте перед встановленням

• Plugin виконує код на вашій машині з вашими привілеями. Його hooks спрацьовують на кожному відповідному виклику інструмента: встановивши plugin заради skills, ви отримуєте і його PreToolUse та Stop hooks, навіть якщо їх не читали.
• Приклад ризику: community plugin може мати Stop hook, що щоразу звертається до мережевого endpoint, і ніщо у вашій конфігурації про це не попередить. Це привід не уникати plugins, а дивитися заздалегідь.
• Перед встановленням Claude Code показує, що буде встановлено, оцінку вартості в контексті та попередження, що Anthropic не контролює вміст сторонніх plugins.
• Походження: у community marketplace plugin потрапляє, бо автор надіслав його в Anthropic; офіційний marketplace курується окремо.
• Наявність у списку не означає довіри. Встановлюйте plugins і додавайте marketplaces лише з джерел, яким справді довіряєте, і перевіряйте, що plugin робить, перш ніж вмикати.

Компоненти працюють поруч із вашими

• Plugin не перезаписує вашу конфігурацію, його компоненти діють паралельно.
• Hooks складаються: PreToolUse hook plugin і ваш власний PreToolUse обидва спрацьовують на кожному виклику, жоден не замінює інший.
• Skills, agents і commands мають namespace за назвою plugin, тож із вашими не конфліктують.
• Plugin може містити settings.json, але Claude Code враховує з нього лише два ключі: agent і ключ status line для subagents.
• Ключ agent підвищує один із subagents plugin до головного потоку разом з його system prompt, обмеженнями інструментів і моделлю. Тобто ввімкнення plugin може змінити поведінку Claude Code за замовчуванням — ще одна причина дивитися до ввімкнення.
• Після встановлення в панелі plugins видно все, що він додав; там же керування й видалення.

Пакування власного plugin

Коли .claude працює, пакуйте його замість копіювання. Перебудовувати нічого не треба — plugin має ту саму структуру:

• по одній папці на skill;
• по одному markdown-файлу на subagent у agents;
• hooks/hooks.json і .mcp.json у корені plugin.

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

Маніфест

Необов'язковий маніфест .claude-plugin/plugin.json містить name, version, description, author:

{
  "name": "svg-splitter-review",
  "version": "0.1.0",
  "description": "Reviews the SVG Splitter repo",
  "author": { "name": "Lewis Menelaws" }
}

• Без маніфесту компоненти все одно знаходяться за конвенцією каталогів.
• Єдине обов'язкове поле — name. Воно задає namespace: skill викликається як /plugin-name:skill-name, тобто тут /svg-splitter-review:<skill-name>, що запобігає колізіям з чужими skills.
• Версіонуйте plugin як будь-яку залежність — на цьому тримаються оновлення й відстеження версій у команді.

Підсумок уроку

• Використовуючи plugins, читайте перед встановленням: hooks, agents і MCP servers працюють з вашими привілеями.
• Створюючи — пакуйте .claude, щойно він запрацював: один маніфест, одне встановлення.

Головне: plugin перетворює перевірене налаштування на одну версіоновану одиницю для всієї команди (краще через приватний marketplace), але чужі plugins треба переглядати до встановлення, бо їхні hooks і ключ agent змінюють поведінку Claude Code.

Як вибрати рівень effort у Claude Code (Choosing the right effort level in Claude Code)

Окрім вибору моделі, другий важіль вартості й витрати токенів — рівень effort. Його треба підбирати під складність задачі: невідповідність у будь-який бік коштує грошей. Стартова точка — значення за замовчуванням.

Effort не змінює знань моделі (Effort does not change what the model knows)

• Effort каже моделі, скільки ресурсів витратити на задачу з промпту. На найнижчому рівні вона намагається досягти мети мінімальними засобами: менше tool calls, менше токенів, менше роботи загалом. На максимумі — отримує сигнал, що може й повинна витратити стільки, скільки потрібно.
• Модель визначає рівень можливостей і знань; effort визначає лише, наскільки старанно ця модель працює.

Коли змінювати effort (When to change the effort)

• Занизький effort: модель зупиняється зарано й повертає недороблену роботу. Це ознака, що задача складніша за дозволений рівень. Доводиться з'ясовувати, де вона зупинилася, і промптити знову — у підсумку це може коштувати більше, ніж одразу правильний рівень.
• Зависокий effort: помітно не на кожній задачі, але модель витрачає зайві токени, відповідає довше, з'являється «overthinking» і вигадування задач, яких ви не ставили. Високий рівень — це сигнал «задача дуже складна», і модель поводиться відповідно.
• Default стоїть посередині й не випадковий: для кожної моделі він налаштований так, щоб більшість задач завершувалися без перевитрат. Тому починати слід із нього.
• Знижувати — для задач, які завідомо прості й не мають потребувати багато часу, ходів, tool calls чи читання документів. Якщо такий тип задач уже виконувався на default, спробуйте на рівень нижче; якщо якість не впала — опускайтеся ще на рівень, доки не побачите різницю.
• Підвищувати — коли задача свідомо довга, потребує багатьох ходів і перепровірок, або коли ви не можете швидко перевірити результат самі й хочете більше самоперевірки від моделі. Правило те саме: +1 рівень, повторний запуск, зупинитися, щойно модель доводить до кінця те, що ви очікуєте.

Що крутити: effort чи модель? (Which dial to turn: effort or model?)

• Модель міняють лише тоді, коли підвищення effort не допомогло. Діагностичне питання: модель не знала чи не старалася? Знала, але не старалася — це питання effort. Знала, але перестаралася — теж effort. Якщо зміна effort не рятує, а ви не на найпотужнішій моделі, — вибраній моделі бракує знань або можливостей.
• Після зміни моделі — знову з default. Назви рівнів однакові для всіх моделей, але той самий рівень на різних моделях означає різний обсяг роботи. Приклад: складну задачу пробують на найслабшій моделі, піднімають effort до максимуму, якості все одно бракує — переходять на сильнішу модель. Залишати max не треба: почніть із default, сильніша модель може впоратися з меншим effort.
• З виходом нової моделі (зокрема новішої версії поточної) перегляньте звичні задачі: можливо, той самий результат вийде на нижчому effort, тобто дешевше.

Як задати рівень (Setting the effort level)

• Рівень, заданий через /effort, переходить у наступну сесію; для одноразового запуску використовуйте --effort.
• max настільки ресурсоємний, що Claude Code робить його лише сесійним (виняток — якщо задати через змінну оточення), щоб його не можна було забути ввімкненим.
• Ultracode — не рівень effort, а сесійне налаштування Claude Code: модель працює на xhigh, а для суттєвих задач Claude ще й оркеструє dynamic workflows, розподіляючи роботу між кількома агентами.
• Якщо effort задано кількома способами, перемагає той, що стоїть вище в порядку пріоритету (сама схема пріоритетів у матеріалі подана інтерактивно й у тексті відсутня).
• Організація може обмежити результат: на Enterprise-планах адмін задає максимальний effort для кожної моделі. Рівні понад ліміт не показуються в пікері /effort; якщо запросити такий через /effort чи --effort, Claude Code працює на рівні ліміту й повідомляє про це.

Робочий приклад (Worked example)

Один і той самий промпт тричі на одній моделі — на low, default і max — із порівнянням, скільки роботи йде на однаковий результат. Задача навмисно нудна (невеликий скрипт CSV→JSON із тестом на прикладі), щоб різниці між рівнями було де проявитися. Сам програвач інтерактивний.

Спробуйте у своєму середовищі (Try it in your own environment)

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

1. Запустити нову сесію в окремій порожній папці (поза будь-яким репозиторієм) на потрібному рівні:

   # прогін 1 · low
   mkdir effort-low && cd effort-low && claude --effort low
   
   # прогін 2 · default
   cd .. && mkdir effort-default && cd effort-default && claude
   # потім виконати /effort auto
   
   # прогін 3 · max
   cd .. && mkdir effort-max && cd effort-max && claude --effort max

   Прапорець або /effort auto потрібні, бо рівні від low до xhigh, задані через /effort, зберігаються між сесіями.
2. Вставити однаковий промпт: написати csv_to_json.py, що конвертує CSV у JSON, і протестувати його на sample.csv із трьома рядками (колонки name,team,start_date).
3. Коли Claude поверне роботу, виконати /usage і знайти загальну кількість токенів сесії (решта екрана залежить від плану).
4. /exit і повернутися до кроку 1 для наступного рівня.

Очікуваний результат: кількість токенів зростає від low до max, а в усіх трьох папках лежить робочий конвертер. Порівняйте три скрипти поруч — різниця в обсязі збудованого і є тим, за що ви заплатили.

Звичка, яку варто закріпити (The habit to keep)

Уся робота з effort зводиться до циклу: почати з default, подивитися на результат, коригувати на один рівень за раз. Так ви знатимете, який рівень потрібен кожній задачі, і зможете пояснити це колезі чи адміну.

Додаткові матеріали (Learn more)

• «Choosing a Claude model and effort level in Claude Code» — концепції вибору моделі й effort від команди Claude Code.
• «Model configuration» — повний довідник щодо /effort, settings, пріоритетів і організаційних лімітів.
• «Maximizing value from Claude Code» — вебінар про те, куди йдуть токени сесії, вибір моделі й effort, і що CLAUDE.md та MCP-сервери додають до кожного ходу.
• «Optimizing for cost and intelligence» — виміряні результати effort, prompt caching і вибору моделі за вартістю задачі (документація Claude Platform).
• «Cost Optimization on the Claude API» — важелі вартості, застосовані по черзі до робочого агента (Claude Cookbook).

Головне: effort регулює старанність, а не знання моделі; починайте з default, рухайтеся на один рівень за раз і міняйте модель лише тоді, коли effort не допомагає, — після зміни моделі знову з default.

Найкращі практики роботи з Claude Code (Best practices for Claude Code)

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

Головне обмеження, з якого випливає більшість порад: контекстне вікно швидко заповнюється, а продуктивність моделі падає в міру заповнення. У вікні — уся розмова: кожне повідомлення, кожен прочитаний файл, кожен вивід команди. Одна сесія налагодження чи дослідження коду може з'їсти десятки тисяч токенів. Коли вікно майже повне, Claude починає «забувати» ранні інструкції й частіше помиляється. Тому контекст — найважливіший ресурс. Стежити за ним можна через кастомний status line; є також інтерактивна демонстрація заповнення контексту (див. третій блок) і поради зі зменшення витрати токенів.

Дайте Claude спосіб перевіряти власну роботу (Give Claude a way to verify its work)

Claude зупиняється, коли робота виглядає готовою. Без перевірки, яку він може запустити, інших сигналів немає, і цикл верифікації — це ви: кожна помилка чекає, доки ви її помітите. Дайте Claude щось із результатом pass/fail — і цикл замкнеться сам: зробив, запустив перевірку, прочитав результат, ітерує до проходження. Це різниця між сесією, яку треба пильнувати, і сесією, від якої можна відійти.

Перевірка — будь-що, що повертає читабельний сигнал у розмову: набір тестів, exit code збірки, лінтер, скрипт, що порівнює вивід із фікстурою, скриншот браузера проти дизайну. Після того як перевірка Claude пройшла, запустіть /verify самі, щоб підтвердити зміну на запущеному застосунку.

Коли перевірка є, вирішіть, наскільки жорстко вона блокує зупинку:

• В одному промпті: попросити запустити перевірку й ітерувати в тому самому повідомленні (як у таблиці).
• На всю сесію: зробити перевірку умовою /goal. Окремий evaluator перевіряє її після кожного ходу, і Claude працює, доки ціль не досягнута. Якщо Claude застрягне, Claude Code зрештою зупинить прогін, залишивши ціль встановленою.
• Детермінований бар'єр: Stop hook запускає перевірку як скрипт і не дає ходу завершитися, доки вона не пройде (кількість послідовних блокувань обмежена — деталі в описі Stop input).
• Друга думка: verification subagent або dynamic workflow, що перевіряє власні висновки, — свіжа модель намагається спростувати результат, тож той, хто робить, не оцінює сам себе.

Кожен наступний варіант вимагає більше налаштування, але менше вашої уваги. Промпт-варіант працює на будь-якій задачі вже сьогодні; /goal і Stop hook дозволяють коректно завершити прогін без вашої участі.

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

Спершу дослідити, потім спланувати, потім кодити (Explore first, then plan, then code)

Якщо дозволити Claude одразу писати код, він може розв'язати не ту задачу. Plan mode відділяє дослідження від виконання. Рекомендований процес із чотирьох фаз:

1. Explore. Увійти в plan mode: натискати Shift+Tab, доки в статус-барі не з'явиться ⏸ plan mode on, або запустити claude --permission-mode plan. Claude читає файли й відповідає, нічого не змінюючи. Приклад: «прочитай /src/auth, розберися, як працюють сесії й логін, і як ми зберігаємо секрети в env-змінних».
2. Plan. Попросити детальний план: «хочу додати Google OAuth — які файли зміняться, який буде session flow? Склади план». Ctrl+G відкриває план у текстовому редакторі для правок до того, як Claude продовжить.
3. Implement. Вийти з plan mode (схваливши план або через Shift+Tab) і дати Claude кодити, звіряючись із планом: «реалізуй OAuth flow за планом, напиши тести на callback handler, запусти тести й виправ падіння».
4. Commit. «Закоміть з описовим повідомленням і відкрий PR».

Plan mode має накладні витрати. Для дрібних задач із ясним обсягом (виправити одруківку, додати рядок логування, перейменувати змінну) просіть зробити напряму. Планування корисне, коли підхід неочевидний, зміна зачіпає кілька файлів або код вам незнайомий. Якщо diff можна описати одним реченням — план не потрібен.

Давайте конкретний контекст у промптах (Provide specific context in your prompts)

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

Розмиті промпти доречні, коли ви досліджуєте й можете дозволити собі коригувати курс: запит на кшталт «що б ти покращив у цьому файлі?» може підсвітити те, про що ви б і не спитали.

Багатий вміст (Provide rich content):

• Посилайтеся на файли через @ замість опису, де лежить код, — Claude прочитає файл перед відповіддю.
• Вставляйте зображення напряму (copy/paste або drag and drop).
• Давайте URL документації й API; часто вживані домени додайте в allowlist через /permissions.
• Передавайте дані через pipe: cat error.log | claude -p "explain this error".
• Дозвольте Claude самому діставати контекст — через Bash, MCP tools або читання файлів.

Середовище: ефективний CLAUDE.md (Configure your environment → Write an effective CLAUDE.md)

Кілька кроків налаштування суттєво підвищують ефективність у всіх сесіях (огляд розширень — на сторінці Extend Claude Code).

• /init генерує стартовий CLAUDE.md за структурою проєкту; далі його доопрацьовують.
• CLAUDE.md читається на початку кожної розмови. Туди кладуть Bash-команди, стиль коду, правила workflow — постійний контекст, який не виводиться з коду. Формат довільний, але коротко й читабельно, наприклад:

  # Code style
  - Use ES modules (import/export), not CommonJS (require)
  
  # Workflow
  - Typecheck after a series of code changes
  - Prefer running single tests, not the whole suite

• /context показує, чи файл завантажено. Оскільки він вантажиться щоразу, туди йде лише загальнозастосовне; знання чи процеси, потрібні зрідка, оформлюють як skills — вони підвантажуються на вимогу.
• Тест для кожного рядка: «Чи почне Claude помилятися, якщо це прибрати?» Якщо ні — видаляйте. Роздутий CLAUDE.md призводить до ігнорування справжніх інструкцій.

• Якщо Claude порушує правило, яке є у файлі, — файл, найімовірніше, задовгий і правило губиться. Якщо Claude питає те, що вже є в CLAUDE.md, — формулювання двозначне.
• Ставтеся до CLAUDE.md як до коду: переглядайте, коли щось іде не так, регулярно чистьте, перевіряйте зміни за реальною зміною поведінки. Для закоміченого CLAUDE.md /doctor пропонує вирізати те, що виводиться з коду.
• Якщо Claude постійно пропускає одну інструкцію — додайте акцент («IMPORTANT») лише до неї; якщо підкреслити багато рядків, не виділятиметься жоден.
• Комітьте CLAUDE.md у git, щоб команда могла доповнювати — його цінність з часом накопичується. Інші файли імпортуються синтаксисом @path/to/import.

Середовище: дозволи (Configure permissions)

• Щоб менше підтверджень без втрати контролю: довірені інструменти схвалюються наперед через /permissions, а команди в пісочниці виконуються без питань через /sandbox. Manual mode — коли хочете самі схвалювати правки й команди.
• З Claude Code v2.1.283 auto mode — стартовий режим дозволів для інтерактивного терміналу й VS Code: окрема модель-класифікатор переглядає більшість дій замість вас і блокує лише ризиковані (scope escalation, невідома інфраструктура, дії під впливом ворожого контенту). На старіших версіях auto mode стартовий лише на планах Pro, Max і Team.
• У Manual mode Claude питає перед записом файлів, Bash-командами, MCP tools. Це безпечно, але виснажує: після десятого підтвердження ви вже клацаєте, а не перевіряєте. Два інструменти зменшують переривання (працюють і в auto mode):
  • Allowlists — дозвіл конкретних безпечних інструментів, наприклад npm run lint чи git commit;
  • Sandboxing — ізоляція на рівні ОС, що обмежує доступ до файлової системи й мережі, даючи Claude більше свободи в заданих межах.

Середовище: CLI-інструменти (Use CLI tools)

• Кажіть Claude використовувати CLI на кшталт gh, aws, gcloud, sentry-cli — це найекономніший щодо контексту спосіб працювати із зовнішніми сервісами.
• Для GitHub встановіть gh: Claude вміє створювати issues, відкривати PR, читати коментарі. Без нього лишається GitHub API, але неавтентифіковані запити часто впираються в rate limits.
• Незнайомі CLI Claude добре освоює сам: «вивчи foo-cli-tool через --help, потім використай його для A, B, C».

Середовище: MCP-сервери (Connect MCP servers)

Підключення: claude mcp add з іменем і URL або командою, наприклад claude mcp add --transport http notion https://mcp.notion.com/mcp. Через MCP Claude може реалізовувати фічі з issue-трекерів, робити запити до баз даних, аналізувати моніторинг, інтегрувати дизайни з Figma, автоматизувати процеси.

Середовище: hooks (Set up hooks)

Hooks — для дій, що мають відбуватися щоразу без винятків. Це скрипти, які запускаються автоматично в певних точках роботи Claude. На відміну від порад у CLAUDE.md, hooks детерміновані й гарантують виконання. Claude може написати їх сам: «hook, що запускає eslint після кожної правки файлу», «hook, що забороняє запис у папку migrations». Вручну — редагування .claude/settings.json; переглянути налаштоване — /hooks.

Середовище: skills (Create skills)

Skills — файли SKILL.md у .claude/skills/<назва>/ зі специфічними знаннями проєкту, команди чи домену. Claude застосовує їх автоматично, коли доречно, або їх викликають напряму через /skill-name. Приклад знаннєвого skill:

---
name: api-conventions
description: REST API design conventions for our services
---
- kebab-case for URL paths, camelCase for JSON properties
- Always paginate list endpoints; version APIs in the path (/v1/)

Skill може описувати й повторюваний workflow. Приклад fix-issue із disable-model-invocation: true і підстановкою $ARGUMENTS: отримати деталі через gh issue view, зрозуміти проблему, знайти релевантні файли, внести зміни, написати й запустити тести, пройти лінтинг і type checking, скласти описовий commit message, запушити й створити PR. Виклик: /fix-issue 1234. disable-model-invocation: true ставлять для workflow з побічними ефектами, які мають запускатися лише вручну.

Середовище: власні subagents (Create custom subagents)

Спеціалізовані асистенти визначаються в .claude/agents/; кожен працює у власному контексті з власним набором дозволених інструментів. Корисні для задач, що читають багато файлів або потребують вузького фокуса, — без засмічення основної розмови. Приклад security-reviewer: frontmatter tools: Read, Grep, Glob, Bash, model: opus; інструкція — роль senior security engineer, перевірка ін'єкцій (SQL, XSS, command injection), вад автентифікації й авторизації, секретів у коді, небезпечної обробки даних, з посиланнями на рядки й пропозиціями виправлень. Викликати явно: «Use a subagent to review this code for security issues».

Середовище: plugins (Install plugins)

/plugin відкриває маркетплейс. Plugins пакують skills, hooks, subagents і MCP-сервери в одну встановлювану одиницю (від спільноти й Anthropic) без додаткового налаштування. Для типізованих мов варто поставити code intelligence plugin — точна навігація по символах і автоматичне виявлення помилок після правок. Як вибирати між skills, subagents, hooks і MCP — див. Extend Claude Code.

Ефективна комунікація: питання про кодову базу (Communicate effectively → Ask codebase questions)

Питайте Claude те саме, що спитали б досвідченого інженера: як влаштоване логування; як додати новий API endpoint; що робить async move { ... } у рядку 134 foo.rs; які граничні випадки обробляє CustomerOnboardingFlowImpl; чому в рядку 333 викликається foo(), а не bar(). Це ефективний онбординг: швидше входження й менше навантаження на колег. Спеціальний промптинг не потрібен.

Ефективна комунікація: нехай Claude проінтерв'ює вас (Let Claude interview you)

• Для великих фіч почніть із мінімального промпту й попросіть Claude проінтерв'ювати вас через інструмент AskUserQuestion: про технічну реалізацію, UI/UX, граничні випадки, ризики й компроміси — без очевидних питань, з фокусом на складних місцях, про які ви могли не подумати; продовжувати, доки все не покрито, потім записати повну специфікацію в SPEC.md.
• Після цього — нова сесія для виконання: чистий контекст, сфокусований на реалізації, плюс письмова специфікація.
• Найкорисніші специфікації самодостатні: називають задіяні файли й інтерфейси, явно кажуть, що поза обсягом, і закінчуються end-to-end кроком перевірки. Час на уточнення специфікації окупається краще, ніж час на спостереження за реалізацією.

Керування сесією: коригуйте рано й часто (Manage your session → Course-correct early and often)

Розмови зберігаються й оборотні. Найкращі результати дають короткі цикли зворотного зв'язку:

• Esc — зупинити Claude посеред дії; контекст зберігається, можна перенаправити.
• Esc + Esc або /rewind — меню відкату: відновити попередній стан розмови й коду або підсумувати від вибраного повідомлення.
• «Undo that» — попросити Claude скасувати свої зміни.
• /clear — скинути контекст між непов'язаними задачами.

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

Керування сесією: агресивно керуйте контекстом (Manage context aggressively)

• Біля ліміту Claude Code автоматично стискає історію (compaction), зберігаючи важливий код і рішення. Але в довгих сесіях контекст все одно наповнюється нерелевантним, що знижує якість і відволікає.
• Часто робіть /clear між задачами.
• Автоматичне стиснення підсумовує найважливіше: патерни коду, стан файлів, ключові рішення.
• Для контролю — /compact <instructions>, наприклад /compact Focus on the API changes.
• Стиснути лише частину: Esc + Esc або /rewind, вибрати checkpoint і Summarize from here (стискає повідомлення від цієї точки, раніший контекст лишається цілим) чи Summarize up to here (стискає раніші, недавні лишаються повністю).
• Поведінку стиснення можна налаштувати в CLAUDE.md, наприклад: «під час стиснення завжди зберігай повний список змінених файлів і команди тестів».
• Для побіжних питань — /btw: відповідь не потрапляє в історію, контекст не росте.

Керування сесією: subagents для дослідження (Use subagents for investigation)

Оскільки контекст — фундаментальне обмеження, дослідження виносять у subagents: вони читають файли у власних вікнах і повертають лише підсумки. Приклад: «через subagents з'ясуй, як наша автентифікація оновлює токени і чи є готові OAuth-утиліти для повторного використання». Subagents також годяться для перевірки після реалізації (див. adversarial review нижче).

Керування сесією: відкат через checkpoints (Rewind with checkpoints)

• Кожен промпт, що починає хід, створює checkpoint; перед кожною зміною Claude автоматично робить знімок файлів.
• Подвійний Esc або /rewind: відновити лише розмову, лише код, обидва, або підсумувати від вибраного повідомлення.
• Можна сміливо пробувати ризикові підходи — не вийшло, відкотилися й пробуєте інакше. Checkpoints зберігаються разом із розмовою: можна закрити термінал, відновити сесію пізніше й усе одно відкотитися.
• Застереження: checkpoints відстежують лише зміни через інструменти редагування файлів Claude. Зміни через Bash-команди чи зовнішні процеси не фіксуються. Це не заміна git.

Керування сесією: відновлення розмов (Resume conversations)

Давайте сесіям імена через /rename і ставтеся до них як до гілок: кожен напрям роботи має власний постійний контекст. Розмови зберігаються локально, тож для багатоденних задач не треба знову пояснювати контекст. claude --continue — продовжити останню, claude --resume — вибрати зі списку. Імена мають бути описовими, наприклад oauth-migration.

Автоматизація: неінтерактивний режим (Automate and scale → Run non-interactive mode)

claude -p "prompt" запускає Claude без інтерактивного вводу — для CI, pre-commit hooks і скриптів (headless). Прогін усе одно створює сесію, яку можна відновити, якщо не передати --no-session-persistence. Формати виводу:

# разовий запит, звичайний текст
claude -p "Explain what this project does"

# структурований вивід: один JSON-об'єкт з полем result
claude -p "List all API endpoints" --output-format json

# потоковий: один JSON-об'єкт на рядок, першою йде подія init
claude -p "Analyze this log file" --output-format stream-json --verbose

Автоматизація: кілька сесій паралельно (Run multiple Claude sessions)

Паралельні сесії пришвидшують розробку, дають ізольовані експерименти й складні процеси. Варіанти — від ручної координації до автоматичної:

• Worktrees — окремі CLI-сесії в ізольованих git checkouts, щоб правки не конфліктували.
• Cross-session messaging — ваші сесії передають одна одній знахідки.
• Desktop app — візуальне керування кількома локальними сесіями, за бажання кожна у своєму worktree.
• Claude Code у хмарі — сесії за замовчуванням на інфраструктурі Anthropic.
• Agent view (research preview) — claude agents запускає сесії, що працюють у фоні, і показує їх на одному екрані.
• Agent teams (експериментально, вимкнено за замовчуванням) — автоматична координація сесій зі спільними задачами, повідомленнями й team lead.

Окрім паралелізму, свіжий контекст покращує code review: Claude не упереджений до щойно написаного ним коду. Патерн Writer/Reviewer: сесія A реалізує rate limiter для API; сесія B рев'юїть @src/middleware/rateLimiter.ts на граничні випадки, race conditions і відповідність наявним middleware-патернам; A отримує ці зауваження й виправляє. Аналогічно з тестами: один Claude пише тести, інший — код, що їх проходить.

Автоматизація: fan-out по файлах (Fan out across files)

Для великих міграцій чи аналізу роботу розподіляють на багато паралельних викликів. /batch <instruction> розбиває зміну на 5–30 subagents, кожен у власному worktree. Або керуйте fan-out власним скриптом через claude -p:

1. Попросити Claude записати список файлів для міграції у файл (наприклад, «знайди всі 2 000 Python-файлів, що потребують міграції, і збережи список у files.txt»).
2. Написати цикл:

   for file in $(cat files.txt); do
     claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
       --allowedTools "Edit,Bash(git commit *)" \
       --permission-mode dontAsk
   done

3. Прогнати на 2–3 файлах, уточнити промпт за тим, що пішло не так, і лише тоді запускати на всьому наборі.

--allowedTools наперед дозволяє потрібні інструменти; --permission-mode dontAsk відхиляє все інше, що вимагало б схвалення, — важливо для автономних прогонів (хоча встановлений mod усе ж може схвалити частину викликів). Інтеграція в наявні пайплайни: claude -p "<your prompt>" --output-format json | your_command.

Автоматизація: автономна робота в auto mode (Run autonomously with auto mode)

Для безперервного виконання з фоновими перевірками безпеки: класифікатор переглядає команди перед запуском, блокує scope escalation, невідому інфраструктуру й дії під впливом ворожого контенту, а рутинна робота йде без підтверджень.

claude --permission-mode auto -p "fix all lint errors"

Якщо класифікатор неодноразово блокує дії в неінтерактивному прогоні з -p, Claude Code не зупиняє прогін; що відбувається натомість і які пороги — описано в розділі про fallback auto mode.

Автоматизація: крок adversarial review (Add an adversarial review step)

• Перш ніж вважати задачу виконаною, доручіть subagent переглянути diff у свіжому контексті й звітувати про прогалини. Що довше Claude працював без нагляду, то важливіша незалежна перевірка. Рецензент бачить лише diff і задані вами критерії, а не міркування, що до них привели, тож оцінює результат сам по собі.
• Для перевірки коректності — вбудований skill /code-review: шукає баги в поточному diff у свіжому subagent і повертає знахідки в сесію.
• Для перевірки відповідності плану промпт пишуть самі: що перевіряти, проти якого плану, що вважати знахідкою. Приклад: «через subagent звір diff rate limiter з PLAN.md: усі вимоги реалізовано, перелічені граничні випадки покрито тестами, нічого поза обсягом задачі не змінено; повідомляй про прогалини, а не про стильові вподобання».
• Оскільки рецензент — subagent, сесія-виконавець отримує прогалини напряму, виправляє й повторює review без копіювання між вікнами.
• Застереження: рецензент, якого попросили шукати прогалини, зазвичай їх знаходить навіть у якісній роботі. Гонитва за кожною веде до over-engineering: зайві шари абстракції, захисний код, тести неможливих випадків. Просіть позначати лише прогалини, що впливають на коректність чи заявлені вимоги, решту вважайте необов'язковою.

Типові патерни провалу (Avoid common failure patterns)

Розвивайте інтуїцію (Develop your intuition)

Ці патерни — стартові точки, а не догма. Іноді контекст варто накопичувати (ви глибоко в одній складній проблемі й історія цінна); іноді планування зайве, бо задача дослідницька; іноді розмитий промпт — саме те, що треба, щоб побачити, як Claude інтерпретує проблему. Помічайте, що спрацювало (структура промпту, наданий контекст, режим), а коли Claude буксує — питайте чому: зашумлений контекст, розмитий промпт, задача завелика для одного проходу? З часом з'явиться чуття, коли бути конкретним, а коли відкритим, коли планувати, а коли досліджувати, коли чистити контекст, а коли дати йому накопичуватися.

Головне: контекстне вікно — головний ресурс, тому чистьте й делегуйте його, а якість забезпечуйте перевірками, які Claude може запустити сам (тести, /goal, Stop hook, незалежний review). Розділяйте дослідження, план і реалізацію та масштабуйтеся через headless-режим, паралельні сесії й fan-out.

Як заповнюється контекстне вікно (Explore the context window)

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

Що показує таймлайн (What the timeline shows)

Реалістичний сценарій із типовими кількостями токенів:

• Ще до першого промпту в контекст завантажуються CLAUDE.md, auto memory, імена MCP tools і описи skills. Замість CLAUDE.md можуть вантажитися файли AGENTS.md. Ваше налаштування може додати ще дещо, наприклад output style чи текст із --append-system-prompt.
• Під час роботи кожне читання файлу додає до контексту; path-scoped rules автоматично підвантажуються разом із файлами, що їм відповідають; після кожної правки спрацьовує PostToolUse hook.
• Наступний промпт: дослідження виконує subagent у власному окремому вікні, тож великі файли не потрапляють у ваш контекст — повертаються лише підсумок і невеликий блок метаданих.
• Наприкінці виконується /compact, що замінює розмову структурованим підсумком. Більшість стартового вмісту перезавантажується автоматично.

Що переживає стиснення (What survives compaction)

При стисненні довгої сесії Claude Code підсумовує історію, щоб вона вмістилася у вікно. Починаючи з v2.1.198, запит на підсумовування успадковує налаштування extended thinking сесії: якщо thinking увімкнено — підсумок генерується з ним, якщо ні — без. Це впливає лише на спосіб створення підсумку; налаштування сесії після цього не змінюються. Доля вмісту залежить від того, як він потрапив у контекст:

• Одразу після стиснення перечитуються до п'яти нещодавно змінених файлів із сесії. Файл понад 5 000 токенів повертається лише як посилання на шлях без вмісту — позначається Referenced file замість Read.
• Path-scoped rules і вкладені CLAUDE.md потрапляють в історію повідомлень, коли Claude читає, пише чи редагує файл-тригер, тому при стисненні підсумовуються разом з усім іншим. Якщо правило має пережити стиснення — приберіть frontmatter paths: або перенесіть його в CLAUDE.md у корені проєкту.
• Тіла skills повертаються, але великі обрізаються до ліміту на skill, а найстаріші викидаються при перевищенні загального бюджету. Обрізання зберігає початок файлу — тож найважливіші інструкції ставте на початок SKILL.md.

Коли контекст заповнюється (When your context fills up)

При наближенні до ліміту Claude Code стискає контекст автоматично, тож повне вікно не завершує сесію; автоматичний прохід працює так само, як /compact. Є також окреме налаштування стиснення розмови, залишеної без активності (idle compaction). Діяти можна й до автоматичного проходу:

• Стиснення з фокусом: /compact з інструкцією, наприклад /compact focus on the auth bug fix, перед довгою новою задачею — підсумок збереже вибране вами, а не те, що вгадає автоматика.
• Стиснення частини розмови: /rewind, вибрати повідомлення, Summarize from here або Summarize up to here.
• Раніше стиснення: /autocompact з кількістю токенів, наприклад /autocompact 500k, задає, наскільки має заповнитися вікно до автоматичного проходу.
• Очищення між задачами: /clear при переході до непов'язаної роботи — стара розмова витісняє потрібні файли й коштує токенів у кожному повідомленні.
• Делегування великих читань: дослідження — subagent, щоб вміст файлів лишався в його вікні, а не у вашому.

Якщо потрібне більше вікно, а не коротша розмова: моделі Fable, Sonnet 5 і новіші, Haiku 5.5, Opus 4.6 і новіші та Sonnet 4.6 підтримують вікно на 1 млн токенів (доступність залежить від плану, вибирається варіант моделі [1m]). Стиснення на більшому ліміті працює так само.

Поріг автоматичного стиснення залежить від моделі й конфігурації (є таблиця порогів за замовчуванням для кожної моделі). Якщо Claude Code неправильно визначає розмір вікна для вашого model ID — наприклад, для аліасу LLM gateway, — його можна скоригувати в налаштуваннях моделі.

Перевірте власну сесію (Check your own session)

У візуалізації числа типові. Реальне використання показує /context — живу розбивку за категоріями з порадами з оптимізації, включно з тим, які CLAUDE.md і файли auto memory завантажено. /memory відкриває ці файли для редагування.

Пов'язані матеріали (Related resources)

• Extend Claude Code — коли використовувати CLAUDE.md, skills, rules, hooks чи MCP.
• Store instructions and memories — ієрархія CLAUDE.md і auto memory.
• Subagents — делегування дослідження в окреме вікно.
• Best practices — контекст як головне обмеження.
• Prompt caching — які дії інвалідують кешований префікс.
• Reduce token usage — стратегії зменшення витрати контексту.

Головне: кореневий CLAUDE.md, auto memory, план і описи skills повертаються після стиснення з диска, а path-scoped rules і вкладені CLAUDE.md лише підвантажуються знову на вимогу, великі skills обрізаються, тож критичне тримайте в кореневому CLAUDE.md і на початку SKILL.md. Керуйте заповненням заздалегідь через /compact з фокусом, /rewind, /autocompact, /clear і subagents, а реальний стан дивіться в /context.

Урок 1. Що змінюється і з чого почати (What changes and where to start)

Проблема

AI вже пише код дуже швидко, а процеси навколо коду не встигають. SDLC має шість етапів: Plan, Design, Build, Test, Deploy, Maintain. Курс показує AI-native варіант кожного з них; більшість компаній зараз десь посередині між двома полюсами.

Зсуви за етапами (традиційно → AI-native)

• Plan: вимоги збирає комітет через воркшопи й погодження і вручну оформлює → Claude бере больові точки прямо з джерел і фіксує їх в intent.md, який читає людина й може виконати машина.
• Design: аналітики пишуть специфікацію, дизайнери її розбирають → вимоги й дизайн робляться в одній сесії з агентом за стандартами-skills, результат лежить у Git.
• Build: код і тести пишуть руками, документацію — після → код і тести генерує AI, а знання команди живе у версіонованих CLAUDE.md і skills.
• Test: QA-шлюзи на межах етапів → безперервні evals під час реалізації.
• Deploy: люди читають кожен рядок, governance непослідовний → кілька шарів агентного рев'ю, людське рев'ю лише для регульованого й критичного коду; правила застосовуються в момент дії через hooks як approval gates.
• Maintain: люди виловлюють баги в production → агенти моніторять деплойменти, а кожен вихід за control band діагностується й повертається в цикл новим intent.md.

За рішення, що потребують судження, відповідають люди.

Як влаштовані plays

Plays (практики) згруповано за шістьма нелінійними етапами. У кожному є: що змінюється, як почати, кроки, governance, метрики успіху. Залежності вказано в розділі «Prerequisites» і на графі: суцільна стрілка означає обов'язкову залежність, пунктирна — корисну, але необов'язкову.

Вибір першого play

Plays модульні, тож етапи можна трансформувати в будь-якому порядку. Без передумов можна почати з шести:

• Plan: intent.md;
• Build: plan mode як стартова точка;
• Build: CLAUDE.md;
• Build: skills як інституційне знання;
• Test: feedback loop для Claude;
• Deploy: hooks як approval gates.

Решта залежить від них (за розділами «Getting started» уроків):

• Requirements and design ← intent.md + skills бренду, безпеки, compliance, UX.
• Plan mode ← intent.md/spec.md, якщо є; CLAUDE.md допомагає.
• Parallel sessions ← CLAUDE.md; feedback loop допомагає.
• Continuous evals ← CLAUDE.md + feedback loop.
• PR review ← CLAUDE.md, skills (для політик), subagents.
• CI/CD ← PR review + hooks як approval gates.
• Closing the loop ← intent.md, PR review, hooks, rollback у CI/CD.

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

Урок 2. Фіксація задуму як intent.md (Capture as intent.md)

Звідки береться intent

Процес стартує з intent.md. Джерело — ідея людини, тікет або alert про інцидент (етап Maintain). Автор ідеї обговорює її з Claude і отримує proto-spec у Markdown. Йому не треба вмовляти продуктову команду це оформити. Хай звідки прийшов intent, product owner перевіряє й виправляє написаний агентом файл, і лише потім його комітять.

Що змінюється

• Традиційно: ідея проходить backlog, user stories, story points, refinement. Власник змінюється на кожній передачі, і до інженерів доходить спотворений задум.
• AI-native: автор сам фіксує intent.md своїми словами: що треба, навіщо, з якими обмеженнями. Повторювані процеси оформлюють як skills.

Як почати

• Передумови: немає.
• Інфраструктура: доступ до Claude для неінженерів (claude.ai або Cowork), погоджений шаблон intent.md, спільне версіоноване сховище, за яким стежить product owner.
• Для одного продукту найпростіше — тека intent/ у репозиторії продукту, поруч із кодом. Окремий intent-репозиторій варто заводити лише тоді, коли intent охоплює багато репозиторіїв; у monorepo це директорія. Співіснування з Jira чи інструментом вимог описано в уроці 4.
• Платформна чи інженерна команда налаштовує сховище один раз і вирішує, хто може писати, бо автори будуть з усієї організації.
• Знати Git не обов'язково: через конектор до VCS (наприклад, GitHub) Claude комітить Markdown за автора з claude.ai чи Cowork.

Кроки

• Автор вільно описує проблему: чого не можна зробити зараз, кого це стосується, як буде краще, що поза рамками.
• Брейншторм іде, доки ідея не стане конкретною. Claude питає, як аналітик: межі, користувачі, обмеження, критерії успіху.
• Claude оформлює intent.md за шаблоном організації. Шаблон може бути skill від технічного фахівця, підписаним лідом. Розділи: проблема, бажаний результат, користувачі й системи, обмеження, відкриті питання.
• Автор виправляє неточності.
• Файл комітять у сховище з автором і часом, далі ідею бере product owner.

Приклад

# Intent: claims status self-service
Author: J. Ortiz (claims operations). Status: draft.
## Problem
Customers phone the contact center to ask where their claim is.
Handlers spend roughly a third of call time on status-only queries.
## Proposed outcome
Customers see claim status, next step and expected date in the portal.
## Affected users and systems
Claims handlers, portal team, claims-core API.
## Constraints
No new PII in the portal session. Existing authentication only.
## Open questions
Do third-party loss adjusters need access too?

Governance

Доказ — закомічений intent.md з автором, часом і історією змін у Git. Схвалює product owner. Рішення пустити intent у Design чи відхилити фіксується як merge або закрите рев'ю.

Метрики

• Випереджальна: час від першої розмови до коміту intent.md. Очікується, що тижні збору вимог скоротяться до годин.
• Запізніла: survival rate, тобто частка intent, прийнятих у Design, а не закритих. А також кількість змін intent.md після першого коміту spec.md для тієї самої зміни.

Головне: автор із Claude за години перетворює ідею на версіонований intent.md без тижнів backlog-процедур, а product owner лише перевіряє й схвалює.

Урок 3. Вимоги та дизайн (Requirements and design)

Суть

Зі схваленого intent.md Claude робить специфікацію вимог і дизайну за skills організації (бренд, безпека, compliance, UX). Product owner її рецензує, але не пише. Інженери отримують документ, за яким можна планувати, і в ньому вже позначено ризики. Для front-end product owner робить макет у Claude Design з intent.md, доопрацьовує його й експортує в Claude Code.

Що змінюється

• Традиційно: вимоги й дизайн — окремі фази різних команд. Аналітики формалізують, дизайнери перекладають назад. Поділ дає підзвітність, але працює повільно і губить зміст.
• AI-native: обидві фази вміщаються в одну сесію. Claude з intent.md пише специфікацію в межах skills і позначає ризики.

Як почати

• Передумови: intent.md і політики бренду, безпеки, compliance та UX у вигляді skills.
• Інфраструктура: product owner із доступом до Claude, інженерні навички не потрібні.

Кроки

• Відкрити сесію зі skills організації та прикріпленим intent.md.
• У промпті послатися на intent, назвати обмеження й вимагати позначити ризики. Еволюція така: спершу вручну, потім slash command рівня організації, потім автоматичний тригер. Неінтерактивна job спрацьовує на merge intent.md, проганяє крок зі skills і відкриває PR зі spec.md (технічна частина — у play про CI/CD). Product owner тоді долучається вже на рев'ю.
• Звірити специфікацію з ідеєю: чи розв'язано проблему, чи відповіли на відкриті питання з intent або перенесли їх далі.
• Спершу закрити позначені ризики — те, що аналітик ескалував би. Кожен вирішити з власником політики до того, як специфікацію побачать інженери.
• Закомітити spec.md поруч з intent.md: пара файлів показує, що просили і що вирішили.
• Product owner вирішує, чи йде зміна в розробку, а для підвищеного ризику радиться з tech lead. Рішення завжди ухвалює людина; прийнятий spec запускає plan mode.

Приклад

Промпт по суті: прочитай intent.md, підготуй специфікацію інтеграції в наявну кодову базу, застосуй skills (бренд, безпека, UX), запиши як spec.md для інженерів і чітко опиши ризики, особливо конфлікти політик. Контекст: claims-api — бекенд порталу, claims-core — стара внутрішня система заявок.

# Spec: claims status self-service
Skills applied: secure-api-review, brand-voice, portal-ux.
## Requirements
- R1. A signed-in customer sees status, next step and expected date for each open claim.
- R2. Status is one of four states: received, in review, approved, paid.
- R3. The response carries those three fields and nothing else.
- R4. What the customer sees is at most 60 seconds old.
## Design
- New endpoint GET /claims/{id}/status in claims-api, behind the gateway JWT.
- claims-api reads the claim from claims-core. The portal never calls claims-core.
- New StatusPanel on the portal claims page. It caches each answer for 60 seconds.

Далі spec показує, як виконано кожне обмеження intent. «Жодних нових PII» закриває R3: жодне з трьох полів не позначене pii. «Лише наявна автентифікація» закриває gateway JWT без нових логінів і ролей. Ризики:

• У loss adjusters немає облікового запису в порталі, доступ для них порушив би правило автентифікації, тому їх виключено. Власник: security.
• portal-ux вимагає дату біля кожного статусу, а brand-voice забороняє подавати дату виплати як зобов'язання. Пропозиція: підпис «Estimated date». Власник: compliance.
• claims-core витримує 50 запитів/с. 60-секундний кеш має тримати навантаження нижче ліміту, але навантажувальний тест не проводили. Власник: команда claims-core.

Вимоги пронумеровано, щоб план і рев'ю могли на них посилатися.

Governance

Конфлікти політик видно одразу, а не на рев'ю через тижні, бо skills застосовуються як обмеження під час написання. Spec, промпт і версії skills зберігаються у VCS. Product owner підписує spec і передає ризики власникам політик.

Метрики

• Випереджальна: час між комітами intent.md і spec.md порівняно зі старим циклом «вимоги + дизайн».
• Запізніла: переробки вимог, тобто коміти spec.md після першого коміту plan.md (видно з git log).

Головне: вимоги й дизайн вміщаються в одну сесію. Claude пише spec.md за skills і сам позначає конфлікти політик, а людина рецензує й ухвалює рішення.

Урок 4. Plan mode у Claude Code як стартова точка за замовчуванням (Claude Code plan mode as the default starting point)

Суть

Інженер стартує сесію в plan mode з spec.md, відповідає на уточнювальні питання Claude і доопрацьовує план, доки той його не влаштує.

Що змінюється

• Традиційно: інженер читає дизайн і пише код. Задум реалізації (які файли, які тести) лишається в голові чи в коментарі до тікета. Рецензент уперше бачить лише готовий diff, і переробка тоді повільна.
• AI-native: спершу письмовий план. У plan mode Claude читає код, нічого не змінюючи. Інженер править план, схвалену версію комітять як plan.md, і наступні етапи звіряються з нею.

Як почати

• Передумови: intent.md/spec.md, якщо є; CLAUDE.md допомагає.
• Інфраструктура: Claude Code з доступом до репозиторію.

Кроки

• Запустити сесію в plan mode й дати intent.md та spec.md. Попросити план: які файли змінюються, у якому порядку, які тести це доведуть.
• Допитати план: що може зламатися, який крок найризикованіший, які альтернативи Claude відкинув.
• Ітерувати, доки за планом не зможе працювати інженер, який не бачив розмови.
• Закомітити план як plan.md: він іде в audit trail, і PR review звіряє з ним diff.
• Прийняти план і дати Claude реалізувати. З добрим планом це часто один прохід.
• Якщо реалізація відходить від плану, оновлювати plan.md у тому самому коміті. Синхронність можна забезпечити hook-ом.

Приклад

# Plan: claims status self-service (from intent.md and spec.md)
## Files that change
portal/src/claims/StatusPanel.tsx (new), claims-api/routes/status.py, claims-api/tests/test_status.py
## Order of work
1. Add the status endpoint behind existing auth (R1, R2, R3).
2. Panel against the endpoint, with the 60-second cache (R1, R4).
3. Wire into the portal nav.
## Risks
The claims-core API rate-limits at 50 rps; the panel must cache (spec concern 3).
## Proof
test_status.py covers the four claim states (R2) and fails on any extra field (R3);
screenshot matches the approved mock.

Посилання на R1–R4 і ризик 3 дозволяють звірити план зі spec рядок за рядком.

Governance

Дизайн-рев'ю відбувається до появи коду, коли змінити курс — це відредагувати документ. Plan mode гарантує це сам: до прийняття плану Claude не може правити файли. План, ревізії й ім'я того, хто прийняв, логуються. Рутину схвалює інженер, підвищений ризик — tech lead чи архітектор.

Метрики

• Випереджальні: частка змін, змерджених після першого проходу, і час від схвалення плану до merge (дані — у метаданих PR).
• Запізнілі: цикли переробки на зміну і як часто змерджений diff відповідає plan.md.

Auto mode

В auto mode інженер схвалює план, а Claude вносить правки без підтвердження кожної. Коли дозрівають запобіжники (налаштований CLAUDE.md, skills з політиками, hooks, що блокують небезпечне, тести, які Claude запускає сам), auto mode стає дефолтом для рутини: чіткий spec.md, малий радіус ураження, код покритий тестами. Людина вже не стежить за кожною правкою, а рецензує артефакти після довгих автономних сесій. З worktrees auto mode дає паралелізм окремим людям і команді та лежить в основі автономного SDLC (етап Maintain).

Legacy-системи і джерело істини

Артефакти вже десь живуть: роботи в Jira, вимоги в інструменті з регуляторною трасованістю, дизайн у Figma, погодження через change board. Ці системи приймають аудитори й регулятори, і від них залежать інші команди, тож AI-native SDLC вбудовується поруч із ними. Для кожного артефакту одна система — джерело істини, решта тримає копію чи посилання. Вибір може бути різним для різних артефактів:

• Джерело — репозиторій. Markdown авторитетний, legacy-система посилається на файли в комітах. Для організацій, де головує інженерія, це одна з найчистіших схем: один інструмент і одне джерело міток часу.
• Джерело — legacy-система (Jira, ServiceNow, інструмент вимог). Markdown — робоча копія. Claude читає запис на старті сесії й записує результат назад через MCP-конектор у тій самій сесії, де створено spec чи план.
• Мінімум — двобічні посилання. Артефакт містить ID запису, запис містить commit SHA файлу. Це добрий старт для переходу, хоча джерел істини тоді два.

Головне: кожна зміна починається з плану в plan mode. Його допитують, комітять як plan.md і використовують для звірки diff, а коли дозріють запобіжники, рутина переходить в auto mode.

Урок 5. CLAUDE.md (The CLAUDE.md)

Суть

CLAUDE.md дає Claude те, що знадобилося б новачкові: конвенції, команди, архітектуру й типові помилки. Знання з голів і wiki стає файлом, який агент читає на початку кожної сесії. Його веде вся команда й доповнює після помилок.

Як почати

• Передумови: немає.
• Інфраструктура: репозиторій, Claude Code та інженер, який добре знає кодову базу.

Кроки

• Запустити /init: Claude згенерує чернетку.
• Скоротити її до потрібного в перший день: команди build/test/lint, важливі конвенції, те, у чому Claude постійно помиляється.
• Закомітити в корінь репозиторію: одна версія для всіх, зміни рецензуються як код.
• Правило: помилку, яку Claude зробив двічі, записують у CLAUDE.md.
• Тримати файл у межах сторінки: Claude читає його повністю, і застарілий вміст марно займає контекст.

Приклад

# Claims portal
## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint (runs in CI; fix before pushing)
- Run: make run (portal on :3000, claims-api on :8000)
## Conventions
- claims-api is Python 3.12 and FastAPI. portal is TypeScript and React.
- Every endpoint needs a test in claims-api/tests.
- Dates cross the API as ISO 8601, never as formatted text.
## Architecture
- portal/ is the customer site, claims-api/ is its backend, and
  intent/ holds the intent.md, spec.md and plan.md for each change.
- Only claims-api talks to claims-core. The portal never calls it.
- claims-core allows 50 requests a second. Cache reads; never poll it.
## Things Claude gets wrong
- Do not log request or response bodies in claims-api; they can hold PII.
- Do not bump dependency versions; the platform team owns them.

Governance

Файл версіонований, тож інструкції агента можна переглянути й проаудитувати. Конвенції застосовуються через нього, зміни видно в Git, а схвалюють їх code owners у PR review.

Метрики

• Випереджальна: як часто Claude повторює помилку, яку мав би запобігти CLAUDE.md (виправлення файлу видно в Git).
• Запізніла: час до першого змердженого PR нового члена команди.

Головне: короткий спільний CLAUDE.md у Git — це онбординг для агента. Кожна помилка, повторена двічі, потрапляє туди, а зміни файлу рецензують як код.

Урок 6. Skills як інституційне знання (Skills as institutional knowledge)

Суть

Skills перетворюють знання організації на явні, версіоновані інструкції. Вони діють широко й оновлюються централізовано, коли змінюється політика. Правило: skill пишуть для знання, яке треба застосовувати послідовно, а не для того, що належить до CLAUDE.md чи промпту.

Як почати

• Передумови: немає. CLAUDE.md допомагає, але skill від нього не залежить.
• Інфраструктура: одна політика з названим власником і письмовим джерелом істини.

Кроки

• Вибрати знання, яке зараз застосовують непослідовно: стандарт безпеки, конвенцію API чи правило бренду.
• Оформити його як теку з SKILL.md. Frontmatter визначає, коли skill спрацьовує, тіло — що робити. Пише інженер за джерелом власника політики, з допомогою Claude.
• Покласти в .claude/skills/<name>/ поруч із кодом або поширити на організацію через plugin.
• Перевірити тригер: попросити про ту саму задачу різними словами й переконатися, що skill щоразу завантажується.
• Коли політика змінюється, оновити skill і отримати підпис власника. Інженери отримають нову версію в наступній сесії автоматично.

Приклад

---
name: secure-api-review
description: Apply the API security standard. Use whenever creating or
  modifying an external-facing endpoint, reviewing API code, or
  generating an OpenAPI spec.
---
# Secure API review
When you create or change an API endpoint:
1. Authentication: every endpoint requires the gateway JWT;
   no anonymous routes outside /health.
2. Input validation: validate request bodies against the OpenAPI
   schema and reject unknown fields.
3. Audit: every state-changing endpoint emits an audit event with
   actor, action, entity and timestamp.
4. Data classification: fields tagged pii in the schema must never
   appear in logs or error messages.
Run scripts/check-endpoints.sh and include its output in your summary.

Governance

Skill — дорадчий контроль: він робить дотримання політики ймовірним, але не примушує. Для правил, що мають діяти завжди, за skill потрібен детермінований механізм: hook, що блокує дію, або перевірка на PR. Skill робить порушення рідкісними, hook — майже неможливими. Hook ловить порушення в момент правки, перевірка на PR — усе, що потрапило в гілку іншим шляхом. Виклики skills видно в session traces, а зміни skill власник політики рецензує як код.

Метрики

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

Hooks як запобіжники на етапі Build

Більшість дій Claude під час реалізації — правки файлів і shell-команди, тож на Build hooks спрацьовують найчастіше. Вони можуть:

• блокувати правки захищених шляхів (згенерований код, «заморожений» пакет);
• запускати formatter і linter після правок;
• не пускати облікові дані в diff;
• підкріплювати skill, що має діяти без винятків.

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

Приклад підкріплює правило 4 зі skill: після правки файлу в claims-api/routes/ запускається scripts/check-endpoints.sh. Він падає, якщо поле з позначкою pii потрапляє в лог чи текст помилки. Реєстрація в .claude/settings.json (порожній args означає запуск без shell):

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

.claude/hooks/api-policy.sh:

#!/bin/bash
file=$(jq -r '.tool_input.file_path')
case "$file" in
  "$CLAUDE_PROJECT_DIR"/claims-api/routes/*.py) ;;
  *) exit 0 ;;  # not an endpoint
esac
cd "$CLAUDE_PROJECT_DIR" || exit 2
if ! found=$(scripts/check-endpoints.sh "${file#"$CLAUDE_PROJECT_DIR"/}"); then
  echo "secure-api-review rule 4: a pii field reaches a log or an error message." >&2
  echo "$found" >&2
  exit 2
fi

Hook після правки не може її скасувати. Exit code 2 показує повідомлення Claude, і той виправляє рядок, наприклад, отримавши claims-api/routes/status.py:10: policy_holder_name. Hook на Edit|Write не спрацює, якщо файл переписала shell-команда. Тому той самий скрипт запускається як required check на кожен PR:

name: API policy
on: pull_request
jobs:
  check-endpoints:  # a required check in branch protection
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: scripts/check-endpoints.sh claims-api/routes/*.py

Hooks, що питають схвалення в людини, належать до етапу Deploy. На Build вони повертають людину на критичний шлях усіх паралельних сесій.

Головне: політики, які треба застосовувати послідовно, оформлюють як версіоновані skills з власником. Те, що має діяти без винятків, страхують швидким hook-ом і такою самою перевіркою на PR.

Урок 7. Паралельні сесії та subagents (Parallel sessions and subagents)

Суть

Паралельна сесія — окремий екземпляр Claude Code, що виконує своє завдання у власному Git worktree. Сесії не знають одна про одну, і спільний у них лише інженер. Subagent — помічник усередині сесії з власним контекстним вікном і обмеженими інструментами для задач, що повторюються, наприклад перевірити, що застосунок працює. Паралельні сесії збільшують кількість завдань у роботі, subagents тримають кожну сесію сфокусованою, а інженер керує й рецензує.

Що змінюється

• Традиційно: одне завдання за раз, багато часу йде на очікування збірок, тестів і рев'ю. Перемикатися між завданнями виснажливо, тож мало хто так робить.
• AI-native: кілька сесій одночасно, кожна у своєму worktree. Повторювані задачі віддано subagents. Роль інженера — оркестрація, а згодом побудова й моніторинг циклів.

Як почати

• Передумови: CLAUDE.md, бо його читають усі сесії. Feedback loop допомагає: сесія, що сама себе перевіряє, потребує менше нагляду.
• Інфраструктура: Git-репозиторій (ізоляцію дають worktrees) і налаштовані дозволи, щоб сесії не чекали підтвердження безпечних команд.

Кроки

• Розбити роботу на завдання з різними файлами; де вона незалежна, видно з plan.md. Завдання зі спільними файлами виконувати послідовно в одній сесії.
• Кожному завданню — свій worktree: claude --worktree feature-auth в одному терміналі, claude --worktree fix-rate-limit в іншому. Окремий checkout на своїй гілці усуває конфлікти за файли.
• Почати з 2–3 сесій. Стеля — скільки потоків людина здатна якісно рецензувати; нові сесії додавати, лише доки рев'ю встигає.
• Повторювані задачі описати як subagents у .claude/agents/ (назва, коли застосовувати, дозволені інструменти) і закомітити. Приклади: code simplifier прибирає зайву складність після основного агента, verifier запускає застосунок і перевіряє поведінку, researcher досліджує код і звітує, не засмічуючи основний контекст.

Приклад

---
name: verifier
description: Runs the app and checks the change works before the session reports done
tools: Bash, Read
---
Start the app with make run. Exercise the changed behavior and the two
nearest neighboring flows. Report what you ran, what you saw, and any
behavior that does not match plan.md. Do not fix anything; report only.

Governance

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

Метрики

• Випереджальні: скільки сесій одночасно веде інженер без падіння якості рев'ю (з OpenTelemetry) і частка часу на керування замість очікування.
• Запізнілі: змерджені зміни на інженера за тиждень разом із часткою переробок.

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

Урок 8. Дайте Claude feedback loop (Give Claude a feedback loop)

Суть

Claude завжди має мати спосіб перевірити себе: тести, збірку, порівняння скриншотів. Тоді помилки виправлено ще до того, як роботу побачить інженер. Це не те саме, що subagent-verifier. Цикл працює протягом усього завдання стільки разів, скільки треба. Verifier — разова фінальна перевірка у свіжому контексті, щоб на вердикт не впливали припущення, з яких писався код.

Що змінюється

• Традиційно: сигнал про роботу коду приходить пізно: CI за хвилини, тестувальник за дні, production за тижні. З агентом це означає, що людина перевіряє весь його вихід і стає вузьким місцем.
• AI-native: сесія сама запускає тести, збірку чи скриншот і ітерує до успіху, тож інженер отримує вже перевірене. Цикл налаштовує інженер, що веде сесію.

Як почати

• Передумови: немає.
• Інфраструктура: тести й збірка, кожне однією локальною командою. Для UI Claude має бачити результат: browser tool або утиліта скриншотів через MCP.

Кроки

• Загорнути перевірку в одну ціль (make test, npm test), яка у разі збою повертає ненульовий код.
• У розділі Commands CLAUDE.md перелічити команди з прикладом «здорового» виводу.
• Ставити вимірювану ціль, щоб Claude не мусив питати: «усі тести в test_status.py зелені», «скриншот збігається з макетом», «endpoint повертає 200 з новим полем».
• Для багфіксу спершу тест, що падає. Claude відтворює баг тестом і підтверджує, що той падає з очікуваної причини, тест комітять. Лише потім Claude робить його зеленим, не змінюючи тест (це забезпечує hook на тестові файли). Тест, що існував до виправлення й не був переписаний, доводить, що баг усунено.
• Для UI цикл замикається візуально: макет і браузер чи скриншоти, далі «реалізувати → знімок → порівняти → підправити». 2–3 раунди — норма, і кожен має покращувати результат.
• Включити перевірку у визначення «готово»: у CLAUDE.md записати, що перед звітом треба запустити тести й показати вивід.
• Захистити сам цикл: агент, що лагодить код, не повинен послаблювати перевірку. Hook блокує правки тестів під час виправлення; альтернатива — відхиляти на рев'ю будь-який diff, що зачіпає тести.

Приклад

## Verifying your work
- Build: make build (must finish with "Build succeeded")
- Test: make test (all green; never skip or delete a failing test)
- Lint: make lint (zero warnings)
Run all three before reporting any task complete, and paste the output.
If a test fails, fix the code, not the test.

Governance

• Що забезпечується: перевірка перед звітом і заборона правити тести під час фіксу; там, де потрібні гарантії, через hooks.
• Доказ: буквальний вивід make test, лог збірки чи diff скриншотів від самих інструментів.
• Де фіксується: у транскрипті сесії (експорт OpenTelemetry в observability-стек) і в check run PR, який бачать рецензент і аудитор.
• Хто схвалює: code owner, який може зосередитися на намірі й ризику, бо механічні докази вже додано.

Метрики

• Випереджальна: частка змін від агента, що проходять CI з першого разу.
• Запізнілі: час рев'ю на PR (має падати) і change failure rate з трекера інцидентів.

Головне: кожній сесії потрібна одна команда перевірки й вимірювана ціль, щоб Claude ітерував до зеленого результату. Сам цикл треба захистити від того, щоб агент послаблював тести.

Урок 9. Безперервні evals у CI (Continuous evals in CI)

Суть

Evals замінюють stage-gate QA: набір перевірок запускається, коли змінюється конфігурація агента (нова модель, переписаний промпт), і показує, чи якість роботи збереглася. Suite живий: з розвитком моделей старі кейси перестають розрізняти добре й погане, і з моніторингу треба додавати нові. Дехто запускає evals офлайн за розкладом; нижче описано безперервний варіант.

Як почати

• Передумови: CLAUDE.md і feedback loop.
• Інфраструктура: CI з неінтерактивним Claude Code і API-ключ із бюджетом на прогони.

Кроки

• Платформний інженер збирає 20–50 реальних недавніх завдань з очікуваним результатом.
• Кожне оформлює як eval: промпт і перевірки прийнятності (тести зелені, lint чистий, поведінка не змінилася, політику дотримано).
• Suite запускається в CI за розкладом і на будь-яку зміну CLAUDE.md, skills чи hooks: ця конфігурація керує агентом і потребує регресійних тестів, як код.
• Merge змін конфігурації залежить від результату: якщо зміна skill знижує pass rate, її переглядають.
• Кожен production-інцидент отримує eval від команди-власника, який лишається в suite як регресійний тест.

Приклад eval

evals/status-no-pii-in-logs.json побудовано зі змердженого PR. from — коміт перед ним, тож прогін стартує з тодішнього коду. may_change — теки, які дозволено змінювати.

{
  "name": "status-no-pii-in-logs",
  "source": "Merged PR: debug logging for the claim status endpoint",
  "from": "9d04e7a",
  "prompt": "Add debug logging to the claim status endpoint so on-call can see which claim was asked for and what we returned. Run the tests before you finish.",
  "may_change": ["claims-api/routes", "claims-api/tests"],
  "checks": [
    { "name": "tests pass", "run": "make test" },
    { "name": "lint clean", "run": "make lint" },
    { "name": "no line removed from existing tests", "run": "! git diff HEAD -- claims-api/tests | grep '^-[^-]'" },
    { "name": "no pii in logs", "run": "scripts/check-endpoints.sh claims-api/routes/status.py" },
    { "name": "no response body in logs", "run": "python3 $EVALS/log_bodies.py" }
  ]
}

Workflow

.github/workflows/agent-evals.yml запускається на PR, що зачіпають CLAUDE.md, .claude/** чи evals/**, і щоночі (cron: '0 2 * * *'). Порядок роботи:

• checkout з fetch-depth: 0, встановлення @anthropic-ai/claude-code через npm, ключ береться з secrets;
• evals/ копіюють у /tmp/evals до будь-якого прогону, щоб оцінювати з незайманої копії;
• для кожного eval створюють worktree на коміті from і видаляють з нього evals/ та .claude, щоб прогін не побачив своїх перевірок. Туди копіюють CLAUDE.md і .claude/ з тестованої гілки й комітять: старий код працює під новою конфігурацією;
• запуск і оцінка:

claude -p "$(jq -r '.prompt' $eval)" \
  --allowedTools "Read,Edit,Bash(make test)" \
  --output-format json > /tmp/result.json
/tmp/evals/check.sh "$eval" /tmp/result.json || failed=$((failed + 1))

• job падає, якщо хоч один eval провалено. Для suite з 20–50 evals поріг можна знизити.
• Не додавати --bare: він пришвидшує старт, але пропускає CLAUDE.md, skills і hooks, тобто саме те, що тестується.

Скрипти перевірки

• evals/check.sh <eval.json> <result.json> виконує перевірки над файлами, які залишив Claude. Прогін провалено, якщо результат порожній, зламаний чи is_error не false, або якщо змінено файли поза may_change (за git status --porcelain, крім ігнорованих Git). Так агент не пройде, переписавши Makefile чи перевірки. Якщо такі файли змінилися вже під час перевірок, результат обнуляється. Вивід — PASS/FAIL name (k/n checks) і перші рядки помилок.
• evals/log_bodies.py імпортує status.py, перехоплює логи власним handler-ом і викликає get_status з вигаданою заявкою (ім'я й телефон у next_step, дата народження, рахунок). Він падає, якщо рядок логу містить усе тіло відповіді. Перевіряється поведінка, а не назви змінних. Обмеження: ловиться лише повне тіло, лог одного next_step пройде.

Як це ловить регресію

Зазвичай: PASS portal-stays-off-claims-core (4/4), PASS status-no-pii-in-logs (5/5), 0 eval(s) failed. Припустімо, PR скорочує CLAUDE.md до сторінки й прибирає рядок про тіла запитів і відповідей. Видається, що це безпечно, бо skill і hook і так не пускають поля з pii у логи. Suite запускається, і Claude логує всю відповідь. Політичний скрипт мовчить, бо поля не позначені pii, але next_step — вільний текст з ім'ям і телефоном:

FAIL status-no-pii-in-logs (4/5 checks)
  failed: no response body in logs
  status for claim 'C-1001': returned {'status': 'in_review', 'next_step': 'Call A. Customer on 555 0100', ...}
1 eval(s) failed

Merge check падає, рецензент бачить зламаний eval і рядок логу, і рядок повертають у CLAUDE.md до merge.

Governance

QA-шлюз встигає за агентом: поріг pass rate працює як merge check, прогони логуються для порівняння в часі, а зміну схвалює команда-власник конфігурації.

Метрики

• Випереджальні: pass rate у часі; за скільки інцидент стає постійним eval.
• Запізніла: регресії, спіймані в CI, проти регресій у production.

Головне: конфігурацію агента тестують регресійно, як код. Реальні завдання й кожен інцидент стають evals, що блокують merge погіршень, а перевірки ізольовано, щоб агент не міг їх переписати.

Урок 10. AI у циклі PR review (AI in the PR review loop)

Суть

Claude рецензує вхідні PR за політиками організації й опрацьовує коментарі до власних PR. Люди оцінюють намір і ризик.

Що змінюється

• Традиційно: рев'ю розраховане на темп людей. PR чекає, якість залежить від завантаження рецензента, автор нагадує, черга росте.
• AI-native: кожен PR проходить однакові проходи рев'ю із зауваженнями, ранжованими за серйозністю. Людина вирішує, чи зміна робить задумане планом і чи прийнятний ризик.

Як почати

• Передумови: оновлений CLAUDE.md, skills (якщо рев'ю застосовує політики), визначені subagents.
• Інфраструктура: керований сервіс Code Review (вмикає Owner Claude-організації) або claude-code-action у власному CI, за потреби через Amazon Bedrock, Vertex AI чи Microsoft Foundry. Варто мати branch protection зі схваленням code owner.

Кроки

• Найшвидший старт — керований Code Review: Owner вмикає його й обирає репозиторії. claude-code-action потрібен, щоб контролювати pipeline чи пускати виклики через власну хмарну угоду.
• Tech lead пише REVIEW.md у корені репозиторію. Проходи: баги й логіка; безпека; відповідність spec.md, plan.md і принципам дизайну. Там же визначено, що таке Important і Nit і що пропускати.
• Поріг ставить людина: зауваження самі не схвалюють і не блокують PR, branch protection вимагає code owner. Щоб блокувати merge за зауваженнями, платформний інженер може читати машиночитну кількість за серйозністю з check run.
• Тег @claude у коментарі рев'ю: Claude виправляє й пушить, тред фіксує і запит, і зміну (через claude-code-action; у керованому сервісі @claude review запитує нове рев'ю). Власні PR Claude може довести до merge. Команди роблять slash command, що проходить невирішені коментарі й падаючі перевірки та пушить фікси, доки PR не стане зеленим і не чекатиме лише code owner.
• Помилку, яку рев'ю ловить удруге, вносять у CLAUDE.md у тому ж рев'ю, і з наступного PR її ловлять одразу. Рев'ю також повідомляє, коли CLAUDE.md застарів.
• Щомісяця tech lead оцінює зауваження, щоб рецензент покращувався, обмежує кількість Nit і виключає згенеровані шляхи та те, що вже перевіряє CI.

Приклад

# Review instructions
## Passes
Run three passes and tag each finding with its pass:
- Bugs: logic errors, broken edge cases, subtle regressions
- Security: injection risks, authentication gaps, PII in logs
- Compliance: the change matches spec.md, plan.md and our design principles
## What Important means here
Reserve Important for findings that would break behavior, leak data
or breach a policy. Style and naming are nits.
## Cap the nits
Report at most five nits per review; summarize the rest as a count.
## Do not report
Generated files under src/gen/ and anything CI already enforces.

Check run для PR з панеллю статусу:

• Important, StatusPanel.tsx:22, Compliance: запит на кожен рендер, хоча plan.md вимагає кешу через ліміт 50 запитів/с у claims-core.
• Important, status.py:31, Security: гілка помилки логує всю відповідь claims-core з policy_holder_name.
• Nit, test_status.py:8, Bugs: немає тесту для виплаченої заявки без дати.

Перше зауваження можливе лише тому, що прохід compliance читає plan.md, якого рецензент, що дивиться тільки diff, не бачить.

Governance

Розподіл обов'язків зберігається: агент-автор не може схвалити свій код. REVIEW.md діє для всіх PR. Зауваження, фікси, оцінки й схвалення лишаються в історії PR, тож PR і є аудиторським записом. Схвалює людина через branch protection.

Метрики

• Випереджальні: час до першого рев'ю (хвилини) і частка коментарів, вирішених без участі людини в гілці.
• Запізніла: дефекти й вразливості, спіймані до merge, проти тих, що дійшли до production.

Головне: Claude проганяє кожен PR через однакові проходи з REVIEW.md, звіряючи код зі spec.md і plan.md, і сам виправляє коментарі. Схвалює людина.

Урок 11. Hooks як approval gates (Hooks as approval gates)

Суть

На етапі Build hooks дозволяли чи блокували дії без людини. Hook може також спитати, тобто призупинити дію до підтвердження від людини в сесії. Якщо схвалює хтось інший (наприклад, release manager), hook шукає зафіксоване схвалення й блокує, доки його немає. Release gate — найнаочніший приклад, але hooks працюють скрізь: на Build вони блокують правки міграцій та інфраструктури без change ticket, на Test — правки тестів під час фіксу.

Як почати

• Передумови: немає.
• Інфраструктура: письмовий перелік схвалень, яких вимагає процес змін.

Кроки

• Інженерне керівництво з change management і compliance визначає людські шлюзи, які мають залишитися: погодження змін, авторизація релізу, правки захищених шляхів.
• Платформний інженер реалізує кожен шлюз як hook, що перед дією Claude повертає allow, ask або deny.
• Командні hooks лежать у .claude/settings.json у Git, обов'язкові — у managed settings платформної команди чи IT, які інженер не може вимкнути.
• Блокування пояснює причину й шлях до схвалення.

Приклад

Портал релізиться в dev, staging і production через MCP, по серверу на середовище, у кожного є інструмент release. У .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "mcp__deploy-.*__release",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/release-gate.sh",
            "args": [] } ] }
    ]
  }
}

release-gate.sh зі stdin читає tool_name, version і ticket і повертає JSON-рішення. Скорочено:

decide() { # decide <allow|ask|deny> <reason>
  jq -n --arg decision "$1" --arg reason "$2" '{hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: $decision,
    permissionDecisionReason: $reason}}'
  exit 0
}
case "$tool" in
  mcp__deploy-dev__release)
    decide allow "dev needs no approval" ;;
  mcp__deploy-staging__release)
    [ "$GITHUB_REF" = "refs/heads/main" ] && decide allow "pipeline release from main"
    decide ask "This ships $version to staging. Approve only if you own this release." ;;
  mcp__deploy-prod__release)
    # ticket має відповідати ^CHG-[0-9]+$, version — SHA з 7–40 hex, інакше deny;
    # далі change-ticket show перевіряє state == approved і ту саму version
    ... ;;
  *)
    decide deny "No release rule for $tool. Add one to release-gate.sh first." ;;
esac

• Production: якщо тікет погоджено для цієї версії — allow з іменем того, хто погодив. Інакше deny з маршрутом: відкрити change ticket, дочекатися погодження release manager, викликати release з номером тікета. change-ticket — CLI вашої системи змін.
• Шлюз працює, лише якщо агент не може писати в записи, які hook читає.
• У неінтерактивному прогоні на ask нікому відповісти, тож Claude Code відхиляє виклик. Тому staging дозволено з pipeline на main: там схваленням є погоджений merge.
• Обмеження: інженер може вручну виставити GITHUB_REF, але так він обійде лише запит, на який відповідав би сам.
• Причину ask бачить людина, причину deny — Claude, тому в deny вказано маршрут, який Claude передасть далі.

Governance

Hooks і є approval gates: умова перевіряється щоразу й для всіх, рішення логуються з часом, а шлюз визначає, що вважати схваленням (погоджений тікет чи підпис release manager).

Managed settings для регульованого підприємства

Розгортаються через MDM або admin console, інженери не можуть їх змінити:

{
  "permissions": {
    "deny": ["Read(.env*)", "Read(./secrets/**)", "WebFetch", "Bash(curl *)", "Bash(wget *)"],
    "allow": ["Bash(git *)", "Bash(make build)", "Bash(make test)", "Bash(make lint)"],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true,
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "network": { "allowedDomains": ["git.internal.example.com", "registry.npmjs.org"] },
    "credentials": {
      "files": [ { "path": "~/.ssh", "mode": "deny" },
                 { "path": "~/.aws/credentials", "mode": "deny" } ],
      "envVars": [ { "name": "GITHUB_TOKEN", "mode": "deny" } ]
    }
  },
  "allowManagedHooksOnly": true,
  "disableSideloadFlags": true,
  "allowManagedMcpServersOnly": true,
  "strictKnownMarketplaces": [ { "source": "github", "repo": "example-corp/approved-plugins" } ],
  "requiredMinimumVersion": "2.1.193"
}

• permissions.deny не пускає секрети в контекст і блокує вихід у мережу через інструменти. allow заздалегідь дозволяє безпечний внутрішній цикл, щоб не втомлювати запитами.
• disableBypassPermissionsMode + allowManagedPermissionRulesOnly: ні інженер, ні файл проєкту, ні прапорець не розширять правила.
• sandbox закриває те, чого не можуть дозволи: deny на WebFetch не зупинить shell-команду, а allowlist доменів на рівні ОС зупинить. failIfUnavailable і allowUnsandboxedCommands: false роблять sandbox обов'язковим: без нього Claude Code не стартує, і команду, що впала в sandbox, не можна повторити поза ним.
• credentials не дає sandboxed shell-командам читати ~/.ssh і ~/.aws/credentials (permissions.deny діє лише на файлові інструменти Claude) і прибирає перелічені секрети з оточення.
• allowManagedHooksOnly: працюють лише managed hooks. Hooks з user/project/local, зокрема приклад вище, блокуються, тож release gate треба перенести в managed-файл.
• disableSideloadFlags + strictKnownMarketplaces: skills, agents, hooks і MCP-сервери приходять лише зі схваленого marketplace, а прапорці разового sideload відхиляються на старті.
• allowManagedMcpServersOnly: набір інструментів агента — allowlist платформної команди.
• requiredMinimumVersion: на версії нижче оціненої організацією Claude Code не стартує.

Це відправна точка: кожне deny забирає можливості, і баланс залежить від класифікації даних репозиторію. Усі ключі описано в settings reference.

Метрики

• Випереджальна: час очікування на кожному шлюзі. Кожне рішення hook іде в OpenTelemetry з часом і вердиктом.
• Запізніла: порушення шлюзів у production до і після hooks.

Головне: людські шлюзи стають hooks (allow/ask/deny з поясненням маршруту). Обов'язкові з них разом із дозволами, sandbox і allowlist-ами закріплюють у managed settings, які інженер не може вимкнути.

Урок 12. Інтеграція з CI/CD і деплой (CI/CD integration and deployment)

Суть

Claude Code працює неінтерактивно в pipeline і в sandbox, деплой доступний йому через MCP, а rollback відпрацьовують заздалегідь.

Що змінюється

• Традиційно: pipelines детерміновані, а все, що потребує судження (flaky-тест, changelog, причина падіння збірки), чекає людину. Деплой і rollback — runbooks, які виконують під тиском.
• AI-native: Claude робить кроки, що потребують судження, у sandbox з обмеженими обліковими даними. Через MCP той самий workflow, що написав і протестував зміну, випускає й відкочує її в межах шлюзів, заданих для кожного середовища.

Як почати

• Передумови: PR review loop і hooks як approval gates: шлюзи мають з'явитися раніше, ніж автоматизація почне через них щось проганяти.
• Інфраструктура: CI з claude-code-action або runner з claude -p; модель через API чи Bedrock, Foundry, Vertex AI, якщо трафік має лишатися в хмарній угоді; MCP-сервери середовищ; sandbox-профіль без постійних production-облікових даних.

Кроки

• Почати з read-only: claude -p розбирає впалу збірку, підсумовує flaky-тест, пише чернетку changelog.
• Потім кроки із записом за наявними шлюзами: фікс lint, оновлення згенерованої документації, коментарі через @claude. Усе надходить як PR через branch protection, шляху в main немає.
• Агентні jobs працюють у контейнерах під мережевою політикою, з короткоживучими обмеженими токенами і без production-облікових даних за замовчуванням.
• Deploy, status і rollback — MCP-інструменти, окремі для кожного середовища. Повноваження агента задає allowlist, а не shell-скрипт із ключами.
• Автономія залежить від середовища: у dev агент деплоїть вільно, у production лише готує реліз, а авторизує release manager (через hook); staging — посередині.
• Rollback — найвідпрацьованіший шлях: одна команда, доступна агенту й регулярно перевірена на staging. Етап Maintain викликає її при виході за control band.

Приклад

- name: Triage failed build
  if: failure()
  run: >
    claude -p "Read the build log at out/build.log. Identify the most
    likely cause, say whether the failure looks flaky or real, and write a
    three-line summary for the PR thread." >> triage.md

Правило дозволу для MCP називає сервер та інструмент, але не аргументи, тому окремий сервер для кожного середовища — єдиний спосіб відрізнити staging від production в allowlist. У .mcp.json три HTTP-сервери з окремими токенами:

"deploy-staging": {
  "type": "http",
  "url": "https://deploy.example.com/mcp/staging",
  "headers": { "Authorization": "Bearer ${DEPLOY_STAGING_TOKEN}" }
}
// так само deploy-dev (${DEPLOY_DEV_TOKEN}) і deploy-prod (${DEPLOY_PROD_TOKEN})

Інструменти кожного сервера: release (на вході версія, у production ще тікет; повертає ID релізу після завершення розгортання), status (чекає 5 хвилин після релізу й повертає частку 5xx для кожного endpoint), rollback (повертає версію, що знову live). Staging-job на push у main має лише staging-токен, тож інші сервери її відкидають:

- name: Release to staging and roll back if it is unhealthy
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    DEPLOY_STAGING_TOKEN: ${{ secrets.DEPLOY_STAGING_TOKEN }}  # no other environment's token
  run: >
    claude -p "Release version ${{ github.sha }} of the claims portal to staging,
    then call status. If the 5xx rate on any endpoint is over 1%, roll back.
    Finish with three lines for the release notes: what you released, what status
    reported, and whether you rolled back."
    --allowedTools "mcp__deploy-staging__release,mcp__deploy-staging__status,mcp__deploy-staging__rollback"
    --permission-mode dontAsk >> release-notes.md

У dontAsk будь-який виклик, що потребував би підтвердження, відхиляється, і job ніколи не чекає відповіді. Три рівні з hook з уроку 11:

• Dev: allowlist — release, status, rollback; hook дозволяє; схвалення не потрібне.
• Staging: те саме; hook питає або дозволяє з pipeline на main; схвалює інженер або merge.
• Production: allowlist — лише status і rollback. Release проходить тільки з allow від hook, бо dontAsk виконує схвалені hook-ом виклики. Отже production fails closed: якщо hook не спрацював, реліз відхилено. Схвалює release manager через тікет. rollback у списку, бо це заздалегідь схвалений runbook.

Якщо runner має managed settings з allowManagedHooksOnly, hook має бути в managed settings, а з allowManagedMcpServersOnly сервери мають бути в managed allowlist.

Governance

Принцип: агент діє аж до production-шлюзу, але не проходить його. Це забезпечують branch protection (усе — через PR), production-hook (реліз лише з авторизацією названого release manager) і рівні дозволів по середовищах. Неінтерактивні прогони працюють під власною ідентичністю агента, тож лог відділяє його дії від дій інженера, який їх запустив.

Метрики

• Випереджальна: частка падінь pipeline, розібраних без виклику людини.
• Запізнілі: метрики DORA з CI та інструментів деплою.

Головне: у pipeline Claude спершу лише читає, потім пише через PR, а деплоїть через MCP-інструменти окремо для кожного середовища. Production захищений hook-шлюзом і release manager, а rollback відпрацьовано наперед.

Урок 13. Замикання циклу на метриках (Closing the loop on metrics)

Суть

Попередні етапи запускає людина, а етап Maintain працює автономно й headless. Наприклад, агент моніторингу з баг-тікета створює intent.md, і той проходить вимоги, план, розробку, тести й рев'ю. Між етапами стоїть незалежний confidence gate (детермінована перевірка або адверсарний агент-рецензент), який вирішує, пропустити результат далі чи ескалювати людині.

Що змінюється

• Традиційно: супровід реактивний: тікети й інциденти чекають людину. Alert о 3-й ночі можна пропустити, тікет лежить у backlog, дії з post-mortem не доходять до коду через нову пожежу.
• AI-native: тригер (вихід за control band, тікет, повідомлення, розклад) запускає Claude без людини. Claude діагностує, діє лише через шлюзи й записує знахідки як intent.md. Люди сортують і рецензують, але не мусять запускати.

Детермінований скрипт стежить за production і викликає Claude при виході метрики за межі. Інші канали — у розділі про Claude Tag.

Control band

• Норма — середнє погодинних значень за 30 днів, σ — стандартне відхилення. Межі: середнє + 1σ, + 2σ, + 3σ.
• За нормального розподілу вище 1σ потрапляє ~1 з 6 значень, вище 2σ — 1 з 44, вище 3σ — 1 з 740. За 720 вимірювань на місяць самий шум дає ~4 значення на день вище 1σ, ~16 на місяць вище 2σ і ~1 на місяць вище 3σ. Тому 1σ лише логують, а навіть 3σ обмежено шлюзами.
• Правила Western Electric (довідник з контролю якості 1956 року) ловлять повільний дрейф, що може не перетнути 3σ: 4 з 5 останніх значень вище 1σ або 8 поспіль вище середнього.

Як почати

• Передумови: intent.md (структурований вихід циклу), прискорене рев'ю PR, hooks як межа дій, rollback у CI/CD (для найвищого рівня).
• Інфраструктура: сховище метрик (Prometheus, API CI тощо), доступ на читання до репозиторію, неінтерактивний Claude Code в CI або Agent SDK для сервісу, що приймає webhooks.

Кроки

• Власник сервісу чи платформний інженер обирає одну метрику зі стабільною ковзною базою: частка падінь тестів у CI, 5xx після деплою або PR cycle time.
• Скрипт детекції рахує середнє й σ у ковзному вікні та застосовує правила дрейфу. Він версіонований і покритий unit-тестами; детекція повністю детермінована, без моделі.
• Рівні реакції — у версіонованому bands.yaml. 1σ: лише лог. 2σ: Claude діагностує в режимі read-only. 3σ: Claude діє, але лише через PR у шлюз рев'ю або через заздалегідь схвалений runbook. Дрейф прирівнюється до 2σ.
• Тригер — запланований workflow у GitHub/GitLab, webhook від моніторингу або cron усередині мережі. Claude stateless: неінтерактивний крок на CI-runner або сервіс на Agent SDK у sandbox-контейнері. Тому цикл може пройти від початку до кінця без жодної людини.
• Агент пише діагноз як intent.md у форматі етапу Plan (аномалія й докази, бажаний результат, системи, відкриті питання), і далі він іде звичайним pipeline.
• Власник сервісу чи on-call розбирає чергу: виправити зараз, запланувати чи відхилити. Продуктові питання передають product owner. Відхилення допомагають налаштувати межі й зменшити шум.
• Коли фікс випущено, додають eval для інциденту.

Приклад

metric: ci_test_failure_rate
baseline: rolling_30d
rules: western_electric
tiers:
  1sigma: { action: log }
  2sigma: { action: diagnose,
            tools: "Read,Grep,Bash(gh run view *)" }
  3sigma: { action: propose,
            routes: [pull_request, runbook:rollback-deploy] }

Для production-метрики змінюється лише перший рядок: metric: status_5xx_rate.

Скрипт детекції — 33 рядки Python на стандартній бібліотеці. Він читає зі stdin JSON-список погодинних значень за 30 днів, рахує середнє й σ без останнього значення і друкує найгірший рівень для нього. MIN_SIGMA = 0.01 (в одиницях метрики) не дає пласкій базі перетворювати кожен сплеск на тривогу. Потрібно щонайменше 24 значення бази. Правила від найгіршого: вище 3σ → 3sigma; вище 2σ, 4 з 5 вище 1σ або 8 поспіль вище середнього → 2sigma; вище 1σ → 1sigma. Для частки помилок важлива лише верхня межа.

def above(readings, line, need, out_of):
    """True if at least `need` of the last `out_of` readings sit above `line`."""
    return sum(r > line for r in readings[-out_of:]) >= need

Щогодинна job знаходить рівень у bands.yaml і запускає Claude з відповідними інструментами. Для propose allowlist містить gh pr create і одну команду запуску runbook.

Сценарій: реліз о 13:52 обнуляє 60-секундний кеш панелі, і кожен перегляд іде в claims-core (50 запитів/с), який починає відмовляти. О 14:00:

{"tier": "3sigma", "rule": "reading above 3 sigma", "reading": 1.9, "mean": 0.2, "sigma": 0.02}

Рівень propose, і реліз вийшов перед стрибком, тож агент запускає схвалений runbook rollback-deploy і пише intent.md:

# Intent: status endpoint 5xx after release 4f2c9e1
Author: monitoring agent (status_5xx_rate, 3 sigma). Status: draft.
## Problem
The 5xx rate on GET /claims/{id}/status read 1.9% at 14:00. The 30-day mean is 0.2%.
Release 4f2c9e1 went out at 13:52. It changes CACHE_SECONDS in StatusPanel.tsx from 60 to 0.
With no cache, every page view reaches claims-core, which allows 50 requests a second (CLAUDE.md).
## Proposed outcome
Customers get fresher status without the portal passing the claims-core limit.
## Constraints
The panel's spec.md allows status to be up to 60 seconds old (R4). The claims-core limit is fixed.
## Action already taken
Ran the rollback-deploy runbook at 14:02. It reported version 8c41d07 live again at 14:04.
## Open questions
Who asked for live status, and is 60 seconds too slow for them?

Після фіксу з'являється eval status-panel-keeps-its-cache: from: "4f2c9e1~1", промпт «клієнти кажуть, що панель статусу застаріла, зроби її живою», may_change — claims-api/routes, claims-api/tests, portal/src. Перевірки: make test, make lint і

grep -Eq 'CACHE_SECONDS = [1-9]' portal/src/claims/StatusPanel.tsx

Governance

Межі рівнів задає версіонований конфіг. Дозволи й managed settings закривають доступ до production. Виклики, знахідки й рішення розбору логуються з часом. Знахідки схвалює власник сервісу, зміни йдуть через звичайне рев'ю PR, а runbooks агента схвалено заздалегідь.

Метрики

• Випереджальна: час від виходу за межі до intent.md у черзі (з логу детекції) проти старого «від інциденту до дій із post-mortem».
• Запізнілі: частка знахідок, що стали змердженими фіксами, і повторні інциденти того самого класу; їх має ставати менше завдяки новим evals.

Приклади

• CI test failure rate вище 3σ: агент ставить flaky-тест на карантин або відкриває revert PR, рішення за шлюзом рев'ю.
• 5xx після деплою вище 3σ з деплоєм у вікні: агент запускає наявний rollback pipeline.
• Дрейф PR cycle time: агент пише звіт для керівництва. Механізм працює й для процесних метрик.

Claude на чергуванні з Claude Tag

Інциденти приходять і через Slack чи Microsoft Teams, наприклад термінове повідомлення о 22:00 у каналі інцидентів. Claude Tag (public beta, наразі в Slack) додає Claude в канали під власною ідентичністю, тож кожен інцидент одразу отримує first responder, а реакція стає частиною циклу й пам'яті.

• Розмова й знання лишаються в каналі. Будь-хто може скеровувати реакцію, перевіряти гіпотези й досліджувати варіанти, а історія каналу додає аудитованості.
• Через MCP Claude перевіряє, що метрика повернулася до норми, підтверджує це в треді й записує post-mortem у версіонований файл уроків для майбутніх розслідувань.
• Claude Tag бере не лише інциденти: якщо Claude позначили на тікеті через MCP або спитали в каналі, він так само сортує роботу. Невеликий чіткий фікс приходить як PR через рев'ю, більше завдання — як intent.md для етапу Plan, і цикл живить сам себе.

Головне: детермінований скрипт із control bands визначає рівень реакції: лог, read-only діагноз або дія лише через PR чи схвалений runbook. Claude перетворює кожну аномалію на intent.md і новий eval, тож цикл запускається без людини, але проходить людські шлюзи.

Урок 14. Підсумки та ресурси (Closing thoughts and resources)

Підсумки

Сучасні моделі й harness-и дозволяють трансформувати весь SDLC, а не лише написання коду. Людське судження лишається в центрі, і враховано вимоги governance й регулювання великих підприємств. Playbook узагальнює практики, які команда Applied AI авторів курсу щодня застосовує з клієнтами.

Ресурси для платформної команди

Документація приблизно в порядку розгортання контролів:

• Set up Claude Code for your organization — карта рішень для адміністратора, з неї варто починати;
• Settings reference і пріоритети налаштувань, усі managed-only ключі;
• Server-managed settings з admin console;
• Permissions;
• Sandboxing (ізоляція файлової системи й мережі на рівні ОС);
• Hooks guide і hooks reference;
• Skills;
• Plugins and private marketplaces (поширення skills і hooks на організацію);
• Managed MCP (централізований контроль інструментів агента);
• Enterprise deployment overview (Bedrock, Vertex AI, Microsoft Foundry);
• Enterprise network configuration;
• Monitoring (OpenTelemetry) і analytics dashboard;
• Compliance API (журнал активності, отримання й видалення чатів);
• Security model.

Головне: AI-native SDLC змінює весь життєвий цикл, а людське судження й governance лишаються в центрі. Контролі розгортають, починаючи з admin decision map.