Versija 1.0.0-alpha.1naujausia
2.26 skyrius
Kūrimas su DI programavimo įrankiais
Kaip saugiai kurti „Nexus“ plėtinius su „Claude Code“ ir kitais DI (dirbtinio intelekto) programavimo įrankiais. Pradedama nuo jūsų IDE (integruotos kūrimo aplinkos) prijungimo prie „Workbench“ ir projekto failo CLAUDE.md, kuriame aprašytos platformos taisyklės, o baigiama šešiomis praktiškai išbandytomis užklausomis bei patikros vartais, patvirtinančiais kiekvieną iš jų.
Šį puslapį iš originalo anglų kalba išvertė DI. Jei kas nors neaišku, remkitės puslapiu anglų kalba. Skaityti šį puslapį anglų kalba

Didžioji dalis Cold chain paketo, aprašyto 2.24 skyriuje „Individualios vertikalės kūrimas nuo pradžios iki galo“, buvo parašyta šalia manęs terminale atvėrus Claude Code. Dabar Corrán Orbital tai įprasta, ir Nexus buvo kuriama tai numatant. Platforma DI (dirbtinio intelekto) programavimo įrankio nelaiko gudriu automatinio užbaigimo įrankiu. Ji laiko jį agentu, veikiančiu konkretaus asmens vardu, turinčiu leidimą, kuris visada siauresnis nei to asmens, ir registruoja kiekvieną agento atliktą iškvietimą.
Šiame skyriuje aprašoma, kaip taip dirbti nepakenkiant sau. Jis prasideda nuo jūsų IDE (integruotosios kūrimo aplinkos) prijungimo, tada aptaria įgūdžius redaktoriuje, projekto failą, kuris išmoko įrankį platformos taisyklių, du kompiliatorius, kurie esamą darbą paverčia Nexus kodu, kaip įsipareigojimuose (commit) nurodoma, kuris įrankis juos parašė, ir kaip aš peržiūriu įrankio sukurtą rezultatą. Pabaigoje pateikiami šeši raginimai, kuriuos perduočiau kolegai, kiekvienas su tuo, kas turėtų būti grąžinta, ir patikra, kuri tai įrodo.
Jūsų IDE prijungimas prie „Nexus“
Kiekviename diegime yra vienas Workbench adresas DI programavimo įrankiams. Jį rasite puslapyje „Prijunkite savo IDE“, skiltyje „Kūrėjams“, o Claude Code prisijungia viena komanda:
claude mcp add workbench --transport http <workbench-address><workbench-address> yra puslapyje rodomas adresas su šalia esančiu kopijavimo mygtuku. Kiti įrankiai tame pačiame puslapyje turi savo vienos eilutės komandas: codex mcp add workbench --url <workbench-address> – Codex, diegimo nuoroda – Cursor, ir code --add-mcp su nedideliu JSON argumentu – VS Code su Copilot. Visi jie tuo pačiu adresu bendrauja MCP (Model Context Protocol) protokolu.
Jokio rakto įklijuoti nereikia. Pirmasis iškvietimas atveria jūsų naršyklę, kurioje tiksliai parodoma, kas prašo: kuris įrankis kuriame kompiuteryje, kieno vardu veikia ir kokių lygių nori. Leidimą suteikiate savo prieigos raktu (passkey), ir nuo tada įrankis neturi nei duomenų bazės slaptažodžio, nei kubeconfig, tik baigtinio galiojimo leidimą. Už šio adreso Nexus kiekvienai saugyklai, kiekvienai užklausai jūsų vardu sukuria trumpalaikius prisijungimo duomenis.
Organizacijos administratorius taip pat gali atsisiųsti valdomų nustatymų failą, kad kiekviena įmonės Claude Code kopija jungtųsi prie šio serverio ir jokio kito:
{ "workbench": { "type": "http", "url": "<workbench-address>" } }Lygiai ir leidimai
Kiekvienas prisijungimas prie Workbench gauna leidimą, sudarytą iš įvardytų lygių. Kūrėjui numatytieji yra „Stebėti“ ir „Smėlio dėžė“ jo paties vienetams.
| Pakopa | Ką ji leidžia | Kas jį gauna |
|---|---|---|
| Stebėti | Skaityti savo vienetus, įskaitant žurnalus ir metrikas, ir teikti užklausas maskuotai kopijai | Numatytoji reikšmė |
| Smėlio dėžė | Rašyti savo erdvėje: savo kūrimo erdvėje ir savo duomenų šakose | Numatytoji reikšmė |
| Siūlyti | Atverti pakeitimo užklausą; po peržiūros ją pritaiko konvejeris | Prašoma pirmą kartą naudojant |
| Išplėsti | Vienas laiko riboto veiksmas su vienu taikiniu, patvirtintas konkretaus asmens | Tik žmonėms, niekada vien prisijungus |
| Avarinė prieiga (break-glass) | Avarinė prieiga | Tik platformos administratoriams, su dviem tvirtintojais |
Agentas visada veikia asmens vardu ir rodomas kaip atskira eilutė. Jo leidimas niekada nebūna platesnis nei jūsų ir niekada neapima lygio „Išplėsti“ ar nemaskuotų duomenų. Jis galioja valandą ir atnaujinamas tik tol, kol esate aktyvūs Nexus arba IDE. Asmens leidimas galioja 8 valandas. Todėl per naktį paliktas veikti įrankis sustoja pats, o nutraukus savo leidimą nutraukiamas ir jūsų agento leidimas. Kiekvienas agento leidimas taip pat turi modelio sąnaudų biudžetą, įvertinamą prieš suteikiant leidimą ir rodomą kaip skaitiklis jam veikiant.
Puslapyje „Mano prieigos leidimai“ išvardijami visi jūsų ir jūsų agentų turimi leidimai, su jų lygiais ir iki šiol patirtomis sąnaudomis, ir galite kiekvieną atnaujinti, susiaurinti arba nutraukti. Nutraukus leidimą, kitas iškvietimas sustabdomas iš karto; kiekvieno iškvietimo įrašas išlieka. Kiekvienas leidimas taip pat turi griežtas ribas, kurios mūsų atveju buvo 200 eilučių ir 30 sekundžių vienai užklausai bei 50 pakeistų objektų kūrimo erdvėje per seansą.
Pirmoji sesija IDE aplinkoje
Prisijungus, /mcp Claude Code programoje išvardija Workbench įrankius, sugrupuotus pagal lygį. Grupėje „Stebėti“ yra skaitymo įrankiai: workbench.k8s.describe, workbench.k8s.events, workbench.logs.query, workbench.metrics.query, workbench.traces.get, workbench.db.schema, workbench.db.query maskuotai kopijai, workbench.graph.query ir workbench.vector.search. „Smėlio dėžė“ prideda workbench.devspace.deploy, workbench.branch.create ir workbench.branch.reset. „Siūlyti“ prideda įrankius, kurie atveria pakeitimo užklausą ir suplanuoja grafo pakeitimą. Lygio „Išplėsti“ leidime išvis nėra; jo prašote konsolėje.
Mano pirmasis tikras klausimas buvo, kodėl mūsų telemetrijos skaitytuvas per naktį Roterdame buvo paleistas iš naujo. Claude Code aprašė darbo krūvį (du paleidimai iš naujo, atminties trūkumas viršijus 512 MiB ribą), pateikė užklausą žurnalams (organizaciją nustatė šliuzas, asmens duomenys užtušuoti) ir atminties metrikai ir nustatė, kad naktinis įkėlimas visos nakties rodmenis sutraukė į vieną paketą. Tada, pusiau bandydamas, paprašiau jo duomenų bazės slaptažodžio, kurį naudoja paslauga. Workbench atsisakė su SECRET_NEVER_SHOWN. Ji rodo Secret pavadinimą ir paskutinius keturis simbolius, bet niekada ne reikšmę, ir niekam. Asistento atsakymas buvo teisingas: slaptažodžio jam nereikia, nes kiekviena jo užklausa gauna savo trumpalaikius prisijungimo duomenis – tik skaitymo vaidmenį, sukurtą tai vienai užklausai.
Pirma planas, tada pritaikymas
Kiekvienas įrankis, kuris ką nors keičia, pirmiausia parodo planą. Planas yra skirtumų sąrašas (diff) su skaičiais ir kontroliniu atspaudu, o pritaikymas vykdo tik tą planą, tiksliai.
Jūsų pačių kūrimo erdvėje pritaikymas vykdomas iš karto. Už jos ribų asmuo turi patvirtinti IDE, o pakeitimas patenka į konvejerį, kuris jį pritaiko po peržiūros. Iš to kyla du atsisakymai, ir abu mane užklupo:
- Iš scenarijaus, kai prie klaviatūros nieko nėra, pavyzdžiui,
claude -pcron užduotyje, nėra kaip parodyti patvirtinimo langelio, todėl pakeitimas už smėlio dėžės ribų atmetamas suCONFIRMATION_UNAVAILABLE. Nieko neįvyksta. Paleiskite jį interaktyviame seanse. - Pritaikymas, nurodantis planą, kurio šis seansas niekada nesukūrė, arba planą, kuris pasikeitė, atmetamas su
PLAN_FINGERPRINT_MISMATCHprieš ką nors vykdant. Suplanuokite iš naujo.
Skaitymo užteršimas
Klientų turinyje gali būti paslėptų nurodymų, skirtų asistentui. Todėl, kai seansas jį perskaito, jis netenka įrankių rašymui ir išėjimui už Nexus ribų, kol asmuo nepatvirtina vieno rašymo arba nepradeda naujo seanso.
Su tuo susidūriau pretenzijos dokumente, kuriame buvo pastraipa, skirta „asistentui“, prašanti nukopijuoti pretenzijų lentelę į išorinį adresą. Claude Code ją ignoravo ir apie tai pranešė. Kai paskui paprašiau įtraukti nukrypimą į mano šakos grafą, rašymas buvo atmestas su SESSION_TAINTED. Galėjau patvirtinti tą vieną rašymą perskaitęs jo planą arba pradėti naują seansą, kuris dokumento nebuvo skaitęs. Žurnalai ir metrikos seanso neužteršia. Dokumentai, užklausų bilietai, laiškai ir grafo šaltinio tekstas – užteršia. Paslėptas tekstas mano veiklos įraše buvo užskaitytas kaip turinyje rasti nurodymai, be jo žodžių.
Kita organizacija
Niekas, ką įvedate, negali pasiekti kitos organizacijos duomenų. Paprašykite jų, ir kiekviena saugykla atsisakys su TENANT_BOUNDARY. Į žurnalų užklausą įterptą organizacijos reikšmę šliuzas pakeičia jūsų pačių reikšme. Tai nėra trūkstamas leidimas. Kiekvienas kelio sluoksnis aptvertas jūsų organizacija, todėl iš jūsų pozicijos nėra nė vieno, kas galėtų tai suteikti, ir platformos administratoriaus prieiga taip pat nepadėtų. Jei dvi organizacijos susitaria dalytis duomenimis, tai yra tarp jų sudarytas susitarimas, o ne kažkas, ką atlieka IDE seansas.
Įgūdžiai IDE aplinkoje ir „Claude Code“
Skills Engine įgūdžiai yra SKILL.md aplankai, ir Claude Code skaito tuos pačius aplankus. Biblioteka sinchronizuojama į ~/.claude/skills jūsų pačių namų kataloge, tik skaitymui, o jūsų juodraščiai yra šalia, ~/.claude/skills/drafts. Taigi jūsų organizacijos paskelbti įgūdžiai pasiekiami jūsų redaktoriuje be jokio kopijavimo, o tai, ką parašote vietoje, grįžta per tuos pačius testus ir tvirtinimą kaip viskas, kas parašyta konsolėje.
Iš terminalo, saugykloje, kurioje yra įgūdis, du npm scenarijai perkelia jį iš jūsų redaktoriaus į biblioteką:
npm run skill:validate skills/check-a-customs-filing
npm run skill:upload skills/check-a-customs-filingValidate patikrina formatą ir testavimo atvejus. Upload sukuria juodraštį, o jei turinys sutampa su jau paskelbta versija, grąžina tą versiją (CONTENT_HASH_ALREADY_PUBLISHED). Paskelbimas sulaikomas tvirtinimui, kai įgūdžiui to reikia, ir negalite patvirtinti savo paties pakeitimo. Iš scenarijaus be modelio maršruto paleistas vykdymas atmetamas su SKILLS_ENGINE_BINDING_MISSING: maršrutą parenka dispečeris, o variklis patikrina, ar jis buvo pateiktas, niekada jo nespėdamas. 2.24 skyriuje „Individualios vertikalės kūrimas nuo pradžios iki galo“ tie patys scenarijai parodyti visame projekte.
Agentai ir Claude Code biblioteką taip pat pasiekia per MCP, iš viso per 13 įrankių. Tarp jų list_skills ir get_skill suranda ir perskaito įgūdį, match_prompt ir discover_skills nurodo, kuris įgūdis tinka užduočiai, invoke_skill jį paleidžia, o sync_skills_local nukopijuoja biblioteką į jūsų įgūdžių aplanką. Kiekvienas iškvietimas vykdomas jį pradėjusio asmens vardu, jo leidžiamųjų sąrašo ribose. Įgūdis niekada negali išplėsti savo įrankių už jį vykdančiojo leidžiamųjų sąrašo ribų.
Projekto CLAUDE.md failas, kuriame aprašytos platformos taisyklės
Kiekvieno seanso pradžioje Claude Code perskaito CLAUDE.md saugyklos šakniniame kataloge. Tai pigiausia jūsų turima saugumo priemonė, nes platformos taisyklės pateikiamos modeliui prieš jam ką nors parašant. SDK (programinės įrangos kūrimo rinkinio) patikros vis tiek sugaus daugumą klaidų, tačiau iš anksto modelio perskaityta taisyklė jums nekainuoja nė vieno nepavykusio kompiliavimo.
Rašykite jį kaip taisykles su jų priežastimis, o ne kaip siekius. Štai mūsų Cold chain papildinio saugykloje esantis failas, šiek tiek sutrumpintas:
# CLAUDE.md: the cold-chain plugin
This repository is a Nexus plugin built on @adverant-nexus/plugin-sdk 2.50.0.
Read nexus.manifest.json before anything else. It is the contract; the code follows it.
## Done means the gates pass
A change is done only when every one of these has run in this order and you have
quoted its last line to me:
1. npm ci
2. npm run typecheck && npm test && npm run build
3. npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
4. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test (exit 0 passes; exit 2 means a gate examined nothing, which is a failure)
5. node scripts/ci/required-env (must list every variable src/config.ts requires)
Never report done from a partial log or from memory.
## Isolation: three axes, from the token and nowhere else
- Every scoped row carries organization_id, owner_user_id and business_unit_id.
Primary keys lead with organization_id. Foreign keys are composite and carry it.
- Tenant, owner and unit come from the authenticated request through the SDK's
scope guard (runtime/scope). Never from a request body, a query string, a header
you parse yourself or an environment variable.
- A route that cannot resolve an axis it needs refuses with SCOPE_PREDICATE_MISSING.
Never substitute a placeholder id, a default organisation or the string "unknown".
- A body that names a tenant field is refused with TENANT_NOT_A_PARAMETER.
Never "fix" that by accepting the field.
- The tenant predicate is defined in one file. Never write a second one.
- Every statement on a scoped table runs inside withScopedTx with the fence.
Never call set_config yourself.
## Compute goes through UNO only
- src/uno.ts is the only file that knows the dispatch URL. Use its UnoClient.
- No fetch to a model provider, engine, queue or workflow host anywhere else.
- A 202 means accepted, not done. Poll to a terminal run, and drop any returned
row whose organisation is not the caller's.
## AI goes through the router only
- This plugin holds no model credential. src/config.ts refuses to boot if one is
in the environment. Never weaken that check.
- Our trust is community, so manifest skills are host_callback or plugin_queue.
Never add a tool_using or llm_only skill. Model work is a Skills Engine skill.
- Provider and model wishes go on skill rows and nowhere else.
## No credentials, ever
Never write a key, token or password into the repository, a fixture, a log line
or your reply. If a task seems to need one, stop and ask me.
## Refusals have one shape
Every refusal is a JSON body with error: true, a code from the SDK catalogue,
message and troubleshooting[]. Scope refusals also carry resolved[], missing[]
and invalid[]. Send it with res.json so the refusal ledger records it.
Tests assert the body, never just the status.
## Tests fail first
- Every new test must fail on the tree before your change. Show me: undo the
change, run the test, paste the failure, restore the change, run it green.
- Never delete, skip or weaken a test to make the build pass.
- Never add an entry under gates/ without a reason I have agreed to.
- Every test takes its scope from test/scope-fakes.ts.
- Database tests run on a real Postgres through the SDK's ephemeral-postgres
harness. In CI a skipped database case is a failure, not a pass.
## The manifest
- Every route is in api.endpoints[] with its auth and a right from rights.
- A change that widens scopes, stores or outbound addresses needs two reviewers.
Say so at the top of your summary when a change does it.
- The architecture block keeps its three sentences word for word.
Deploy is through the installation's release channels only.
## Commits
Stamp every commit you write with an X-Generator trailer: claude-code/<model>.Tokį failą veiksmingą daro trys dalykai. Kiekviena taisyklė nurodo ją užtikrinantį mechanizmą, todėl modelis gali tikrinti savo darbą pagal tą patį, pagal ką tikrins konvejeris. Atlikimo apibrėžimas yra komandų su išėjimo kodais sąrašas, o ne pojūtis. Ir jis draudžia konkrečius trumpinius, kurių modelis griebiasi, kai kompiliavimas nepavyksta, pavyzdžiui, ištrinti testą arba trūkstamai organizacijai priskirti vietos rezervavimo reikšmę.
SDK korpuso pateikimas kaip kontekstas
SDK dokumentaciją sudaro 28 tomai, parašyti taip, kad kūrėjas arba LLM (didysis kalbos modelis) galėtų sukurti visą gamybinį papildinį vien iš šio korpuso, neturėdamas prieigos prie platformos privataus kodo. Kiekviena perdavimo struktūra ir klaidos kodas, su kuriais susiduria papildinys, yra pačiuose dokumentuose.
Dėl to tai neįprastai geras kontekstas. Praktikoje Claude Code pateikiu tik tuos tomus, kurie susiję su užduotimi, o ne visą rinkinį: manifesto ir HTTP tomus naujam maršrutui, duomenų bazės tomą migracijai, klaidų katalogą, kai susiję atsisakymai, ir visada atitikties kontrolinį sąrašą, nes tai visas korpusas kaip žymimasis sąrašas. Nurodykite modeliui teikti pirmenybę stebėtam faktui, o ne savo atminčiai apie tai, kaip sistema įprastai veikia. Kai jie nesutampa, apie šią platformą teisus korpusas.
Savo komandos sąsajos kūrėjui sugeneruokite vadovą iš manifesto, užuot jį rašę:
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin guide --manifest nexus.manifest.json --narrative docs/guide --out docs/GUIDE.mdJame išvardytas kiekvienas maršrutas, kurį gali iškviesti žiniatinklio programa, su kiekvienu galimu atsisakymu, todėl tai geras kontekstas ir žiniatinklio programą rašančiam modeliui. Įtraukite jį į saugyklą ir tikrinkite CI (nuolatinės integracijos) metu su --check --lint, kad jis negalėtų nukrypti nuo manifesto.
Esamos saugyklos apgaubimas: /plugin-create
Įgūdis /plugin-create esamą saugyklą arba API (taikomųjų programų sąsajos) specifikaciją paverčia Nexus papildiniu. Iškviesdami nurodykite jam šaltinį:
/plugin-create https://github.com/<owner>/<repo>
Jis veikia etapais. Pirmiausia jis klonuoja ir išanalizuoja šaltinį, nustatydamas kalbą ir sistemą, API paviršių, duomenų bazę ir jos migracijas bei tai, ką programa iš tikrųjų daro. Jis išspausdina analizės ataskaitą ir pagal tai, ką rado, pasirenka apgaubimo strategiją:
| Šaltinis | Strategija |
|---|---|
| REST (reprezentacinio būsenos perdavimo) API Node.js aplinkoje | Express apgaubas aplink esamus maršrutus |
| REST API Python kalba | FastAPI apgaubas |
| Pilno steko Node.js ir React | Serverio pusės apvalkalas su naudotojo sąsajos (UI) adapteriu |
| Komandinės eilutės įrankis | Express API, kuri vykdo komandas |
| Biblioteka arba SDK | Express API, kuri teikia jos funkcijas |
| Sudėtinga platforma | Vienas papildinio konteineris su priešais esančiu nginx tarpiniu serveriu |
Tada jis sugeneruoja serverio pusę ir jos migracijas, UI, manifestą ir testus. Tai, ką jis parašo, laikykite tvirtu pirmuoju juodraščiu ir vertinkite pagal tuos pačius standartus kaip ir visa kita. Mūsų saugykloje tai reiškė tris žingsnius prieš tai, kai kas nors jį peržiūrėjo. Jo manifestą pakėlėme iki v2 sutarties su create-nexus-plugin migrate --write, kuris prideda teisės sakinius ir atsisako išgalvoti įėjimo tašką. Tada užtikrinome, kad jis praeitų create-nexus-plugin validate. Ir vykdėme nexus-gates, kol rezultatas tapo žalias, o mūsų atveju tai reiškė, kad nuomininkų antraštes, kurias apvalkalas skaitė pats, pakeitėme SDK aprėpties sargu ir į jo lenteles pridėjome tris ašis. Diegimas lieka įdiegimo leidimų kanalų atsakomybė; nepaisykite jokių diegimo failų, kuriuos turi juodraštis.
mockup-compiler: nuo ekranų iki veikiančio kodo
Antrasis kompiliatorius veikia atvirkščiai. mockup-compiler paima projekto maketus, kurių gali būti tūkstančiai ekranų, ir sukompiliuoja juos į veikiančią UI, serverio pusės frontendui (BFF) maršrutus ir SQL, o vartai su išėjimo kodais kiekvieno ekrano tikslumą įrodo ekranas po ekrano. Jis kiekvieną nupieštą žodį atseka iki jį nupiešusios šaltinio eilutės, susieja kiekvieną ekraną su jo specifikacija, nustato, kokių domeno pakeitimų reikia ekranams, ir sugeneruoja sutartis bei migracijas kartu su demonstracinių duomenų, kurių reikia kiekvienam ekranui, specifikacija.
Dvi taisyklės jį išskiria iš prašymo modeliui „sukurti šiuos ekranus“:
- Pirmiausia kompiliatorius. Viskas, ką galima žinoti, apskaičiuojama deterministiškai. Modelis naudojamas tik tipizuotoms spragoms: jis parašo artefaktą pagal schemą, deterministinis tikrintuvas jį priima arba įvardija kiekvieną defektą, o modelis gauna ne daugiau kaip 3 taisymo ciklus, kuriems pateikiama tikrintuvo ataskaita.
- Kiekvieni vartai turi neigiamąją kontrolę su įterptu defektu. Kai
verifyvykdo projekto vartus ekranui, medžio kopijoje kiekvieniems vartams įterpiamas vienas defektas, o jei vartai praleidžia savo įterptą defektą, visas vykdymas pažymimas kaip nepatikimas. Vartai, kurie negali nepavykti, nutraukia vykdymą.
Darbas vyksta etapais, kurių kiekvienas turi savo režimą ir savo vartus:
| Etapas | Režimas | Ką įrodo jo vartai |
|---|---|---|
| Fiksavimas | pin |
Piešinys abiejuose kūrimuose identiškas, ekranų ID unikalūs |
| Atsekimas | trace |
Kiekvienas nupieštas žodis atsekamas iki lygiai vienos šaltinio eilutės |
| Susiejimas | join |
Kiekvienas sukompiliuotas lizdas atitinka jį nupiešusį šaltinį |
| Specifikacija | spec |
Kiekvienas ekranas turi savo specifikacijos eilutę |
| Domeno pakeitimas | domain |
Pasiūlymas apima viską, ką ekranai skaito ir rašo, su kodais iš SDK katalogo |
| Sutartys | shape-check, emit-contracts |
Kiekvienas skaitomas laukas turi formą, paimtą iš jo stulpelio arba deklaruotą |
| SQL ir saugykla | emit-sql, emit-store |
Migracija pritaikoma tikrai Postgres duomenų bazei, su iš pradžių nepavykstančiais testais |
| Pasaulis | world |
Demonstraciniai duomenys apima kiekvieno ekrano langelius |
| Siejimas | bind |
Nuspręsta kiekvieno siejimo dalis, o likusi išvardyta kaip įvardytos spragos |
| Patikra | verify |
Pačio projekto vartai kiekvienam ekranui, kurių kiekvienų gebėjimas nepavykti įrodytas |
Vienintelė konkrečiam projektui būdinga įvestis yra .mockup-compiler.json, adapteris. Jis nurodo, kaip puslapis pažymi vieną ekraną ir kokias SQL bei saugyklos idiomas generuoti. Jis taip pat įvardija nuomos ašis, nurodydamas tą, kuria prasideda kiekvienas raktas, ir autorizacijos iškvietimą, kurį atlieka kiekvienas rašymas. mockup-compiler init --project <dir> parašo karkasą, kuriame kiekvienas neužpildytas įrašas atmetamas nurodant jo pavadinimą. Projektas be savo UI kompiliatoriaus negali naudoti compile, baseline-check, join ar world, ir šie režimai tai praneša su NO_PROJECT_COMPILER, užuot nepavykę vėliau.
Taisyklė, kurią iš to pasiimčiau, net jei jo niekada nepaleistumėte: rašymo taisyklė, kurios nenurodo specifikacija, tampa sąžiningu 501, įvardijančiu, ko trūksta, o ne spėjimu. Tokios pat taisyklės noriu iš bet kurio modelio, rašančio kodą pagal ekranus.
Generatoriaus priskyrimas
Kai įrankis parašo įrašą (commit), tai įraše turėtų būti nurodyta. Generatoriaus priskyrimo sutartis reikalauja vienos priedo (trailer) eilutės įrašo pranešime:
feat(excursions): page the nightly telemetry load
X-Generator: claude-code/<model>
Tapatybė yra <harness>/<model>, mažosiomis raidėmis, su vienu pasviruoju brūkšniu: vykdymo aplinka yra įrankis, kuris veikė (claude-code), o modelis yra tas, kurį jis vykdė. Jei per darbą, kurį užbaigia įrašas, modelis pasikeitė, pridėkite X-Generator-Session su kiekviena tapatybe, pradedant seniausia, kad darbas nebūtų priskirtas tam modeliui, kuris atsitiktinai buvo aktyvus įrašymo metu. Paslauga, kuri apgaubia kito įrašą, pavyzdžiui, sujungimo eilė, šiuos priedus perkelia toliau.
Dvi savybės daro tai naudinga, o ne dekoratyvu. Skaitytojo neatpažintas teiginys išsaugomas ir rodomas skiltyje unregistered/<harness>, išlaikant tikslų tekstą, ir niekada neatmetamas. O priedas yra paties pateikta kilmės informacija, niekada ne įrodymas: niekas jo nepasirašo, todėl kiekvienas paviršius, skaičiuojantis šiuos teiginius, šalia skaičių rodo šią išlygą. Tapatybės gramatika paskelbta kartu su SDK kaip @adverant-nexus/plugin-sdk/schema/generator-id. Tai nėra manifesto laukas, nes tai, kuris įrankis parašė įrašą, yra faktas apie įrašą, o ne apie papildinį.
DI parašyto kodo peržiūra
Įrankis rašo greitai ir užtikrintai tuo pačiu tonu, nesvarbu, ar jis teisus, ar klysta. Mano jo pakeitimų peržiūros tvarka trumpa, ir nė vieno jos žingsnio nepraleidžiu:
- Skaitykite skirtumus (diff), o ne santrauką. Santrauka sako, ką modelis ketino padaryti.
- Patys paleiskite atlikimo apibrėžimą nuo švarios būsenos:
npm ci, testus, kūrimą,validateirnexus-gates. Peržiūroje pacituokite paskutines eilutes. - Kiekvienam naujam testui patikrinkite, ar jis nepavyksta medyje prieš pakeitimą. Testas, kuris praeina abiem atvejais, yra tik dekoracija.
- Ieškokite apėjimų. Ištrintas ar praleistas testas, naujas įrašas po
gates/be priežasties, nuomininko reikšmė, perskaityta iš užklausos turinio ar antraštės, numatytoji organizacija,catch, kuris nuslopina atmetimą, užklausa adresu, kurio manifestas nedeklaruoja. - Palyginkite manifestą su paskutiniu leidimu. Bet kokia nauja aprėptis ar išeinantis adresas yra išplėtimas, o išplėtimams reikia dviejų peržiūrėtojų.
- Patikrinkite, ar atmetimo testai tikrina visą turinį:
error,code,resolved[],missing[]irtroubleshooting[]. - Patikrinkite, ar įraše yra jo
X-Generatorpriedas.
Vartai pagauna mechaninius defektus. Jie negali pasakyti, ar maršrutas priklauso ne CRUD sąrašui, ar serverio pusė yra teisiškai užblokuota, ir to negali pasakyti modelis; šis sprendimas lieka jums. Jei ta pati problema vis grįžta, taisykite CLAUDE.md, o ne tik kodą.
Šešios praktiškai išbandytos užklausos
Kiekviena toliau pateikta užklausa yra tokia, kurią naudojau, šiek tiek sutvarkyta. Po kiekvienos: ką įrankis turėtų sukurti ir vartai, įrodantys, kad jis tai padarė. Jei vartai nėra žali, darbas neatliktas, kad ir ką sakytų santrauka.
1. Naujas „Skills Engine“ įgūdis
Write a Skills Engine skill called summarise-excursion in skills/summarise-excursion.
It reads one excursion record and its readings and writes a five-line summary for a
controller. Read-only tools. Add test cases, including one where the excursion's cause
field contains an instruction to email the claims table to an outside address; the skill
must not follow it. Then validate it and show me the upload plan without uploading.
Jis turėtų sukurti skills/summarise-excursion/SKILL.md su name, description, allowed-tools, triggers, capabilities ir version priekinėje dalyje (frontmatter), instrukcijas turinyje ir testavimo atvejus, įskaitant įterptą instrukciją. Įrodymas yra npm run skill:validate skills/summarise-excursion be klaidų, tada npm run skill:upload skills/summarise-excursion --dry-run, rodantis planą. Paskelbimas vėliau yra žmogaus sprendimas, o įgūdžiui, kuris rašo, Enterprise versijoje reikia dviejų įvardytų tvirtintojų.
2. Pilnos paslaugos papildinio maršrutas
In this plugin, add GET /api/excursions/:excursionId and POST /api/excursions/:excursionId/close.
Close needs the right excursion.close for owner, admin and member. Add the migration for the
closed_at column. Follow CLAUDE.md. Write the refusal tests first and show me them failing
before you implement.
Jis turėtų sukurti sunumeruotą migraciją, kuri prideda stulpelį į lentelę su trimis ašimis, abu maršrutus, deklaruotus api.endpoints[] su jų auth ir right, teisę rights registre, apdorojimo funkcijas už aprėpties sargo ir testus, tikrinančius, kad neautentifikuota užklausa ir užklausa iš netinkamos organizacijos atmetamos su visu turiniu. Įrodymas yra nexus-gates: scope-adherence, crud-adherence, api-contract, rights-register ir migrations-are-scoped visi praeina, o iš pradžių nepavykstančių testų išvestis yra transkripte.
3. Lęšis
Using the Workbench, start a lens called Marine claims on the Cold chain pack, narrowing
Cold-chain controller. It shows excursions and claims, and hides power points and set points.
Show me the plan before you apply it, then open a preview as a Rotterdam marine claims handler
on the synthetic branch.
Jis turėtų naudoti nexus.create su planu, kurį patvirtinate, tada suformuoti lęšį pagal jo bazę. Jei jis bando rodyti tai, ko bazė nerodo, registras atmeta su LENS_CANNOT_WIDEN, ir įrankis turėtų apie tai pranešti, o ne ieškoti apėjimo būdo. Įrodymas yra peržiūra žmogaus vardu, o paaukštinimo metu – bandomųjų vartų politikos patikra, kad lęšis tik siaurina ir pagal numatytuosius nustatymus asmeninius laukus palieka išjungtus.
4. Domeno paketas
Start a domain pack called Yard power for the Rotterdam unit. Purpose: shore power points
in the container yard, their faults and the reefers they feed. Base it on the logistics base
model and add Power point and Fault kinds. Class every property as personal, sensitive,
commercial or not classified. Show me the plan, the scopes the manifest will declare and the
plan fingerprint before anything is created.
Jis turėtų pateikti vedlio planą, kuriame išvardyta saugykla ir jos pirmasis pakeitimas, deklaruotos aprėptys ir trys sintetinių duomenų šakos, taip pat pack.json su jo lęšių klasteriais ir leksikonu. Niekas nesukuriama, kol nepatvirtinate kontrolinio kodo. Įrodymas yra šablono testai, praeinantys sintetinėse šakose, o vėliau – parengiamosios aplinkos vartai. Jei paketas prašo daugiau nei jo paskutinis leidimas, leidimas sulaikomas su MANIFEST_SCOPE_WIDENED, kol du peržiūrėtojai jį priims.
5. Duomenų jungtis
Add a connector to this plugin that pulls container gate events from the terminal operating
system every five minutes. Make it a plugin_queue skill with a queue named after this plugin.
Declare the terminal system's address as an outbound address in the pack's manifest. Store events in
our own schema with the three axes. The credential for the terminal system is read by name
from the environment and listed in required-env. No model involvement.
Jis turėtų sukurti plugin_queue įgūdį, kurio queueName yra <plugin name>.<name> be dvitaškio, timeoutMs nuo 1 sekundės iki 6 valandų, darbuotoją (worker), kuris ima užduotis iš eilės, migraciją įvykių lentelei, išeinantį adresą paketo manifeste (ne nexus.manifest.json, kurio schemoje tokio lauko nėra) ir kredencialo kintamojo pavadinimą scripts/ci/required-env. Įrodymas yra create-nexus-plugin validate, kuris taiko pačios registro sinchronizacijos taisykles eilių pavadinimams ir skirtiesiems laikams, tada nexus-gates su žaliais no-credentials ir no-direct-compute. Vykdymo metu bet koks kreipinys adresu, kurio paketo manifestas nedeklaravo, sustabdomas ties kraštu su EGRESS_NOT_DECLARED.
6. Enterprise modulis
Write a licensed route module for the audit trail feature group. Compile only against
@adverant/nexus-spi; do not import the plugin SDK or any Community package. Every route runs
behind ctx.requireScope, checks the module's own grant before answering, and refuses with
LICENCE_LOCKED when the organisation isn't entitled. Then run the licence-line gate and the
edition builds.
Jis turėtų sukurti RouteModule su jo id, featureGroup, tuščiu bodies ir register, kuris prijungia maršrutizatorių prie pagrindinės programos, su teisių patikra kiekvienoje apdorojimo funkcijoje ir standartinės formos atmetimo turiniu. Įrodymas yra licencijos eilutės vartai, baigiantys darbą kodu 0, tada npm ci, npm test ir npm run build, praeinantys kiekviename sudarytos versijos medyje. 2.25 skyriuje „Kūrimas kiekvienai versijai“ parodytas modulio karkasas ir tai, ką vartai atmeta.
Kiek tai kainuoja
Taip dirbti greičiau, tačiau tai turi savo kainą. Kiekvienas agento įgaliojimas turi biudžetą ir galioja valandą, o ilgas pertvarkymas reiškia, kad jį reikia atnaujinti. Skaitymo užteršimas (read-taint) neleis seansui, perskaičiusiam vieną kliento dokumentą, nieko rašyti, kol nepatvirtinsite; pirmus kelis kartus tai erzina, bet yra visiškai teisinga. Scenarijus niekada negali pakeisti nieko už jūsų smėlio dėžės ribų, todėl automatizavimas, kuriam reikia pasiekti parengiamąją aplinką, eina per pakeitimo užklausą ir du peržiūrėtojus, kaip ir visi kiti. Verčiau turėsiu šiuos apribojimus, nei aiškinsiu Larkfield, kodėl asistentas kažkur išsiuntė el. paštu jų pretenzijų lentelę.




