Claude Code — Best Practices

Привіт!

Тут раніше лежала стаття про практики роботи з Cursor. Я її переписав.

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

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

Усе впирається в контекст

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

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

Звідси висновок, з якого росте все інше. Контекстом треба керувати свідомо: вирішувати, що туди потрапить, а що ні. Не «хай накопичується, потім стиснеться».

Дайте агентові спосіб перевірити себе

Це перше, що варто налаштувати, і це ж найчастіше пропускають.

Агент зупиняється, коли робота має вигляд зробленої. Якщо перевірити її нічим, «має вигляд» — єдиний доступний сигнал, і перевіряльником стаєте ви. Кожна помилка чекає, поки ви її помітите.

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

Різниця видно просто у формулюванні завдання:

✗ зроби функцію валідації email

✓ зроби функцію валідації email. Приклади: [email protected] — правильно,
  invalid — ні, [email protected] — ні. Після реалізації запусти тести
  і покажи виведення

✗ збірка падає

✓ збірка падає ось із цим: [текст помилки]. Виправ причину, а не симптом,
  і переконайся, що збірка проходить

У мене в проєкті перевірка вшита в правило про коміт: перед комітом обов'язково проганяються перевірка типів, збірка і два валідатори контенту. Не «бажано», а обов'язково, зі вказівкою, що результат перевірок іде у звіт справжнім, а не «начебто все зелено».

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

Спершу розвідка, потім план, потім код

Якщо одразу просити код, отримаєте охайне розв'язання не того завдання.

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

План читайте очима. Це найдешевша точка втручання: виправити абзац плану — хвилина, переробити реалізацію — пів години.

Для великого завдання добре працює прийом «хай агент вас проінтерв'ює». Описуєте ідею одним абзацом і просите ставити питання: про реалізацію, про межові випадки, про те, чого ви могли не врахувати. Наприкінці — записати специфікацію у файл. Далі нова сесія з чистим контекстом і прохання реалізувати за цією специфікацією.

Хочу зробити [одне речення про фічу]. Проінтерв'юй мене докладно,
через інструмент питань.

Питай про реалізацію, інтерфейс, межові випадки, ризики й розміни.
Очевидного не питай, копай у складні місця, які я міг не врахувати.

Коли закінчимо — запиши повну специфікацію у SPEC.md.

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

Три рівні налаштування

Знання агентові передається трьома способами, і вони не взаємозамінні.

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

Хороший тест для кожного рядка: якщо це прибрати, агент почне помилятися? Ні — прибирайте.

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

---
paths:
  - "src/api/**/*.ts"
  - "apps/backend/**/*.ts"
---

# Правила для API

- Кожен ендпоїнт валідує вхід, без винятків.
- Помилки віддаються в спільному форматі з `ErrorResponse`.
- Новий ендпоїнт спершу описується в api.md, потім пишеться код.

Скіли — знання на вимогу. Каталог із файлом усередині; тіло потрапляє в контекст лише тоді, коли завдання йому відповідає або коли ви викликали скіл самі. Тому великі довідники мають бути скілами: у сплячому стані вони не коштують нічого.

Розкладка, якою користуюся я:

факт, потрібний завжди → інструкції проєкту;
обов'язкова поведінка → правило;
процедура або довідник, потрібні інколи → скіл;
те, що зобов'язане виконуватися завжди, без участі моделі → хук.

Останній пункт стоїть осібно. Усе, що вище, — текст, який модель читає і зазвичай виконує. Хук — код, який виконається незалежно від її рішення. Критична поведінка має бути хуком, а не абзацом в інструкціях. Розбір хуків з усіма подіями та робочими прикладами в мене в окремій статті.

І все це — промпти

Думка, до якої я дійшов не одразу, а варто було б від самого початку.

Інструкції проєкту, правила, скіли, описи підагентів — це не конфігурація. Це системні промпти, які хтось (ви) пише один раз, а модель читає в кожній сесії. Різниця між «агент постійно робить не те» і «агент працює передбачувано» дуже часто виявляється різницею між недбало й акуратно написаним промптом.

Що з технік промпт-інжинірингу справді окупається в цих файлах:

Структура та роздільники. Заголовки, переліки, явні блоки: модель розбирає структурований текст надійніше за суцільну прозу, а ви дістаєте змогу послатися на конкретний шматок з іншого правила. Докладніше про роздільники та структуру промпта.
Ієрархія правил. Коли правил більше п'яти, вони починають конфліктувати, і треба прямо написати, яке з них головніше. У мене, наприклад, правило «не комітити без прохання» стоїть вище за правило про перевірку перед комітом, і в тексті це сказано словами, а не мається на увазі. Про те, як задавати ієрархію правил, є окремий розділ.
Позитивні формулювання замість заборон. «Залиш зміни в робочому дереві й розкажи, що зробив» працює краще, ніж «не коміть». Самі лише заборони залишають модель без зразка поведінки.
Приклади замість описів. Пара «так погано / так добре» у правилі варта трьох абзаців пояснення. Це звичайний few-shot, просто застосований до конфігурації проєкту.
Явний формат відповіді. Якщо ви хочете певну форму звіту, її треба описати, а краще показати. Про контроль формату відповіді — там само.
Економія контексту. Кожен рядок інструкцій і правил оплачується в кожній сесії, тому зайве слово тут дорожче, ніж у звичайному промпті. Це рівно те, що в статті про промпти зветься контекст-інжинірингом.

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

Повний розбір технік — у статті про промпт-інжиніринг; далі за текстом я посилатимуся на конкретні розділи звідти.

Як це виглядає на живому проєкті

Далі показую на робочому репозиторії. Там зараз дев'ять правил, довідник з 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-endpoint
description: Процедура додавання HTTP-ендпоїнта: контракт, валідація, шари,
  тести, регенерація клієнта. Застосовувати під час створення нового
  ендпоїнта або модуля на бекенді.
---

# Новий ендпоїнт

1. Описати контракт в `api.md` — до коду, інакше файл і код розійдуться.
2. Контролер лише приймає й віддає; логіка в сервісі, доступ до даних
   у репозиторії.
3. Валідація входу обов'язкова, помилки — спільним форматом.
4. Тести: успішний шлях, відмова валідації, відсутність прав.
5. Перегенерувати клієнт фронтенду і перевірити, що він збирається.

## Чек-лист
- [ ] api.md оновлено до коду
- [ ] логіка поза контролером
- [ ] три тести на місці
- [ ] клієнт перегенеровано, збірка зелена

Опис — найважливіше поле: за ним агент вирішує, чи підходить скіл завданню. «Довідник з FastAPI» працює погано. «Архітектура і продакшн-практики FastAPI; застосовувати під час створення та рев'ю сервісів на FastAPI» — добре.

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

Вимоги як скіли. Скіл із вимогами має вигляд нормального документа аналітика. Сценарії зі своїми номерами, персонажі, межі, критерії приймання. Нічого «під агента» в ньому немає:

## 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 читає свій файл інструкцій, але вміє імпортувати AGENTS.md, тож обидва варіанти вживаються. Хороший вибір для команди, де різні люди працюють різними агентами. Обмеження те саме, що в інструкцій проєкту: це один файл, і роздувати його до довідника не можна.

Зовнішня вікі через MCP. Confluence, Notion, Linear і будь-що інше: документація лишається там, де її й так ведуть люди, а агент ходить туди по MCP-серверу. Аналітик править сторінку у звичному інтерфейсі, з коментарями та історією, а агент читає те саме. Платою йдуть мережа, акаунти й те, що версія документації живе окремо від версії коду: сторінка змінилася вчора, а гілка, яку ви лагодите, відповідає стану місячної давності.

Obsidian і його рідня. Локальне сховище markdown-файлів, до якого агента підключають або MCP-сервером, або просто відкриваючи йому каталог. Формат той самий plain-text, тому сховище можна тримати в гіті, а поверх нього працює і людина зі своїм графом посилань і пошуком, і агент. Люди використовують це як спільну пам'ять між інструментами та сесіями: нотатки, рішення, напрацювання в одному місці, доступному і Claude Code, і іншому агентові. Для особистої бази знань варіант чудовий. Для проєктної документації команди слабший: зв'язок із кодом знову втрачається, а сховище живе своїм життям.

Платформи документації з MCP і llms.txt. Сучасні сервіси на кшталт GitBook чи Mintlify віддають документацію одразу у двох виглядах: людський сайт і машиночитний шар, аж до автоматично піднятого MCP-сервера. Розумно, коли документація публічна і її все одно треба десь видавати.

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

Чим скіли виграють

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

Далі по дрібному, але приємно. Документація версіонується разом із кодом, і в старій гілці лежить та документація, яка відповідає старому коду. Правки проходять звичайне рев'ю в pull request'і. Нічого не треба налаштовувати, все працює офлайн, без токенів і зовнішніх сервісів. І формат стандартизується: той самий скіл можна віддати не лише Claude Code.

Чим розплачуєшся

Мінуси чесніше перелічити одразу.

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

Людям читати незручно. Усередині репозиторію немає ні пошуку по документації, ні змісту, ні коментарів на полях, ні зручної роботи з картинками. Аналітик, звиклий до Confluence, у GitHub по вимоги не піде. У мене це розв'язується тим, що вимоги править та сама людина, яка працює з агентом, але у великій команді це стане проблемою.

Немає спільного редагування й обговорення. Коментар до абзацу, обговорення просто в документі, сповіщення «вас згадали» — усього цього немає. Є pull request, що в рази формальніше.

Кілька репозиторіїв — кілька копій. Спільні для компанії практики доведеться або дублювати, або пов'язувати символічними посиланнями, або пакувати в плагін. У монорепозиторії проблеми немає, а от на п'яти репозиторіях вона помітна.

Спокуса звалити туди все. Скіли дешеві, тому в них легко накидати сто файлів і дістати ту саму мертву вікі, тільки в гіті. Один порятунок: опис, за яким агент обирає скіл. Якщо його написано недбало, документ не підтягнеться ніколи, і ви навіть не дізнаєтеся.

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

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

Скільки це коштує

Інструкції проєкту й правила завантажуються в кожну сесію цілком. У мене це 571 рядок інструкцій плюс 1245 рядків правил. Майже дві тисячі рядків до того, як ви надрукували перше слово.

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

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

Документація: як і де

Принцип простий. Уся документація, яку читає агент, живе в правилах і скілах. Окремої папки «доки для агента» немає взагалі — щоб не було двох джерел істини. Це рішення конкретного проєкту, а не єдино можливе: варіанти та їхню ціну я розібрав вище.

Що з цього випливає:

Правила й скіли — джерело істини. Агентові прямо заборонено вигадувати поведінку, що їм суперечить. Вважає документ неправим — каже людині, а не діє по-своєму.

Не правити документацію без прохання. Спершу видається дивним, потім виявляється необхідним: агент, що спіткнувся об незручне правило, охоче приведе правило у відповідність до своєї поведінки.

Нове — новий документ, зміна наявного — правка наявного. Інакше за пів року в проєкті два скіли про одне й те саме з різними версіями істини.

Єдиний шаблон. Є окремий скіл про те, як писати правила й скіли: структура, формулювання, роздільники, обов'язковий чек-лист наприкінці. Чек-лист перетворює опис на перевіряну вимогу, а заразом дає агентові спосіб самому перевірити, чи виконав він документ.

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

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-003
title: 'Sign-in loops on an expired token'
severity: P1
status: CONFIRMED
module: auth
area: 'sign-in / refresh token'
found: 2026-08-04
closed:
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 |

Деталі, важливі на практиці:

Номери вічні. Не використовуються повторно і не перенумеровуються ніколи: на них посилаються коміти, листування та інші записи.

Папки названо за вимогами. Область запису зветься так само, як файл вимог, який нею володіє: req-uc-auth → папка auth. Завдання й баги ділять ті самі папки. Дрібниця, але прибирає вічну суперечку «куди це покласти» і з'єднує трекер із документацією.

Закриття лише через git mv. Змінюється статус, ставиться дата, дописується рядок у журнал, файл переїжджає в папку закритих. Звичайне переміщення має в історії вигляд видалення плюс новий файл, і вся історія запису втрачається. Я це дізнався не з документації.

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

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

Що в трекер не потрапляє ніколи

Найважливіше правило обліку, і воно суперечить звичці: у трекері лише продукт.

Тест рівно один. Чи працює це в замовника? Застосунки, бібліотеки, з яких вони зібрані, дані, інфраструктура — так, це продукт.

Усе, що існує лише щоб нам було зручніше будувати продукт, не потрапляє в трекер узагалі. Ні завданням, ні багом, незалежно від обсягу роботи і від того, хто попросив. Документація репозиторію, правила, скіли, сам трекер і його скрипт, хуки, службові скрипти, налаштування CI, перекладання папок. Це просто робиться, а записом лишається коміт і автоматичний журнал сесії.

Формулювання в правилі звучить жорстко, і це навмисно:

Жодного запису взагалі — хоч би яким зламаним воно виглядало і скільки б роботи
не коштувало: застарілий документ, мертве посилання, хибний шлях у правилі,
дефект у цьому самому трекері або в службовому скрипті, хук, що неправильно
читає свій ввід, крива настройка CI, перейменована папка, правило,
про яке хтось попросив. До замовника нічого з цього не доїжджає,
отже це не баг. А перетворити його на завдання — та сама помилка під іншою
вивіскою. Не заводьте. Зробіть роботу, коміт скаже за неї.

Спокуса велика: роботи багато, хочеться, щоб вона була видна. Але трекер, напханий господарськими справами, ніхто не читає, а він заводився рівно заради читання.

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

Рішення

Поруч із завданнями лежать архітектурні рішення, по файлу на рішення. Формат звичайний, знайомий за ADR:

---
id: ADR-0001
title: Where user sessions are stored: database or cache
status: Proposed
date: 2026-07-31
deciders: Engineering lead / Architect
related:
  - 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-purpose
session 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/

Причому це має бути забороною на рівні інструмента, а не проханням у тексті. Різниця рівно та сама, що між правилом і хуком.

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

Підагенти

Підагент — окрема сесія зі своїм контекстом, своїми інструментами і своїм системним промптом. Робить частину роботи, повертає результат.

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

Свого підагента описують одним файлом:

---
name: security-reviewer
description: Рев'ю змін щодо вразливостей. Запускати перед
  релізом і за правок в авторизації, завантаженні файлів, роботі з БД.
tools: Read, Grep, Glob, Bash
model: opus
---

Ти старший інженер з безпеки. Дивись зміни щодо:
- ін'єкцій (SQL, XSS, команди оболонки);
- дір в автентифікації та авторизації;
- секретів у коді;
- небезпечної роботи з користувацькими даними.

Вказуй конкретні рядки і пропонуй виправлення. Стилістику не чіпай.

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

Друге застосування — незалежна перевірка. Той, хто писав код, поганий перевіряльник: він бачить не diff, а свої наміри. Просити підагента варто конкретно:

Підагентом перевір зміни проти PLAN.md. Переконайся, що кожну вимогу
реалізовано, що на перелічені межові випадки є тести і що
нічого поза завданням не змінилося. Пиши про прогалини, а не про смаки.

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

І про гроші. Підагенти дешевшими не бувають: кожен несе свій контекст і свою обв'язку. Віяло з десяти коштує приблизно як десять сесій. Правка в одному-двох файлах завжди швидша в основній сесії; делегувати має сенс читання багатьох файлів.

Окрема історія — кілька паралельних сесій. Найпростіше розводити їх по робочих деревах гіта: у кожної свій каталог і своя гілка, правки не стикаються. Схема «один пише, інший перевіряє» працює з тієї самої причини, що й підагент-рецензент: свіжий контекст не заражений міркуваннями автора.

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

Прийоми, якими користуюся постійно:

Нове завдання — чистий контекст. Очищення між незв'язаними завданнями дешевше за будь-яку оптимізацію. Хвіст чужого завдання — це і зайві токени, і зайві приводи відволіктися.

Дві невдалі спроби — стоп. Виправили двічі й усе ще не те? Річ уже не у формулюванні: контекст напханий невдалими підходами. Чиста сесія з точнішою постановкою майже завжди обганяє довгу з накопиченими виправленнями.

Стиснення налаштовується. Коли вікно закінчується, історія стискається автоматично. Можна попросити стиснути з акцентом на потрібному, а в інструкціях проєкту вказати, що зберігати обов'язково:

Під час стиснення контексту обов'язково зберігай: перелік змінених файлів,
команди запуску тестів і ухвалені архітектурні рішення з їхніми причинами.

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

Коротке питання вбік. Для дрібниці на кшталт «що робить цей прапорець» є режим, де відповідь не потрапляє в історію.

Рядок стану. Заповненість вікна краще тримати перед очима. Інакше ви помічаєте проблему в той момент, коли стиснення вже сталося.

Дозволи

За замовчуванням агент питає дозвіл на все, що змінює систему. Безпечно і нестерпно: після десятого підтвердження ви вже не читаєте, а клацаєте.

Способів скоротити три, різної радикальності. Перелік заздалегідь дозволених команд:

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Read(src/**)"
    ],
    "deny": [
      "Read(.env)",
      "Read(.secrets/**)",
      "Bash(git push:*)"
    ]
  }
}

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

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

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

Моделі, зусилля та гроші

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

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

---
name: dev-changelog
description: Зібрати changelog з історії комітів між двома тегами.
model: haiku
effort: low
disable-model-invocation: true
---

Окрема тема — ліміти підписки. Агент їх не бачить, тому не може співвідносити витрати: він однаково охоче запускає віяло підагентів і коли до скидання чотири години, і коли бюджет на межі. У мене це розв'язано хуком, який приносить живі цифри в контекст і забороняє віяльні запуски в гарячій зоні. Подробиці у статті про хуки.

MCP і консольні утиліти

Два способи дати агентові доступ до зовнішнього світу.

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

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

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

Що лишилося вірним із практик Cursor

Частина порад зі старої статті нікуди не поділася. Вони про роботу з моделлю взагалі.

Декомпозуйте і контролюйте кроки. Прохання «зроби все» дає код, який працює не так, як ви очікували, і розбиратися в ньому дорожче, ніж було б написати. Кроки мають бути самодостатніми: після кожного проєкт збирається.

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

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

Уточнюйте спосіб розв'язання заздалегідь. Одну річ можна зробити п'ятьма способами, і без уточнення вибір робить модель — на підставі того, що частіше траплялося в навчальних даних. Запитайте про варіанти й мінуси до того, як код написано.

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

Як усе зіпсувати

Зібрав ті способи, які бачу найчастіше. У себе зокрема.

Сесія-смітник. Почали з одного завдання, запитали про інше, повернулися до першого. Контекст напханий усім одразу.

Нескінченні виправлення. Агент зробив не те, ви виправили, знову не те. Після двох кіл дешевше почати заново.

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

Довіра без перевірки. Правдоподібна реалізація, що не покриває межові випадки. Перевірити нічим — не надсилайте.

Нескінченна розвідка. «Розберися, як тут усе влаштовано» без меж, і агент прочитав двісті файлів, а вікно скінчилося. Обмежуйте область або віддавайте розвідку підагентові.

Коротко

Якщо забирати зі статті одне: спершу налаштуйте середовище, потім просіть код.

Перевірка, яку агент може запустити сам. Короткі інструкції проєкту, де лише те, чого він не виведе з коду. Правила для обов'язкової поведінки, скіли для знання на вимогу, хуки для того, що має відбуватися завжди. Облік завдань поруч із кодом. Свідоме ставлення до контексту.

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

І ще раз про те, з чого починав: усе це — промпти. Інструкції, правила, скіли, описи підагентів. Написані недбало, вони дають рівно той результат, який дають недбалі промпти, тільки ви платите за нього в кожній сесії, а не один раз. Техніки, які тут працюють, розібрано у статті про промпт-інжиніринг.

Про хуки — механізм, що робить поведінку агента детермінованою, — окрема стаття з усіма подіями і трьома робочими прикладами.