Робота з агентами для коду

Мій улюблений колега ніколи не спить

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

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

Слова, які ви зустрінете

Дайте контекст раніше, ніж він спитає

Агент нічого не знає про ваш проєкт, доки щось не прочитає. Можна дозволити йому все з’ясовувати через grep — повільно й галасливо, — а можна записати головне у файл AGENTS.md чи CLAUDE.md у корені репозиторію.

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

1# Проєкт
2 
3API менеджера завдань. TypeScript, Fastify, Postgres, Vitest.
4 
5## Команди
6 
7- npm run dev — запустити сервер розробки
8- npm test — запустити тести (завжди запускай перед завершенням)
9- npx tsc --noEmit — перевірка типів
10 
11## Домовленості
12 
13- Маршрути в src/routes, один файл на ресурс
14- Усі обробники перевіряють ввід схемами zod
15- Лише м’яке видалення: виставляй deletedAt, ніколи не роби DELETE рядків
16- Тести: блоки describe називаються за іменем маршруту

До файлу йдуть три речі: команди (npm test), домовленості (де лежать файли, як називати речі) і жорсткі правила (ніколи не видаляти рядки, завжди перевіряти ввід). Три речі лишаються поза ним: історія, філософія та все, що ви не стали б обстоювати на рев’ю коду.

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

Невеликі завдання з чіткими межами

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

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

Переглядайте кожен дифф. Кожен.

Дифф — це просто список змін: додані рядки, видалені рядки, змінені рядки — те, що ви гортаєте, перш ніж натиснути «злити».

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

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

Git — ваша страхувальна сітка

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

Шаблон промпту, який працює

Після сотень сесій мій найнадійніший шаблон складається з трьох фаз:

1. Дослідження. «Прочитай потрібні файли й поясни, як зараз працює X. Поки що не пиши код». Ви отримуєте відповідь у вигляді плану й можете поправити розуміння агента, поки це ще дешево.
2. План. «Запропонуй план реалізації. Перелічи файли, які ти зачепиш». Невеликі плани затверджуються, великі — розбиваються.
3. Реалізація. «Виконай крок 1 плану. Коли закінчиш, запусти тести».

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

Ваш перший промпт — готовий до вставлення

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

Ти — старший інженер, який працює в цьому репозиторії.

ЗАВДАННЯ: додати ендпоінт POST /login, який перевіряє email і пароль
за таблицею users, із тестами.

КОНТЕКСТ:
- Дотримуйся шаблону з src/routes/auth.ts
- Перевіряй ввід схемою zod
- Лише м’яке видалення: виставляй deletedAt, ніколи не роби DELETE рядків

ПЕРШ НІЖ ПИСАТИ КОД:
1. Прочитай потрібні файли й поясни, як вхід працює зараз.
2. Запропонуй короткий план і перелічи файли, які ти зачепиш.
Дочекайся мого схвалення. Поки що не пиши код.

КОЛИ Я СХВАЛЮ:
- Реалізуй крок за кроком.
- Запусти: npm test
- Виправ збої самостійно, а потім знову запусти тести.

НАПРИКІНЦІ: коротко опиши, що саме змінено і що лишилося недоторканим.

Що агент насправді бачить

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

Ось сесія, розіграна за кроками. Натисніть «▶ запуск» і стежте за смугою:

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

Коли не варто доручати

Дещо я досі роблю руками, і думаю, що вам теж варто:

• Проєктні рішення. Іменування, архітектура, моделювання даних — міркування, які і є справжньою роботою. Агент може перелічити варіанти; вибираєте ви.
• Нові галузі, які ви опановуєте. Якщо доручити це агентові, ви нічого не навчитеся. Друкуйте код самі, коли мета — ваша власна навичка.
• Код, критичний для безпеки. Автентифікація, криптографія, платежі. Агент робить чернетку, а ви звіряєте кожен рядок із чек-листом — або, ще краще, зі спеціалістом.
• Розпливчасті завдання. «Зроби краще» — це не завдання. Якщо ви не можете сказати, як перевірити успіх, то й агент не зможе.

Перевірте себе

Що забрати з собою

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

1. Витратьте десять хвилин на AGENTS.md сьогодні. Команди, домовленості, жорсткі правила. Файл окупається в першій же сесії, а з кожною наступною віддача лише зростає.
2. Скоротіть наступне завдання до трьох речень. Назвіть файл, шаблон, якого дотримуватися, і команду, яка доведе, що все працює.
3. Спершу перегляньте — потім запускайте. Прочитайте дифф, а тоді запустіть самі. Зелені тести — це свідчення, а рішення залишається за вами.
4. Робіть коміт після кожного завершеного кроку. Невеликі контрольні точки перетворюють «агент пішов не туди» зі рятувальної операції на відкіт за дві секунди.

Зробіть ці чотири речі — і агент стане тим колегою, якого обіцяє заголовок.