Claude Code — Best Practices
Привіт!
Тут раніше лежала стаття про практики роботи з Cursor. Я її переписав.
Річ не в тім, що Cursor став гіршим. Змінився сам спосіб роботи: агент більше не «розумне автодоповнення», а виконавець, якому ви готуєте робоче місце, і від того, наскільки добре це місце підготовлено, результат залежить куди сильніше, ніж від того, як гарно ви сформулювали запит. Тільки готувати — не означає описувати все підряд: код сучасна модель прочитає сама, і швидше, ніж ви б його переказали. Записувати варто те, чого в коді немає.
Далі — про Claude Code. Що покласти в репозиторій, як планувати роботу, як не спалити контекст і гроші. Приклади взято з робочого проєкту, де все це налаштовано й обкатано на кількох місяцях реальної розробки; числа теж звідти, а не з голови. Знімок проєкту зроблено в серпні 2026 року, а що в ньому змінилося за наступні три місяці і чому — у розділі «Три місяці по тому».
Контекст: не стіна, а ціна
У моделі є контекстне вікно, і в нього вміщується вся сесія цілком: ваші повідомлення, кожен прочитаний файл, виведення кожної команди, зокрема той трьохсотрядковий лог, який агент вивів один раз і більше до нього не повертався. Одне налагодження легко з'їдає десятки тисяч токенів.
Ще нещодавно це був головний обмежувач. Тепер у більшості моделей вікно на мільйон токенів, а перед його заповненням Claude Code сам стискає історію, тож упертися в стіну вдається рідко. В офіційних рекомендаціях Anthropic порада «контекстне вікно — головний обмежувач, економте його агресивно» тепер значиться серед застарілих.
Але як ціна контекст нікуди не подівся. Кожен запит надсилає моделі всю розмову заново: поки кеш теплий — зі знижкою, після паузи — за повною ціною (на підписці кеш живе близько години, за API-ключем п'ять хвилин). Сесія, у якій лежать три незв'язані завдання, на кожному ході четвертого перечитує всі три. І як шум теж: дві невдалі спроби, що лишилися в історії, модель перечитує разом з вдалою, а домовленість, дана лише в чаті, може не пережити стиснення.
Звідси висновок, з якого росте все інше. Контекстом і далі треба керувати свідомо: вирішувати, що туди потрапить, а що ні. Тільки тепер заради ціни й фокусу, а не зі страху, що вікно скінчиться.
Дайте агентові спосіб перевірити себе
Це перше, що варто налаштувати, і це ж найчастіше пропускають.
Агент зупиняється, коли робота має вигляд зробленої. Якщо перевірити її нічим, «має вигляд» — єдиний доступний сигнал, і перевіряльником стаєте ви. Кожна помилка чекає, поки ви її помітите.
Дайте щось з однозначним «пройшло / не пройшло», і цикл замкнеться сам. Агент править, запускає перевірку, читає результат, повторює. Перевіркою може бути набір тестів, код повернення збірки, лінтер, скрипт порівняння з еталоном, скріншот для звірки з макетом.
Різниця видно просто у формулюванні завдання:
✗ зроби функцію валідації email
✓ зроби функцію валідації email. Приклади: user@example.com — правильно, invalid — ні, user@.com — ні. Після реалізації запусти тести і покажи виведення
✗ збірка падає
✓ збірка падає ось із цим: [текст помилки]. Виправ причину, а не симптом, і переконайся, що збірка проходитьУ мене в проєкті перевірка вшита в правило про коміт: перед комітом обов'язково проганяються перевірка типів, збірка і два валідатори контенту. Не «бажано», а обов'язково, зі вказівкою, що результат перевірок іде у звіт справжнім, а не «начебто все зелено».
Наскільки жорстко тримати перевірку, вирішуєте ви, і щаблів тепер чотири. У запиті: «прожени тести auth і продовжуй, доки не пройдуть» — коли досить, агент вирішує сам. Ціллю: /goal задає умову, яку після кожного ходу звіряє з розмовою окрема модель, і агент працює, доки її не виконано; це потрібно здебільшого для довгих фонових прогонів, де він інколи закінчує хід звітом про прогрес, хоча пункти ще відкриті. Хуком Stop: ваш скрипт запускається щоразу, коли агент намагається закінчити хід, і код виходу 2 повертає його до роботи. Це тримає вже сам Claude Code, а не модель. І чужими очима: /code-review перевіряє diff у свіжому підагенті, який не бачив вашої розмови й не заражений міркуваннями, з яких виріс код.
Для того, чого тести й перевірка типів не ловлять, є /verify: агент збирає й запускає сам застосунок і дивиться на результат.
І просіть показувати доказ: виведення тестів, саму команду, скріншот. Прочитати доказ швидше, ніж переперевіряти руками. А для сесії, за якою ви не стежили, це взагалі єдиний спосіб зрозуміти, що сталося.
Спершу розвідка, потім план, потім код
Якщо одразу просити код, отримаєте охайне розв'язання не того завдання.
У Claude Code є окремий режим планування — Shift+Tab або /plan перед одним запитом: агент читає файли, запускає команди для розвідки й пише план, але вихідний код не чіпає. Робочий цикл виходить такий: розібратися в потрібній частині коду → скласти план → схвалити його, і режим вимкнеться сам → реалізувати → коміт.
План читайте очима. Це найдешевша точка втручання: виправити абзац плану — хвилина, переробити реалізацію — пів години.
Для великого завдання добре працює прийом «хай агент вас проінтерв'ює». Описуєте ідею одним абзацом і просите ставити питання: про реалізацію, про межові випадки, про те, чого ви могли не врахувати. Наприкінці — записати специфікацію у файл. Далі нова сесія з чистим контекстом і прохання реалізувати за цією специфікацією.
Хочу зробити [одне речення про фічу]. Проінтерв'юй мене докладно,через інструмент питань.
Питай про реалізацію, інтерфейс, межові випадки, ризики й розміни.Очевидного не питай, копай у складні місця, які я міг не врахувати.
Коли закінчимо — запиши повну специфікацію у SPEC.md.Тільки не перетворюйте це на ритуал. Якщо правку можна описати одним реченням, план не потрібен: зайве коло коштує дорожче, ніж користь від нього. Для зрозумілого завдання зазвичай вистачає першого ж простого запиту: потрібний код агент прочитає сам.
Три рівні налаштування
Знання агентові передається трьома способами, і вони не взаємозамінні.
Інструкції проєкту читаються на початку кожної сесії. Сюди йдуть факти, потрібні завжди: як зібрати, як запустити тести, чим цей проєкт відрізняється від типового. Рекомендація Anthropic — триматися в межах двохсот рядків, і це не формальність. Що довший файл, то гірше дотримуються його ж вказівок.
Хороший тест для кожного рядка: якщо це прибрати, агент почне помилятися? Ні — прибирайте. В Anthropic тест іще суворіший: чи може агент знайти це, прочитавши код, і чи піде він дивитися? Якщо обидві відповіді «так», рядок зайвий. Тому описувати в інструкціях архітектуру й розкладку папок більше нема чого: репозиторій агент прочитає сам, і швидше, ніж ви поясните. Потрібне те, чого в коді немає: рішення, ухвалене на дзвінку, процес деплою, що живе в голові однієї людини, змінна середовища для інтеграційних тестів, місце, де код оманливий.
Початкову версію файлу збере /init, далі робота здебільшого у викреслюванні. А /doctor prompt-audit проходить інструкціями, правилами й скілами і шукає вказівки, написані під старі моделі, посилання на неіснуючі файли та суперечності між файлами; правки він пропонує, але без запиту нічого не змінює.
Правила лежать окремими файлами в каталозі правил, по файлу на тему, і завантажуються так само. Їх можна обмежити масками шляхів, і тоді правило підтягнеться лише коли агент чіпає відповідні файли:
---paths: - "src/api/**/*.ts" - "apps/backend/**/*.ts"---
# Правила для API
- Кожен ендпоїнт валідує вхід, без винятків.- Помилки віддаються в спільному форматі з `ErrorResponse`.- Новий ендпоїнт спершу описується в api.md, потім пишеться код.Правило з масками підтягується, коли агент читає або править відповідний файл. Нюанс, про який легко не знати: під час стиснення контексту таке правило йде разом з історією і повернеться, лише коли агент знову торкнеться відповідного файлу. Правила без масок і кореневий файл інструкцій після стиснення перечитуються з диска.
Скіли — знання на вимогу. Каталог із файлом усередині; тіло потрапляє в контекст лише тоді, коли завдання йому відповідає або коли ви викликали скіл самі. Тому великі довідники мають бути скілами: у сплячому стані від них у контексті лише ім'я та опис. А процедуру з побічними ефектами, на кшталт випуску релізу, варто позначити disable-model-invocation: true: тоді сам агент її не запустить, лише ви командою /ім'я, і в переліку вона місця не займає.
Розкладка, якою користуюся я:
- факт, потрібний завжди → інструкції проєкту;
- обов'язкова поведінка → правило;
- процедура або довідник, потрібні інколи → скіл;
- те, що зобов'язане відбуватися (або не відбуватися) завжди, без участі моделі → хук або заборона в налаштуваннях дозволів.
Останній пункт стоїть осібно. Усе, що вище, — текст, який модель читає і зазвичай виконує. Хук — код, який виконається незалежно від її рішення. Критична поведінка має бути хуком, а не абзацом в інструкціях. Зворотне теж правда: хук на те, що насправді вподобання, шкідливий. У вподобань бувають винятки, і модель, маючи перед собою код, зазвичай краще розсудить, чи підходить правило до випадку, ніж ви, написавши його заздалегідь. Anthropic радить тримати набір жорстких заборон маленьким: якщо їх набралося під сорок, більшість — смаківщина. Розбір хуків з усіма подіями та робочими прикладами в мене в окремій статті.
І все це — промпти
Думка, до якої я дійшов не одразу, а варто було б від самого початку.
Інструкції проєкту, правила, скіли, описи підагентів — це не конфігурація. Це системні промпти, які хтось (ви) пише один раз, а модель читає в кожній сесії. Різниця між «агент постійно робить не те» і «агент працює передбачувано» дуже часто виявляється різницею між недбало й акуратно написаним промптом.
Що з технік промпт-інжинірингу справді окупається в цих файлах:
- Структура та роздільники. Заголовки, переліки, явні блоки: модель розбирає структурований текст надійніше за суцільну прозу, а ви дістаєте змогу послатися на конкретний шматок з іншого правила. Докладніше про роздільники та структуру промпта.
- Ієрархія правил. Коли правил більше п'яти, вони починають конфліктувати, і треба прямо написати, яке з них головніше. У мене, наприклад, правило «не комітити без прохання» стоїть вище за правило про перевірку перед комітом, і в тексті це сказано словами, а не мається на увазі. Про те, як задавати ієрархію правил, є окремий розділ.
- Позитивні формулювання замість заборон. «Залиш зміни в робочому дереві й розкажи, що зробив» працює краще, ніж «не коміть». Самі лише заборони залишають модель без зразка поведінки.
- Спокійний тон замість крику. IMPORTANT і великі літери були потрібні старим моделям. Нинішні дотримуються спокійно сформульованого рядка, а від натиску починають застосовувати правило надто широко, і там, де воно не підходить.
- Приклади замість описів. Пара «так погано / так добре» у правилі варта трьох абзаців пояснення. Це звичайний few-shot, просто застосований до конфігурації проєкту.
- Явний формат відповіді. Якщо ви хочете певну форму звіту, її треба описати, а краще показати. Про контроль формату відповіді — там само.
- Економія контексту. Кожен рядок інструкцій і правил оплачується в кожній сесії, тому зайве слово тут дорожче, ніж у звичайному промпті. Це рівно те, що в статті про промпти зветься контекст-інжинірингом.
Ще одне спостереження з практики: описувати треба не лише що робити, а й яку помилку правило запобігає. Модель, яка розуміє, від чого її страхують, набагато краще застосовує правило до ситуації, не описаної дослівно. Половина моїх правил тому починається з абзацу «відомий сценарій провалу має такий вигляд».
Повний розбір технік — у статті про промпт-інжиніринг; далі за текстом я посилатимуся на конкретні розділи звідти.
Як це виглядає на живому проєкті
Далі показую на робочому репозиторії в тому вигляді, у якому він був у серпні 2026 року: дев'ять правил, довідник з API, сто два скіли й трекер завдань просто в проєкті. Усе це виросло не одразу, а із ситуацій, коли те саме доводилося пояснювати втретє.
Правила
Правило — те, що агент зобов'язаний дотримувати завжди. Кожне лежить окремим файлом і закінчується чек-листом: за ним видно, дотримано його чи ні.
Ось як має вигляд правило цілком, найкоротше з моїх:
# Жодних комітів, доки не попросили
**Не запускати `git commit` (а також push, PR, merge), доки користувачне попросив про це прямо, своїми словами.**Закінчена робота, зелена збірка й відчуття «начебто готово» дозволомне є.
Зробив правки — залиш їх у робочому дереві, коротко розкажи, що змінилося,і зупинися. Сумніваєшся, просили чи ні, — не коміть, запитай.
## Чек-лист
- [ ] Жодного коміту, push чи PR без явного прохання своїми словами.- [ ] Роботу залишено в робочому дереві, зміни описано.- [ ] За сумніву поставлено питання, а не зроблено коміт.Має вигляд перебору. До першого разу, коли агент вирішує, що раз тести зелені, то можна й закомітити, і забирає в історію ваші недороблені експерименти.
Далі пройдуся рештою восьми. Оригінали в мене написані англійською (так історично склалося, правила переїжджали між проєктами), тому цитати наводжу в перекладі.
Перевірка перед комітом
Найдовше правило, набуває чинності коли коміт таки попросили. Чотири стадії: прочитати весь diff шматками; розібрати все, чого зміни стосуються поза межами diff, тобто код, що викликає, контракти й документацію, яка від цих правок щойно застаріла; пополювати на дефекти; винести вердикт.
Вердиктів рівно три, і написані вони так, щоб агентові не було куди викрутитися:
PASS — не знайдено нічого, або все знайдене вже виправлено й переперевірено.
FIX, ПОТІМ PASS — є справжні, але полагоджувані знахідки. Лагодь їх сам, негайно, прожени перевірку заново по виправленому стану і чесно розкажи розробникові, що знайшов і що полагодив. Лагодити — поведінка за замовчуванням: проблеми ніколи не «лишають на потім» і ніколи не обмежуються згадкою у звіті.
STOP — серйозна проблема (втрата даних, діра в безпеці, зламаний контракт, зміна суперечить власній вимозі) або справжня розвилка, де обидві конструкції захисні і вибір належить розробникові. Коміту немає. Поясни просто й конкретно, у чому проблема.Далі йде фраза, яку я вважаю найкориснішою в усьому правилі: виправлення, зроблене під час перевірки, само є зміною і проходить ті самі чотири стадії заново. Повторювати, доки черговий повний прохід не знайде нічого нового. Тільки цей стан вважається чистим.
Ще зазначено, що --no-verify заборонено: хук, що впав, лагодять, а не глушать.
Окремо скажу про прийом, який тут працює. Стадії пронумеровано, у кожної свій перелік того, що перевіряти, а наприкінці — обов'язковий вердикт одним словом. Це той самий контроль формату відповіді, що й у звичайних промптах: моделі значно важче «приблизно перевірити» і сказати «начебто нормально», коли від неї вимагається обрати один із трьох позначених результатів.
Стиль відповіді
Правило про те, як зі мною розмовляти. Починається воно так:
Користувач — людина, що читає чат, а не Claude Code.У нього НЕ відкрито вихідний код паралельно, і він НЕ хоче розшифровуватиідентифікатори коду, імена полів і шляхи до файлів усередині відповіді.Говори з ним як колега, а не як інструмент код-рев'ю.
Вважай, що читач — компетентний розробник, який НЕ зануренийу цей проєкт. Він уміє писати код, але, найпевніше, веде кількапроєктів одразу і не тримає специфіку цього в голові.Далі — перелік того, що заборонено за замовчуванням: фрагменти коду, посилання виду «файл:рядок», імена полів і класів, великі таблиці, ASCII-діаграми. Усе це дозволено, лише якщо я прямо попросив.
Окремий шматок описує формат фінального звіту: зроблено / лишилося / що потрібно від людини. І там-таки приклад, узятий із життя:
✗ «Лишилося: своє дерево міграцій з перевіркою розбіжності, образ і маніфест, проводка у скрипті запуску.»
✓ «Лишилося: - Описати зміни бази окремими кроками оновлення: зараз таблиця створюється на льоту, і на справжньому сервері її просто не буде. - Зібрати образ і додати в опис кластера, інакше нікуди розгортати. - Прописати сервіс у скрипті запуску, щоб піднімався разом з рештою.»Три різні справи, зліплені в один рядок словами, зрозумілими лише тому, хто їх щойно написав. Читач кивне і не прочитає, а потім виявиться, що він погодився на те, чого не зрозумів.
Пара «погано / добре» тут працює краще за будь-який опис, і це рівно few-shot: один показаний приклад замінює абзац пояснень про самодостатність формулювань.
Бюджет сесії
Витрачай токени пропорційно до реальної складності завдання — найдешевшимшляхом, який надійно його розв'язує, а не найретельнішим, який дозволив бибюджет. Ліміти — це огорожа: вони показують, де ти впрешся у стінуабо в обмеження частоти, щоб зупинитися заздалегідь, а не бюджет,який треба освоїти.ЗЕЛЕНА зона НЕ означає «пали вільно».Далі в правилі таблиця класів завдань: тривіальне — правимо одразу, без роздумів і розвідки; маленьке — точкові читання, усе в одному потоці; середнє — один прохід планування і високі зусилля лише на складній розвилці; велике — фазами, з контрольною точкою між ними.
І окремий розділ про підагентів із прямим підрахунком: віяло з N агентів коштує як N сесій, тому запускати їх має сенс лише заради явної економії. Це правило працює в парі з хуком, який приносить живі цифри лімітів, — про нього докладно у статті про хуки.
Сумніваєшся — шукай в інтернеті
Коротке правило, сімнадцять рядків, і майже все в ньому — опис одного сценарію:
Відомий сценарій провалу, якого треба уникнути: щось не працює →ти застосовуєш виправлення, засноване на тому, що «знаєш» → все одноне працює → кожне наступне виправлення закопує розв'язання, побудованена хибному припущенні.
Тому в УСІХ сумнівних випадках — коли щось неясно, неочевидно,поводиться не так, як ти очікував, або розходиться з твоїми знаннями —ЗАВЖДИ шукай в інтернеті, перш ніж лагодити далі, і дивись насампередна свіжу офіційну документацію.
Якщо і пошук не дав розв'язання — ЗУПИНИСЯ і запитай користувача.Зверніть увагу на структуру: спершу описано провал, потім вимогу. Так правило застосовується і до ситуацій, які в ньому дослівно не описані, бо модель розуміє, від чого її страхують.
А от великі літери я б сьогодні прибрав, і в нинішній версії правила їх уже немає: чому, сказано вище, у розділі про промпти.
Підтягнути гілку перед роботою
Ціна пропуску — не конфлікт злиття наприкінці. Це робота, побудованана базі, якої більше немає: баг, уже полагоджений кимось іншим; рев'ю коду,який відтоді змінився; номер запису в трекері або часова позначкаміграції, вже зайняті; рішення, ухвалене за файлом двотижневої давності.Нічого з цього не спливе, доки роботу не буде закінчено.Далі три кроки: отримати зміни й подивитися, наскільки гілка відстала; перемотати; прочитати те, що прийшло, якщо воно стосується вашої області. І окремий розділ на випадок брудного робочого дерева.
Зупинятися на архітектурних розвилках
Мабуть, найцінніше правило з усіх. Починається з формулювання, яке мені подобається:
Частина рішень — це правка. Частина — переписування. Це правило про другий тип.
Коли ти помічаєш, що роботу можна розумно побудувати більш ніж однимспособом і вибір дорого скасовувати, — зупинися перш ніж писати код,розберися в картині цілком і поклади розвилку перед розробникомз передісторією та розкладеними варіантами.
Мовчки обрати і піти далі — ось провал, якому це правилозапобігає: його ціна не видна в diff, вона спливає місяці по томуу вигляді роботи, яку доведеться викинути.Далі — ознаки, за якими рішення вважається розвилкою: важко скасувати; розходиться більш ніж на один компонент або команду; визначає, хто чим володіє і де проходить межа довіри; змінює те, що видно ззовні (розгорнутий компонент, схему даних, контракт API); зачіпає гроші, безпеку чи приватність. Дві ознаки й більше — стоп.
А ось друга половина правила, без якої перша шкідлива:
Підняти розвилку коштує розробникові справжньої уваги. Перш ніж піднімати:
— Оборотно протягом дня? → вирішуй сам.— Проєкт уже ухвалював рівнозначне рішення? → дотримуйся його; прецедент важливіший за вподобання.— Тебе влаштував би будь-який з варіантів? → це не розвилка, це смак. Обирай.— Неясно лише тому, що ти не подивився? → спершу подивися. Більшість «розвилок» розчиняється під час читання.
Очікуй у проєкті кілька справжніх розвилок, а не по одній на завдання.Якщо ти піднімаєш їх щотижня — фільтр налаштовано неправильно.Без цього фільтра правило перетворюється на свою протилежність: агент починає питати з будь-якого приводу, людина перестає читати питання і пропускає те єдине, яке було важливим.
Символьна навігація
У проєкті підключено сервер, що дає перехід до визначення, пошук використань і правку за символом. Правило вимагає користуватися ним замість читання файлів цілком, і центральна його частина — таблиця відповідностей:
| Завдання | Інструмент | Замість чого || Зрозуміти API файлу | огляд символів | читання всього файлу || Знайти клас або функцію | пошук символа | grep за іменем || Прочитати тіло одного символа | символ із тілом | читання з відступом || Дізнатися, хто це викликає | пошук посилань | grep за іменем || Перейменувати по всьому проєкту | перейменування символа | десятків правок |Далі — розділ «коли звичайні інструменти правильний вибір». Це важлива половина: у мовного сервера є мови, яких він не розуміє, і чесно перелічити їх корисніше, ніж вимагати неможливого.
Облік робіт
Дев'яте правило — про трекер: що потрапляє в завдання й баги, що не потрапляє ніколи, як пов'язані записи й вимоги. Воно велике, і розбираю я його нижче окремим розділом, бо там цікаве не так формулювання, як сама схема обліку.
Скіли — це документація
Головна думка розділу: скіли в мене не «плагіни для агента», а документація проєкту. Та сама, яку раніше писали у вікі й ніхто не відкривав.
Документація у вікі живе окремо від коду і повільно з ним розходиться. Документація в репозиторії правиться в тому самому pull request'і, що й код, і її читає виконавець. Причому вибірково: тіло скіла потрапляє в контекст лише тоді, коли завдання йому відповідає. Двадцять шість тисяч рядків документації обходяться рядком у переліку на кожен скіл, доки не знадобилися.
Префікс в імені — це адресат. Скіли розкладено не за темами, а за тим, чиїй команді адресовано:
.claude/skills/├── req-uc-auth/SKILL.md вимоги: сценарії авторизації├── req-personas/SKILL.md вимоги: персонажі├── req-business-rules-core/SKILL.md вимоги: бізнес-правила├── ba-acceptance-criteria/SKILL.md бізнес-аналіз: як писати критерії├── qa-bug-report/SKILL.md тестування: як оформлювати знахідки├── dev-backend-new-endpoint/SKILL.md розробка: процедура нового ендпоїнта├── dev-tests-backend-unit/SKILL.md розробка: юніт-тести└── dev-workflow-git/SKILL.md розробка: конфлікти злиттяПриходить нова роль у команді — з'являється новий префікс, а не нова вікі.
Як має вигляд скіл. Заголовок з іменем та описом, далі звичайний markdown:
---name: dev-backend-new-endpointdescription: Процедура додавання HTTP-ендпоїнта: контракт, валідація, шари, тести, регенерація клієнта. Застосовувати під час створення нового ендпоїнта або модуля на бекенді.---
# Новий ендпоїнт
1. Описати контракт в `api.md` — до коду, інакше файл і код розійдуться.2. Контролер лише приймає й віддає; логіка в сервісі, доступ до даних у репозиторії.3. Валідація входу обов'язкова, помилки — спільним форматом.4. Тести: успішний шлях, відмова валідації, відсутність прав.5. Перегенерувати клієнт фронтенду і перевірити, що він збирається.
## Чек-лист- [ ] api.md оновлено до коду- [ ] логіка поза контролером- [ ] три тести на місці- [ ] клієнт перегенеровано, збірка зеленаОпис — найважливіше поле: за ним агент вирішує, чи підходить скіл завданню. «Довідник з FastAPI» працює погано. «Архітектура і продакшн-практики FastAPI; застосовувати під час створення та рев'ю сервісів на FastAPI» — добре. У переліку опис разом із полем when_to_use обрізається на 1536 символах, тож головний сценарій ставте першим.
По суті це маленький промпт маршрутизації: він має містити і предмет, і умову спрацювання. Тіло скіла при цьому тримають коротким, бо після завантаження воно лишається в розмові до кінця сесії і їде в кожному наступному запиті. А після стиснення контексту від кожного викликаного скіла повертається лише початок — перші п'ять тисяч токенів, і на всі скіли разом не більше двадцяти п'яти тисяч, — тому найважливіше ставлять на початок файлу. Тут працюють ті самі міркування, що й у контекст-інжинірингу: довгий довідник краще розбити, винісши деталі в сусідні файли, на які скіл посилається.
Вимоги як скіли. Скіл із вимогами має вигляд нормального документа аналітика. Сценарії зі своїми номерами, персонажі, межі, критерії приймання. Нічого «під агента» в ньому немає:
## UC-AUTH-002 Увійти поштою і паролем
**Персони:** PER-001 Агент, PER-002 Менеджер**Пріоритет:** P0
### Критерії приймання- AC-UC-AUTH-002-001 — за правильних даних сесія відкрита і діє в обох застосунках без повторного входу.- AC-UC-AUTH-002-002 — за хибного пароля відповідь однакова незалежно від того, чи існує акаунт (не підказуємо перебором).- AC-UC-AUTH-002-003 — після п'яти невдач поспіль вхід за цією поштою блокується на 15 хвилин.А далі головне: на ці номери посилаються завдання й баги. У записі трекера стоїть не переказ, а посилання. Текст вимоги не копіюється нікуди і живе в одному місці. Якщо запис і вимога розійшлися — правий документ із вимогою.
Лікує знайому хворобу: критерій, переписаний у завдання, у вікі й у тест-кейс, і три його версії за пів року.
Але це лише один із варіантів
Тримати документацію скілами — мій вибір, а не єдино правильний шлях. Люди розв'язують це завдання дуже по-різному, і варто знати, з чого взагалі обирають.
Звичайна папка з документацією в репозиторії. Найпростіший варіант: markdown у docs/, а в інструкціях проєкту рядок «документація лежить там-то». Нічого налаштовувати не треба, читається людьми в GitHub як є. Мінус рівно один, але суттєвий: агент про неї не згадає, доки ви не назвете файл. Він не знає, що там усередині, і в кращому разі знайде потрібне пошуком за словами.
AGENTS.md. Крос-інструментальний файл контексту, який читають Codex, Cursor і ще десяток агентів. Claude Code теж читає його сам, але лише якщо в проєкті немає ні CLAUDE.md, ні CLAUDE.local.md, тож його вимикає навіть особистий CLAUDE.local.md з вашими нотатками. Якщо CLAUDE.md є, за замовчуванням читається він, а AGENTS.md підключають рядком @AGENTS.md усередині нього або налаштуванням, яке велить читати обидва файли. Хороший вибір для команди, де різні люди працюють різними агентами. Обмеження те саме, що в інструкцій проєкту: це один файл, і роздувати його до довідника не можна.
Зовнішня вікі через MCP. Confluence, Notion, Linear і будь-що інше: документація лишається там, де її й так ведуть люди, а агент ходить туди по MCP-серверу. Аналітик править сторінку у звичному інтерфейсі, з коментарями та історією, а агент читає те саме. Платою йдуть мережа, акаунти й те, що версія документації живе окремо від версії коду: сторінка змінилася вчора, а гілка, яку ви лагодите, відповідає стану місячної давності.
Obsidian і його рідня. Локальне сховище markdown-файлів, до якого агента підключають або MCP-сервером, або просто відкриваючи йому каталог. Формат той самий plain-text, тому сховище можна тримати в гіті, а поверх нього працює і людина зі своїм графом посилань і пошуком, і агент. Люди використовують це як спільну пам'ять між інструментами та сесіями: нотатки, рішення, напрацювання в одному місці, доступному і Claude Code, і іншому агентові. Для особистої бази знань варіант чудовий. Для проєктної документації команди слабший: зв'язок із кодом знову втрачається, а сховище живе своїм життям.
Платформи документації з MCP і llms.txt. Сучасні сервіси на кшталт GitBook чи Mintlify віддають документацію одразу у двох виглядах: людський сайт і машиночитний шар, аж до автоматично піднятого MCP-сервера. Розумно, коли документація публічна і її все одно треба десь видавати.
Пошук по великому корпусу. Якщо документації тисячі сторінок, жоден із варіантів вище в контекст не влізе, і питання переходить у площину пошуку: векторна база, гібридний пошук, окремий сервер, який віддає агентові потрібні шматки. Це вже окрема інженерія, а не «поклав файли в папку».
Чим скіли виграють
Однією властивістю, заради якої я на них і перейшов: агент завжди знає, що вони існують. Перелік скілів з описами потрапляє в контекст на початку кожної сесії (крім тих, що викликаються лише вручну), тому потрібний документ агент підтягує сам, без нагадувань. З папкою документації так не виходить: доки не назвеш файл, його ніби немає.
Далі по дрібному, але приємно. Документація версіонується разом із кодом, і в старій гілці лежить та документація, яка відповідає старому коду. Правки проходять звичайне рев'ю в pull request'і. Нічого не треба налаштовувати, все працює офлайн, без токенів і зовнішніх сервісів. І формат відкритий: скіли Claude Code дотримуються стандарту Agent Skills, який розуміють і інші інструменти.
Чим розплачуєшся
Мінуси чесніше перелічити одразу.
Перелік скілів сам займає контекст. Не тіла, а саме перелік імен і описів, зате в кожній сесії. Бюджет у цього переліку — один відсоток контекстного вікна. Коли скілів стільки, що він не вміщується, Claude Code викидає описи тих, якими користуються найрідше, і від них лишаються самі імена. Тобто платите ви вже не стільки токенами, скільки невидимістю: без опису агент не зрозуміє, що скіл підходить до завдання. Скільки коштує ваш перелік, оцінить /doctor, а які скіли майже не використовуються, покаже /skill-doctor.
Людям читати незручно. Усередині репозиторію немає ні пошуку по документації, ні змісту, ні коментарів на полях, ні зручної роботи з картинками. Аналітик, звиклий до Confluence, у GitHub по вимоги не піде. У мене це розв'язується тим, що вимоги править та сама людина, яка працює з агентом, але у великій команді це стане проблемою.
Немає спільного редагування й обговорення. Коментар до абзацу, обговорення просто в документі, сповіщення «вас згадали» — усього цього немає. Є pull request, що в рази формальніше.
Кілька репозиторіїв — кілька копій. Спільні для компанії практики доведеться або дублювати, або пов'язувати символічними посиланнями, або пакувати в плагін. У монорепозиторії проблеми немає, а от на п'яти репозиторіях вона помітна.
Спокуса звалити туди все. Скіли дешеві, тому в них легко накидати сто файлів і дістати ту саму мертву вікі, тільки в гіті. Один порятунок: опис, за яким агент обирає скіл. Якщо його написано недбало, документ не підтягнеться ніколи, і ви навіть не дізнаєтеся.
Рольової фільтрації немає. Скіли аналітика бачить розробник, і навпаки, а платять контекстом усі. Про це докладніше нижче, у розділі про ролі.
Якщо зводити до одного правила: те, що потрібне агентові в момент роботи над кодом, краще тримати поруч із кодом; те, що потрібне людям для обговорення й планування, краще тримати там, де люди звикли працювати. У мене межа проходить приблизно так: вимоги й практики — скілами, а плани, терміни й листування лишаються в зовнішній системі.
Скільки це коштує
Інструкції проєкту й правила завантажуються в кожну сесію цілком. У серпні в мене це становило 571 рядок інструкцій плюс 1245 рядків правил. Майже дві тисячі рядків до того, як ви надрукували перше слово.
Помітно більше за рекомендоване, і плачу я за це контекстом. Розміняв свідомо: передбачуваність у проєкті з кількома застосунками й спільною інфраструктурою дорожча за заощаджені токени. Але в розміну є межа. Якби файл ріс далі, я б розтягнув правила за масками шляхів.
До речі, якщо агент уперто порушує якесь правило — річ майже завжди не у формулюванні, а в обсязі. Правило загубилося. Лікується скороченням, а не додаванням великих літер. А якщо правило не повинно знати винятків узагалі, його місце не в тексті, а в хуку чи забороні.
Три місяці по тому
Розмін «передбачуваність дорожча за токени» довелося переглянути. Файл інструкцій до кінця серпня доріс до 653 рядків, його скоротили до 216, а на початку жовтня проєкт пройшов повне чищення. Після нього в інструкціях близько ста п'ятдесяти рядків, а скілів замість ста двох — тридцять шість: сімдесят два прибрали, а шість нових за цей час додалися.
Що змінилося:
- Сімдесят два загальні скіли. Довідники на кшталт найкращих практик FastAPI чи продуктивності Python. Усе це модель знає і без нас, а платили ми за них місцем у переліку кожної сесії. Лишилися вимоги, двадцять чотири скіли, і процедури, які є тільки в цьому проєкті, як-от рев'ю pull request'а за правилами команди.
- Нотатки про частини проєкту зібрано в окремі CLAUDE.md у папках бекенду, фронтенду, інфраструктури та інших. Такий файл підвантажується, лише коли агент починає працювати у своїй папці.
- Файли
.claudeignore. Claude Code їх не читає: закрити файл від агента можна тільки забороною на читання в налаштуваннях дозволів. - Три правила — не комітити без прохання, перевірка перед комітом і підтягнути гілку — перетворилися на два: «перед початком роботи» і «завершення роботи», де ревізія змін, коміт лише на прохання і pull request до зелених перевірок. Готове завдання один раз перевіряє окремий підагент-рецензент.
Додалися правила про якість коду, про конфлікти злиття і про самостійну роботу: перш ніж питати, пошукай сам, і доводь завдання до кінця, а не повертай на півдорозі. Усього правил тепер одинадцять плюс довідник з API, близько тисячі ста рядків, і всі, крім стилю відповіді, переписано заново. Цитати вище — із серпневих версій: як зразки формулювань вони й далі годяться.
Висновок збігся з тим, до якого дійшла й сама Anthropic: писати агентові варто лише те, чого він не знайде в коді сам. Як узагалі пишуть хороший бекенд, модель і так знає, а от як заведено у вашій команді — ні.
Документація: як і де
Принцип простий. Уся документація, яку читає агент, живе в інструкціях, правилах і скілах. Окремої папки «доки для агента» немає взагалі — щоб не було двох джерел істини. Це рішення конкретного проєкту, а не єдино можливе: варіанти та їхню ціну я розібрав вище.
Що з цього випливає:
Правила й скіли — джерело істини. Агентові прямо заборонено вигадувати поведінку, що їм суперечить. Вважає документ неправим — каже людині, а не діє по-своєму.
Не правити документацію без прохання. Спершу видається дивним, потім виявляється необхідним: агент, що спіткнувся об незручне правило, охоче приведе правило у відповідність до своєї поведінки.
Нове — новий документ, зміна наявного — правка наявного. Інакше за пів року в проєкті два скіли про одне й те саме з різними версіями істини.
Єдиний шаблон. Є окремий скіл про те, як писати правила й скіли: структура, формулювання, роздільники, обов'язковий чек-лист наприкінці. Чек-лист перетворює опис на перевіряну вимогу, а заразом дає агентові спосіб самому перевірити, чи виконав він документ.
Цей скіл, по суті, звід технік промпт-інжинірингу, прикладений до конфігурації проєкту, і правило вимагає застосовувати його під час створення чи правки будь-якого правила й будь-якого скіла. Звучить бюрократично, але окупається: документи, написані за одним шаблоном, рідше суперечать одне одному й краще дотримуються. Розбір самих технік — у статті про промпт-інжиніринг.
README для людей, інструкції для агента. Обидва потрібні, але читачі різні. README пояснює новій людині, що тут відбувається; агент спирається на інструкції, правила та скіли. Змінюється структура проєкту — правляться обидва, інакше розробник і агент живуть у різних уявленнях про репозиторій.
Технічні довідники окремо. Розгортання, міграції, результати навантажувальних тестів лежать у звичайній папці документації в корені. Агентові в роботі над кодом вони не потрібні, а людині потрібні епізодично.
Трекер завдань і багів просто в репозиторії
Найсвоєрідніша частина моєї конфігурації.
Завдання й баги лежать у репозиторії звичайними markdown-файлами, по файлу на запис. Жодної бази, жодного вебінтерфейсу, жодних перевірок у CI. Скрипт уміє дві речі: завести запис і перезібрати індекс. На цьому автоматизація закінчується.
management/├── tasks/│ ├── auth/TASK-001-one-password-for-both-apps.md│ ├── billing/TASK-037-invoice-pdf-export.md│ ├── done/TASK-012-import-legacy-contacts.md│ ├── INDEX-AUGUST-2026.md│ └── TEMPLATE.md├── bugs/│ ├── auth/BUG-003-sign-in-loops-on-expired-token.md│ ├── done/BUG-001-avatar-upload-fails-over-2mb.md│ └── INDEX-AUGUST-2026.md├── decisions/ADR-0001-where-user-sessions-are-stored.md├── logs/roman/2026-08-06/a1b2c3d4.log└── new.pyЩо це дає. Агент бачить завдання цілком, не виходячи з проєкту, разом із вимогою, на яку воно посилається, і кодом, який воно править; запис живе в тій самій історії, що й код, тому завжди видно, яким комітом його закрито і що по ньому змінювалося дорогою. Дві людини (або два агенти) над різними записами фізично не редагують один файл, тож конфліктів злиття не буває за побудовою — це, мабуть, головний аргумент проти одного великого файлу з переліком завдань, до якого всі звикли. Плюс усе працює офлайн, без акаунтів і токенів.
Як має вигляд запис
Ось справжній шаблон бага, тільки з вигаданим змістом:
---id: BUG-003title: 'Sign-in loops on an expired token'severity: P1status: CONFIRMEDmodule: autharea: 'sign-in / refresh token'found: 2026-08-04closed:assignee: ''req: 'AC-UC-AUTH-002-001'source: 'QA wave 12'---
# BUG-003 — Sign-in loops on an expired token
- **Steps:** open the app with a token older than 24h → sign-in screen → enter valid credentials → back to the sign-in screen.- **Expected:** AC-UC-AUTH-002-001 — a valid sign-in opens a session.- **Actual:** the refresh call returns 401 and the client retries forever.- **Log:** - 2026-08-04 — filed from the QA wave. - 2026-08-05 — reproduced on staging, confirmed. Refresh interceptor does not clear the stale token before retrying.
## Screenshots
- 2026-08-04 — `BUG-003_04-AUGUST-2026_11-20_loop.png` — the loop, three redirects in the network tab.Заводиться командою, а не копіюванням файлу руками:
python management/new.py bug --module=auth --severity=P1 \ --title="Sign-in loops on an expired token"
python management/new.py task --module=auth --priority=P1 \ --title="One password for both apps"
python management/new.py attach BUG-003 shot.png --note="the loop after the fix"Скрипт видає наступний вільний номер, кладе файл у папку модуля і перезбирає індекс місяця. Індекс має такий вигляд:
# Task index — AUGUST 2026
**Entries:** 31 · **Open:** 30 · **Closed:** 1
| ID | Prio | Status | Batch | Module | Title || --- | --- | --- | --- | --- | --- || TASK-029 | P1 | IN_PROGRESS | 2026-08-04-export | billing | Export invoices as PDF from the admin panel || TASK-030 | P1 | TODO | PROJ-42 | platform | Choose a feature-flag library || TASK-031 | P1 | TODO | PROJ-42 | platform | Set up CI/CD for the staging environment |Деталі, важливі на практиці:
Номери вічні. Не використовуються повторно і не перенумеровуються ніколи: на них посилаються коміти, листування та інші записи. Наскрізну нумерацію, щоправда, згодом довелося змінити на випадкові коди з чотирьох символів на кшталт BUG-2W7F: дві людини на двох гілках брали той самий «наступний вільний номер», і git спокійно зливав обидва записи, адже імена файлів у них різні. Старі записи свої номери зберегли.
Папки названо за вимогами. Область запису зветься так само, як файл вимог, який нею володіє: req-uc-auth → папка auth. Завдання й баги ділять ті самі папки. Дрібниця, але прибирає вічну суперечку «куди це покласти» і з'єднує трекер із документацією.
Закриття через git mv. Змінюється статус, ставиться дата, дописується рядок у журнал, файл переїжджає в папку закритих. Переміщень git не зберігає: git mv дає той самий результат, що й звичайне переміщення, а git log --follow простежує файл за схожістю вмісту. Тому історія запису рветься, лише якщо разом із перенесенням файл сильно переписано, і ось цього в закривному коміті варто уникати.
Скріншоти в репозиторії. Окрема команда кладе картинку в папку вкладень, називає за схемою і дописує рядок у запис. Лише зображення, до чотирьох мегабайтів, обрізані: гіт зберігає кожен байт назавжди. Відео — посиланням. Розділ зі скріншотами дописується в кінець, бо баг, що жив три тижні, несе знімок на кожен стан, і старі рядки мають показувати, як було тоді.
Мова — англійська латиницею. Ім'я файлу будується із заголовка, а трекер читають люди без спільної рідної мови. Опис можна лишити мовою скарги, якщо попросили, але заголовок і службові поля завжди латиницею.
Що в трекер не потрапляє ніколи
Найважливіше правило обліку, і воно суперечить звичці: у трекері лише продукт.
Тест рівно один. Чи працює це в замовника? Застосунки, бібліотеки, з яких вони зібрані, дані, інфраструктура — так, це продукт.
Усе, що існує лише щоб нам було зручніше будувати продукт, не потрапляє в трекер узагалі. Ні завданням, ні багом, незалежно від обсягу роботи і від того, хто попросив. Документація репозиторію, правила, скіли, сам трекер і його скрипт, хуки, службові скрипти, налаштування CI, перекладання папок. Це просто робиться, а записом лишається коміт і автоматичний журнал сесії.
Формулювання в правилі звучить жорстко, і це навмисно:
Жодного запису взагалі — хоч би яким зламаним воно виглядало і скільки б роботине коштувало: застарілий документ, мертве посилання, хибний шлях у правилі,дефект у цьому самому трекері або в службовому скрипті, хук, що неправильночитає свій ввід, крива настройка CI, перейменована папка, правило,про яке хтось попросив. До замовника нічого з цього не доїжджає,отже це не баг. А перетворити його на завдання — та сама помилка під іншоювивіскою. Не заводьте. Зробіть роботу, коміт скаже за неї.Спокуса велика: роботи багато, хочеться, щоб вона була видна. Але трекер, напханий господарськими справами, ніхто не читає, а він заводився рівно заради читання.
Другий поділ — завдання проти багів. Усе, що знайшло тестування, це баг, і тільки баг. Виправлення бага не породжує завдання. Завдання — нова функціональність або переробка наявної, про яку попросили.
Рішення
Поруч із завданнями лежать архітектурні рішення, по файлу на рішення. Формат звичайний, знайомий за ADR:
---id: ADR-0001title: Where user sessions are stored: database or cachestatus: Proposeddate: 2026-07-31deciders: Engineering lead / Architectrelated: - management/tasks/auth/TASK-001, TASK-002 - Requirements BR-SEC-004 (one session shared by both apps)supersedes: none---
## Context що змусило ухвалювати рішення і яке питання заблоковано## Decision пронумеровані пункти: що саме вирішено## Verified facts (checked in code, not assumed) таблиця «факт → де в коді»## Consequences що це спрощує і чим за це платимо## Alternatives що розглядали і чому відкинулиРозділ із перевіреними фактами вигадався після того, як одне рішення ухвалили на підставі чужого переказу, а в коді виявилося інакше. Тепер кожен факт в ADR несе посилання на місце в коді, звідки його взято.
Користь проста: суперечка, яка розв'язується один раз, потім не спливає заново кожні два місяці.
Журнал сесій, що пишеться сам
Третя частина обліку, і її ніхто не веде руками. Хук записує все, що відбувалося в сесії: ваші запити, питання агента і що ви обрали, статистику по кожному ходу, змінені файли з кількістю рядків, фінальний звіт. Файл на сесію, папка на день, папка на розробника.
Має такий вигляд:
session start: source=startup · model=claude-opus-5
════════════════════════════════════════════════════════════
prompt:полагодь нескінченний редирект на протухлому токені, BUG-003
turn: model=claude-opus-5 · effort=high · 4m 12s · tools=23 (Read 9, Grep 5, Edit 3, Bash 6) · subagents=1
files: ~ apps/web/src/api/interceptors.ts +14/-6 +[41-48,52-57] -[41-46] ~ apps/web/tests/auth.spec.ts +31/-0 +[88-118]
answer:Причина була в тому, що перехоплювач повторював запит зі старим токеном...
subagent done: general-purposesession end: reason=prompt_input_exit · duration=51mНавіщо, якщо є сам агент? Затим, що питати в нього, що було в сесії, — погана ідея. Наприкінці довгої роботи його контекст уже стиснуто: частина подробиць втрачена, частина переказана оптимістично. Механічний запис, зроблений не моделлю, — єдина чесна відповідь на питання «що взагалі сталося».
Сорок сім таких файлів накопичилося до серпня, до листопада їх понад сімсот. Відкривав я їх частіше, ніж очікував: зазвичай щоб зрозуміти, коли і чому з'явилося дивне місце в коді. Заразом це відповідь на питання «а де обліковується робота над самим репозиторієм, яку заборонено заводити завданням». Ось тут. Автоматично, без жодного рядка ручного обліку.
Чого в схеми немає
Чесно про обмеження. Тут немає дошки, сповіщень, звітів за спринтом, обліку часу. Якщо менеджмент живе в Jira, ця схема її не замінює: у мене, наприклад, мітка групування зберігає якраз ключ із Jira.
Поділ виходить такий. У зовнішній системі — планування і звітність для менеджера. У репозиторії — те, що потрібне виконавцеві в момент роботи, разом із кодом і вимогами.
Чого бракує: ролі
Раз уже я розклав скіли за префіксами під різні команди, скажу і про те, чого для цієї схеми бракує в самому інструменті.
Префікс в імені — домовленість, а не механізм. Аналітик, тестувальник і розробник працюють в одному репозиторії і отримують ту саму конфігурацію: однакові інструкції, увесь набір скілів, однакові права на запис.
Три неприємності, і всі три я бачив наживо. Аналітик просить звірити специфікацію з кодом, а агент, навантажений інструкціями для розробника, починає правити вихідники. Тестувальник просить відтворити дефект, а в спільних інструкціях написано «перед перевіркою застосуй міграції», і агент чесно застосовує їх на спільному стенді. І тихіше, але дорожче: усі платять контекстом за всі скіли, зокрема ті, яких їхня робота не стосується ніколи.
Обхідний шлях очевидний і поганий: кожен заводить особисту конфігурацію в себе в домашній папці. Вона не в репозиторії, її ніхто не рев'ює, у новачка її просто немає.
Правильне розв'язання — зробити роль повноцінним шаром конфігурації в репозиторії. Своя частина інструкцій, свій набір скілів і агентів, свої дозволи і, головне, своя область запису, за межі якої правки не виходять:
.claude/├── CLAUDE.md спільна частина для всіх├── settings.json├── skills/└── roles/ ├── dev/{CLAUDE.md, settings.json, skills/, agents/} ├── qa/{CLAUDE.md, settings.json} заборона на міграції й деплой └── ba/{CLAUDE.md, settings.json} запис лише в docs/ і specs/Причому це має бути забороною на рівні інструмента, а не проханням у тексті. Різниця рівно та сама, що між правилом і хуком.
Частину схеми вже можна зібрати з того, що є. --agent дає сесії інструменти й модель потрібного підагента, а файл налаштувань, переданий через --settings, додає заборони й параметром skillOverrides ховає від агента чужі скіли або лишає від них самі імена. Але обирається все це руками під час запуску, а не лежить у репозиторії готовою роллю.
Я оформив це запитом на додавання ролей у Claude Code: з описом проблеми, тим, що вже закривають прапорці --agent і --settings, і тим, чого бракує. Повна версія зі схемою злиття налаштувань (роль може лише звужувати проєктні права, але не розширювати) — у першому запиті, який закрив бот неактивності. Якщо біль знайомий, зайдіть підтримати — що більше підтверджень, то вищий шанс, що до цього дійдуть руки.
Підагенти
Підагент — окрема сесія зі своїм контекстом, своїми інструментами і своїм системним промптом. Робить частину роботи, повертає результат. Є і форк: він не починає з чистого аркуша, а успадковує всю поточну розмову.
Користь не в тому, що підагент розумніший: за замовчуванням це та сама модель або простіша, і те саме завдання він розв'яже не краще за основну сесію. Користь у чотирьох речах. Паралельність: незалежні шматки роботи йдуть одночасно. Шумне виведення — повний прогін тестів, широкий пошук по коду — лишається в підагента, а не їде потім у кожному запиті основної сесії. Свіжий погляд для перевірки. І урізані права: рецензент, який може читати, але не може правити, і цю заборону тримає сам інструмент.
Просити про це найчастіше не треба: широкий пошук по коду Claude Code сам віддає вбудованому підагентові Explore, побічні завдання — форкам, і запускає їх у фоні, щоб основна розмова не стояла.
Свого підагента описують одним файлом:
---name: security-reviewerdescription: Рев'ю змін щодо вразливостей. Запускати перед релізом і за правок в авторизації, завантаженні файлів, роботі з БД.tools: Read, Grep, Glob, Bashmodel: opus---
Ти старший інженер з безпеки. Дивись зміни щодо:- ін'єкцій (SQL, XSS, команди оболонки);- дір в автентифікації та авторизації;- секретів у коді;- небезпечної роботи з користувацькими даними.
Вказуй конкретні рядки і пропонуй виправлення. Стилістику не чіпай.Тіло такого файлу — системний промпт окремої моделі, а не нотатка для себе. Працює все те саме: задана роль, явні межі («стилістику не чіпай»), формат відповіді й умова виклику в описі. Про те, як писати промпти для агентів і виклику інструментів, є окремий розділ у статті про промпти.
Ще одне застосування — незалежна перевірка. Той, хто писав код, поганий перевіряльник: він бачить не diff, а свої наміри. Просити підагента варто конкретно:
Підагентом перевір зміни проти PLAN.md. Переконайся, що кожну вимогуреалізовано, що на перелічені межові випадки є тести і щонічого поза завданням не змінилося. Пиши про прогалини, а не про смаки.Застереження, яке краще знати заздалегідь: перевіряльник, якого попросили знайти недоліки, їх знайде. Навіть коли роботу зроблено добре, бо його про це попросили. Гнатися за кожним зауваженням — прямий шлях до зайвих шарів абстракції й тестів на неможливі випадки.
І про гроші. Підагенти не безкоштовні: кожен шле свої запити, і вони йдуть у ті самі ліміти, що й основна розмова. Свіжому підагентові ще й доводиться заново збирати контекст, який в основної сесії вже був, тож інколи він виходить навіть повільнішим. Віяло з десяти коштує приблизно як десять сесій. Заощадити можна на моделі: просту роботу на кшталт збирання файлів, що імпортують модуль, віддають підагентові на Haiku, рядком model: haiku у його описі. Правка в одному-двох файлах завжди швидша в основній сесії.
Окрема історія — кілька паралельних сесій. Найпростіше розводити їх по робочих деревах гіта: у кожної свій каталог і своя гілка, правки не стикаються. claude -w ім'я одразу запускає сесію в новому робочому дереві, а файли, які гіт ігнорує, на кшталт .env, і яких у свіжому дереві немає, Claude Code скопіює сам, якщо перелічити їх у .worktreeinclude в корені репозиторію. Схема «один пише, інший перевіряє» працює з тієї самої причини, що й підагент-рецензент: свіжий контекст не заражений міркуваннями автора.
Контекст на практиці
Прийоми, якими користуюся постійно:
Перша хвилина. Дивіться, куди пішов агент, і тисніть Esc, щойно він звернув не туди: він зупиниться, зберігши все зроблене, і можна виправити курс.
Нове завдання — чистий контекст. Очищення між незв'язаними завданнями дешевше за будь-яку оптимізацію. Хвіст чужого завдання — це і зайві токени, і зайві приводи відволіктися. /clear нічого не коштує, а з іменем, /clear oauth, ще й підписує сесію, до якої потім можна повернутися.
Дві невдалі спроби — стоп. Виправили двічі й усе ще не те? Річ уже не у формулюванні: контекст напханий невдалими підходами. Чиста сесія з точнішою постановкою майже завжди обганяє довгу з накопиченими виправленнями.
Стиснення налаштовується. Перед заповненням вікна історія стискається автоматично. Можна стиснути й вручну, з акцентом на потрібному (/compact залиш зміни API і команди тестів), а в інструкціях проєкту вказати, що зберігати обов'язково:
Під час стиснення контексту обов'язково зберігай: перелік змінених файлів,команди запуску тестів і ухвалені архітектурні рішення з їхніми причинами.Тільки пам'ятайте, що стиснення довгої сесії саме по собі великий запит: модель перечитує всю розмову, щоб її переказати. Якщо історія не потрібна, /clear дешевший.
Відкат замість обережності. Кожен ваш запит — точка повернення: /rewind або Esc двічі на порожньому рядку, і повернути можна листування, файли або те й інше. Це змінює стиль роботи: замість довгого обмірковування ризикованого кроку простіше спробувати й відкотитися. Тільки пам'ятайте, що відкат не замінює гіт: він пам'ятає лише файли, які агент правив своїми інструментами в основній розмові, а зміни через командний рядок не відстежує.
Коротке питання вбік. Для дрібниці на кшталт «що робить цей прапорець» є /btw: відповідь не потрапляє в історію.
Рядок стану і /usage. Розмір контексту й витрати краще тримати перед очима: у рядку стану — постійно. А /usage на підписці розкладає витрати за скілами, підагентами, плагінами та MCP-серверами і сам підказує, що змінити.
Дозволи
Режимів дозволів кілька, і за замовчуванням тепер працює не найсуворіший. Інтерактивні сесії в терміналі та VS Code стартують в автоматичному режимі: окрема модель-класифікатор дивиться дію до виконання і зупиняє те, що зупинили б і ви, — curl | bash, деплой і міграції на проді, force push поверх чужої роботи, надсилання чутливих даних назовні, дії, схожі на команди з прочитаного агентом тексту, а не від вас. Після трьох блокувань поспіль або двадцяти загалом режим здається і знову питає людину. Якщо неінтерактивний запуск claude -p іде в автоматичному режимі, питати нікого: заблокована дія просто не виконується, і Claude продовжує роботу без неї.
На іншому кінці — ручний режим, де ви підтверджуєте кожну правку й кожну команду, крім читання. Безпечно і нестерпно: після десятого підтвердження ви вже не читаєте, а клацаєте. А режим зовсім без перевірок, bypassPermissions, має сенс лише в одноразовому контейнері. Режими, зокрема планування, перемикаються через Shift+Tab.
Автоматичний режим — це судження моделі, а не правило, і він може помилитися. Тому все, що «ніколи», записується так, щоб тримав сам інструмент: заборонами в налаштуваннях і хуками. Заборони й хуки PreToolUse діють у будь-якому режимі, зокрема в автоматичному й bypassPermissions, і спрацьовують раніше, ніж класифікатор узагалі побачить дію:
{ "permissions": { "allow": [ "Bash(npm run test *)", "Bash(npm run lint)", "Bash(npm run build)" ], "ask": ["Bash(git push *)"], "deny": [ "Read(.env)", "Read(.secrets/**)" ] }}Записані без ./, ці правила ловлять такий файл на будь-якій глибині під папкою, де запущено Claude Code; Read(./.env) закрив би лише той, що лежить у ній самій. Заборона на читання .env закриває і інструмент читання, і cat .env у командному рядку: поширені команди читання файлів Claude Code впізнає. Скрипт, який відкриє файл сам, він уже не впіймає. Дозволяти читання всередині проєкту й команди на кшталт git status чи git diff не потрібно, підтвердження вони й так не вимагають. Зірочка через пробіл — нинішній запис; стара форма test:* працює й далі, але діалог дозволів пише нову. Увесь синтаксис правил — у довіднику з команд і налаштувань.
Якщо класифікатор раз у раз зупиняє те, що у вас рутина, не підтверджуйте вручну, а опишіть середовище словами в особистих налаштуваннях: які домени свої, який стенд можна чіпати. У ручному режимі допомагає зворотне: /fewer-permission-prompts переглядає минулі сесії й додає часті безпечні команди до переліку дозволених.
Найсуворіший варіант — пісочниця (/sandbox, на macOS, Linux і WSL2): обмеження файлової системи й мережі на рівні ОС для команд, які запускає агент. Вона підхоплює і ваші заборони на читання, тож для всього, що стосується безпеки, потрібні обидва шари.
Хоч би що ви обрали, одне правило лишається. Перед комітом дивитися повний diff. Воно було важливим і до агентів, а зараз важливіше: модель охоче править те, про що не просили, і заразом упорядковує сусідній файл.
Коли ніхто не дивиться
Усе сказане вище вдвічі важливіше, коли агент працює без вас. Поки ви дивитеся, пропущений шматок контексту — не біда: помітите за повідомлення-друге. Запустили завдання на ніч — і вранці дізнаєтеся, що всю ніч воно будувалося на хибному припущенні.
Перед таким запуском варто пройтися п'ятьма питаннями, саме для цього завдання:
- Чи знає агент, який вигляд має «готово»? Умова цілі, файл специфікації, тест, який зараз падає і який треба зробити зеленим.
- Чи може він перевірити себе? Тести, хук
Stop, крок рев'ю. - Що йому можна чіпати? Правила дозволів, пісочниця, окреме робоче дерево, єдина гілка, куди можна пушити.
- Що його зупинить?
--max-turns,--max-budget-usd, ліміт витрат. - Куди піде результат і хто його прийме? Pull request або звіт — і людина, яка схвалює злиття.
Сам запуск — claude -p "завдання" у скрипті або CI. З --permission-mode dontAsk усе, що не дозволено заздалегідь через --allowedTools, відхиляється, а не висить в очікуванні відповіді. Повторювати завдання за таймером у відкритій сесії вміє /loop, а /schedule заводить хмарне завдання за розкладом, яке працює й за закритого ноутбука. Починайте з трьох файлів, а не з трьохсот: подивіться, що пішло не так, виправте запит, потім запускайте решту.
Моделі, зусилля та гроші
Робота агента складається з кроків дуже різної складності. Розібратися в завданні, знайти файли, застосувати правку, перевірити результат. Тримати на всіх кроках найдорожчу модель ні до чого.
Практика така: основна сесія на сильній моделі, механічна робота делегується підагентам на моделі простішій, рівень зусиль підвищується лише там, де є складна розвилка. І скіли, і підагенти вміють задавати модель і зусилля для себе, тож маршрутизацію можна описати один раз:
---name: dev-changelogdescription: Зібрати changelog з історії комітів між двома тегами.model: haikueffort: lowdisable-model-invocation: true---Застереження для скілів: без context: fork модель скіла діє в основній розмові до кінця ходу. Дешевша модель тоді отримує всю історію, а кеш промпту основної моделі на неї не поширюється, тож у довгій сесії економія може обернутися перевитратою. З context: fork скіл запускається у власному підагенті й бачить лише свої інструкції.
Головний регулятор того, скільки модель думає, — рівень зусиль: low, medium, high, xhigh і max, перемикається командою /effort. У Opus 5.5, Sonnet 5.5 і Haiku 5.5 за замовчуванням стоїть medium, і для звичайної роботи зі зрозумілими межами цього вистачає; в інших моделей із рівнями зусиль за замовчуванням high, а в Opus 4.7 — xhigh. Підвищувати варто, коли правильність залежить від випадків, які легко пропустити: баг у чужому коді, нестабільний тест, зміна схеми, у якої треба знайти всіх читачів. max — для складного завдання, яке агент розв'язує без вас; на звичайному він розмірковує понад потребу, і ви платите за відповідь не кращу, ніж дав би high. Фрази на кшталт «подумай гарненько» в запиті — звичайний текст, рівня зусиль вони не підвищують. А для одного складного питання посеред рутини є слово ultrathink: воно просить глибше подумати лише на цьому ході.
Окрема тема — ліміти підписки. За замовчуванням агент їх не бачить, тому не може співвідносити витрати: він однаково охоче запускає віяло підагентів і коли до скидання чотири години, і коли бюджет на межі. Людині їх показує /usage, у запусків зі скриптів є жорсткі межі --max-turns і --max-budget-usd, а в мене це розв'язано хуком, який приносить живі цифри в контекст і забороняє віяльні запуски в гарячій зоні. Подробиці у статті про хуки.
MCP і консольні утиліти
Два способи дати агентові доступ до зовнішнього світу.
Консольні утиліти — найощадливіший за контекстом шлях. Є в сервісу CLI — агент чудово ним користується: заводить завдання, читає коментарі, дивиться логи, розгортає середовище. Незнайомі утиліти він теж опановує, якщо попросити розібратися за вбудованою довідкою.
MCP-сервери — коли потрібен структурований доступ: база, трекер, макети, моніторинг. Тут-таки живе корисна категорія серверів для роботи із самим кодом: символьна навігація замість читання файлів цілком заощаджує на великих репозиторіях дуже помітно. Для типізованих мов у Claude Code є й офіційні плагіни code intelligence на мовних серверах: перехід до визначення замість grep і читання кількох файлів-кандидатів, а після правки — помилки типів одразу, без запуску компілятора.
Порада з практики: підключайте лише те, чим справді користуєтеся. Повні описи інструментів MCP тепер підвантажуються на вимогу, але імена інструментів та інструкції сервера лежать у контексті кожної сесії і їдуть у кожному запиті, тож десяток серверів «про всяк випадок» обходиться дорожче, ніж здається. Непотрібні вимикаються в /mcp.
Які поради застаріли
Моделі помітно підтягнулися, і частина порад, які ще нещодавно були слушними, тепер заважають. Якщо щось із цього лишилося у вас у звичках чи в інструкціях — сміливо викидайте:
- «Контекст — головний обмежувач». Вікно на мільйон токенів і автоматичне стиснення зробили впирання в стіну рідкістю. Чистити контекст між завданнями й далі варто, але заради ціни та фокусу.
- «Віддавайте роботу підагентам, щоб зберегти контекст». Підагенти добрі для паралельної роботи, шумного виведення й незалежної перевірки, і кожен коштує токенів.
- «Підагент відповість краще». Та сама модель на тому самому завданні розумнішою не стане. Допомагає свіжий погляд рецензента, але це інше.
- «Подумай гарненько» в запиті. За глибину відповідає рівень зусиль, а ці слова — звичайний текст. Працює лише
ultrathink, і лише на один хід. - IMPORTANT і великі літери. Нинішні моделі від них застосовують правило надто широко. Не тримається рядок — отже, файл задовгий або це робота для хука.
- «Не лінуйся, продовжуй до кінця». Домовлене завдання моделі й так доводять до кінця, а такі рядки радше спричиняють зайву роботу. Дати перевірку, яку треба пройти, — інша річ, це й далі корисно.
- Опис архітектури й розкладки папок в інструкціях. Репозиторій агент читає сам. Пишіть лише те, чого в ньому немає.
Що лишилося вірним із практик Cursor
Частина порад зі старої статті нікуди не поділася. Вони про роботу з моделлю взагалі.
Декомпозуйте і контролюйте кроки. Прохання «зроби все» дає код, який працює не так, як ви очікували, і розбиратися в ньому дорожче, ніж було б написати. Кроки мають бути самодостатніми: після кожного проєкт збирається.
Логуйте щедро. Людині перевантажена логами консоль заважає, агентові допомагає: зіставляючи виведення з кодом, він точніше розуміє, що зламалося.
Просіть свіжі версії бібліотек і дивіться на ліцензії. Модель підставить версію, яку найчастіше бачила під час навчання, а це рідко остання: дані навчання відстають від релізу моделі на місяці, а частота згадок тягне до версій ще старших. На ліцензію вона не дивиться зовсім, а затягти в закритий проєкт бібліотеку з копілефтом легко.
Уточнюйте спосіб розв'язання заздалегідь. Одну річ можна зробити п'ятьма способами, і без уточнення вибір робить модель — на підставі того, що частіше траплялося в навчальних даних. Запитайте про варіанти й мінуси до того, як код написано.
Різні завдання — різні сесії. Порада про новий чат під кожне завдання перекочувала без змін, тільки тепер у неї є точне пояснення: це про ціну і фокус контексту.
Як усе зіпсувати
Зібрав ті способи, які бачу найчастіше. У себе зокрема.
Сесія-смітник. Почали з одного завдання, запитали про інше, повернулися до першого. Контекст напханий усім одразу.
Нескінченні виправлення. Агент зробив не те, ви виправили, знову не те. Після двох кіл дешевше почати заново.
Роздуті інструкції. Файл виріс, половина вказівок перестала працювати: важливе загубилося. Лікується безжальним скороченням.
Довіра без перевірки. Правдоподібна реалізація, що не покриває межові випадки. Перевірити нічим — не надсилайте.
Нескінченна розвідка. «Розберися, як тут усе влаштовано» без меж, і сесія оплатила двісті прочитаних файлів. Широкий пошук Claude Code сам віддає підагентові, але межі задаєте ви: обмежуйте область.
Коротко
Якщо забирати зі статті одне: спершу налаштуйте середовище, потім просіть код. Тільки налаштовуйте те, чого агент не побачить сам: решту він прочитає в коді.
Перевірка, яку агент може запустити сам. Короткі інструкції проєкту, де лише те, чого він не знайде в коді. Правила для обов'язкової поведінки, скіли для знання на вимогу, хуки й заборони — для того, що має відбуватися завжди або ніколи. Облік завдань поруч із кодом. Свідоме ставлення до контексту — заради ціни й фокусу.
Робота разова, окупається в кожній сесії. І різниця між «агент постійно робить не те» і «агент робить що потрібно» зазвичай саме тут, а не в моделі й не у формулюванні чергового запиту.
І ще раз про те, з чого починав: усе це — промпти. Інструкції, правила, скіли, описи підагентів. Написані недбало, вони дають рівно той результат, який дають недбалі промпти, тільки ви платите за нього в кожній сесії, а не один раз. Техніки, які тут працюють, розібрано у статті про промпт-інжиніринг.
Про хуки — механізм, що робить поведінку агента детермінованою, — окрема стаття з усіма подіями і трьома робочими прикладами.