Коли команда впроваджує agentic-інструмент для кодингу, розмова, схоже, неминуча. «Я ж записав це в CLAUDE.md — чому він усе одно так зробив?» Зазвичай відповідь така: файл розрісся, і його вже ніхто не читає. Можливо, так і є, але це не зачіпає справжньої проблеми.
Справжня проблема в тому, що інструмент дає кілька різних способів steering, і вони не взаємозамінні. Memory-файл, skill, hook і subagent різняться тим, коли вони завантажуються, скільки контексту коштують, чи переживають compaction і — найважливіше — чи є вони порадою, чи гарантією. Покладіть інструкцію не туди — і її або проігнорують, або вона з’їдатиме контекст на кожному ході, або тихо зникне посеред довгої сесії.
Нещодавно Anthropic опублікувала коротку, щільну статтю саме про це: Steering Claude Code: skills, hooks, rules, subagents and more. Цей пост — мій інженерський синтез із неї та з пов’язаних статей про CLAUDE.md, hooks, skills і subagents, з моїми власними думками про те, де кожен механізм виправдовує своє місце. Він доповнює пост про AI-native SDLC, який дивиться на весь delivery-цикл; тут ми наближаємося до самого harness.
Одне питання, яке все сортує
Питання, яке я ставлю до будь-якої порції guidance:
Це знання, процедура, гарантія чи окрема робота?
- Знання — факти, потрібні агентові майже завжди: команди збірки, структура директорій, угоди про іменування. Це memory-файл.
- Процедура — багатокроковий «як ми робимо X», важливий інколи: release-чеклист, рецепт міграції, security review. Це skill.
- Гарантія — те, що має статися (або не має статися ніколи) незалежно від рішення моделі: форматування, блокування записів у захищені шляхи, відмова завершувати роботу, поки падають тести. Це hook (плюс permissions).
- Окрема робота — робота, чий проміжний безлад ви не хочете бачити в основній розмові: прочитати сорок файлів заради однієї відповіді, неупереджений review, аналіз логів. Це subagent.
Більшість помилок steering — це категорійні помилки між цими чотирма. Розгляньмо їх по черзі.
CLAUDE.md: завжди ввімкнена мапа
Файл проєктної пам’яті завантажується на початку кожної сесії й залишається там. У цьому і його сила, і його ціна. Усе, що в ньому є, конкурує за увагу на кожному ході, зокрема й на тих, де воно нерелевантне.
Туди належить те, що компетентному новачкові потрібно в перший день і про що він інакше питав би знову й знову: як збирати й тестувати, де що лежить, угоди, неочевидні з коду, і специфічні для проєкту пастки. Стаття про CLAUDE.md формулює це добре: кожен рядок має існувати, бо виправив реальну проблему, яку ви справді зустріли, а не гіпотетичну. Steering-стаття дає конкретну стелю: тримайте кореневий файл до 200 рядків, призначте йому власника і рев’юйте зміни в ньому як код.
Хороший кореневий файл читається як стисла нотатка для онбордингу:
# CLAUDE.md
## Commands
- `npm run dev` — local server on :4321
- `npm run check` — lint + types + i18n parity. Must pass before commit.
## Layout
- App lives in `src/`, not the repo root. Content in `src/src/content/`.
## Conventions
- Every new UI string goes into all four locale files.
- Never construct canonical URLs from the request URL.Те, що легко пропустити:
- Файли в піддиректоріях завантажуються ліниво. CLAUDE.md усередині піддиректорії завантажується лише тоді, коли агент читає файл із цієї директорії. Це робить його дешевим — і водночас означає, що після compaction він може випасти, доки до директорії не звернуться знову. У monorepo так кожна команда отримує власні угоди, не обтяжуючи сесії всіх інших.
- Особисті вподобання не належать у проєктний файл. Ваш улюблений тон комітів чи примхи редактора йдуть у файл на рівні користувача. Проєктний файл — для командних угод, специфічних для цієї кодової бази.
- Жодних секретів, ніколи. Він стає частиною системного промпту; ставтеся до нього як до потенційно публічного.
Rules: CLAUDE.md зі scope
Файли rules у .claude/rules/ — міст між «завжди завантажено» і «завантажено, коли релевантно». Без scope правило поводиться як ще один CLAUDE.md. Додайте поле paths — і воно завантажується лише тоді, коли агент торкається файлів, що збігаються:
---
paths:
- "src/api/**"
---
All API handlers validate input with Zod before any processing.Це правильний дім для наскрізних обмежень, що стосуються частини кодової бази — API-хендлерів, міграцій, згенерованих клієнтів — і були б шумом усюди більше. Path-специфічне правило без path scope — один із найдешевших для виправлення антипатернів.
Skills: процедури за запитом
Skill — це папка з SKILL.md у корені: назва, опис і тіло з інструкціями, плюс, за бажання, скрипти, шаблони та довідкові файли. Ключовий механізм — progressive disclosure: наперед у контексті лежать лише назва й опис; тіло завантажується, коли skill викликають (slash-командою або тому, що агент зіставив опис із завданням), а додаткові файли — лише якщо на них посилаються інструкції. Explainer про skills оцінює вартість метаданих приблизно в 100 токенів на skill, а повних інструкцій — менш ніж у 5k токенів, тому ви можете мати їх багато, не забиваючи вікно.
---
name: release-checklist
description: Use when preparing a release or tagging a version. Bumps
the version, updates CHANGELOG, runs the full check suite, drafts notes.
---
1. Confirm the working tree is clean and on main.
2. Run `npm run check`; stop and report on any failure.
3. ...Дві речі в цьому файлі важать більше за все інше:
- Опис — це тригер. Це єдина частина, яку агент бачить, перш ніж вирішити, чи завантажувати skill. Пишіть його як «що він робить і коли використовувати», словами, які люди справді друкують. Розмитий опис означає, що skill ніколи не спрацьовує або спрацьовує на все.
- Тіло — це процедура, а не есе. Нумеровані кроки, явні умови зупинки, посилання на скрипти для всього детермінованого. Якщо крок — «запусти цю точну команду», покладіть команду в скрипт, який викликає skill, а не сподівайтеся, що модель її відтворить.
Евристика зі steering-статті — та, якою я користуюся найчастіше: якщо ви знайшли в CLAUDE.md 30-рядкову процедуру, це skill, якого ще не витягли. Він платить повну контекстну оренду на кожному ході, щоб бути корисним на кількох.
Skills також комбінуються з конекторами: MCP дає агентові доступ до вашого issue tracker, а skill каже, як ваша команда робить triage.
Hooks: єдине, що справді гарантоване
Ось рядок, який я підкреслив би в усій темі. Усе вищеописане — CLAUDE.md, rules, skills — дорадче. Модель це читає і, зазвичай, виконує. «Зазвичай» годиться для угод. Воно не годиться для «ніколи не пиши в migrations/ без погодження» чи «завжди запускай formatter».
Hooks — інші за своєю природою. Це handlers, зареєстровані в settings, що спрацьовують на lifecycle-події: перед запуском інструмента, після нього, при старті сесії, коли агент намагається зупинитися, перед compaction тощо. Command-, HTTP- та MCP-tool-hooks виконуються детерміновано: жодного судження моделі. PreToolUse hook, що завершується з кодом 2, блокує виклик інструмента, а його stderr повертається агентові, щоб він зрозумів чому.
Мінімальний hook «форматуй після кожної правки» в .claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh" }
]
}
]
}
}Скрипт читає вхід інструмента як JSON зі stdin, дістає шлях до файлу й запускає ваш formatter. Форматування більше не те, що агент, можливо, згадає; воно просто відбувається.
Steering-стаття формулює правило прямо: інструкція — це не guardrail. Якщо ваш CLAUDE.md каже «завжди роби Y після X» — це hook. Якщо каже «ніколи не роби Z» — це hook або permission-правило, а для політик усієї організації — managed settings, які окремі користувачі не можуть перевизначити локально.
Кілька застережень із гайда про hooks, які я вважаю безумовними:
- Hooks працюють з вашими правами користувача. Це довільний shell. Рев’юйте їх як продакшен-код, беріть змінні в лапки, використовуйте абсолютні шляхи до скриптів і санітизуйте те, що приходить зі stdin.
- Matchers чутливі до регістру.
bashне збігається з інструментомBash. Це той тип багу, через який guardrail мовчки не існує. - Не кожен hook детермінований. Hooks типів prompt і agent використовують судження моделі. Корисно, але не плутайте їх із enforcement.
- Почніть з одного. Гайд радить formatter: низький ризик, негайна віддача.
Subagents: окремий контекст для окремої роботи
Subagent — це ізольований екземпляр агента з власним контекстним вікном, власним системним промптом і власними правами на інструменти. Він стартує без історії вашої розмови, виконує роботу й повертає лише своє фінальне повідомлення. Ця ізоляція — і є вся суть.
Кастомні subagents живуть у .claude/agents/ (проєкт) або ~/.claude/agents/ (особисті) як Markdown із frontmatter:
---
name: security-reviewer
description: Reviews a diff for security issues before commit. Use after
implementation, before opening a PR.
tools: Read, Grep, Glob
---
You are a security reviewer. You do not edit files. Report findings
by severity with file and line, and say explicitly if you found none.Зверніть увагу, що тут працює: read-only список інструментів (він не може «з добрих намірів» щось виправити) та опис, який каже, коли делегувати, бо саме цей опис керує автоматичним делегуванням.
Стаття про subagents пропонує емпіричне правило, яке я вважаю по-справжньому корисним: якщо завдання означає дослідження десяти чи більше файлів або у вас три чи більше незалежних шматків роботи, це сильний сигнал делегувати. Інші сильні випадки — свіжий погляд (reviewer, який не бачив ваших відхилень під час дебагу) і верифікація перед комітом.
Не менш корисно знати, коли не делегувати: послідовна робота, де кожному кроку потрібен повний вивід попереднього; паралельні правки одного файлу; малі завдання, де накладні витрати на делегування перевищують виграш; та агенти, яким потрібно розмовляти між собою. Кожен subagent спалює власні токени — економіка токенів fan-out’у реальна.
Розрізнення skill і subagent зі steering-статті — найчіткіше з тих, що я бачив: використовуйте subagent, коли проміжні результати засмічували б вашу розмову; використовуйте skill, коли хочете бачити й спрямовувати кожен крок.
Таблиця вибору
Ось усе на одному екрані. Колонки про завантаження та compaction — зі steering-статті; колонка «для чого» — моя конденсація.
| Механізм | Завантажується | Після compaction | Дорадчий чи примусовий | Для чого |
|---|---|---|---|---|
| Кореневий CLAUDE.md | На старті сесії | Перечитується | Дорадчий | Команди, структура, угоди першого дня |
| CLAUDE.md у піддиректорії | Коли читають цю директорію | Втрачається, доки не торкнуться знову | Дорадчий | Угоди на рівні пакета чи команди |
| Rule зі scope за шляхом | Коли торкаються файлів, що збігаються | Інжектується повторно | Дорадчий | Обмеження для частини кодової бази |
| Skill | Опис на старті, тіло при виклику | Інжектується повторно в межах спільного бюджету | Дорадчий | Процедури, потрібні інколи |
| Subagent | Опис на старті, тіло при виклику | Повертається лише summary | Дорадчий (інструменти примусові) | Ізольовані, шумні чи паралельні side-завдання |
| Hook | На lifecycle-подіях | Обходить compaction | Примусовий (типи command/HTTP/MCP) | Те, що має статися, і те, що не має статися ніколи |
| Permissions / managed settings | Завжди | н/д | Примусові | Жорсткі межі, політика всієї організації |
Steering-стаття також розглядає output styles і дописування до системного промпту. Я вважав би обидва рідкісними інструментами: кастомний output style замінює стандартні інструкції для софтверної інженерії, якщо ви явно їх не збережете, а дотримання доданих інструкцій падає, чим більше їх накопичується. Якщо ви тягнетеся до них, щоб виправити проблему з угодами кодингу, майже завжди кращий дім — один із механізмів вище.
Найпоширеніші антипатерни
Більшість із них — одна й та сама помилка, категорійна, в різному вбранні.
- Правила «ніколи» в прозі. «Ніколи не редагуй згенеровані файли» в CLAUDE.md — це надія.
PreToolUsehook на згенерованому шляху — це факт. - CLAUDE.md розміром із роман. Процедури, історія, обґрунтування та кожен коли-небудь засвоєний урок — усе завантажується на кожному ході. Витягніть процедури в skills, path-специфічні шматки — у rules зі scope, а все, що більше не виправляє реальної проблеми, видаліть.
- Rules без scope. Правило про міграції бази даних, що завантажується, поки хтось правит CSS.
- Subagent на все. Стаття про subagents прямо каже, що забагато кастомних агентів робить автоматичне делегування менш надійним; більшості команд вистачає жменьки добре окреслених.
- Розмите делегування. «Дослідити кодову базу» — це не завдання. «Знайти кожне місце виклику
X, перелічити файл і рядок, не редагувати» — завдання. - Skills із розмитими описами. Якщо опис не каже коли, агент не може вирішити, чи завантажувати його.
- Особисті вподобання в командному файлі. Тепер сесії всіх несуть смак однієї людини.
- Автоматизація до того, як патерн зрозумілий. Написання hooks і агентів для workflow, який ніхто ще не робив руками тричі. Починайте розмовно; кодифікуйте, коли знаєте, що саме кодифікуєте.
Де я був би обережним
- Це специфіка продукту, і вона рухається. Назви файлів, назви подій, поля frontmatter і цифри токенів тут узято зі статей Anthropic на момент написання, і вони змінюватимуться. Патерн — завжди ввімкнена пам’ять, scoped rules, процедури за запитом, детерміновані hooks, ізольовані воркери — це довговічна частина. В інших інструментів є власні аналоги (файл
AGENTS.md, rule-файли для конкретних редакторів тощо); я б зіставляв категорії, а не припускав, що семантика збігається один до одного. - Дорадчість не марна. «Skills радять, hooks примушують» можна перевчити до «важать лише hooks». Більшість того, що робить агента хорошим на вашій кодовій базі, — це знання й процедура, які можуть бути тільки дорадчими. Hooks — це страховка, а не стратегія.
- Hooks — це код з вашими правами. Погано написаний hook — нова поверхня атаки, а конфіг hook, доданий колегою, — це код, який ви ось-ось запустите. Рев’юйте відповідно.
- Ваш harness регресує. Кожна правка CLAUDE.md, skill чи hook змінює поведінку агента. Без якоїсь форми evals на реальних завданнях ви налаштовуєте на відчуттях. І все це, як і раніше, context engineering — механізми лише різні відповіді на питання, коли модель бачить що.
Як би я це впроваджував
Якби я налаштовував команду з нуля, то в такому порядку:
- Спершу CLAUDE.md. Запустіть
/init, а потім жорстко скоротіть: команди, структура, неочевидні угоди. Призначте власника. Робоче правило: коли агент двічі робить ту саму помилку, додайте виправлення — один рядок. - Один hook.
PostToolUseformatter. ПотімPreToolUse-блокування на шляхи, яких не можна торкатися без людини. Підвищте кожне речення «ніколи» з CLAUDE.md до hook або permission. - Задайте scope для часткового. Перенесіть path-специфічні угоди в rules із
paths, а угоди на рівні пакета — у файли в піддиректоріях. - Витягніть перші skills. Шукайте процедури, які ви постійно вставляєте або які роздувають CLAUDE.md, — release, міграція, опис PR. Пишіть стислі описи. Два-три хороші skills краще за двадцять спекулятивних.
- Додайте два-три subagents. Read-only дослідник, read-only reviewer, можливо, verifier, який запускає застосунок і звітує без виправлень. Використовуйте їх розмовно, перш ніж покладатися на автоматичне делегування.
- Запакуйте й керуйте. Коли налаштування стабільне, зберіть skills, агентів і hooks у plugin, щоб команда ділила одну версію, а обов’язкову політику перенесіть у managed settings.
Кар’єрний ракурс
Тут тихо виникає нова навичка: проєктування harness. Це не написання промптів. Це ближче до platform engineering — вирішувати, яке знання є ambient, яке за запитом, яке примусове, а яке працює в ізоляції, а потім тримати цю конфігурацію під рев’ю, у версіонуванні й під тестами, як будь-який інший код. Люди, які в цьому добрі, покращують агентські сесії всім довкола, а оскільки навичка про категорії, а не про синтаксис, вона переноситься на будь-який наступний інструмент.
Глибше
Якщо хочете попрактикуватися на реальній кодовій базі, Claude Code Mastery практично розбирає щоденний цикл і повний steering-інструментарій — memory-файли, skills, hooks і subagents. AI-Native SDLC поміщає цей harness у кероване delivery-життя, з evals на самій конфігурації агента. Для висхідної дисципліни, яка змушує все це працювати краще, дивіться Spec-Driven Development Foundations і OpenSpec Mastery. А якщо хочете будувати власних агентів на тих самих примітивах, наступний крок — Claude Agent SDK.
Джерела: Anthropic, Steering Claude Code: skills, hooks, rules, subagents and more; Using CLAUDE.md files; How to configure hooks; Skills explained; The complete guide to building skills for Claude; Subagents in Claude Code. Цей пост — незалежний коментар; деталі продукту могли змінитися після публікації, тож звіряйтеся з першоджерелами. Пов’язане в цій серії: AI-native SDLC, context engineering, evals, Claude Code у продакшені.
