Субагенты на практыцы: ролі, бюджэты, забароны і ціхія збоі

Навыкі дапамагаюць супрацаваць з аднаго роду забывчывасцю: агент перастае трапляцца ў сітуацыі, калі ён не памятае, як выглядае ваша база коду. Існуе ўсё ж другі род забывчывасці, які стосуецца ідэнтычнасці. У кожнай новай сесіі мадэль дзеяе як той самы энергійны універсаліст, які з радасцю выражае разумную і нейкантэнтную думку пра будзь-што, што ёй паказваюць.

Знанні — гэта проблема навыкаў. Ролі — гэта проблема падагентаў, і самэ гэта розглядаецца ў данай статыі.

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

Першая частка тут – гэта канцэптуальная база: што такое гэтыя файлы, дзе яны знаходзяцца на дыску, як іх стварыць. Гэта можна з’ясавіць з дакументацыі. Другая частка выклікаецца толькі пасля таго, як працавалі два падагента працоўнікі месяцяў у дзесятках рэпазітарыяў і было пазорана, як яны збываюцца так, пра што не паветаралі ніякія інструкцыі з наяўных стандартаў. Обаі агента ў адкрытым кодзе, і справжнія файлы вартаяя чытаць, бо запіт, які быў доўжліва сформульаваны праз рэальныя запускі, навучае больш, чым будзь-якія парады.

Праця падагента

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

Усё гэта не значыць, што модэль слабая. Яе не хапяе ролі. Людзі, якія атрымліваюць атэстацыю на безпеку, думаюць пра іншыя рэчы, чым інжынеры безпекі, а тые, хто шукае багі, аналізуюць іншыя доказы, чым тые, хто вядома трохі разоў сталкнуўся з тым самым крахам. Інтэлект ужо ў наявнасці. Недастаткае толькі правільная структура працы.

Спосаб працы — гэта павтарэнне тая самайяй прэамбулы. Перш чым дазволіць Claude Code адразу паглядзець на змяну, можна запісаць калякву на кшталт: «Разглядзіце гэта як параноічны спеціяліст па безпецы, спачатку пераканаўцеся ў межах аўтэнтыфікацыі, сказаце мне, што прасачыцца ў логах, прыгледзіцеся да дробных стылевых дэталяў». Калі гэта павтарыцца трохі разоў за два тыдні, прыходзіце розумеў: гэтая прэамбула — гэта ролі, а ролі, якія вы павтараеце, — гэта падагенты, якія ўсё ўсё ніхто не стварыў.

Павтарэнне набірання тэксту — гэта трыгер, пра які пішаюць у всіх нарадчыках. Але гэта не тое, што створыла тыя два агенты, якія засталіся, — іх створылі іншыя факторы.

• Эканоміка кантэксту. Адзінбытныя даследаванні ўскладненыя: дваццаць пошукоў, дзесятак атрыманых сторанак, палова з іх беспарадныя. Калі такое адбываецца пад час главнай сесіі, яна заполняецца мусорам, які вы ніколі не хацелі чытаць. Работа павінна вестыцца ў іншым месцы і вярнуцца у віглядзе статыстыкі. Самэй гэтага і існуе агент для пошуку ў інтэрнэце. Ён не ўжо розумней главнага працэсу, а мета проста — выкарыстоўваць тое, што ён прачытаў, не падключаючы гэта да вашага кантэксту.
• Раздзелэнне ролей. Пад час працы над дызайнам вы хочаце застацца ў межах дыскусіі пра дызайн. Калі вас выцягваюць, каб затвердзіць адзінадцатую механічную правку, якая проста вынікае з які ўжо была прынятаяя рашэння, гэта марнасць. Таму рашэнні застаюцца у людзя, а набіранне тэксту — у агенце-выканавцы. Здольнасці не маюць нічынага з гэтым раздзелэннем. Гэта проста вялікае, хто павінен думаць пра шта.

Рэвіюар — гэта прыемны першы сабагент. Шырэйша, гэтыя два падзэлкі разныя: самэўсёлі гэтыя падзэлкі ператвараюць функцыю з простага зручнага атрактыва ў спосаб, па якому на самай працэ практычна адбываецца ведача праекта.

Навыкі проты сабагентоў: ведаць проты дзеяць

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

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

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

Возьмімо інжынера з абярання безпекі, які чытае ваш код. Ён не толькі ведае больш, чым вы. Ён працуе інакш: спачатку абмежэнні аўтэнтыфікацыі, шляхі падвышэння прывілеяў ценяцца значна вышэ, чым некрасівыя назвы зменных, няма затверджэння без прымэты пра секрэты, а нараджэнні проблем выкладваюцца у структураваным спіску. Саме такі парадак увагі і ёсць тым, што кодуе падагент.

Знанні належаць да навыку. Методалогія належыць да падагента.

Што такое падагент у Claude Code

Claude Code ўжо ўважаецца стандартным інструментам, таму што ён выкорыстоўваецца ўсё час. Іншыя інструменты практыкуюцца ў аднальным раздзеле, з урахоўваннем ўсіх ўскладненняў.

У самам Claude Code падагент на самай працоўцы ёсць не чым іншым, як документам у фармаце Markdown, які пачынаецца кароткім блакам YAML. Ёго можна зберагчыць у двух каталогах:

• ~/.claude/agents/ — гэта персональная бібліятэка, доступная ў кожным праекце на апараты. Яе можна розглядаць як «пісочніцу».
• .claude/agents/ унутрь рэпазітарыя прызначана толькі для таго праекта і перавозіцца разам з рэпазітарыем пасля яго зберэжэння.

Фронтматэр кароткі. Ось цэлы працюючы прыклад:

---
name: migration-risk-reviewer
description: Reviews database migration plans and schema changes for rollback risk, lock contention, and data integrity problems. Use before running any migration against real data.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior database engineer reviewing a migration for production risk.

## What you look at first

- Can this be rolled back without losing data?
- Does it hold locks on a busy table during deploy?
- Is the ordering safe for a multi-step change?
- Will existing data violate any new constraint?

## Output shape

Findings in order of severity:

1. Blockers — deploy will fail or data will be lost
2. High risk — real production risk, needs a mitigation
3. Medium risk — should fix, won't necessarily block
4. Notes — worth tracking

For each finding: what it is, why it matters, what to do about it.

Ёсць кілька аспектаў таго, як Claude Code адмаўляецца такым файлам, якія варта знаты.

• Тэкст пад заголовкам ёсць запрос да сістэмы. Усё, што знаходзіцца пад заголовкам, стае інструкцыямі падагента пад час яго запуску. Гэта не дакументацыя, яку мадэль чытае і пасля чаго дзейнае. Мадэль чытае ўсё гэта і спрыймае як свою ідэнтычнасць.
• description мае вялікую значымасць. Claude Code керуецца яй, каб адначасова выбраць момент для автаматычнага перадачы задачы, таму яе трэба пісаць так, каб іншыя моглі ўсё з’ясаваць з кантэксту. Фраза „Іспользаваць перад запускам будзь-якай міграцыі“ будзе зрозумела, а „Дапамагае з працай з базай дадзеных“ — ні. Таксама трэба уключыць негатыўную частку: оба падагента, пра якіх гаворыцца, пішуць, для чаго яны не падходзяць, адколькі сістэма можа без працы перадаць ўпраўління задачэм, якое яму не паслядуе.

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

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

У яго ёсць сае вікна кантэксту. Людзі недаюць гэтаму належнага значэння: падагент працуе ў адзінам кантэксце і вяртае падсумак, таму ваша галоўная сесія не заполняецца всім, што ён прачытаў. Аднак сама гэта асоблівасць таксама можа стаць прычыной проблем, і ў наступным раздзеле будзе показана, як гэта выглядае.

Вам не трэба пісаць файл вручную. Апісацыя ролі для Claude Code прыведзе да стварэння файла ў правым месцы. Команда /agents таксама керуе імі.

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

Слова „агент“ выпрацоўвае занадта многа

Гэты тэрмін вжываецца ў чатырох разных значэннях, і ўзаемнае плутанне іх вызывае сталую плутанню. Раздзелімы іх:

• Падагент (файл у .claude/agents/ або файл .agent.md у рэгіоне Copilot) — гэта повторна вікорыстоўваны файл, які візначае спецыялістскую ролю. Самэ гэта і ёсць тэмай статты.

Рэжым агента або автонамны выконанне — гэта пераключальнік можаў. Вы дазволяеце інструменту выкананы каманды і рэдагаваць файлы без падтверджэння кожнай лініі. Гэта настройка прав, якая не мае нічынага з спецыялістамі.

Агент для кодавання на фоне або ў воблаку — гэта сервіс, які берае задачу, працуе над яю непазірна і вяртае галузь або запрос на з’еднанне. Гэта таксама не ўскладнены файл.

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

Калі ў наступным тэксце з’яўляецца слова „падагент“, яно означае спецыяліста, які можна вікорыстоўваць знову, напісанага аднойчы і запускаемага спецыяльна. Якшто чытна разумеце гэтыя чатыры пункты, гэта раз’ясніць прыблізна палову плутання.

Стварэнне першага

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

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

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

Што включаецца ў тэкст

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

1. Што ён оптымізуе. Эта прычына, за якую гэтая роля стараецца як можна больш правільна ўсё зробіць. Калі з’яўляецца компроміс, гэта тое, за што ён ідзе.
2. Што ён першым пераглядае. Сігналы высокага прыорытэта — гэта тое, што чытае кожны справжні спецыяліст перш за ўсё іншае.
3. Формы абэкцэў. Конкрэтныя способы, калі такая праца паходзіць не так. Справжня экспертыза знаходзіцца тут, і большая часць яе выклікаецца толькі праз назіранне за тым, як агент памыляецца пад час выпання рэальных заданняў.

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

Што ён не павінен робіць. Раней гэты раздзел счылі необавязковым, але гэта не так. У найбольш аднароўнаваным агенце гэта самая дужы частка файла, і кожны ў яе радок аднасецца да конкрэтнага інцыдэту.

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

Прыклад: шукач багоў, які ігноруе апошнія змяны

Гэты прыклад выйшаў з паўтараючыхся проблем. Чыгне што-небудзь, а памылку прыклеююць у Claude Code, і яго першы інстынкт — паглядзець у файл, які быў адрэдагаваны апошнім. Іноды гэта правільна. Але часта апошняя змяна не мала з тым нічынага.

Апэктыўны дэбагер не пачынае з коду. Ён пачынае з доказаў – тыя чыны, якія насправды вызвалі проблему, тое, што пішацца ў логах, і тое, што змянілася ў сэраўысе, і адкрывае код толькі тады, калі гіпатэза заслуговае на перапрацавку. Гэта ўзор адносаў, таму ён быў зафіксаваны як агент:

---
name: bug-investigator
description: Investigates a bug or failure starting from evidence, not from recent code changes. Produces ranked hypotheses with the next diagnostic step for each. Use for "why is this broken" before touching the source.
tools: Read, Grep, Glob, Bash
---

You are a senior engineer investigating a failure. Your job is to find the most
likely cause, rule out the alternatives, and say what to check next.

## Investigation order

1. Start from the symptom — what is actually failing, and how does it show up?
2. Get the error output and any logs from around the time it broke — ask the caller for them if they weren't provided.
3. Only then look at recent changes, and only if the evidence points there.
4. Read source last, once there's a symptom-to-cause hypothesis worth testing.

## Output shape

**Symptoms:** what's failing and how it manifests.
**Likely causes (ranked):** for each — the hypothesis, the evidence for it, the next diagnostic step.
**Ruled out:** what you checked and why it isn't the cause.
**Next steps:** in priority order.
**Open questions:** what you still can't confirm.

## Failure modes to avoid

- Don't assume the last change is the cause without evidence.
- Don't propose a fix before you can name the mechanism.

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

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

Адваротнае да таго, што чакалі: сабэнтэгаваны агент пачынае з нуля

Усі прыступаюць да існуючага вікна кантэксту як да чыстага успеху. Але гэта можа пахідзіць і інакш.

Пасля трохоў перадач аднае рэч была падана агенту-рэалізавальніку, і гэта прызвало да трохоў разных проблем. У справаздачнасцні агента опісваецца, што ён добра знае праект, але нічога не ведае пра планаванне, якое было перад выкананнем задання.

Холадныя адносіны з праектам значаюць, што ён не мае інформацыі пра тые два гадзіны, калі вы адмовіліся ад очвічнага падходу, пераканалі ся не вжываць абстракцый і выбралі дзівнае рашэння з важлівай прычыны. Для падагента нічога з гэтага не адбылася. Тэплыя адносіны з праектам значаюць, што ён мае CLAUDE.md і базу коду, таму ён ужо знае правіла і стандарты працы без дадзення інструкцый.

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

Няхто з кераванняў падрабнічных агентаў не даў такога вывару: перадача — гэта файл, і гэты файл — гэта контракт. Гэта не абарот, напісаны ў запітаў на вікананне задання. Гэта дакумент на дыску з фіксаванымі роздзеламі, адтолькі ўспрымнуты запіт кожы раз тыха прыховвае іншы важны роздзел.

У такім разы перадача — гэта файл TASKS.md у корані рэпазітарыя, створаны спецыяльным механізмам планавання. Актывае заданне мае толькі гэтыя роздзелы, і ніякіх іншых:

• Цель. Чы ўсё будзе так, як трэба, калі праца будзе завершана.
• Чаму (паказвік). Спынак да рашэння, зафіксаванага ў PLAN.md, а не новы аргумент за яго. Паказвік, а не проза.
• Стан віканання. Агент падтрымвае гэты стан у актуальным стане. Больш пра гэта ніжэй, адтолькі гэты роздзел і ўраджае вашу безпеку.

Дыяграма у віглядзе нумераваных элементаў. Абэрантная лінія, дзе [ ] абазаванае, [x] завершанае, а [!] заблаканае; залежнасці пазначаюцца безпосерэдна, напрыклад залежыць ад #2.

Файлы. Месца, дзе выконваецца работа.

Тэсты. Перакананні, якія выкорыстоўваюцца для адзінаковага перагляду.

За межамі. Найцэннейшы раздзел у всім дакуменце.

Атрыбуты звяртання. Чым павінна складацца фінальная паведамленне.

Тое, што робіць гэта працэйным, — гэта правіла: заполніце кожны раздзел пры запуске, і ставіце галочку толькі тады, калі ён сапраўды не паслужыць. Незаполнены раздзел — гэта там, дзе агент прыменшвае сабе свабоду.

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

Стан запуску, таму што сесіі заканчываюцца

Адзін правілл вывяліў больш рэальнай працы, чым будзь-якая хытрая інжынерыя запытоў. Калі агент зупініцца, чы то завершыў, чы то знаходзіцца у блокі, ён павінен задаць фіксацію стану справ: па ходу прызначыць галочку ў поле статусу кожнага элемента і апдэйтаваць зьвістку пра стан выканання, якая мае паведамляць, што было зроблена, што знаходзіцца у блокі і чаму, што застаецца і дзе трэба продаць. Рэдагаванне TASKS.md з гэтай мэтай прымусова ў межах задання, таму што гэты файл ёсьць точкай вяснавання, калі сэсія зьнікне.

Сэсіі дзейсна зьнікаюць. Ноутбук закрываецца, з’ѐднанне перыходзіць, дасягаецца ліміту выкарыстоўвання, або вы проста набываеце нуды і нажымаеце Ctrl-C на чымсь, што ўжо майжэ завершана. Калі такое адбываецца з падагентам, усё, што ён знаў, зьнікае. Калі ўсё, што свідчыла пра прыступкі, знаходзілася толькі ў яго памяці, тады вам даводзіцца паўставляць ваш рэпазітарый у адносе да сваёй памяці, каб здагадацца, на якім ён ўжо ўзьнік.

Таму агент фіксуе прыгрыш у працы на дыску па ходу, у самым файле, які быў прызначаны для віканання задання. Наступная сесія ачынае гэты файл і продовжывае працу з таго месца, дзе ўсё было застопавана. Агент дадае калькі ліній у відпаведнае вызначэнне і перакладае завершаную сесію з статусу «загубленая праца» у статус «паставленая».

Супакоўваючыя правілы стосуюцца працэсу віканання задання, а не ўсунення наследків паставлення. Заблокаваны элемент не зупіняе чэргу. Калі элемент недастаткова апісаны або сталкнуўся з неразв’язным залежнасцю, агент пазначае яго сімволам [!] з адной лінійным поясненнем і продовжывае працаваць з усімі засталымі элементамі, якія не залежаць ад яго, зупініваючыся толькі тады, калі больш нічога не можа будзе продавацца. Агент ніколі не спробуе здагадацца пра структуру задання, а кожны заблокаваны элемент пракладаецца у атлас для подальшага рашэння чалавеком.

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

Хто плаціць за які тып мышлення

Тут поля model мае важлівую ролю, і эканаміка настройкі залежыць ад яго.

Апісанне рэалізавальніка, взятае з рэальнага праекта, гледзіце працоўнік Sonnet, які выкананае абоўсюдзе заданае, механічнае заведзенне кодавання з файла задач, пакалі галоўны поток планавання Opus продавяжае працаваць; не для рашэнняў пра дызайн, відкрытых запытанняў чы жывых тэстаў якасці, якія застаюцца ў галоўным потоку.

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

Такое раздзеленне таксама дазволяе атрымаць два рытмы працы з адной і той жа апаратуры.

• З рэгламентаваным тэмпам. Складзіце два або тры элементы, аправіце агента, а пакуль ён працуе, спланаваце наступную партыю. Ніякая з сторон не застаецца без дзеяння, чакаючы іншую.
• Без прыгляду. Складзіце больш чым дастаткова колькасць элементаў у чаргу, а потым адыходзіце, ўзвратыцеся пазней да рэзынкі, адчытку і запісу пра статус працы, дзе будзе адмечана, які элемент заблокаваў працу і чаму.

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

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

Паралельныя агенты здаюцяся спосабам для прыткай працы, але на самай працэ такога няма. Кожны з іх у канцы канцоў выводзіць усе свае рэзультаты ў той кантэкст, які яго створыў, і хітрая структура розпаду можа занурzyć сесію, якая мусіць усё гэта прачытаць. Такім чынам губіцца рэальная праця. Работа ў паралелі над аднальнымі файламі — гэта спосаб, які трэба выбраць толькі для певнага задачы, а не стандартна практыка. Стандартна практыка — калі адны агент працуе з адной чэргай па парадку.

Без бюджэту ён вытрачае ўсё

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

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

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

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

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

Гэтыя пасляпэльныя словы былі дадзены пасля таго, як запуск адпаведзеў на вопыт на чэтвёртым пошуку, але продаваўся далей, таму што 20 была назначаная колькасць. Патрэбна ясна сказаць, што раннее завершэнне — гэта перамога.

Підрахавайце тыя рэчы, якія купуюцца за певную суму. Бюджэт на запрашэнні включае кожнае запрашэнне ў сеткі — ад стандартных запрашэнняў да кожнага наступнага крока для адкрыцья заблокаваных стораніц, да кожнага HTTP-запрашэння ў дапаможнаму скрыпту; кожна спроба павторнага запрашэння з кодам 429 таксаваная окрэма. У ранней версіі лічыліся толькі „запрашэнні fetch“, і агент неняхуча працаваў праз гэты праслой. Гэта не было обманам; гэта была адказнае выконанне паслаба, напісанага некачэнна.

Змусіце яго аанунсаваць вітраты. Пасля кожнага этапу агент паведамляе рэчы на кшталт [deep: 3/20 пошукоў, 5/30 запрашаў]. Без гэтага немагчыма разлічыць адказвальную працу ад неконтрольванай, пакуль ёй не заканчыцца. Калі бюджэт выкаранае, а запытанні застаюцца без адказу, агент зупініцца і чытальна паведаміць, што застаецца невядомым, які URL найбольш верагатна дае адказ, і што можна прабавіць зноў з глыбэйшым аналізам. Адмовленым крокам ёсць продажчыце працаваць па-пераднім, не паведаміўшы пра гэта, адтак як робітнік сам выбраў рэжым, а перакранацце ліміту паўніста скасоўвае гэты выбор.

Забраненні складаюць большую частку зрэлага агента

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

Адзін прыклад паказвае, чаму самэ ўсё справа ў тых дапаможных прыметках. Агенту сказана ніколі не выкарыстоўваць автаматызацыю прыродніка: ні просты прыроднік, ні вбудованая прадваротка, ні Playwright, ні інструменты дадатка Chrome, ні адкрыванне вікон чы старонак, і калі пропонуецца якісь прыроднічы інструмент, ён не прызначаны для гэтай задачы. Прычына чыста прыказана: адкрыванне старонак для чытання вярсей, якія ўжо былі створэныя, прыводзіць да стварэння абоўсому сотні такіх старонак і паслягае на успех выканання задачы.

Іншы прыклад выходзіць з рэалізавання ў рэпазітарыі research-agent, дзе сам механізм яўляецца галоўной прычыной, чаму хтось будзе паважаць гэтая правілы. Ён ніколі не павінен ствараць файлы пад катэгорыямі agents/ або skills/, таму што agents/ ўключаецца як частка пакета, а менеджэр пакетаў пад час інсталяцыі ператварае кожны файл з расшырэннем .md у окрэмага агента на верхнім рэвэлі. Файл, які там апынуцца, будзе перадаўся ў кожны праект-корыстнік.

Гэтае ўсё прынцып, які трэба выявіць: кожны забароняючы прыказ прызначае свой механізм. Агента не трэба пераканваць. Прычыну трэба запісаць, каліхоў без яе обмежэнні будуць выправлены. Чэрэз шасць недзеяў, праглыбляючы формуліраванні, вы знайдзеце рэчэнне "ніколі не ствараць файлоў тут" — яно будзе здавацца даследным, і вы будзеце корыстна яго узагальніць. Умова пра тое, што інсталяр спрыяе аднаковаму падходу да кожнага праекта-корыстніка, якраз і змусіць вашае будучые я выйсці з гэтага пытання.

Што ўсё больш формаў можу прыняць гэтыя обмежэнні пасля дазволенага часу:

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

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

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

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

Яны зазнаюць невыразных, але впэўненых невяснасцей

Два доследжэння калі-то даўалі рэзультаты, якія былі не проста нормальныя, але і хорашыя: чыстыя нараджэнні, справжнія джэрэлы, цяперозрозумелыя атласы. У обох як галоўнае джэрэла быў названы Reddit. Аднак ніхто з яных не запрашаў нічога з Reddit.

Адзейнасць была такая, што запыт WebSearch, абмежаны site:reddit.com, вернуў дзесяць чыстых, правдападобных рэзультатаў з іншых домэнаў, сярод якіх — форум спяльнай адументнай плошчы, сайт ураду пра малы бізнес і сайт для аднароджэння слайдав, пры чым не было жадных адхылэнняў. Ні 403, ні порожняя колекцыя, ні паведамлення пра проблему. Фільтр домэнаў быў тылу няхутка ігнараваны, і нічога ў рэзультатах гэтага не паказвало. Агент меў апрануты спіс падатлых да вжытку сторанак з неправільных месцаў і зрабіў тое, што робіць будзь-яны разумны працавальнік з такім спіскам: ён іх выкорыстаў і аднавіў пра успех.

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

Неудачны запуск вымагае повторнага запуску. Запуск, які таямна заменяе сваія джэрагі, вымагае рашэння, заснованага на дапамогах, якія, як вы прыпускаеце, паходзяць з месца, дзе яных няма. Аўтаномнае вікно кантэкста, сама гэта функцыя, — гэта прычына, чаму вы не можэце бачыць, як гэта відбываецца: да вас не доходзіць ніякі транскрыпт, толькі тыя выводы, якія агент прыняў рашыцца запісаць.

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

Здзейсніце механічны тэст. Ніякіх адказоў пра адказы не было, таму агент не пачуў патрэбы чаго-небудзь пераглядаць. Рашэнне — адна фраза, якая не трэбуе адгукнення: калі пошук быў абмежаны пэўным домэнам, а жадны з адказных URL-адрэсаў не належыць яму, трэба спрацавваць гэта як нуль рэзультатаў, а не як сэт рэзультатаў. Для гэтага не трэба дадатковых інструментаў, запытоў чы праваў, калі URL-адрэсы вялікі час вучыцца. Указ «Будзьце падозральныя да своіх джэрэл» не дае агенту нічога для выканання, тады калі «Парашчуце імя хоста з тым, якое вы фільтравалі» — дае.

Спрацоўвайце паводжанне як обав’язковы канал выходных даных з схемай. Сюды форма выходных даных перастае быць сэтом заглаваў раздзялов і пачынае дзеяць як тып. Два масівы прыкрэпляюцца да іх імен ключаў.

• unreachable[] мае адно элемента на кожную стэну, пры чым ключы ўсёга ўтвараюць source, url і reason. Ён абходзіць як немагчымасць запрашання, так і тыхе замену.
• sources[] мае адно элемента на кожны істочнік, які фактычна падтрымаў адпаведны адпаведзень, пры чым ключы ўсёга ўтвараюць source, url і fields. Старонка, якая была ачынена, але не дала жадных вястэй, не фіксуецца. Істочнік, які адпаведзеў на чатыры пытанні, ўтварае адны элемент з чатырма іменамі, а не чатыры элементы.

Той тонкі кал, які спачатку быў некарэктны: інформацыя пра паходжэнне проста адзначае джэрэлу, але ніколі не блакуе яе. Калі на запытанне адпаведзеў задокументаваны заменнік, полье счытаецца адпаведзеным, а елемент unreachable проста фіксуе, што адпаведзь не падышла з названага джэрэла. Якбы полье магло зазнаць бягучыя проблемы, цэлы працэс бы зупініўся самэ тады, калі існуе спосаб працэўкі.

Адзін неякісны рэштунк несе з сабой урок, які варта выкарыстаць. У першай версіі гэтага агента было напісана, што ён павінен „запісаць гэта як недоступна“ у чатыро разныя месцы, пры тым так і не было названае поле, масіва чыра выходны элемент. Гэтыя інструкцыі нікуды не прывелі. Агенту было трэба запісаць якісь даныя, але не было куды іх падаць, таму ён нічога не запісаў, і ніхто не скаржыўся. Кожны раз, калі вы пішаце інструкцыю для падагента, пераканайцеся, што дзеянне, якое яна опісвае, мае пункт прызначэння. „Звярнуцца з X“ без названага элемента для X нічога не робіць і не мае прычын для скарг.

Пераканайцеся за межамі агента. Тое, чыі агент выпалоў свойі зобав’язанні ў выходных даных, вяршыцца за дапамогою скрыпты, якая запускаецца пасля, а не за адказамі самага агента. Апошнія 180 рэядоў коду на Python пераглядаюць JSON-даныя па адзначаным полям, і гэта мае большую цэню, чым будзь-якія падкрэсленні ў самай інструкцыі.

Тая ж самая ідэя практыкуецца ў інструменце для рэпазітарыяў, у якіх няма набора тэстаў. У інструкцыі зазначаецца, што такога набора няма; у раздзеле «Тэсты» задання перыяктуецца спіс перакананняў, якія выступаюць у ролі тэстаў, кожна з яых павінна быць выканана, а рэзультаты — конкрэтна заданы. Калі перакананне гласі «гэты URL разыяўляецца», гэта значыць, што яго насправды трэба запрашаць. URL, які не можа быць перакананы, не падае ў файл; ён фіксуецца як неперакананы, разам з тым, што сталася, адтуды што чытач, які паверыць лінку, які ніхто не пераканаў, запрашаць будзе дарэмна, таму што адпаведны 404-ы код мог быць ухілены простым пошукам, і тады неперакананы URL стае горшым выборам, чым яго ўзагалі не выкорыстоўваць.

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

Адзін завод для кожнага агента, і прычыны збільшэння файлу

Найлепшыя падагенты маюць адзін завод. Вы можаце заперачыцца, адколькі вышэўказаныя файлы не ў малым размерэ, а файл агента-дзеяча налічва аж 188 ліній. Разлік, які рашае пытанне: завод застаўся адной фразай, тады як файл зрас. Тое, што накапіліваўся, — гэта абмежэнні, правілы выканання і умовы выходу, «шрамавая» ткань навакола фіксаванага «скелета», і жадных новых абавязакоў за год. Даўненне ліній у зв’язку з падбіянням чагось означае, што файл выкананае сваю працу. Даўненне ліній для віканання новага тыпу работ — гэта збільшэння размеру файлу, і спосаб рашэння гэтай проблемы — раздзеліць агента, а не прыўязваць яшчэ адзін раздзял.

Усі перэдметныя версіі выглядаюць аднакова, і кожна з іх колісціла ў які-небудзь момент. Ёсць такі, які аналізуюць усё, але даюць сярэднія значэння па пяці аспектах і не выдзейнаюць у нікаму з іх; ёсць ярлык „старшы інжынер“, але пасля яго няма жадных практычных наследків. Ёсць агенты, які проста перапісваюць ваш CLAUDE.md, дадзягаючы толькі інформацыю пра вартасць токенав, а не пра ўласная дзеязнасць, а таксама тые, які дуплікуюць адну і тую ж навык, пакуль два варыянты не пачнуць розніцявацца. Усія яны маюць адну асновную памылку: задача стала занадта масіўной, як увесь абзац.

Зрозумелы наступны вопыт — што ж, пасля года такога становішча, на самай справе застаецца на робочай плошчы.

Два, які перажылі

Большасць пастаў на гэту тэму проста даўаюць схему структуры агентаў, якія трэба стварыць. Але на самай справе пасля года застаюцца толькі два агенты, і ўсё.

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

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

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

Усе іншае, што знаходзіцца ў папках агентаў, прыбыло разам з фрэймворкамі, і гэта працюе як яшчэ адна папка з непатрэбнымі дакументамі, але з лепшым брэндам, чым справжняя. Спецыялісты, якіх прыпускалі як неабходных (аналізавальнік тэстаў, агент для прыглажвання PR, чалавек, які готавіць дакументацыю, агент для керавання кодавой базай для праектаў, якія былі пакінуты), усі здаваліся разумнымі, але практычна ніхто з іх не быў створаны. Тые, якія застаюцца, насправды не ўсега тые, якія здаваліся корыстнымі. Гэта тые прыклады, дзе тая ж самая конкрэтная проблема працы, якая выклікае труднасці ў неправільным кантэксце або у неправільнай особе, продовжваецца практычна ўсё час.

Тады прыскніце ад схемы структуры організацыі. Зверніце увагу на працу, якая, як вы хочаце, мялася б выконвацца ў іншым месцы, і зафіксавайце яе.

Спачатку шаблон, а потым спецыялізацыя

Патэрн, які дазволіў зробіць другіх, трэціх і чатвертых віконавцаў дышэўскімі, выглядае так: агент генеруецца з шаблону, а пасля выклікае разлікі там, дзе праект разніцяцца.

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

Пасля чаго кожна копія стварыць сабе адзін раздзел для сваёй сферы можлівых абяканоў, і размешчэнне двух копій па боку адна ад другой ёсць інструктыўнае. Шаблон прыказвае агенту падтрымліваць стан тэстовага набора як «зелёны». У аднаго праекта вообшча няма такога набора. Гэта хранілішча запітоў, і ўсім екзекувальным файлам ў ям ёсць верыфікатор. Таму яго розрабальнік кажа абошто іншае: хранілішча маюць запіты і даны, а не код; рэдагаванне файла — значыць рэдагаванне запіту; формулаванне, парадак і акцэнты ёсць часткай рэалізацыі; а перапісваў, які чытаецца лепей, але пасля чаго знікае строгая абмежэння, ёсць рэгрэсіяй, якую нічы не пазначыць, адколі не існуе ні будовы, ні тэстаў.

Копія іншага праекта паклікана вучыцца тым рашэнням у файле PLAN.md, на якія вказывае задача, прычым ужо перад напісаннем коду, а таксама мае рэгламент для адчыткі пра усё, што вымагае втручання Opus або чалавека. Протакол застаецца тым самым, а небяспекі разныя.

Гэтае раздзеленне трэба памятаць. Падмэркавы агент можа перадаць занова свой протакол, а частка, спецыяльная для конкрэтнага праекта, — гэта яго «паверхня абякання». Фарматавайце першую частку за шаблонамі, другую пісаць вручную, і не намагайцеся, каб адна файлавая структура пакрыла або тое, або іншэ.

Направіце агента да ведамасцей, а не копіюйце ў яго

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

Мая паканальніца раней была такой: даваць назву адпаведнаму навыку внутрь самага агента. Але лепшы падход — строгішы: агент чытае ведамасці пад час выканання, перш чым можа дзеяць, а запітач выясняе прычыну.

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

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

Два механізма мелі большое значэнне, чым чакалася.

Кандыдаты па парадку, а не адна дарога. Агент працуе ў праектах, якія арганізаваны інакш, на двух апаратах пад разнымі іменамі выкарыстоўначаў, установленых разнымі інсталярамі. Таму інструкцыя пераказвае месцы розташоўкі кандыдатаў па парадку і працавае з першым, які існуе, пры чым спачатку беруцца копіі з самога праекта, а потым — з рэгістру выкарыстоўнача. Калі закодаваць адну дарогу, усё будзе працаваць толькі на аднам апараце.

Буквальныя назвы прыяўляюць шары адзін да другога, і нічога іх не паўтарае. Дызайн складаецца з трохоў рангаў: навыкі керуюць, агент выканае работу, а модулі дадзеных зберагаюць знанні. Ніякіх імпортаў няма. Навык запускае агента пад яго точным зарэгістраваным назвам, а агент знаходзіць модулі па шляху. Гэта дае рэпазітарыю яго найзвычайнейшы і найбольш апасны пункт — нагадку не перайменаваць агента для веб-шукання, адколі існуючыя корыстувальнікі вызываюць яго безпосерэдна.

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

Дзе знаходзяцца файлы: персональныя, праектныя, запакаваныя

Існуе тры ці рэвангі, і на трэцім жывуць усі справжніе агенты.

• Персональныя (~/.claude/agents/) — гэта спецыялісты, якія патрэбны для кожнага праекту. Спрытваце іх як майстэрню, дзе дазволена падбіянка.
• Праектныя (.claude/agents/, зберажаныя ў коміты) — гэта спецыялісты, якія маюць сэнс толькі ў аднай базе коду, напрыклад, імплементатар, які знае, што ў праекце няма тэстаў. Зберажыце іх у коміты, і яны будуць чакаць, калі вы вернуцеся, нават пасля чатырох месцаў, калі праект забудзецца.
• Упакаваныя (установленыя прамарам зборкі і прыкрэпленыя да конкрэтнага коміту) прыводзяць агента да стану залежнасці. Гэта той рэванг, пра які ніхто не ведае, што ён патрэбен, пакуль той жа агент не опыніцца ў дзесятку рэпазітарыёў, а трохце копій не пачнуць розходзіцца.

Трэці ўзлёт змінюе калькі рэчаў, і лепшая знайсці пра іх інфармацыю прыходзячы туды.

Аб’еднайце агента з навыкамі, якія яго запускаюць. Пакет містыць іх обаякова як адну еўранудзелю з простай прычыны: навыкі, установленыя без адпаведных агентоў, ствараюць ланцоўку, якая ламаецца праз першыя выкарыстанні. Навык, які прабуе запусціць агента па імені, калі яго няма, ўскладнюе установку, пры чым у найкрашчым случае паказваецца чыткае паведамленне пра адмову. Яны ўважаюцца адной еўранудзелю, таму што ўтвараюць адну угоду.

Дазвольце дазнацца, што вашы інсталляр рабіць з файламі. Шырокі пакет інсталюецца праз APM ад Microsoft, які ператварае кожны файл .md у каталозе agents/ на самастоятэльнага агента вышэйшага рангу. Гэты стандартны падход ёсць разумным, але ў той жа час стварае проблемы. Як толькі ў гэтым дрэве каталога з’яўляецца файл дадзеных, кожны праект-спожывач атрымвае фальшывага зарэгістраванага агента. Калі ж там запісаць агента, спецыяльнага для конкрэтнага праекта, ён інсталюецца ў рэпазітарыях усіх спожывачаў. Самэй гэтага модулі стратэгій пошуку знаходзяцца ў каталозе skills/, а не ў каталозе agents/, дзе, здавалася, ім і мясцо: у agents/ яны бы пасля інсталляцыі втрачалі свою структуру і стваралі па пяць фантамных агентоў у кожным праект-спожывачы.

Закрэпіце певны коміт, і пам’ятайце, што корыстувальнікі адстаюць пазурамі. Корыстувальнікі завісяць ад SHA-коду, таму патч не стане доступным для нікога, пакуль закрэплены коміт не будзе зменены, а інсталяцыя не перазапусцена. Напісанне патча — гэта не яго розповсюджэнне. На сторанцы гэта здаецца явным, але на практыцы так не ўсё, колі о 23:00 знову з’являецца баг, які быў вылечаны мінулы тыдзень.

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

Тая ж ідэя ў іншых інструментах

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

GitHub Copilot і VS Code называюць іх спецыяльнымі агентамі, якія зберагаюцца у файлах фармату .agent.md, зазвычай у каталозе .github/agents/, пры чым існуе можлівасць стварыць персональную бібліятэку ў дырэктарыі карыстальніка. У фронтматэры ёсць больш поль, чым у Claude: пашчэрасці name, description і tools дапамагаюць, а таксама ёсць argument-hint, model, user-invocable, disable-model-invocation і, што найкрашча, handoffs. Готовы агент можа паказаць кнопку, якая перадае заведамасць іншаму агенту, ужо заполніўшы наступны запіт, такім чынам планаванне, рэалізацыя і перагляд адбываюцца адразу, без злічынення ў аднаго заплутанага агента. Калі чытаць старэйшыя прыклады, гэта можа стаць пасткай: ранейша польна infer была ператворэна на два адзінаковыя поля — user-invocable і disable-model-invocation; згодна з пазнейшым аналізам гэта ўпорадкована змянена, але спачатку яна вельмі заплутальная.

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

Натомст насправе выкорыстоўваецца адзін канонічны запрос плюс просты внутршні элемент для кожнага інструмента. Усі коды агента з боку Copilot у пакеце складаюцца з аднаўсем ліній:

---
name: Web Research Writer
description: "Use for bounded web research that must read a local schema, search and fetch current sources, write one designated result file, and validate it with a local command."
tools: [read, search, web, edit, execute]
user-invocable: false
disable-model-invocation: false
---

Load the installed canonical research prompt from the first existing candidate:

1. `.github/agents/web-search-agent.agent.md`
2. `.claude/agents/web-search-agent.md`

Follow its search budgets, module routing, source standards, tool discipline, output, and validation rules. Ignore that file's incompatible `tools` frontmatter; this wrapper's Copilot-native tool categories govern this session.

Гэта ўсё схэма. Натыўны фронтматэр дазваляе хосту правільна зарэўістраваць агента, лестніца пашоў выкарыстоўваецца для адыскання рэальнага запіту, а адна простая фраза паказвае, які слоўнік інструмента мае прыорытэт. Усе 188 ліній накупленага поведэння знаходзяцца ў аднам файле, а другі інструмент атрыбуецца паказчыкам, а не фарком. Две копіі запіту ствараюць два запіты, і тады, калі ў аднаго выправляецца баг, а ў другога — ні, яны пачынаюць выдаваць ся за аднаго агента.

У докуменце README да праекта паведамляецца аб аднай проблеме. Калі нацэліць ладэр на .github/agents/, канонічны запіт рэўіструецца як самастоятэльны агент, таму Copilot можа паказаць дублікаты імен: „Web Research Writer“ і, пад яным, канонічны файл. Выберыце адну базу для кожнага інструмента або заставіце канонічны файл у .claude/agents/, дзе автадэтэкцыя Copilotа яго ігнаруе.

Усе іншае, укладаючы Курсар і Windsurf, прагне да таго ж пад такімі назвамі, як правілы, рэжымы чыст агенты. Дакладныя вялікія часта зменяюцца, таму лепшая перадаць вас да актуальной дакументацыі кожнага інструмента, чым з упэўненасцю ствараць тверджэння пра змяны, якія адбыліся месяц тыму. Асновная сутнасць не зменяецца: гэта повторна выкарыстоўваны файл, які візначае ролю і які спецыяльна запускаецца. Як толькі вы цэе з’ясуеце, застаецца толькі знайсці, дзе кожны інструмент хавае свой папаку.

Як насправды ствараюцца хорашы інструменты

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

Прыгучайшая частка, тая, якая могла бы памагчыць ўчора, — гэта не «ітэрацыя». Усі кажуць «ітэрацыя». Гэта тое, з чаго складаюцца ітэрацыі.

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

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

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

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

Паглядзіце на работу, якая, як вы хочаце, мусіць выконацца ў іншым месцы. Гэта падагент, які ўсё ўсё чакае на адгук. А калі падагент востатні раз вас падвёў, гэта значыць, што ўсё ўсё чакае на напісанне паведамлення.

Спаднія статты

• Практычныя прыемкі: Пасляўязныя інструкцыі па стварэнню вашага персональнага агента — Дэталізаваны апісанне Практычных прыемакоў: Пасляўязныя інструкцыі па стварэнню вашага персональнага агента: контракты, перакрыцчы і месцы для коду для команд, якія вікорыстоўваюць гэты патэрн.
• Практычныя прыемкі: Qwen3.8–27B як новы выбраны кодаваючы агент з SGLang/vLLM і — Дэталізаваны апісанне Практычных прыемакоў: Qwen3.8–27B як новы выбраны кодаваючы агент з SGLang/vLLM і: контракты, перакрыцчы і месцы для коду для команд, якія вікорыстоўваюць гэты патэрн.

„The Harness Is the Product“: Практычныя вядомасці пра прыстроі керавання ў агентным ІІ — Дазвольце вам дазнацца, што такое прыстрой керавання агента і якія ў яго семь элементаў: ад інструментаў і кантэксту да правілаў і методаў ацэнкі, а таксама пра падагентаў, спосабы абвалення і канструкцыі, якія варта знаць.