Ваш файл AGENTS.md був створений для гіршої моделі: аудит боргу за запити
Старі правила AGENTS.md залишаються актуальними попри недоліки моделі, які вони виправили. Навчіться розпізнавати проблеми з запитами, скорочуйте навички до необхідного мінімуму, встановлюйте дозволи та чітко визначайте критерії завершення роботи ще до початку процесу.
Кожен рядок у файлі AGENTS.md зазвичай додавався для усунення реальної проблеми. Моделі вдосконалюються, проблема зникає, але правило залишається. Це так званий «борг запитів»: тимчасове рішення проблеми однієї моделі перетворюється на постійну політику. Рішенням є надання файлу вужчих обов’язків — охоплення інваріантів, прихованих обмежень та меж дозволів, а також визначення критеріїв завершення роботи.
Щоразу, коли агент для програмування допускає помилку, яку люди пам’ятають, хтось додає нове правило. Воно змінює занадто багато, тому у файлі прописано змінювати лише те, що необхідно. Воно пропускає перевірку, тож інший рядок вимагає виконання всього набору тестів щоразу. Воно змінює залежності без запиту, тож зміни залежностей стають можливими лише після схвалення. Воно «блукає» по репозиторії, тому у файлі чітко вказано, які документи потрібно прочитати спочатку.
Кожне правило мало сенс у момент свого створення. А потім змінилась модель.
OLD: Read A → Edit B → Test C
NEW: Boundaries → Permissions → Definition of done
Найновіше покоління моделей, на прикладі якого слугує GPT-6 Astra, значно краще виконує інструкції, ніж попередні моделі для кодування, що змінює економіку формулювання запитів. Слабка модель може ігнорувати занадто загальні правила, тоді як сильна може дотримуватися їх до останньої літери. Тож інструкція, створена для усунення недоліків старішої моделі, може стати перешкодою для новішої. Якщо оновити модель, не перевіривши її інструкції, старі слабкості залишаться частиною нової системи. Модель покращилася, але спосіб формулювання запитів залишився незмінним.
Кожна невдача залишає „скам’янілість“
Код накопичує технічний борг, коли тимчасове місцеве рішення перетворюється на структурну обмеженість. Інструкції для агентів так само накопичують борг.
Припустимо, старіша модель для кодування постійно забувала перевіряти свої зміни, тож хтось додав:
Always run the entire test suite after every change.
На той момент це могло покращити надійність. Через рік модель вже може виявляти пошкоджені тести та перевіряти власну роботу, проте інструкція все ще існує. Тепер одна-едина корекція може запустити двадцять хвилин тестування інтеграції. Нічого не зламано, і агент сумлінно дотримується правил репозиторію. Проблема в тому, що старий патч поведінки був перетворений на постійну інженерну політику.
Це так званий борг відразу. Правило вирішує реальну проблему, проблема зникає, а правило залишається.
Навички коштують щось перед тим, як вони будуть використані
Навички здаються дешевими, оскільки їхній повний вміст завантажується лише тоді, коли це необхідно. Формат Agent Skills передбачає поступове розкриття інформації: спочатку завантажуються назва та опис навички, а повний файл — лише тоді, коли завдання відповідає їй.
Проте перш ніж модель зможе обрати певну навичку, їй потрібно розпізнати наявні опції, тому назви та описи вже конкурують за увагу.
Уявіть собі репозиторій із окремими навичками, які охоплюють міграції баз даних, PostgreSQL, проектування схем, зберігання даних на серверному рівні, оптимізацію запитів та їх відновлення. Кожна з них містить універсальний опис, у якому згадуються SQL, міграції, схеми, запити, моделі та зберігання даних. Навіть незначна зміна запиту тепер здається релевантною для половини елементів бібліотеки, тому агенту доводиться класифікувати інформацію перед тим, як почати писати код.
Кращим підходом залишається поступове розкриття інформації, що також підтримується у документації навичок OpenAI: детальні інструкції знаходяться у додаткових файлах, які завантажуються лише тоді, коли це необхідно для виконання завдання.
database/
├── router.md
└── references/
├── migrations.md
├── performance.md
└── recovery.md
Кореневий файл потрібен лише для того, щоб спрямувати завдання. Зміна схеми призводить до файлу migrations.md, повільний запит — до performance.md, відновлення чи втрата даних — до recovery.md. Деталі не викидаються; вони з’являються тоді, коли завдання дає агенту причину їх прочитати, що дозволяє краще використовувати контекст, ніж опиратися на припущення щодо операційних знань.
У файлі AGENTS.md мають бути ті речі, які не може пояснити код
Інструкції на рівні репозиторію поводяться інакше, оскільки вони супроводжують агента майже на кожному завданні. Файли на кшталт AGENTS.md завантажуються у сеанс як постійний контекст, як це описано у документах про пам’ять Claude Code, і тому їх використання є неефективним, якщо вони є неправильними, застарілими чи надмірно загальними.
Корисний тест: чи зможе кваліфікований інженер, переглядаючи цей репозиторій, вирішити це питання безпечно та дешево? Якщо так, то це правило, можливо, не повинно бути в AGENTS.md. Якщо ні, то, ймовірно, має бути.
Порівняйте два інструкції. Перша — це знання, специфічні для репозиторію, які модель не може безпечно вивести, тому вона залишається такою:
KEEP
Generated API clients in /src/sdk are immutable.
Edit the generator source instead.
Другий описує процес роботи, який може підійти для архітектурної рефакторизації, але є надмірним для виправлення однослівної помилки, тому його слід перемістити або видалити:
MOVE OR REMOVE
Before making any change:
1. Read ARCHITECTURE.md
2. Inspect the repository map
3. Review all package documentation
4. Identify downstream dependencies
Стабільні інструкції повинні в основному охоплювати три аспекти: інваріанти, які мають залишатися істинними, приховані обмеження, які не є очевидними у кодовій базі, та межі автономії, які вказують, де агент може діяти, а де рішення має приймати людина. Це значно простіше завдання, ніж навчати модель виконувати роботу з програмною інженерією.
Кращі моделі роблять дозволи ще важливішими
Більш суворе дотримання інструкцій призводить до більш тонкого виду невдачі. Агент може настільки ретельно дотримуватися встановлених меж, що зупиняється саме там, де ви хотіли, щоб він продовжував роботу.
Припустимо, він впроваджує зміни, і локальний тест, який залежить від цих змін, провалюється. Він повідомляє про те, що auth_spec.ts не працює, та запитує, чи слід його виправити. Модель знає, як виправити тест, але не знає, чи це входить у її повноваження. У такому випадку надання дозволу допомагає краще, ніж будь-яка інша процедура:
Local tests use disposable fixtures and have no production access.
Run affected tests, fix regressions caused by the requested change,
and rerun them without asking for approval at each step.
Ці рядки повідомляють агенту три речі, які він не завжди може вивести самостійно: середовище є безпечним, корекція входить до сфери дії, і він може продовжувати роботу. Так встановлені межі краще спрямовують прийняття рішень, ніж загальні заборони на кшталт „ніколи не розширювати сферу дії“.
Один із способів розділення обов’язків на практиці:
Потребує схвалення людини:
- Видалення даних з середовища виробництва.
- Зміна політики автентифікації.
- Порушення умов контракту з публічним API.
- Впровадження міграції з операційним ризиком.
Агент зазвичай може продовжувати з:
- Виправлення тесту, який пошкодився внаслідок його власних змін.
- Оновлення суміжних локальних типів.
- Форматування файлів, які він змінив.
- Повторного запуску вплинутих локальних тестів.
Саме наслідки є тим, що розділяє ці списки. Суміжні дії не завжди потребують однакового рівня схвалення.
Визначте, що вважається завершеним, перш ніж описувати шлях
Старіші запити часто описують маршрут:
Read these files.
Modify these modules.
Run this command.
Inspect this output.
Run these tests.
Це може допомогти, коли робочий процес справді крихкий, але здібний агент зазвичай отримує більше користі від чіткого кінцевого пункту. Порівняйте простий запит.
Implement the avatar endpoint.
з версією, яка додає фінішну лінію:
Run the affected local tests, inspect the returned payload,
fix regressions caused by this change, and stop when the requested
behavior works or an external blocker requires a decision from me.
Другий етап ніколи не вказує, який файл відкрити спочатку. Він описує, як буде виглядати кінцевий результат. Ця різниця посилюється, коли моделі набувають достатньої здатності до ухвалення рішень, щоб самостійно обирати шлях у кодовій базі. Люди визначають пункт призначення та небезпечні межі, а агент розраховує маршрут.
Зберігайте ієрархію інструкцій свідомо
Чітка структура складається з трьох окремих рівнів. Перший — це файл репозиторію:
AGENTS.md
↓
Repository invariants
Safety boundaries
Global permissions
Другий включає навички:
Skills
↓
Specialized workflows
Loaded only when relevantTask prompt
↓
Immediate objective
Local constraints
Definition of done
Третім елементом є сам запит на виконання завдання. Проблеми виникають тоді, коли різні компоненти починають переплітатися: одноразовий процес виконання завдання, який потрапляє до файлу AGENTS.md, глобальне правило безпеки, приховане всередині навички, яку модель може ніколи не завантажити, навичка, яка перетворюється на енциклопедію, або запит на виконання завдання, який повторює інформацію з репозиторію, вже наявну у моделі. У міру того, як моделі стають все більш здатними, таке дублювання стає все дорожчим.
Перевірка наявності „боргу“ запитів під час змін моделі
Оновлення моделі має спричинити перевірку існуючих інструкцій. Це не тому, що кожна стара інструкція є неправильною, а тому, що припущення, на яких вони ґрунтуються, могли змінитися. Ефективна перевірка включає чотири етапи.
Підбірка інформації про історичні компенсації
Зберіть усе, що впливає на поведінку агента:
AGENTS.md- описи навичок
- самі навички
- запити до репозиторію на рівні системи
Для кожного правила з’ясуйте, чому воно існує та яка проблема спонукала хтось його додати.
Розрізняйте справжні незмінні властивості від звичок
Запитайте себе, чи може кваліфікований інженер безпечно та дешево вивести це правило з репозиторію. Якщо так, перевірте, чи можна його використовувати. Якщо ні — залиште його. Правила, що стосуються ризиків у продакшені, генерованих артефактів, поведінки прихованої інфраструктури та неочевидних операційних обмежень, потребують особливої уваги.
Перетворюйте складні навички на шаблони
Якщо одна навичка використовується у кількох робочих процесах, зменшіть її точку входу. Включайте інструкції з міграції лише під час міграцій, а процедури відновлення — лише тоді, коли це необхідно. Спеціалізовані знання залишаються, не потрапляючи до кожного сусіднього завдання.
Перечитайте кожен заборонний пункт, щоб зрозуміти ризик, який він приховує
Правила на кшталт „НІКОЛИ не торкатися X“, „ЗАВЖДИ запитувати перед Y“ чи „ЛИШЕ змінювати Z“ можуть бути правильними, але кожне з них слід перевіряти з точки зору наслідків, яких воно має запобігти. Іноді кращим правилом є те, що X можна вільно змінювати під час локальної розробки, але перед впровадженням у продакшн необхідно спочатку поставити запитання, або що регресії, спричинені власними змінами агента, можна виправити, тоді як будь-які більш масштабні зміни потребують схвалення.
Метою не є максимальна автономія. Це спрямовано на те, щоб приділяти людську увагу там, де наслідки це виправдовують.
Що має залишатися незмінним після кожного оновлення
Деякі інструкції мають залишатися актуальними, незалежно від якості моделей. Для розгортання може знадобитися недокументований флаг спадковості. Створені файли можуть здаватися редагованими, хоча будь-які зміни відразу стираються. Локальне середовище може нагадувати продакшн, навіть якщо використовуються тимчасові елементи. Міграція може знадобитися для роботи з двома активними версіями додатку. Вони мають високу цінність, оскільки сама інтелектуальність не дозволяє їх надійно виявити.
Фільтр, який слід використовувати, — це цінність інформації. Якщо інструкція описує щось, що модель не може безпечно виявити, залиште її. Якщо вона лише пояснює, як старішу модель потрібно було використовувати для виконання звичайної інженерної роботи, перегляньте її. Велика кількість інструкцій сама по собі не створює „боргу за запити“. Борг полягає у тих інструкціях, причина існування яких зникла.
Старим підходом до програмування агентів було детальне описування кожного кроку процесу. Зі покращенням моделей краще використовувати простіший дизайн: зберігати незмінні елементи, встановлювати дозволи та чітко визначати, що означає завершення завдання. Середні етапи процесу залишаються на розсуд агента, а коли з’являється нова модель, спочатку переглядаються правила, перш ніж писати щось нове.