Versio 1.0.0-alpha.1uusin
Luku 2.26
Rakentaminen tekoälypohjaisilla koodaustyökaluilla
Kuinka rakentaa Nexus-laajennuksia turvallisesti Claude Coden ja muiden tekoälypohjaisten koodaustyökalujen avulla. Aloitetaan yhdistämällä kehitysympäristönne (IDE, integroitu kehitysympäristö) Workbenchiin ja määrittämällä projektin CLAUDE.md, joka sisältää alustan säännöt, ja lopuksi käydään läpi kuusi valmista kehotetta sekä tarkistusportti, joka todentaa niistä jokaisen.
Tämä sivu on käännetty tekoälyllä englanninkielisestä alkuperäistekstistä. Jos jokin kohta on epäselvä, englanninkielinen sivu on ensisijainen lähde. Lue tämä sivu englanniksi

Suurin osa luvun 2.24, Mukautetun toimialaratkaisun rakentaminen alusta loppuun, Cold chain -paketista kirjoitettiin Claude Code auki päätteessä vieressäni. Se on nykyään tavallista Corrán Orbitalissa, ja Nexus rakennettiin tätä odottaen. Alusta ei kohtele tekoälyyn (artificial intelligence) perustuvaa koodaustyökalua nokkelana automaattisena täydentäjänä. Se kohtelee sitä agenttina, joka toimii nimetyn henkilön puolesta ja jonka kulkulupa on aina kyseisen henkilön lupaa suppeampi, ja se kirjaa jokaisen agentin tekemän kutsun.
Tämä luku käsittelee sitä, miten näin työskennellään ilman vahinkoja. Se alkaa IDE-ympäristön (integrated development environment) yhdistämisestä ja käsittelee sitten taitoja editorissa, projektitiedostoa, joka opettaa työkalulle alustan säännöt, kahta kääntäjää, jotka muuntavat olemassa olevan työn Nexus-koodiksi, sitä, miten commitit kertovat, mikä työkalu ne kirjoitti, sekä sitä, miten tarkistan työkalun tuottaman tuloksen. Luku päättyy kuuteen kehotteeseen, jotka antaisin kollegalle, ja kunkin kohdalla kerrotaan, mitä sen pitäisi palauttaa ja mikä tarkistus sen todistaa.
IDE:n yhdistäminen Nexukseen
Jokaisessa asennuksessa on yksi Workbench-osoite tekoälyä hyödyntäville koodaustyökaluille. Löydätte sen Developers-kohdan Connect your IDE -sivulta, ja Claude Code yhdistetään yhdellä komennolla:
claude mcp add workbench --transport http <workbench-address><workbench-address> on sivulla näkyvä osoite, jonka vieressä on kopiointipainike. Muille työkaluille on samalla sivulla omat yhden rivin komentonsa: codex mcp add workbench --url <workbench-address> Codexille, asennuslinkki Cursorille sekä code --add-mcp pienellä JSON-argumentilla VS Codelle ja Copilotille. Ne kaikki käyttävät MCP:tä (Model Context Protocol) saman osoitteen kanssa.
Mitään avainta ei tarvitse liittää. Ensimmäinen kutsu avaa selaimenne, joka näyttää tarkalleen, mikä pyytää pääsyä: mikä työkalu millä tietokoneella, kenen puolesta ja mitä tasoja se haluaa. Hyväksytte sen pääsyavaimellanne, ja siitä lähtien työkalulla ei ole tietokannan salasanaa eikä kubeconfig-tiedostoa, vaan ainoastaan päättyvä kulkulupa. Osoitteen takana Nexus luo jokaiselle tietovarastolle lyhytikäisen tunnistetiedon kutakin pyyntöä varten, teidän nimissänne.
Organisaation ylläpitäjä voi myös ladata hallittujen asetusten tiedoston, jotta jokainen yrityksen Claude Code -kopio yhdistää tähän palvelimeen eikä mihinkään muuhun:
{ "workbench": { "type": "http", "url": "<workbench-address>" } }Tasot ja kulkuluvat
Jokainen Workbench-kirjautuminen saa kulkuluvan, joka koostuu nimetyistä tasoista. Kehittäjän oletus on Observe ja Sandbox omiin yksiköihin.
| Taso | Mitä se sallii | Kuka sen saa |
|---|---|---|
| Observe | Omien yksiköiden lukeminen, mukaan lukien lokit ja mittarit, sekä kyselyt maskattuun kopioon | Oletus |
| Sandbox | Kirjoittaminen omaan tilaan: oma kehitystila ja omat datahaarat | Oletus |
| Propose | Muutospyynnön avaaminen; putki toteuttaa sen tarkistuksen jälkeen | Pyydetään ensimmäisellä käyttökerralla |
| Elevate | Yksi aikarajattu toimenpide yhteen kohteeseen, nimetyn henkilön hyväksymänä | Vain henkilöille, ei koskaan pelkällä kirjautumisella |
| Break-glass | Hätäkäyttö | Vain alustan ylläpitäjille, kahden hyväksyjän kanssa |
Agentti toimii aina henkilön puolesta ja näkyy omana rivinään. Sen kulkulupa ei ole koskaan laajempi kuin teidän, eikä se koskaan sisällä Elevate-tasoa tai maskaamatonta dataa. Se on voimassa tunnin, ja se uusitaan vain, kun olette aktiivinen Nexusissa tai IDE-ympäristössä. Henkilön kulkulupa on voimassa 8 tuntia. Näin yön yli käyntiin jätetty työkalu pysähtyy itsestään, ja oman kulkulupanne päättäminen päättää myös agenttinne luvan. Jokaiseen agentin kulkulupaan liittyy myös mallikustannusbudjetti, joka arvioidaan ennen luvan myöntämistä ja näytetään mittarina luvan ollessa käytössä.
My access passes -sivu luettelee kaikki teidän ja agenttienne kulkuluvat tasoineen ja tähänastisine kustannuksineen, ja sen kautta voitte uusia, kaventaa tai päättää kunkin niistä. Kulkuluvan päättäminen pysäyttää seuraavan kutsun välittömästi; jokaisen kutsun tallenne säilyy. Jokaisella kulkuluvalla on myös ehdottomat rajat, jotka meillä olivat 200 riviä ja 30 sekuntia kyselyä kohden sekä 50 muutettua objektia kehitystilassa istuntoa kohden.
Ensimmäinen istunto IDE:ssä
Yhdistämisen jälkeen /mcp Claude Codessa luettelee Workbench-työkalut tasoittain ryhmiteltyinä. Observe-ryhmässä ovat lukutyökalut: workbench.k8s.describe, workbench.k8s.events, workbench.logs.query, workbench.metrics.query, workbench.traces.get, workbench.db.schema, workbench.db.query maskatussa kopiossa, workbench.graph.query ja workbench.vector.search. Sandbox lisää workbench.devspace.deploy, workbench.branch.create ja workbench.branch.reset. Propose lisää työkalut, jotka avaavat muutospyynnön ja suunnittelevat graafimuutoksen. Elevate ei ole kulkuluvassa lainkaan; sitä pyydetään konsolissa.
Ensimmäinen todellinen kysymykseni oli, miksi telemetrialukijamme käynnistyi uudelleen Rotterdamissa yön aikana. Claude Code kuvasi kuormituksen (kaksi uudelleenkäynnistystä, muisti loppui 512 MiB:n rajaa vasten), teki kyselyn lokeihin (organisaation asetti yhdyskäytävä, henkilötiedot peitetty) ja muistimittariin sekä havaitsi, että öinen lataus veti kokonaisen yön lukemat yhteen erään. Sitten pyysin siltä puoliksi kokeeksi palvelun käyttämää tietokannan salasanaa. Workbench kieltäytyi koodilla SECRET_NEVER_SHOWN. Se näyttää Secretin nimen ja neljä viimeistä merkkiä, ei koskaan arvoa, kenellekään. Avustajan vastaus oli oikea: se ei tarvitse salasanaa, koska jokainen sen tekemä kysely saa oman lyhytikäisen tunnistetietonsa, juuri tätä yhtä pyyntöä varten luodun vain luku -roolin.
Ensin suunnitelma, sitten toteutus
Jokainen jotakin muuttava työkalu näyttää ensin suunnitelman. Suunnitelma on diff, jossa on määrät ja sormenjälki, ja toteutus suorittaa vain tämän suunnitelman, täsmälleen.
Omassa kehitystilassanne toteutus suoritetaan heti. Sen ulkopuolella henkilön on vahvistettava muutos IDE-ympäristössä, ja muutos menee putkeen, joka toteuttaa sen tarkistuksen jälkeen. Tästä seuraa kaksi torjuntaa, ja kumpikin osui minuun:
- Skriptistä, jonka ääressä ei ole ketään, kuten
claude -pcron-ajossa, vahvistusikkunaa ei voi näyttää, joten hiekkalaatikon ulkopuolinen muutos torjutaan koodillaCONFIRMATION_UNAVAILABLE. Mitään ei tapahdu. Suorittakaa se interaktiivisessa istunnossa. - Toteutus, joka viittaa suunnitelmaan, jota tämä istunto ei ole tehnyt, tai suunnitelmaan, joka on muuttunut, torjutaan koodilla
PLAN_FINGERPRINT_MISMATCHennen kuin mitään suoritetaan. Tehkää suunnitelma uudelleen.
Lukusaastuminen
Asiakkaan sisältöön voi kätkeytyä avustajalle tarkoitettuja ohjeita. Siksi istunto menettää sen luettuaan kirjoittamiseen ja Nexusin ulkopuolelle ulottumiseen tarkoitetut työkalunsa, kunnes henkilö vahvistaa yhden kirjoituksen tai aloittaa uuden istunnon.
Kohtasin tämän korvausvaatimusasiakirjassa, jossa oli "avustajalle" osoitettu kappale, joka pyysi kopioimaan korvausvaatimustaulun ulkopuoliseen osoitteeseen. Claude Code jätti sen huomiotta ja kertoi tehneensä niin. Kun sitten pyysin sitä lisäämään poikkeaman haarani graafiin, kirjoitus torjuttiin koodilla SESSION_TAINTED. Saatoin vahvistaa juuri sen kirjoituksen luettuani sen suunnitelman tai aloittaa uuden istunnon, joka ei ollut lukenut asiakirjaa. Lokit ja mittarit eivät saastuta istuntoa. Asiakirjat, tiketit, sähköposti ja graafin lähdeteksti saastuttavat kaikki. Kätketty teksti kirjattiin toimintatietueeseeni sisällöstä löydettyinä ohjeina, ilman sen sanoja.
Toinen organisaatio
Mikään kirjoittamanne ei voi ulottua toisen organisaation dataan. Jos pyydätte sitä, jokainen tietovarasto torjuu pyynnön koodilla TENANT_BOUNDARY. Jos lokikyselyyn on livahtanut organisaation arvo, yhdyskäytävä korvaa sen omallanne. Kyse ei ole puuttuvasta käyttöoikeudesta. Jokainen polun kerros on rajattu omaan organisaatioonne, joten teidän asemastanne ei ole ketään, joka voisi myöntää sen, eikä alustan ylläpitäjän pääsykään auttaisi. Jos kaksi organisaatiota sopii datan jakamisesta, se on niiden välille perustettu sopimus, ei koskaan jotakin, minkä IDE-istunto tekee.
Taidot IDE:ssä ja Claude Codessa
Skills Engine -taidot ovat SKILL.md-kansioita, ja Claude Code lukee samoja kansioita. Kirjasto synkronoidaan omaan kotihakemistoonne kansioon ~/.claude/skills vain luku -muodossa, ja luonnoksenne ovat niiden vieressä kansiossa ~/.claude/skills/drafts. Näin organisaationne julkaisemat taidot ovat käytettävissä editorissanne ilman kopiointia, ja paikallisesti kirjoittamanne kulkee samojen testien ja hyväksynnän läpi kuin kaikki konsolissa kirjoitettu.
Päätteessä, taidon sisältävässä repositoriossa, kaksi npm-skriptiä vie sen editoristanne kirjastoon:
npm run skill:validate skills/check-a-customs-filing
npm run skill:upload skills/check-a-customs-filingValidate tarkistaa muodon ja testitapaukset. Upload luo luonnoksen, ja jos sisältö vastaa jo julkaistua versiota, se palauttaa kyseisen version (CONTENT_HASH_ALREADY_PUBLISHED). Julkaisu pysäytetään hyväksyntää varten, kun taito sitä edellyttää, eikä omaa muutostaan voi hyväksyä. Skriptistä ilman mallireittiä käynnistetty ajo torjutaan koodilla SKILLS_ENGINE_BINDING_MISSING: välittäjä valitsee reitin ja moottori tarkistaa, että se annettiin, eikä koskaan arvaa sitä. Luku 2.24, Mukautetun toimialaratkaisun rakentaminen alusta loppuun, näyttää samat skriptit kokonaisessa projektissa.
Myös agentit ja Claude Code pääsevät kirjastoon MCP:n kautta, yhteensä 13 työkalulla. Niistä list_skills ja get_skill etsivät ja lukevat taidon, match_prompt ja discover_skills kertovat, mikä taito sopii tehtävään, invoke_skill suorittaa taidon ja sync_skills_local kopioi kirjaston taitokansioonne. Jokainen kutsu suoritetaan sen käynnistäneen henkilön nimissä hänen sallittujen luettelonsa rajoissa. Taito ei voi koskaan laajentaa työkalujaan sen suorittajan sallittujen luetteloa laajemmiksi.
Alustan säännöt sisältävä projektin CLAUDE.md
Claude Code lukee repositorion juuressa olevan CLAUDE.md-tiedoston jokaisen istunnon alussa. Se on edullisin käytettävissänne oleva turvatoimi, koska se tuo alustan säännöt mallin eteen ennen kuin se kirjoittaa mitään. SDK:n (software development kit) tarkistukset havaitsevat useimmat virheet joka tapauksessa, mutta malliin etukäteen luettu sääntö ei maksa teille yhtään epäonnistunutta käännöstä.
Kirjoittakaa se sääntöinä perusteluineen, ei tavoitteina. Tässä on Cold chain -lisäosamme repositoriossa oleva tiedosto hieman lyhennettynä:
# 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>.Kolme asiaa saa tällaisen tiedoston toimimaan. Jokainen sääntö nimeää sitä valvovan mekanismin, jotta malli voi tarkistaa oman työnsä samaa vasten kuin putki. Valmiin määritelmä on luettelo komentoja paluukoodeineen, ei tunne. Lisäksi se kieltää ne tietyt oikotiet, joihin malli tarttuu käännöksen ollessa punaisella, kuten testin poistamisen tai puuttuvan organisaation korvaamisen paikkamerkillä.
SDK-aineiston syöttäminen kontekstiksi
SDK:n dokumentaatio on 28 osan kokonaisuus, joka on kirjoitettu siten, että kehittäjä tai LLM (large language model) voi rakentaa täydellisen tuotantokelpoisen lisäosan pelkän aineiston pohjalta ilman pääsyä alustan yksityiseen koodiin. Jokainen tietoliikennemuoto ja virhekoodi, jonka lisäosa kohtaa, on itse dokumenteissa.
Tämä tekee siitä poikkeuksellisen hyvän kontekstin. Käytännössä annan Claude Codelle tehtävää koskevat osat koko kokonaisuuden sijaan: manifestia ja HTTP:tä koskevat osat uutta reittiä varten, tietokantaosan migraatiota varten, virheluettelon aina kun mukana on torjunta, ja yhdenmukaisuuden tarkistuslistan aina, koska se on koko aineisto rastitettavana listana. Kehottakaa mallia suosimaan havaittua tosiasiaa oman muistinsa sijaan siitä, miten jokin sovelluskehys tavallisesti toimii. Kun nämä kaksi ovat ristiriidassa, aineisto on oikeassa tämän alustan osalta.
Tiimienne frontend-kehittäjää varten luokaa opas manifestista sen sijaan, että kirjoittaisitte sen:
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin guide --manifest nexus.manifest.json --narrative docs/guide --out docs/GUIDE.mdSe luettelee jokaisen reitin, jota verkkosovellus saa kutsua, sekä jokaisen torjunnan, jonka se voi saada takaisin, joten se on hyvä konteksti myös verkkosovellusta kirjoittavalle mallille. Commitoikaa se ja tarkistakaa se CI:ssä (continuous integration) komennolla --check --lint, jotta se ei voi erkaantua manifestista.
Olemassa olevan koodivaraston paketointi: /plugin-create
/plugin-create-taito muuntaa olemassa olevan repositorion tai API-määrittelyn (application programming interface) Nexus-lisäosaksi. Antakaa sille lähde, kun kutsutte sitä:
/plugin-create https://github.com/<owner>/<repo>
Se toimii vaiheittain. Ensin se kloonaa ja analysoi lähteen ja selvittää kielen ja sovelluskehyksen, API-rajapinnan, tietokannan ja sen migraatiot sekä sen, mitä kohde todellisuudessa tekee. Se tulostaa analyysiraportin ja valitsee löydöstensä perusteella käärintästrategian:
| Lähde | Strategia |
|---|---|
| REST (representational state transfer) API Node.js:llä | Express-kääre olemassa olevien reittien ympärille |
| REST API Pythonilla | FastAPI-kääre |
| Full-stack Node.js ja React | Taustajärjestelmän kääre ja käyttöliittymäsovitin (UI) |
| Komentorivityökalu | Express-rajapinta, joka suorittaa komennot |
| Kirjasto tai SDK | Express-rajapinta, joka tarjoaa sen funktiot |
| Monimutkainen alusta | Yksi lisäosasäiliö, jonka edessä on nginx-välityspalvelin |
Sen jälkeen se luo taustajärjestelmän ja sen migraatiot, käyttöliittymän, manifestin ja testit. Pitäkää sen kirjoittamaa vahvana ensimmäisenä luonnoksena ja vaatikaa siltä samaa tasoa kuin kaikelta muultakin. Meidän repositoriossamme se tarkoitti kolmea vaihetta ennen kuin kukaan tarkasti sen. Nostimme sen manifestin v2-sopimuksen mukaiseksi komennolla create-nexus-plugin migrate --write, joka lisää lakilauseet ja kieltäytyy keksimästä aloituspistettä. Sen jälkeen saimme sen läpäisemään create-nexus-plugin validate:n. Ja ajoimme nexus-gates:a, kunnes se näytti vihreää, mikä meidän tapauksessamme tarkoitti, että korvasimme kääreen itse lukemat vuokralaisotsakkeet SDK:n laajuusvartijalla ja lisäsimme kolme akselia sen tauluihin. Käyttöönotto pysyy asennuksen julkaisukanavilla; jättäkää huomiotta kaikki luonnoksen sisältämät käyttöönottotiedostot.
mockup-compiler: näkymistä toimivaksi koodiksi
Toinen kääntäjä toimii päinvastoin. mockup-compiler ottaa projektin mallikuvat, joita voi olla tuhansia näkymiä, ja kääntää ne toimivaksi käyttöliittymäksi, backend for frontend (BFF) -reiteiksi ja SQL:ksi, joiden uskollisuus todistetaan näkymä kerrallaan poistumiskoodeja palauttavilla porteilla. Se jäljittää jokaisen piirretyn sanan lähdekoodiriviin, joka sen piirsi, yhdistää jokaisen näkymän sen spesifikaatioon, päättelee näkymien tarvitsemat toimialuemuutokset ja tuottaa sopimukset ja migraatiot sekä spesifikaation demotiedoista, joita jokainen näkymä tarvitsee.
Kaksi sääntöä erottaa sen siitä, että mallia pyydetään ”rakentamaan nämä näkymät”:
- Kääntäjä ensin. Kaikki, mikä voidaan tietää, lasketaan deterministisesti. Mallia käytetään vain tyypitettyihin aukkoihin: se kirjoittaa artefaktin skeemaa vasten, deterministinen tarkistin hyväksyy sen tai nimeää jokaisen virheen, ja malli saa enintään 3 korjauskierrosta, joille syötetään tarkistimen raportti.
- Jokaisella portilla on istutetun virheen negatiivinen kontrolli. Kun
verifyajaa projektin portit näkymälle, puun kopioon istutetaan yksi virhe porttia kohden, ja jos portti päästää istutetun virheensä läpi, koko ajo merkitään epäluotettavaksi. Portti, joka ei voi epäonnistua, keskeyttää ajon.
Työ etenee vaiheittain, ja jokaisella vaiheella on oma tilansa ja oma porttinsa:
| Vaihe | Tila | Mitä sen portti todistaa |
|---|---|---|
| Kiinnitys | pin |
Piirros on identtinen kahden koonnin välillä, ja näkymätunnisteet ovat yksilöllisiä |
| Jäljitys | trace |
Jokainen piirretty sana jäljitetään täsmälleen yhteen lähdekoodiriviin |
| Yhdistäminen | join |
Jokainen käännetty paikka vastaa lähdettä, joka sen piirsi |
| Spesifikaatio | spec |
Jokaisella näkymällä on oma rivinsä spesifikaatiossa |
| Toimialuemuutos | domain |
Ehdotus kattaa kaiken, mitä näkymät lukevat ja kirjoittavat, SDK:n luettelon koodeilla |
| Sopimukset | shape-check, emit-contracts |
Jokaisella luettavalla kentällä on muoto, joka on otettu sen sarakkeesta tai määritelty |
| SQL ja tallennus | emit-sql, emit-store |
Migraatio soveltuu oikeaan Postgres-tietokantaan, ja testit epäonnistuvat ensin |
| Maailma | world |
Demotiedot kattavat jokaisen näkymän solut |
| Sidonta | bind |
Kunkin sidonnan päätetty osa, ja loput listattuna nimettyinä aukkoina |
| Varmennus | verify |
Projektin omat portit näkymäkohtaisesti, ja jokaisen todistetaan pystyvän epäonnistumaan |
Ainoa projektikohtainen syöte on .mockup-compiler.json, sovitin. Se kertoo, miten sivu merkitsee yhden näkymän ja mitä SQL- ja tallennusidiomeja tuotetaan. Se myös nimeää vuokralaisakselit, mukaan lukien sen, joka on jokaisen avaimen ensimmäinen, sekä valtuutuskutsun, jonka jokainen kirjoitus tekee. mockup-compiler init --project <dir> kirjoittaa rungon, jossa jokainen täyttämätön kohta hylätään nimeltä. Projekti, jolla ei ole omaa käyttöliittymäkääntäjää, ei voi käyttää tiloja compile, baseline-check, join tai world, ja nämä tilat ilmoittavat sen NO_PROJECT_COMPILER:llä sen sijaan, että epäonnistuisivat myöhemmin.
Sääntö, jonka ottaisin siitä mukaan, vaikka ette koskaan ajaisi sitä: kirjoitussäännöstä, jota spesifikaatio ei määritä, tulee rehellinen 501, joka nimeää puuttuvan asian, ei koskaan arvausta. Samaa sääntöä vaadin jokaiselta mallilta, joka kirjoittaa koodia näkymiä vasten.
Generaattorin attribuutio
Kun työkalu kirjoittaa commitin, commitin pitää kertoa se. Generaattorin attribuutiosopimus edellyttää yhtä loppuriviä commit-viestiin:
feat(excursions): page the nightly telemetry load
X-Generator: claude-code/<model>
Tunniste on <harness>/<model>, pienillä kirjaimilla ja yhdellä kauttaviivalla: harness on työkalu, joka suoritti työn (claude-code), ja malli on se, jota se käytti. Jos malli vaihtui commitin päättämän työn aikana, lisätkää X-Generator-Session jokaisella tunnisteella vanhimmasta alkaen, jotta työtä ei lueta sen mallin tiliin, joka sattui olemaan aktiivinen commit-hetkellä. Palvelu, joka käärii jonkun muun commitin, kuten yhdistämisjono, siirtää nämä loppurivit eteenpäin.
Kaksi ominaisuutta tekee tästä hyödyllisen eikä pelkästään koristeellisen. Väite, jota lukija ei tunnista, säilytetään ja näytetään kohdassa unregistered/<harness> täsmälleen alkuperäisenä tekstinä, eikä sitä koskaan pudoteta. Ja loppurivi on itse ilmoitettua alkuperätietoa, ei koskaan todiste: mikään ei allekirjoita sitä, joten jokainen näitä väitteitä laskeva näkymä näyttää tämän varauman lukujen vieressä. Tunnisteen kielioppi julkaistaan SDK:n mukana nimellä @adverant-nexus/plugin-sdk/schema/generator-id. Se ei ole manifestin kenttä, koska commitin kirjoittanut työkalu on tieto commitista, ei lisäosasta.
Tekoälyn kirjoittaman koodin katselmointi
Työkalu kirjoittaa nopeasti ja itsevarmasti samalla äänellä, oli se oikeassa tai väärässä. Sen muutosten tarkastusrutiinini on lyhyt, enkä ohita siitä mitään:
- Lukekaa diff, älkää yhteenvetoa. Yhteenveto kertoo, mitä malli aikoi tehdä.
- Ajakaa valmiin määritelmä itse puhtaalta pohjalta:
npm ci, testit, koonti,validatejanexus-gates. Lainatkaa viimeiset rivit tarkastukseen. - Tarkistakaa jokaisen uuden testin kohdalla, että se epäonnistuu puussa ennen muutosta. Testi, joka menee läpi molemmin tavoin, on koriste.
- Etsikää oikoteitä. Poistettu tai ohitettu testi, uusi merkintä kohdassa
gates/ilman perustetta, vuokralaisarvo luettuna rungosta tai otsakkeesta, oletusorganisaatio,catch, joka nielee hylkäyksen, nouto osoitteeseen, jota manifesti ei määritä. - Verratkaa manifestia edelliseen julkaisuun. Jokainen uusi laajuus tai lähtevä osoite on laajennus, ja laajennukset vaativat kaksi tarkastajaa.
- Tarkistakaa, että hylkäystestit tarkistavat koko rungon:
error,code,resolved[],missing[]jatroubleshooting[]. - Tarkistakaa, että commitissa on sen
X-Generator-loppurivi.
Portit havaitsevat mekaaniset virheet. Ne eivät voi kertoa, kuuluuko reitti ei-CRUD-luetteloon tai onko taustajärjestelmä oikeudellisesti estetty, eikä malli voi sitä kertoa; se harkinta jää teille. Jos sama ongelma toistuu, korjatkaa CLAUDE.md, älkää pelkästään koodia.
Kuusi käytännön kehotetta
Jokainen alla oleva kehote on sellainen, jota olen käyttänyt, kevyesti siistittynä. Kunkin jälkeen: mitä työkalun pitäisi tuottaa ja portti, joka todistaa sen tehneen niin. Jos portti ei ole vihreä, työ ei ole valmis, sanoi yhteenveto mitä tahansa.
1. Uusi Skills Engine -taito
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.
Sen pitäisi tuottaa skills/summarise-excursion/SKILL.md, jonka frontmatterissa ovat name, description, allowed-tools, triggers, capabilities ja version, ohjeet rungossa sekä testitapaukset, joihin sisältyy istutettu ohje. Todisteena on npm run skill:validate skills/summarise-excursion nollalla virheellä ja sen jälkeen npm run skill:upload skills/summarise-excursion --dry-run, joka näyttää suunnitelman. Julkaiseminen on sen jälkeen ihmisen päätös, ja kirjoittava taito tarvitsee Enterprise-versiossa kaksi nimettyä hyväksyjää.
2. Täyden palvelun lisäosan reitti
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.
Sen pitäisi tuottaa numeroitu migraatio, joka lisää sarakkeen tauluun, jossa on kolme akselia, molemmat reitit määriteltyinä tiedostossa api.endpoints[] niiden auth- ja right-arvoineen, oikeus rights-rekisterissä, käsittelijät laajuusvartijan takana sekä testit, jotka varmistavat, että todentamaton pyyntö ja väärän organisaation pyyntö hylätään täysin rungoin. Todisteena on nexus-gates: scope-adherence, crud-adherence, api-contract, rights-register ja migrations-are-scoped menevät kaikki läpi, ja ensin epäonnistuvien testien tuloste on keskusteluhistoriassa.
3. Linssi
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.
Sen pitäisi käyttää nexus.create:tä vahvistamallanne suunnitelmalla ja sen jälkeen muotoilla linssi sen perustaa vasten. Jos se yrittää näyttää jotain, mitä perusta ei näytä, rekisteri hylkää sen koodilla LENS_CANNOT_WIDEN, ja työkalun pitäisi raportoida tästä sen sijaan, että se etsisi kiertotietä. Todisteena on esikatselu ihmisenä ja ylennyksen yhteydessä pilottiportin käytäntötarkistus, jonka mukaan linssi vain rajaa ja pitää henkilötietokentät oletuksena pois päältä.
4. Toimialapaketti
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.
Sen pitäisi tuottaa ohjatun toiminnon suunnitelma, jossa luetellaan repositorio ja sen ensimmäinen muutos, määritellyt laajuudet ja kolme synteettisen datan haaraa, sekä pack.json linssiklustereineen ja sanastoineen. Mitään ei luoda ennen kuin vahvistatte sormenjäljen. Todisteena on, että mallipohjan testit menevät läpi synteettisissä haaroissa, ja myöhemmin staging-portti. Jos paketti pyytää enemmän kuin edellinen julkaisunsa, julkaisu pidätetään koodilla MANIFEST_SCOPE_WIDENED, kunnes kaksi tarkastajaa hyväksyy sen.
5. Dataliitin
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.
Sen pitäisi tuottaa plugin_queue-taito, jonka queueName on <plugin name>.<name> ilman kaksoispistettä, timeoutMs välillä 1 sekunti ja 6 tuntia, työprosessi, joka noutaa jonon, migraatio tapahtumataululle, lähtevä osoite paketin manifestissa (ei tiedostossa nexus.manifest.json, jonka skeemassa ei ole tällaista kenttää) sekä tunnistetiedon muuttujan nimi kohdassa scripts/ci/required-env. Todisteena on create-nexus-plugin validate, joka soveltaa rekisterisynkronoinnin omia sääntöjä jonojen nimiin ja aikakatkaisuihin, ja sen jälkeen nexus-gates, jossa no-credentials ja no-direct-compute ovat vihreitä. Ajon aikana kutsu mihin tahansa osoitteeseen, jota paketin manifesti ei määrittänyt, pysäytetään reunalla koodilla EGRESS_NOT_DECLARED.
6. Enterprise-moduuli
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.
Sen pitäisi tuottaa RouteModule, jossa on sen id, featureGroup, tyhjä bodies ja register, joka liittää reitittimen isännän sovellukseen, oikeustarkistus jokaisen käsittelijän sisällä ja hylkäysrunko vakiomuodossa. Todisteena on, että lisenssirivin portti päättyy koodiin 0, ja sen jälkeen npm ci, npm test ja npm run build menevät läpi jokaisessa kootussa versiopuussa. Luku 2.25, Rakentaminen kullekin versiolle, näyttää moduulin rungon ja sen, mitä portti hylkää.
Mitä se maksaa
Tällä tavalla työskentely on nopeampaa, eikä se ole ilmaista. Jokaisella agenttikierroksella on budjetti ja tunnin elinikä, ja pitkä refaktorointi tarkoittaa sen uusimista. Lukukontaminaatio estää istuntoa, joka on lukenut yhden asiakasasiakirjan, kirjoittamasta mitään ennen kuin vahvistatte, mikä ärsyttää muutamalla ensimmäisellä kerralla ja on juuri oikein. Skripti ei voi koskaan muuttaa mitään hiekkalaatikkonne ulkopuolella, joten automaatio, jonka on päästävä staging-ympäristöön, kulkee muutospyynnön ja kahden tarkastajan kautta kuten kaikki muutkin. Otan mieluummin nämä rajoitukset kuin selitän Larkfieldille, miksi avustaja lähetti heidän korvaushakemustaulunsa sähköpostilla jonnekin.




