Dauguma komandų, kurios susiduria su sunkumais dirbant su DI sugeneruotu kodu, mano, kad pagrindinė problema yra dirbtiniam intelektui pateikta užklausa. Jos tiki, kad parašius geresnę užklausą, agentas pagaliau sukurs kodą, kurį bus verta įtraukti į projektą. Mūsų patirtis rodo, kad iš tikrųjų ši problema nėra tokia dažna. Puikus agento sukurtas rezultatas nėra atsitiktinumas, ir tai nėra vien tinkamos formuluotės radimo klausimas. Tai yra programuojamo konteksto, dokumentacijos, taisyklių ir struktūros, kurią komanda sukuria aplink agentą prieš jam parašant bet kokią kodo eilutę, rezultatas.
Komandos, kurios nuosekliai gauna gerus rezultatus iš „Claude Code”, „Codex”, „Cursor” ar bet kurio kito kodavimo agento, nebando tiesiog geriau formuluoti užklausų. Jos kuria kontekstą, kuriuo agentas naudojasi savo darbe.
Kontekstas yra infrastruktūra, o ne popierizmas
Pirmasis pokytis, kuris turi įvykti, yra kognityvinis: projektavimo dokumentai, architektūros užrašai, API sutartys, naudotojų sąveikos scenarijai ir kodavimo taisyklės nėra dokumentacija, kurią rašote žmonėms, tikėdamiesi, kad agentas į ją užmes akį. Tai infrastruktūra, kurią agentas naudoja tiesiogiai kiekvieną kartą, kai jis paleidžiamas. Jei šios infrastruktūros trūksta arba ji pasenusi, agentas dirba aklai, ir jokia gudri užklausa to neištaisys.
Penki lygiai, kurių agentui reikia
Mes į kontekstą žiūrime kaip į piramidę, kurioje kiekvienas lygis atsako į skirtingą klausimą, kurį agentas turi žinoti, kad galėtų tinkamai atlikti užduotį:
Strateginis kontekstas: kam iš tikrųjų skirtas produktas, kaip atrodo sėkmė ir ko mes aiškiai neketiname daryti.
Sistemos kontekstas: architektūra, technologijų rinkinys, API sutartys, kurios apibrėžia, kaip komponentai bendrauja tarpusavyje.
Modulio kontekstas: už ką atsakingas konkretus komponentas, nuo ko jis priklauso ir kaip gerai jis yra testuojamas.
Užduoties kontekstas: konkretus šio darbo etapo planas, jo tinkamumo kriterijai ir bet kokie apribojimai, kaip jis turi būti atliktas.
Kodo kontekstas: konkretūs pavyzdžiai, naujausi pakeitimai ir konkrečiai saugyklai taikomos taisyklės, kurios išlaiko naujo kodo nuoseklumą su tuo, kas jau egzistuoja.
Praleiskite lygį, ir agentas tą tarpsnį užpildys spėjimais. Kartais tie spėjimai yra pakankamai tikslūs. Dažnai ne, ir tada pradeda kauptis peržiūros ciklai.
Keturi modeliai, kurie atskiria patikimą agento rezultatą nuo netvarkos
Skaidykite darbą į nedideles užduotis
Didelių, neapibrėžtų užduočių reikalavimus lengva pamiršti. Sprendimas yra užduočių skaidymas: padalinkite darbą į vienetus, kuriuos galima savarankiškai patikrinti, apytiksliai užtrunkančius 15-30 minučių. Tokio dydžio užduotį lengva patikrinti, lengva pakartoti, jei kas nutinka blogai, ir lengva perduoti, nesvarbu, ar tam pačiam agentui rytoj, ar visai kitam agentui.
Pateikite rezultatus etapais, o ne visą iš karto.
Prašymas agentui vienu kartu sukurti pagrindą, esminį funkcionalumą, ribinių atvejų apdorojimą ir galutinį poliravimą skatina nepastebimą projekto apimties augimą. Progresyvus tobulinimas (pirmiausia pagrindas, tada esmė, tada patikimumas, tada optimizavimas, tada tobulinimas) leidžia kiekvieną etapą lengvai peržiūrėti ir neleidžia agentui priimti projektavimo sprendimų trimis sluoksniais į priekį nuo to, kur komanda faktiškai yra.
Pasakykite agentui, ko jam nereikia daryti.
Tai modelis, kurį dauguma komandų praleidžia, ir jis atlieka didžiausią darbą. Agentas, kuriam tik pasakoma, ką kurti, mielai perrašys gretimą kodą, pervardins kintamuosius, kurių jo nebuvo prašyta liesti, arba pertvarkys modulį taip, kaip niekas nenorėjo, nes iš jo perspektyvos tai atrodo naudinga. Trumpas, konkretus apribojimų sąrašas, kas nepatenka į apimtį, kas neturi keistis, kokių modelių vengti, pašalina daugumą šių neprašytų nukrypimų prieš jiems atsirandant.
Pateikite tikslų kontekstą, o ne visą informaciją vienu metu
Visos saugyklos įklijavimas į užklausą nėra tas pats, kas suteikti agentui gerą kontekstą. Tai priešingybė: signalas, kurio agentui iš tikrųjų reikia, paskęsta triukšme, kuriame jis pats turi rasti svarbią informaciją. Komandos, kurios gauna geriausius rezultatus, apgalvoja, kas turėtų priklausyti kiekvienam piramidės lygiui ir pagal tai atnaujina projekto kontekstą.
Kaip žinoti, ar tai veikia
Konteksto architektūra naudinga tik tuo atveju, jei galite įvertinti, ar ji atsiperka. Keletas rodiklių, kuriuos verta stebėti:
Bent 80% užduočių turėtų būti sujungiamos su pagrindine kodo šaka per tris ar mažiau peržiūros ciklų.
10-20% užduočiai skiriamo laiko išleidimas konteksto paruošimui yra normalu, ne švaistomos pastangos.
Beveik visi DI sukurti pakeitimų pasiūlymai turėtų įtraukti ir kodo testus, o projekte įtrauktų testų neturėtų mažėti.
Didelės pataisos, apibrėžiamos kaip daugiau nei 30% eilučių pakeitimas po peržiūros, turėtų sudaryti ne daugiau nei 20% visų užduočių.
DI sukurto kodo klaidų dažnis, skaičiuojant tūkstančiui eilučių, turėtų būti lygus arba mažesnis nei jūsų komandos rankinio darbo bazinis rodiklis.
Dokumentacijos ir kodo santykis turėtų būti apytiksliai 1:4, tiek, kiek pakanka agentui nukreipti, bet nepavirsta savarankiška priežiūros našta.
Kai šie skaičiai pradeda nukrypti, priežastį dažniausiai galima atsekti. Kai peržiūros ciklai ištęsiami virš trijų, tai rodo, kad užduotys yra pernelyg didelės arba neaiškios, ir sprendimas yra jas skaidyti dar smulkiau ir sugriežtinti apribojimus. Didelių pataisų padažnėjimas rodo silpną modulio kontekstą, dažnai išsprendžiamą atnaujinant komponento aprašą ir aiškiai nurodant taisykles, kurių jam būtina laikytis. Trūkstami testai arba mažėjantis padengimas yra proceso, o ne technologijos, spraga, ir geriausia jį sugauti blokuojant kodo sujungimą, kol nebus sukurti reikiami testai. Kylantis DI klaidų dažnis dažniausiai reiškia konteksto trūkumus: prieš pradedant kitą užduotį, pridėkite atkartojimo testo reikalavimą ir sugriežtinkite statinius patikrinimus.
Kaip tai atrodo priklausomai nuo įrankio
Principas yra tas pats visur: suteikti agentams struktūrizuotą, aktualų kontekstą. Įgyvendinimas skiriasi priklausomai nuo įrankio.
„Claude Code” atveju failas CLAUDE.md saugyklos šaknyje automatiškai užsikrauna kaip kontekstas kiekvienai sesijai, pakartotinai naudojami veiksmų scenarijai laikomi kataloge .claude/commands/, o failas .mcp.json iš anksto sukonfigūruoja išorinius įrankius, kuriuos agentui leidžiama naudoti.
Naudojant „OpenAI Codex”, komandos paprastai pradeda tik skaitymo pokalbio režimu, peržiūri pasiūlytą planą ir pereina į agento režimą tik tada, kai planas atrodo tinkamas. Ilgesnės, kelias valandas trunkančios užduotys vykdomos izoliuotoje aplinkoje, o gera pradžia yra tokia, kai agentas iš naujo išdėsto savo prielaidas ir pasiūlo žingsnis po žingsnio planą prieš pradedant liesti kodą.
„Cursor” atveju projekto taisyklės saugomos .cursor/rules/*.mdc failuose, kurie užkoduoja politiką kaip kodą, o ne kaip pokalbį, kurį agentas galėtų pamiršti, o @DocName užklausa pagal reikalą pritraukia srities žinias. Daugelis komandų tai naudoja kartu su PRD paremtu ciklu: viena naudotojo istorija per sesiją, peržiūrima prieš pradedant kitą.
Minimali saugyklos struktūra, tinkanti visiems trims, gali atrodyti taip:
project-root/
├─ README.md
├─ docs/ (architektūra, sprendimai, api, db schemos)
├─ src/ (moduliai, kiekvienas su AI_SUMMARY.md failu)
├─ .cursorrules
├─ CONTRIBUTING.md
└─ TASKS/ (datuoti darbo planai)
Klaidos, kurios visa tai sugriauna
Net komandos, kurios supranta konteksto architektūrą, patenka į keletą pasikartojančių spąstų. Magiškos užklausos klaida yra tikėjimas, kad viena pakankamai gudri mega-užklausa gali pakeisti tikrą struktūrą, tačiau ji to padaryti negali. Konteksto perkrova yra priešinga klaida: visos kodo saugyklos įklijavimas agentui, vietoj to, kad būtų atrenkama iš tikrųjų agentui svarbi informacija. Besąlygiško sutikimo spąstai yra agento pakeitimų priėmimas be reikalavimo atlikti testus ar peržiūrą, vien dėl to, kad kodas atrodo tikėtinas. O apimties augimo skatinimas yra tai, kas atsitinka, kai apribojimai lieka neparašyti, leidžiant agentui interpretuoti naudingumą taip, kaip jam patinka.
Trumpas patikros scenarijus, kurį agentas gali paleisti prieš pripažįstant užduotį atlikta, tipų tikrinimas, vienetų testai, pagrindiniai galutiniai scenarijai ir stiliaus tikrinimas, duoda visiems patikrinamą įrodymą, kad pakeitimas yra suderintas prieš jam pasiekiant pakeitimų pasiūlymą, vietoj vilties, kad kodas tikriausiai yra tinkamas.
Pagrindinė mintis
DI agentų kodo kokybė nėra užklausos formulavimo problema. Tai projektavimo problema, ir jai taikoma ta pati disciplina, kurią gera programinės įrangos architektūra visada turėjo: aiškūs konteksto lygiai, mažos patikrinamos užduotys, etapinis pateikimas ir aiškūs draudžiamų pokyčių apribojimai. Komandos, kurios šią struktūrą nusprendžia iš karto, sumažina dažnai technologijos silpnybe laikomų reikiamų peržiūros ciklų kiekį.
Jei jūsų komanda susiduria su nenuosekliais DI kodavimo agentų rezultatais ir norite gauti antrą nuomonę dėl jūsų konteksto struktūros, susisiekite su mumis.