Галоўная / Артыкулы

Ваш AGENTS.md пісаўся для горшай мадэлі: аўдыт промпт-доўгу

Старыя правілы AGENTS.md перажываюць хібы мадэляў, якія яны закрывалі. Як заўважыць промпт-доўг, скараціць навыкі да маршрутызатараў, наладзіць дазволы і вызначыць «гатова» раней за шлях.

Выдавец: REACTAPP.TOP8 хв чытання1854 слоў

Крыніцы: Your AGENTS.md Was Written for a Worse Model

Кожны лінійкі ў файле 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
  • опісы навыкаў
  • самыя навыкі
  • інструкцыі для рэпазітарыя на рэжыме сістэмы
  • Інструкцыі, якія павтараюцца ў шаблонах заданняў
  • Для кожнага правіла выявіце, чаму яно існуе і якая прычына неудачы спаканула людзей да яго дадагаў.

    Разлічыце справжнія інварыянты ад прыzwычак

    З’ясавіце, чы можа кваліфікаваны інжынер безпечна і дашчаўна вывесты гэта правіло з базы дадзеных. Калі так, пераканацеся, чы ён можа працаваць. Калі ні, застаўце яго. Правілы, якія стосуюцца рызыкаў у працэсе вырабоцтва, ствароўваных артыфактав, поведання скрытай інфраструктуры і неочывічных операцыйных абмежэнняў, апэўнаюцься ў спецыяльнай увазе.

    Ператворыце складныя навыкі на кансэрты

    Калі адны навык павінаваны з калькама рабочых процэсаў, зменшыце пункт яго застосавання. Інструкцыі па перанасенні дадзеных застаўляйце толькі для перанасення, а інструкцыі па вяснаванні — толькі тады, калі гэта неабходна. Спецыялізаваныя знанні застаюцца, не будучы прымушанымі включацца ў кожнае суседзяючае заданне.

    Перачытайце кожную заборону, ўбачыце рызык, які за яю стоіць

    Правіла у стыле «НІКОГДА не чырагнуцься да X», «ЗАВЁЖДА спытваць перш чым зрабіць Y» або «Толькі менаваты Z» можаць застацца правільнымі, але кожна з іх трэба пераканацца ў спадчынных наследках, якія яны мяжу прабавіцца запобiec. Інодзе лепшым правілам ёсць тое, што X можа быць вольна менаваны ў локальнай разработцы, але ў рэальных умовах патрэбны падтверджэння, або што рэгрэсіі, якія вынікаюць ад сабеіншых змян, можна ліквідаваць, тады калі болей значныя змяны трэбуюць санкцыі.

    Мэтай ня ёсць максымальная автонамія. Гэта — направіць людскую увагу там, дзе наследкі гэтага падтрымліваюцься.

    Што должна перазіць кожную апдэйтаванне

    Некія інструкцыі павінны застацца, незалежна ад таго, насколькі хорашыя ў нас ёсць мадэлі. Для запуску можа знадобіцца флаг наследства, які не задокументаваны. Створаныя файлы можуць выглядаць так, нібы ўможлівлены ў яных змены, хоча ўсе змены будуць перазапісваны. Локальная асяроддзе можа прымаць відтворэнне рэальнай асяроддзя аплікацыі, калі вікорыстоўваюцца тымчасовыя элементы. Міграцыя можа патрабаваць працы з двумя актыўнымі версіямі аплікацыі. Што стосуецца іх, то яны маюць вялікую цэннасць, адтолькі сама інтэлігэнція не можа надзеязліва ўсё ў яных адкрыць.

    Фільтр, які трэба вікорыстоўваць, — цэ гэта цэннасць інформацыі. Калі інструкцыя пакрывае ўсё тое, што мадэль не можа безпечна адкрыць, то яе трэба застаць. Калі ж яна толькі опісвае, як старэйшую мадэль трэба было ведаць праз звычную інжынерную працу, тады трэба пераглянуць такую інструкцыю. Веліка колькасць інструкцый не ёсць прычыной „боргу“ праптыў. Борг заключаецца ў тых інструкцыях, прычына існавання якіх знікла.

    Старым падчынам для стварэння агентаў-програмістаў было дакладна працэсаваць кожны элемент маршруту. Калі мадэлі стаюць лепшымі, простыяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяя

  • Ваша семантычная мадэль — гэта API: надаўчы агентам сертыфікаваныя показнікі — Чаму агенты AI ствараюць прыватныя вызначэнні доходу і запасоў, і як кераваная семантычная мадэль з дэталізацыямі, власнікамі і адмовамі дае ўсім іх аднай угодзе.