--- title: "Claude Code — Best Practices" url: "https://romankryvolapov.com/uk/claude-code-best-practices/" description: "Як організувати роботу з Claude Code: інструкції проєкту, правила та скіли, трекер завдань і багів у репозиторії, план перед кодом, підагенти, контекст, дозволи й витрати бюджету." language: uk updated: 2026-08-06 --- **Привіт!** Тут раніше лежала стаття про практики роботи з Cursor. Я її переписав. Річ не в тім, що Cursor став гіршим. Змінився сам спосіб роботи: агент більше не «розумне автодоповнення», а виконавець, якому ви готуєте робоче місце, і від того, наскільки добре це місце підготовлено, результат залежить куди сильніше, ніж від того, як гарно ви сформулювали запит. Далі — про Claude Code. Що покласти в репозиторій, як планувати роботу, як не спалити контекст і гроші. Приклади взято з робочого проєкту, де все це налаштовано й обкатано на кількох місяцях реальної розробки; числа теж звідти, а не з голови. ## Усе впирається в контекст У моделі є контекстне вікно, і в нього вміщується вся сесія цілком: ваші повідомлення, кожен прочитаний файл, виведення кожної команди, зокрема той трьохсотрядковий лог, який агент вивів один раз і більше до нього не повертався. Одне налагодження легко з'їдає десятки тисяч токенів. Проблема навіть не в тому, що вікно скінчиться. Якість падає задовго до цього: ближче до кінця довгої сесії агент починає забувати ранні домовленості і частіше помиляється, бо потрібна вказівка тоне серед сотень кілобайтів прочитаного коду, і жодна наполегливість у формулюваннях цього не лікує. Звідси висновок, з якого росте все інше. Контекстом треба керувати свідомо: вирішувати, що туди потрапить, а що ні. Не «хай накопичується, потім стиснеться». ## Дайте агентові спосіб перевірити себе Це перше, що варто налаштувати, і це ж найчастіше пропускають. Агент зупиняється, коли робота має вигляд зробленої. Якщо перевірити її нічим, «має вигляд» — єдиний доступний сигнал, і перевіряльником стаєте ви. Кожна помилка чекає, поки ви її помітите. Дайте щось з однозначним «пройшло / не пройшло», і цикл замкнеться сам. Агент править, запускає перевірку, читає результат, повторює. Перевіркою може бути набір тестів, код повернення збірки, лінтер, скрипт порівняння з еталоном, скріншот для звірки з макетом. Різниця видно просто у формулюванні завдання: ```text ✗ зроби функцію валідації email ✓ зроби функцію валідації email. Приклади: user@example.com — правильно, invalid — ні, user@.com — ні. Після реалізації запусти тести і покажи виведення ✗ збірка падає ✓ збірка падає ось із цим: [текст помилки]. Виправ причину, а не симптом, і переконайся, що збірка проходить ``` У мене в проєкті перевірка вшита в правило про коміт: перед комітом обов'язково проганяються перевірка типів, збірка і два валідатори контенту. Не «бажано», а обов'язково, зі вказівкою, що результат перевірок іде у звіт справжнім, а не «начебто все зелено». І просіть показувати доказ: виведення тестів, саму команду, скріншот. Прочитати доказ швидше, ніж переперевіряти руками. А для сесії, за якою ви не стежили, це взагалі єдиний спосіб зрозуміти, що сталося. ## Спершу розвідка, потім план, потім код Якщо одразу просити код, отримаєте охайне розв'язання не того завдання. У Claude Code є окремий режим планування: агент читає файли, відповідає на питання, але нічого не змінює. Робочий цикл виходить такий: розібратися в потрібній частині коду → скласти план → вийти з режиму планування → реалізувати → коміт. План читайте очима. Це найдешевша точка втручання: виправити абзац плану — хвилина, переробити реалізацію — пів години. Для великого завдання добре працює прийом «хай агент вас проінтерв'ює». Описуєте ідею одним абзацом і просите ставити питання: про реалізацію, про межові випадки, про те, чого ви могли не врахувати. Наприкінці — записати специфікацію у файл. Далі нова сесія з чистим контекстом і прохання реалізувати за цією специфікацією. ```text Хочу зробити [одне речення про фічу]. Проінтерв'юй мене докладно, через інструмент питань. Питай про реалізацію, інтерфейс, межові випадки, ризики й розміни. Очевидного не питай, копай у складні місця, які я міг не врахувати. Коли закінчимо — запиши повну специфікацію у SPEC.md. ``` Тільки не перетворюйте це на ритуал. Якщо правку можна описати одним реченням, план не потрібен: зайве коло коштує дорожче, ніж користь від нього. ## Три рівні налаштування Знання агентові передається трьома способами, і вони не взаємозамінні. **Інструкції проєкту** читаються на початку кожної сесії. Сюди йдуть факти, потрібні завжди: як зібрати, як запустити тести, чим цей проєкт відрізняється від типового. Рекомендація Anthropic — триматися в межах двохсот рядків, і це не формальність. Що довший файл, то гірше дотримуються його ж вказівок. Хороший тест для кожного рядка: якщо це прибрати, агент почне помилятися? Ні — прибирайте. **Правила** лежать окремими файлами в каталозі правил, по файлу на тему, і завантажуються так само. Їх можна обмежити масками шляхів, і тоді правило підтягнеться лише коли агент чіпає відповідні файли: ```markdown title=".claude/rules/api-endpoints.md" --- paths: - "src/api/**/*.ts" - "apps/backend/**/*.ts" --- # Правила для API - Кожен ендпоїнт валідує вхід, без винятків. - Помилки віддаються в спільному форматі з `ErrorResponse`. - Новий ендпоїнт спершу описується в api.md, потім пишеться код. ``` **Скіли** — знання на вимогу. Каталог із файлом усередині; тіло потрапляє в контекст лише тоді, коли завдання йому відповідає або коли ви викликали скіл самі. Тому великі довідники мають бути скілами: у сплячому стані вони не коштують нічого. Розкладка, якою користуюся я: - факт, потрібний завжди → інструкції проєкту; - обов'язкова поведінка → правило; - процедура або довідник, потрібні інколи → скіл; - те, що зобов'язане виконуватися завжди, без участі моделі → хук. Останній пункт стоїть осібно. Усе, що вище, — текст, який модель читає і зазвичай виконує. Хук — код, який виконається незалежно від її рішення. Критична поведінка має бути хуком, а не абзацом в інструкціях. Розбір хуків з усіма подіями та робочими прикладами в мене в [окремій статті](/uk/claude-code-hooks/). ### І все це — промпти Думка, до якої я дійшов не одразу, а варто було б від самого початку. Інструкції проєкту, правила, скіли, описи підагентів — це не конфігурація. Це системні промпти, які хтось (ви) пише один раз, а модель читає в кожній сесії. Різниця між «агент постійно робить не те» і «агент працює передбачувано» дуже часто виявляється різницею між недбало й акуратно написаним промптом. Що з технік промпт-інжинірингу справді окупається в цих файлах: - **Структура та роздільники.** Заголовки, переліки, явні блоки: модель розбирає структурований текст надійніше за суцільну прозу, а ви дістаєте змогу послатися на конкретний шматок з іншого правила. Докладніше про [роздільники та структуру промпта](/uk/prompt-engineering/#Delimiters-and-structure). - **Ієрархія правил.** Коли правил більше п'яти, вони починають конфліктувати, і треба прямо написати, яке з них головніше. У мене, наприклад, правило «не комітити без прохання» стоїть вище за правило про перевірку перед комітом, і в тексті це сказано словами, а не мається на увазі. Про те, як задавати [ієрархію правил](/uk/prompt-engineering/#Rule-hierarchy), є окремий розділ. - **Позитивні формулювання замість заборон.** «Залиш зміни в робочому дереві й розкажи, що зробив» працює краще, ніж «не коміть». Самі лише заборони залишають модель без зразка поведінки. - **Приклади замість описів.** Пара «так погано / так добре» у правилі варта трьох абзаців пояснення. Це звичайний [few-shot](/uk/prompt-engineering/#Few-shot-examples), просто застосований до конфігурації проєкту. - **Явний формат відповіді.** Якщо ви хочете певну форму звіту, її треба описати, а краще показати. Про [контроль формату відповіді](/uk/prompt-engineering/#Output-format-control) — там само. - **Економія контексту.** Кожен рядок інструкцій і правил оплачується в кожній сесії, тому зайве слово тут дорожче, ніж у звичайному промпті. Це рівно те, що в статті про промпти зветься [контекст-інжинірингом](/uk/prompt-engineering/#Context-engineering). Ще одне спостереження з практики: описувати треба не лише що робити, а й **яку помилку правило запобігає**. Модель, яка розуміє, від чого її страхують, набагато краще застосовує правило до ситуації, не описаної дослівно. Половина моїх правил тому починається з абзацу «відомий сценарій провалу має такий вигляд». Повний розбір технік — у статті [про промпт-інжиніринг](/uk/prompt-engineering/); далі за текстом я посилатимуся на конкретні розділи звідти. ## Як це виглядає на живому проєкті Далі показую на робочому репозиторії. Там зараз дев'ять правил, довідник з API, сто два скіли й трекер завдань просто в проєкті. Усе це виросло не одразу, а із ситуацій, коли те саме доводилося пояснювати втретє. ### Правила Правило — те, що агент зобов'язаний дотримувати завжди. Кожне лежить окремим файлом і закінчується чек-листом: за ним видно, дотримано його чи ні. Ось як має вигляд правило цілком, найкоротше з моїх: ```markdown title=".claude/rules/never-commit-unless-asked.md" # Жодних комітів, доки не попросили **Не запускати `git commit` (а також push, PR, merge), доки користувач не попросив про це прямо, своїми словами.** Закінчена робота, зелена збірка й відчуття «начебто готово» дозволом не є. Зробив правки — залиш їх у робочому дереві, коротко розкажи, що змінилося, і зупинися. Сумніваєшся, просили чи ні, — не коміть, запитай. ## Чек-лист - [ ] Жодного коміту, push чи PR без явного прохання своїми словами. - [ ] Роботу залишено в робочому дереві, зміни описано. - [ ] За сумніву поставлено питання, а не зроблено коміт. ``` Має вигляд перебору. До першого разу, коли агент вирішує, що раз тести зелені, то можна й закомітити, і забирає в історію ваші недороблені експерименти. Далі пройдуся рештою восьми. Оригінали в мене написані англійською (так історично склалося, правила переїжджали між проєктами), тому цитати наводжу в перекладі. #### Перевірка перед комітом Найдовше правило, набуває чинності коли коміт таки попросили. Чотири стадії: прочитати весь diff шматками; розібрати все, чого зміни стосуються поза межами diff, тобто код, що викликає, контракти й документацію, яка від цих правок щойно застаріла; пополювати на дефекти; винести вердикт. Вердиктів рівно три, і написані вони так, щоб агентові не було куди викрутитися: ```text PASS — не знайдено нічого, або все знайдене вже виправлено й переперевірено. FIX, ПОТІМ PASS — є справжні, але полагоджувані знахідки. Лагодь їх сам, негайно, прожени перевірку заново по виправленому стану і чесно розкажи розробникові, що знайшов і що полагодив. Лагодити — поведінка за замовчуванням: проблеми ніколи не «лишають на потім» і ніколи не обмежуються згадкою у звіті. STOP — серйозна проблема (втрата даних, діра в безпеці, зламаний контракт, зміна суперечить власній вимозі) або справжня розвилка, де обидві конструкції захисні і вибір належить розробникові. Коміту немає. Поясни просто й конкретно, у чому проблема. ``` Далі йде фраза, яку я вважаю найкориснішою в усьому правилі: виправлення, зроблене під час перевірки, само є зміною і проходить ті самі чотири стадії заново. Повторювати, доки черговий повний прохід не знайде нічого нового. Тільки цей стан вважається чистим. Ще зазначено, що `--no-verify` заборонено: хук, що впав, лагодять, а не глушать. Окремо скажу про прийом, який тут працює. Стадії пронумеровано, у кожної свій перелік того, що перевіряти, а наприкінці — обов'язковий вердикт одним словом. Це той самий [контроль формату відповіді](/uk/prompt-engineering/#Output-format-control), що й у звичайних промптах: моделі значно важче «приблизно перевірити» і сказати «начебто нормально», коли від неї вимагається обрати один із трьох позначених результатів. #### Стиль відповіді Правило про те, як зі мною розмовляти. Починається воно так: ```text Користувач — людина, що читає чат, а не Claude Code. У нього НЕ відкрито вихідний код паралельно, і він НЕ хоче розшифровувати ідентифікатори коду, імена полів і шляхи до файлів усередині відповіді. Говори з ним як колега, а не як інструмент код-рев'ю. Вважай, що читач — компетентний розробник, який НЕ занурений у цей проєкт. Він уміє писати код, але, найпевніше, веде кілька проєктів одразу і не тримає специфіку цього в голові. ``` Далі — перелік того, що заборонено за замовчуванням: фрагменти коду, посилання виду «файл:рядок», імена полів і класів, великі таблиці, ASCII-діаграми. Усе це дозволено, лише якщо я прямо попросив. Окремий шматок описує формат фінального звіту: зроблено / лишилося / що потрібно від людини. І там-таки приклад, узятий із життя: ```text ✗ «Лишилося: своє дерево міграцій з перевіркою розбіжності, образ і маніфест, проводка у скрипті запуску.» ✓ «Лишилося: - Описати зміни бази окремими кроками оновлення: зараз таблиця створюється на льоту, і на справжньому сервері її просто не буде. - Зібрати образ і додати в опис кластера, інакше нікуди розгортати. - Прописати сервіс у скрипті запуску, щоб піднімався разом з рештою.» ``` Три різні справи, зліплені в один рядок словами, зрозумілими лише тому, хто їх щойно написав. Читач кивне і не прочитає, а потім виявиться, що він погодився на те, чого не зрозумів. Пара «погано / добре» тут працює краще за будь-який опис, і це рівно [few-shot](/uk/prompt-engineering/#Few-shot-examples): один показаний приклад замінює абзац пояснень про самодостатність формулювань. #### Бюджет сесії ```text Витрачай токени пропорційно до реальної складності завдання — найдешевшим шляхом, який надійно його розв'язує, а не найретельнішим, який дозволив би бюджет. Ліміти — це огорожа: вони показують, де ти впрешся у стіну або в обмеження частоти, щоб зупинитися заздалегідь, а не бюджет, який треба освоїти. ЗЕЛЕНА зона НЕ означає «пали вільно». ``` Далі в правилі таблиця класів завдань: тривіальне — правимо одразу, без роздумів і розвідки; маленьке — точкові читання, усе в одному потоці; середнє — один прохід планування і високі зусилля лише на складній розвилці; велике — фазами, з контрольною точкою між ними. І окремий розділ про підагентів із прямим підрахунком: віяло з N агентів коштує як N сесій, тому запускати їх має сенс лише заради явної економії. Це правило працює в парі з хуком, який приносить живі цифри лімітів, — про нього докладно у статті про хуки. #### Сумніваєшся — шукай в інтернеті Коротке правило, сімнадцять рядків, і майже все в ньому — опис одного сценарію: ```text Відомий сценарій провалу, якого треба уникнути: щось не працює → ти застосовуєш виправлення, засноване на тому, що «знаєш» → все одно не працює → кожне наступне виправлення закопує розв'язання, побудоване на хибному припущенні. Тому в УСІХ сумнівних випадках — коли щось неясно, неочевидно, поводиться не так, як ти очікував, або розходиться з твоїми знаннями — ЗАВЖДИ шукай в інтернеті, перш ніж лагодити далі, і дивись насамперед на свіжу офіційну документацію. Якщо і пошук не дав розв'язання — ЗУПИНИСЯ і запитай користувача. ``` Зверніть увагу на структуру: спершу описано провал, потім вимогу. Так правило застосовується і до ситуацій, які в ньому дослівно не описані, бо модель розуміє, від чого її страхують. #### Підтягнути гілку перед роботою ```text Ціна пропуску — не конфлікт злиття наприкінці. Це робота, побудована на базі, якої більше немає: баг, уже полагоджений кимось іншим; рев'ю коду, який відтоді змінився; номер запису в трекері або часова позначка міграції, вже зайняті; рішення, ухвалене за файлом двотижневої давності. Нічого з цього не спливе, доки роботу не буде закінчено. ``` Далі три кроки: отримати зміни й подивитися, наскільки гілка відстала; перемотати; прочитати те, що прийшло, якщо воно стосується вашої області. І окремий розділ на випадок брудного робочого дерева. #### Зупинятися на архітектурних розвилках Мабуть, найцінніше правило з усіх. Починається з формулювання, яке мені подобається: ```text Частина рішень — це правка. Частина — переписування. Це правило про другий тип. Коли ти помічаєш, що роботу можна розумно побудувати більш ніж одним способом і вибір дорого скасовувати, — зупинися перш ніж писати код, розберися в картині цілком і поклади розвилку перед розробником з передісторією та розкладеними варіантами. Мовчки обрати і піти далі — ось провал, якому це правило запобігає: його ціна не видна в diff, вона спливає місяці по тому у вигляді роботи, яку доведеться викинути. ``` Далі — ознаки, за якими рішення вважається розвилкою: важко скасувати; розходиться більш ніж на один компонент або команду; визначає, хто чим володіє і де проходить межа довіри; змінює те, що видно ззовні (розгорнутий компонент, схему даних, контракт API); зачіпає гроші, безпеку чи приватність. Дві ознаки й більше — стоп. А ось друга половина правила, без якої перша шкідлива: ```text Підняти розвилку коштує розробникові справжньої уваги. Перш ніж піднімати: — Оборотно протягом дня? → вирішуй сам. — Проєкт уже ухвалював рівнозначне рішення? → дотримуйся його; прецедент важливіший за вподобання. — Тебе влаштував би будь-який з варіантів? → це не розвилка, це смак. Обирай. — Неясно лише тому, що ти не подивився? → спершу подивися. Більшість «розвилок» розчиняється під час читання. Очікуй у проєкті кілька справжніх розвилок, а не по одній на завдання. Якщо ти піднімаєш їх щотижня — фільтр налаштовано неправильно. ``` Без цього фільтра правило перетворюється на свою протилежність: агент починає питати з будь-якого приводу, людина перестає читати питання і пропускає те єдине, яке було важливим. #### Символьна навігація У проєкті підключено сервер, що дає перехід до визначення, пошук використань і правку за символом. Правило вимагає користуватися ним замість читання файлів цілком, і центральна його частина — таблиця відповідностей: ```text | Завдання | Інструмент | Замість чого | | Зрозуміти API файлу | огляд символів | читання всього файлу | | Знайти клас або функцію | пошук символа | grep за іменем | | Прочитати тіло одного символа | символ із тілом | читання з відступом | | Дізнатися, хто це викликає | пошук посилань | grep за іменем | | Перейменувати по всьому проєкту | перейменування символа | десятків правок | ``` Далі — розділ «коли звичайні інструменти правильний вибір». Це важлива половина: у мовного сервера є мови, яких він не розуміє, і чесно перелічити їх корисніше, ніж вимагати неможливого. #### Облік робіт Дев'яте правило — про трекер: що потрапляє в завдання й баги, що не потрапляє ніколи, як пов'язані записи й вимоги. Воно велике, і розбираю я його нижче окремим розділом, бо там цікаве не так формулювання, як сама схема обліку. ### Скіли — це документація Головна думка розділу: скіли в мене не «плагіни для агента», а документація проєкту. Та сама, яку раніше писали у вікі й ніхто не відкривав. Документація у вікі живе окремо від коду і повільно з ним розходиться. Документація в репозиторії правиться в тому самому pull request'і, що й код, і її читає виконавець. Причому вибірково: тіло скіла потрапляє в контекст лише тоді, коли завдання йому відповідає. Двадцять шість тисяч рядків документації не коштують нічого, доки не знадобилися. **Префікс в імені — це адресат.** Скіли розкладено не за темами, а за тим, чиїй команді адресовано: ```text .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: ```markdown title=".claude/skills/dev-backend-new-endpoint/SKILL.md" --- name: dev-backend-new-endpoint description: Процедура додавання HTTP-ендпоїнта: контракт, валідація, шари, тести, регенерація клієнта. Застосовувати під час створення нового ендпоїнта або модуля на бекенді. --- # Новий ендпоїнт 1. Описати контракт в `api.md` — до коду, інакше файл і код розійдуться. 2. Контролер лише приймає й віддає; логіка в сервісі, доступ до даних у репозиторії. 3. Валідація входу обов'язкова, помилки — спільним форматом. 4. Тести: успішний шлях, відмова валідації, відсутність прав. 5. Перегенерувати клієнт фронтенду і перевірити, що він збирається. ## Чек-лист - [ ] api.md оновлено до коду - [ ] логіка поза контролером - [ ] три тести на місці - [ ] клієнт перегенеровано, збірка зелена ``` Опис — найважливіше поле: за ним агент вирішує, чи підходить скіл завданню. «Довідник з FastAPI» працює погано. «Архітектура і продакшн-практики FastAPI; застосовувати під час створення та рев'ю сервісів на FastAPI» — добре. По суті це маленький промпт маршрутизації: він має містити і предмет, і умову спрацювання. Тіло скіла при цьому тримають коротким, бо після завантаження воно лишається в контексті до кінця ходу й оплачується кожним наступним повідомленням. Тут працюють ті самі міркування, що й у [контекст-інжинірингу](/uk/prompt-engineering/#Context-engineering): довгий довідник краще розбити, винісши деталі в сусідні файли, на які скіл посилається. **Вимоги як скіли.** Скіл із вимогами має вигляд нормального документа аналітика. Сценарії зі своїми номерами, персонажі, межі, критерії приймання. Нічого «під агента» в ньому немає: ```markdown title=".claude/skills/req-uc-auth/SKILL.md (фрагмент)" ## 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 рядків правил. Майже дві тисячі рядків до того, як ви надрукували перше слово. Помітно більше за рекомендоване, і плачу я за це контекстом. Розміняв свідомо: передбачуваність у проєкті з кількома застосунками й спільною інфраструктурою дорожча за заощаджені токени. Але в розміну є межа. Якби файл ріс далі, я б розтягнув правила за масками шляхів. До речі, якщо агент уперто порушує якесь правило — річ майже завжди не у формулюванні, а в обсязі. Правило загубилося. Лікується скороченням, а не додаванням великих літер. ## Документація: як і де Принцип простий. Уся документація, яку читає агент, живе в правилах і скілах. Окремої папки «доки для агента» немає взагалі — щоб не було двох джерел істини. Це рішення конкретного проєкту, а не єдино можливе: варіанти та їхню ціну я розібрав вище. Що з цього випливає: **Правила й скіли — джерело істини.** Агентові прямо заборонено вигадувати поведінку, що їм суперечить. Вважає документ неправим — каже людині, а не діє по-своєму. **Не правити документацію без прохання.** Спершу видається дивним, потім виявляється необхідним: агент, що спіткнувся об незручне правило, охоче приведе правило у відповідність до своєї поведінки. **Нове — новий документ, зміна наявного — правка наявного.** Інакше за пів року в проєкті два скіли про одне й те саме з різними версіями істини. **Єдиний шаблон.** Є окремий скіл про те, як писати правила й скіли: структура, формулювання, роздільники, обов'язковий чек-лист наприкінці. Чек-лист перетворює опис на перевіряну вимогу, а заразом дає агентові спосіб самому перевірити, чи виконав він документ. Цей скіл, по суті, звід технік промпт-інжинірингу, прикладений до конфігурації проєкту, і правило вимагає застосовувати його під час створення чи правки будь-якого правила й будь-якого скіла. Звучить бюрократично, але окупається: документи, написані за одним шаблоном, рідше суперечать одне одному й краще дотримуються. Розбір самих технік — у статті [про промпт-інжиніринг](/uk/prompt-engineering/). **README для людей, інструкції для агента.** Обидва потрібні, але читачі різні. README пояснює новій людині, що тут відбувається; агент спирається на інструкції, правила та скіли. Змінюється структура проєкту — правляться обидва, інакше розробник і агент живуть у різних уявленнях про репозиторій. **Технічні довідники окремо.** Розгортання, міграції, результати навантажувальних тестів лежать у звичайній папці документації в корені. Агентові в роботі над кодом вони не потрібні, а людині потрібні епізодично. ## Трекер завдань і багів просто в репозиторії Найсвоєрідніша частина моєї конфігурації. Завдання й баги лежать у репозиторії звичайними markdown-файлами, по файлу на запис. Жодної бази, жодного вебінтерфейсу, жодних перевірок у CI. Скрипт уміє дві речі: завести запис і перезібрати індекс. На цьому автоматизація закінчується. ```text 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 ``` Що це дає. Агент бачить завдання цілком, не виходячи з проєкту, разом із вимогою, на яку воно посилається, і кодом, який воно править; запис живе в тій самій історії, що й код, тому завжди видно, яким комітом його закрито і що по ньому змінювалося дорогою. Дві людини (або два агенти) над різними записами фізично не редагують один файл, тож конфліктів злиття не буває за побудовою — це, мабуть, головний аргумент проти одного великого файлу з переліком завдань, до якого всі звикли. Плюс усе працює офлайн, без акаунтів і токенів. ### Як має вигляд запис Ось справжній шаблон бага, тільки з вигаданим змістом: ```markdown title="management/bugs/auth/BUG-003-sign-in-loops-on-expired-token.md" --- 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. ``` Заводиться командою, а не копіюванням файлу руками: ```bash 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" ``` Скрипт видає наступний вільний номер, кладе файл у папку модуля і перезбирає індекс місяця. Індекс має такий вигляд: ```markdown title="management/tasks/INDEX-AUGUST-2026.md" # 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, перекладання папок. Це просто робиться, а записом лишається коміт і автоматичний журнал сесії. Формулювання в правилі звучить жорстко, і це навмисно: ```text Жодного запису взагалі — хоч би яким зламаним воно виглядало і скільки б роботи не коштувало: застарілий документ, мертве посилання, хибний шлях у правилі, дефект у цьому самому трекері або в службовому скрипті, хук, що неправильно читає свій ввід, крива настройка CI, перейменована папка, правило, про яке хтось попросив. До замовника нічого з цього не доїжджає, отже це не баг. А перетворити його на завдання — та сама помилка під іншою вивіскою. Не заводьте. Зробіть роботу, коміт скаже за неї. ``` Спокуса велика: роботи багато, хочеться, щоб вона була видна. Але трекер, напханий господарськими справами, ніхто не читає, а він заводився рівно заради читання. Другий поділ — завдання проти багів. Усе, що знайшло тестування, це баг, і тільки баг. Виправлення бага не породжує завдання. Завдання — нова функціональність або переробка наявної, про яку попросили. ### Рішення Поруч із завданнями лежать архітектурні рішення, по файлу на рішення. Формат звичайний, знайомий за ADR: ```markdown title="management/decisions/ADR-0001-session-storage.md (структура)" --- 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 несе посилання на місце в коді, звідки його взято. Користь проста: суперечка, яка розв'язується один раз, потім не спливає заново кожні два місяці. ### Журнал сесій, що пишеться сам Третя частина обліку, і її ніхто не веде руками. Хук записує все, що відбувалося в сесії: ваші запити, питання агента і що ви обрали, статистику по кожному ходу, змінені файли з кількістю рядків, фінальний звіт. Файл на сесію, папка на день, папка на розробника. Має такий вигляд: ```text title="management/logs/roman/2026-08-06/a1b2c3d4.log" 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. Поділ виходить такий. У зовнішній системі — планування і звітність для менеджера. У репозиторії — те, що потрібне виконавцеві в момент роботи, разом із кодом і вимогами. ## Чого бракує: ролі Раз уже я розклав скіли за префіксами під різні команди, скажу і про те, чого для цієї схеми бракує в самому інструменті. Префікс в імені — домовленість, а не механізм. Аналітик, тестувальник і розробник працюють в одному репозиторії і отримують ту саму конфігурацію: однакові інструкції, увесь набір скілів, однакові права на запис. Три неприємності, і всі три я бачив наживо. Аналітик просить звірити специфікацію з кодом, а агент, навантажений інструкціями для розробника, починає правити вихідники. Тестувальник просить відтворити дефект, а в спільних інструкціях написано «перед перевіркою застосуй міграції», і агент чесно застосовує їх на спільному стенді. І тихіше, але дорожче: усі платять контекстом за всі скіли, зокрема ті, яких їхня робота не стосується ніколи. Обхідний шлях очевидний і поганий: кожен заводить особисту конфігурацію в себе в домашній папці. Вона не в репозиторії, її ніхто не рев'ює, у новачка її просто немає. Правильне розв'язання — зробити роль повноцінним шаром конфігурації в репозиторії. Своя частина інструкцій, свій набір скілів і агентів, свої дозволи і, головне, своя область запису, за межі якої правки не виходять: ```text .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/ ``` Причому це має бути забороною на рівні інструмента, а не проханням у тексті. Різниця рівно та сама, що між правилом і хуком. Я оформив це [запитом на додавання ролей](https://github.com/anthropics/claude-code/issues/81615) у Claude Code: з описом проблеми, схемою злиття налаштувань (роль може лише звужувати проєктні права, але не розширювати), способами обрати роль і мінімальною корисною версією. Якщо біль знайомий, зайдіть підтримати — що більше підтверджень, то вищий шанс, що до цього дійдуть руки. ## Підагенти Підагент — окрема сесія зі своїм контекстом, своїми інструментами і своїм системним промптом. Робить частину роботи, повертає результат. Головна користь не у швидкості, а в чистоті контексту. Агент, що розбирається в незнайомому коді, прочитає десятки файлів, і все це осяде у вашій сесії. Підагент читає їх у себе і повертає висновки. Свого підагента описують одним файлом: ```markdown title=".claude/agents/security-reviewer.md" --- name: security-reviewer description: Рев'ю змін щодо вразливостей. Запускати перед релізом і за правок в авторизації, завантаженні файлів, роботі з БД. tools: Read, Grep, Glob, Bash model: opus --- Ти старший інженер з безпеки. Дивись зміни щодо: - ін'єкцій (SQL, XSS, команди оболонки); - дір в автентифікації та авторизації; - секретів у коді; - небезпечної роботи з користувацькими даними. Вказуй конкретні рядки і пропонуй виправлення. Стилістику не чіпай. ``` Тіло такого файлу — системний промпт окремої моделі, а не нотатка для себе. Працює все те саме: задана роль, явні межі («стилістику не чіпай»), формат відповіді й умова виклику в описі. Про те, як писати промпти для агентів і виклику інструментів, є [окремий розділ](/uk/prompt-engineering/#Agentic-and-tools) у статті про промпти. Друге застосування — незалежна перевірка. Той, хто писав код, поганий перевіряльник: він бачить не diff, а свої наміри. Просити підагента варто конкретно: ```text Підагентом перевір зміни проти PLAN.md. Переконайся, що кожну вимогу реалізовано, що на перелічені межові випадки є тести і що нічого поза завданням не змінилося. Пиши про прогалини, а не про смаки. ``` Застереження, яке краще знати заздалегідь: перевіряльник, якого попросили знайти недоліки, їх знайде. Навіть коли роботу зроблено добре, бо його про це попросили. Гнатися за кожним зауваженням — прямий шлях до зайвих шарів абстракції й тестів на неможливі випадки. І про гроші. Підагенти дешевшими не бувають: кожен несе свій контекст і свою обв'язку. Віяло з десяти коштує приблизно як десять сесій. Правка в одному-двох файлах завжди швидша в основній сесії; делегувати має сенс читання багатьох файлів. Окрема історія — кілька паралельних сесій. Найпростіше розводити їх по робочих деревах гіта: у кожної свій каталог і своя гілка, правки не стикаються. Схема «один пише, інший перевіряє» працює з тієї самої причини, що й підагент-рецензент: свіжий контекст не заражений міркуваннями автора. ## Контекст на практиці Прийоми, якими користуюся постійно: **Нове завдання — чистий контекст.** Очищення між незв'язаними завданнями дешевше за будь-яку оптимізацію. Хвіст чужого завдання — це і зайві токени, і зайві приводи відволіктися. **Дві невдалі спроби — стоп.** Виправили двічі й усе ще не те? Річ уже не у формулюванні: контекст напханий невдалими підходами. Чиста сесія з точнішою постановкою майже завжди обганяє довгу з накопиченими виправленнями. **Стиснення налаштовується.** Коли вікно закінчується, історія стискається автоматично. Можна попросити стиснути з акцентом на потрібному, а в інструкціях проєкту вказати, що зберігати обов'язково: ```markdown title="CLAUDE.md" Під час стиснення контексту обов'язково зберігай: перелік змінених файлів, команди запуску тестів і ухвалені архітектурні рішення з їхніми причинами. ``` **Відкат замість обережності.** Кожен ваш запит — точка повернення, повернути можна і листування, і файли. Це змінює стиль роботи: замість довгого обмірковування ризикованого кроку простіше спробувати й відкотитися. Тільки пам'ятайте, що відкат не замінює гіт: зміни через командний рядок він не відстежує. **Коротке питання вбік.** Для дрібниці на кшталт «що робить цей прапорець» є режим, де відповідь не потрапляє в історію. **Рядок стану.** Заповненість вікна краще тримати перед очима. Інакше ви помічаєте проблему в той момент, коли стиснення вже сталося. ## Дозволи За замовчуванням агент питає дозвіл на все, що змінює систему. Безпечно і нестерпно: після десятого підтвердження ви вже не читаєте, а клацаєте. Способів скоротити три, різної радикальності. Перелік заздалегідь дозволених команд: ```json title=".claude/settings.json" { "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. Воно було важливим і до агентів, а зараз важливіше: модель охоче править те, про що не просили, і заразом упорядковує сусідній файл. Корисна деталь про хуки: заборона з хука сильніша за будь-який режим дозволів, вона спрацює навіть там, де підтвердження вимкнено зовсім. Тому те, що не можна чіпати за жодних обставин, закривається хуком, а не проханням. ## Моделі, зусилля та гроші Робота агента складається з кроків дуже різної складності. Розібратися в завданні, знайти файли, застосувати правку, перевірити результат. Тримати на всіх кроках найдорожчу модель ні до чого. Практика така: основна сесія на сильній моделі, механічна робота делегується підагентам на моделі простішій, рівень зусиль підвищується лише там, де є складна розвилка. І скіли, і підагенти вміють задавати модель і зусилля для себе, тож маршрутизацію можна описати один раз: ```markdown title=".claude/skills/dev-changelog/SKILL.md" --- name: dev-changelog description: Зібрати changelog з історії комітів між двома тегами. model: haiku effort: low disable-model-invocation: true --- ``` Окрема тема — ліміти підписки. Агент їх не бачить, тому не може співвідносити витрати: він однаково охоче запускає віяло підагентів і коли до скидання чотири години, і коли бюджет на межі. У мене це розв'язано хуком, який приносить живі цифри в контекст і забороняє віяльні запуски в гарячій зоні. Подробиці у статті про хуки. ## MCP і консольні утиліти Два способи дати агентові доступ до зовнішнього світу. Консольні утиліти — найощадливіший за контекстом шлях. Є в сервісу CLI — агент чудово ним користується: заводить завдання, читає коментарі, дивиться логи, розгортає середовище. Незнайомі утиліти він теж опановує, якщо попросити розібратися за вбудованою довідкою. MCP-сервери — коли потрібен структурований доступ: база, трекер, макети, моніторинг. Тут-таки живе корисна категорія серверів для роботи із самим кодом: символьна навігація замість читання файлів цілком заощаджує на великих репозиторіях дуже помітно. Порада з практики: підключайте лише те, чим справді користуєтеся. Кожен сервер додає описи своїх інструментів у контекст кожної сесії, і десяток серверів «про всяк випадок» обходиться дорожче, ніж здається. ## Що лишилося вірним із практик Cursor Частина порад зі старої статті нікуди не поділася. Вони про роботу з моделлю взагалі. **Декомпозуйте і контролюйте кроки.** Прохання «зроби все» дає код, який працює не так, як ви очікували, і розбиратися в ньому дорожче, ніж було б написати. Кроки мають бути самодостатніми: після кожного проєкт збирається. **Логуйте щедро.** Людині перевантажена логами консоль заважає, агентові допомагає: зіставляючи виведення з кодом, він точніше розуміє, що зламалося. **Просіть свіжі версії бібліотек і дивіться на ліцензії.** Модель підставить версію, яку пам'ятає, а пам'ятає вона дво-трирічної давності. На ліцензію вона не дивиться зовсім, а затягти в закритий проєкт бібліотеку з копілефтом легко. **Уточнюйте спосіб розв'язання заздалегідь.** Одну річ можна зробити п'ятьма способами, і без уточнення вибір робить модель — на підставі того, що частіше траплялося в навчальних даних. Запитайте про варіанти й мінуси до того, як код написано. **Різні завдання — різні сесії.** Порада про новий чат під кожне завдання перекочувала без змін, тільки тепер у неї є точне пояснення: це про контекст. ## Як усе зіпсувати Зібрав ті способи, які бачу найчастіше. У себе зокрема. **Сесія-смітник.** Почали з одного завдання, запитали про інше, повернулися до першого. Контекст напханий усім одразу. **Нескінченні виправлення.** Агент зробив не те, ви виправили, знову не те. Після двох кіл дешевше почати заново. **Роздуті інструкції.** Файл виріс, половина вказівок перестала працювати: важливе загубилося. Лікується безжальним скороченням. **Довіра без перевірки.** Правдоподібна реалізація, що не покриває межові випадки. Перевірити нічим — не надсилайте. **Нескінченна розвідка.** «Розберися, як тут усе влаштовано» без меж, і агент прочитав двісті файлів, а вікно скінчилося. Обмежуйте область або віддавайте розвідку підагентові. ## Коротко Якщо забирати зі статті одне: спершу налаштуйте середовище, потім просіть код. Перевірка, яку агент може запустити сам. Короткі інструкції проєкту, де лише те, чого він не виведе з коду. Правила для обов'язкової поведінки, скіли для знання на вимогу, хуки для того, що має відбуватися завжди. Облік завдань поруч із кодом. Свідоме ставлення до контексту. Робота разова, окупається в кожній сесії. І різниця між «агент постійно робить не те» і «агент робить що потрібно» зазвичай саме тут, а не в моделі й не у формулюванні чергового запиту. І ще раз про те, з чого починав: усе це — промпти. Інструкції, правила, скіли, описи підагентів. Написані недбало, вони дають рівно той результат, який дають недбалі промпти, тільки ви платите за нього в кожній сесії, а не один раз. Техніки, які тут працюють, розібрано у статті [про промпт-інжиніринг](/uk/prompt-engineering/). Про хуки — механізм, що робить поведінку агента детермінованою, — [окрема стаття](/uk/claude-code-hooks/) з усіма подіями і трьома робочими прикладами.