Кодові агенти — це не автодоповнення. Claude Code, OpenAI Codex, Copilot coding agent чи агентний режим Cursor читають репозиторій, редагують десятки файлів, запускають команди, дивляться на результат і пробують знову. За правильного використання вони перетворюють рутину на пів дня на двадцятихвилинне рев'ю. За неправильного — видають розлогі диффи, які виглядають правдоподібно, але ламають речі так, що ніхто не помічає до продакшену. У цьому гайді зібрані практики, які, за нашим досвідом і за опублікованими рекомендаціями вендорів, розділяють ці два сценарії.
Як насправді працює кодовий агент
Під капотом кожен кодовий агент — це один і той самий цикл: модель отримує задачу і контекст, обирає дію (прочитати файл, пошукати, відредагувати, запустити команду), обв'язка виконує її, а результат повертається в контекст. Цикл триває, доки модель не вирішить, що закінчила, або не впреться в ліміт. Це патерн «агента», описаний у статті Anthropic Building effective agents і формалізований у дослідженнях на кшталт ReAct.
З цього випливають два наслідки:
- Агент знає лише те, що є в його контекстному вікні. Він не «пам'ятає» ваших домовленостей, якщо їх не записано там, де він читає.
- Агент настільки хороший, наскільки хороший його зворотний зв'язок. Якщо він може запускати тести, перевірку типів і лінтер, то виправляє власні помилки. Якщо ні — вгадує.
Дослідження SWE-agent показало, що дизайн інтерфейсу агент–комп'ютер — як показуються файли, як застосовуються правки, що повертають команди — сильно впливає на частку розв'язаних реальних задач з GitHub (Yang et al., 2024). Більшість практик нижче — про покращення цього інтерфейсу для вашого репозиторію.
Практика 1: Напишіть файл інструкцій проєкту
Кожен серйозний агент підтримує файл інструкцій на рівні репозиторію, який завантажується в контекст на початку сесії: CLAUDE.md для Claude Code, AGENTS.md для Codex та низки інших інструментів, .github/copilot-instructions.md для Copilot. Тримайте його коротким, конкретним і актуальним.
# CLAUDE.md
## Команди
- Встановлення: `pnpm install`
- Dev-сервер: `pnpm dev` (порт 3000)
- Тести: `pnpm test` (Vitest, ~20 с). Один файл: `pnpm test path/to/file.test.ts`
- Типи: `pnpm tsc --noEmit` — має проходити, перш ніж казати «готово»
- Лінт: `pnpm lint --fix`
## Архітектура
- Next.js App Router в `app/`, спільний UI в `components/`, доменна логіка в `lib/`
- Серверний код імпортує "server-only"; ніколи не імпортуй його з клієнтських компонентів
- Усі грошові значення — цілі числа в мінорних одиницях (копійки, центи)
## Правила
- Не редагуй згенеровані файли в `lib/api/generated/`
- Не додавай залежності без запиту
- Невеликі коміти з conventional commit messages
Що включати: команди, архітектуру в кількох рядках, неочевидні домовленості й жорсткі «ніколи». Що не включати: загальні поради, які модель і так виконує («пиши чистий код»), довгі стайлгайди, які все одно перевіряє лінтер, і секрети. Рекомендації Anthropic щодо Claude Code радять ітерувати цей файл як промпт: якщо агент повторює помилку, додайте один рядок, що її запобігає.
Практика 2: Дослідити, спланувати, потім виконати
Найчастіша помилка — дозволити агенту одразу редагувати. Для всього, що більше за виправлення в одному файлі, поділіть сесію на фази:
- Дослідження. «Прочитай модуль платежів і тести повернень. Код поки не пиши. Підсумуй, як повернення проходять системою».
- План. «Запропонуй план підтримки часткових повернень. Перелічи файли, які зміниш, і тести, які додаси». Перегляньте план. Виправляйте непорозуміння тут — це вдесятеро дешевше, ніж виправляти код.
- Виконання. «Реалізуй крок 1 плану. Запускай тести після кожного кроку».
- Перевірка й коміт. «Запусти повний набір тестів, перевірку типів і лінт. Підсумуй, що змінилося і що ти перевірив».
Багато інструментів мають окремий режим планування, що забороняє правки до вашого схвалення. Користуйтеся ним. Для складних задач просіть агента записати план у файл (docs/plans/partial-refunds.md): він переживе скидання контексту і стане документацією.
Практика 3: Дайте агенту спосіб перевірити роботу
Агенти працюють значно краще, коли можуть самі перевіряти результат. Конкретно:
- Швидкі тести. Переконайтеся, що точковий запуск тестів триває секунди. Якщо повний набір повільний, задокументуйте, як запустити один файл чи тест.
- Спершу тести для нової поведінки. Попросіть агента написати тести, що падають, переконатися, що вони падають, закомітити їх, а потім реалізовувати, доки вони не пройдуть. Це запобігає класичній помилці, коли агент «виправляє» тест під баговий код.
- Перевірка типів і лінтер як частина критеріїв готовності.
- Візуальний зворотний зв'язок для UI. Для фронтенду інструмент автоматизації браузера чи скриншот дозволяє агенту порівняти результат із дизайном.
- Скрипти відтворення багів. «Напиши скрипт, що відтворює баг, переконайся, що він падає, потім виправ».
Детальніше про генерацію тестів — у статті AI-генерація юніт-тестів.
Практика 4: Керуйте контекстом свідомо
Довгі сесії деградують. Контекст заповнюється застарілим вмістом файлів, невдалими спробами й виводом інструментів, а увага моделі до ранніх інструкцій падає. Практичні звички:
- Одна задача — одна сесія. Очищуйте контекст між непов'язаними задачами.
- Явно вказуйте файли, а не просіть агента «роздивитися».
- Субагенти для дослідження. Багато інструментів можуть запустити субагента зі свіжим контекстом, щоб дослідити питання й повернути лише висновок (субагенти Claude Code). Так основний контекст лишається сфокусованим.
- Стискайте або підсумовуйте, коли сесія задовга, і перезапускайтеся з файлу плану, якщо якість падає.
Принципи, що стоять за цим, описані в статті контекстна інженерія для AI-агентів.
Практика 5: Встановіть дозволи, як для нового підрядника
Агент із доступом до shell може зробити все, що може ваш обліковий запис. Налаштуйте дозволи явно:
| Дія | Рекомендоване значення |
|---|---|
| Читати файли репозиторію | Дозволити |
| Редагувати файли репозиторію | Дозволити, переглядати дифф |
| Запускати тести, лінтери, перевірку типів | Дозволити |
| Встановлювати залежності | Запитувати |
git commit |
Дозволити у feature-гілках |
git push, відкриття PR |
Запитувати |
Мережеві виклики, curl, хмарні CLI |
Запитувати або заборонити |
| Клієнти БД, скрипти деплою | Заборонити |
Читання .env, ~/.ssh, файлів з обліковими даними |
Заборонити |
Для роботи без нагляду запускайте агентів у контейнері або dev-VM, особливо в режимах, що пропускають підтвердження. Пам'ятайте: агент може читати недовірений контент — текст задач, вебсторінки, README залежностей — з вбудованими інструкціями. Це prompt injection, і захист від неї архітектурний; див. безпеку AI-агентів.
Ще один важіль — хуки: детерміновані скрипти, що запускаються до чи після викликів інструментів, наприклад, щоб запускати форматер після кожної правки або блокувати запис у захищені шляхи (хуки Claude Code). Хуки забезпечують виконання правил, про які модель може забути.
Практика 6: Тримайте диффи придатними для рев'ю
Агент пише код швидше, ніж ви встигаєте його переглядати. Захищайте свій ресурс рев'ю:
- Вузько формулюйте задачі. «Додай часткові повернення в API» краще, ніж «покращ модуль платежів».
- Просіть невеликі, логічно розділені коміти. Механічні перейменування — в одному коміті, зміни поведінки — в іншому.
- Заборонте попутні рефакторинги у файлі інструкцій: «Не рефактор код, не пов'язаний із задачею».
- Переглядайте, як код людини. Читайте кожен рядок немеханічних змін. Перевіряйте обробку помилок, граничні випадки і те, чи тести справді тестують поведінку.
- Попросіть агента переглянути власний дифф зі свіжим контекстом, перш ніж це зробите ви. Він ловить напрочуд багато проблем; див. AI-рев'ю коду.
Практика 7: Знайте, де агенти буксують
Агенти чудово справляються з чітко специфікованою роботою, яку можна перевірити: міграції, нові ендпоінти за наявними патернами, тести, виправлення збірки, пояснення незнайомого коду. Складно їм дається:
- Неоднозначні вимоги. Агент обере одну інтерпретацію і впевнено її реалізує.
- Наскрізні архітектурні рішення. Вибір архітектури потребує компромісів, які знаєте лише ви.
- Проблеми конкурентності й продуктивності, що потребують вимірювань, а не міркувань.
- Величезні файли й згенерований код, що не вміщаються комфортно в контекст.
- Задачі без зворотного зв'язку, як-от код, що працює лише в продакшені.
Тут використовуйте агента як дослідника — «знайди всі місця, де ми блокуємо цю таблицю», — а рішення залишайте за людьми.
Практика 8: Паралельні агенти — обережно
Коли команда довіряє своєму процесу, паралельні агенти стають привабливими: кілька сесій працюють над незалежними задачами в окремих Git worktree чи хмарних пісочницях. Це працює, якщо задачі справді незалежні й кожна має власну перевірку. Не працює, коли агенти чіпають ті самі файли або коли накопичуються рев'ю. Починайте з двох паралельних сесій, а не з десяти. Про фонові агенти, що запускаються з задач чи CI, — у статті AI-агенти в CI/CD.
Шаблон сесії
Задача: Підтримати часткові повернення для карткових платежів (issue #482).
Контекст:
- Логіка повернень: lib/payments/refunds.ts, тести в lib/payments/__tests__/
- Документація API провайдера: docs/providers/stripe-refunds.md
- Обмеження: суми — цілі числа в мінорних одиницях
Процес:
1. Прочитай файли вище й підсумуй поточний потік повернень. Зупинись.
2. Після мого схвалення напиши тести для часткових повернень, що падають. Зупинись.
3. Реалізуй, доки тести не пройдуть. Запусти `pnpm test lib/payments` і `pnpm tsc --noEmit`.
4. Підсумуй зміни й усе, у чому ти не був упевнений.
FAQ
Чи варто джунам користуватися агентами? Так, із запобіжниками: вони мають уміти пояснити кожну зміну на рев'ю. Агенти — чудові репетитори, коли їх питають «чому», і погані, коли ними лише генерують результат.
Як не дати агенту змінювати тести, щоб вони проходили? Комітьте тести першими, напишіть у файлі інструкцій, що тести — це специфікація, і переглядайте диффи тестів окремо.
Яку модель використовувати агенту? Найздібнішу — для планування і складних змін; швидшу й дешевшу — для механічних правок, якщо інструмент дозволяє перемикатися. Див. як обрати LLM.
Чи безпечно залишати агента працювати без нагляду? Лише в ізольованому середовищі без продакшен-доступів, у гілці, і з проходженням звичайного рев'ю.
Джерела
- Anthropic. Claude Code best practices for agentic coding.
- Anthropic. Building effective agents.
- Yang et al. (2024). SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering.
- Yao et al. (2022). ReAct: Synergizing Reasoning and Acting in Language Models.
- Anthropic. Документація Claude Code: субагенти і хуки.
- AGENTS.md — відкритий формат інструкцій для кодових агентів.