Version 1.0.0-alpha.1dernière version
Chapitre 2.26
Développer avec des outils de codage par IA
Comment développer des extensions Nexus en toute sécurité avec Claude Code et d'autres outils de codage par l'IA (intelligence artificielle). Cela commence par la connexion de votre IDE (environnement de développement intégré) au Workbench et un fichier CLAUDE.md de projet qui intègre les règles de la plateforme, et se termine par six invites détaillées ainsi que la porte de contrôle qui valide chacune d'elles.
Cette page a été traduite par l'IA à partir de l'original en anglais. En cas de doute, la page en anglais fait foi. Lire cette page en anglais

La majeure partie du pack Cold chain présenté au chapitre 2.24, Construire un secteur vertical sur mesure de bout en bout, a été écrite avec Claude Code ouvert dans le terminal à mes côtés. C'est désormais la norme chez Corrán Orbital, et Nexus a été conçu en ce sens. La plateforme ne traite pas un outil de codage basé sur l'IA (intelligence artificielle) comme une simple saisie semi-automatique intelligente. Elle le traite comme un agent agissant pour le compte d'une personne nommée, muni d'un laissez-passer toujours plus restreint que celui de cette personne, et elle enregistre chaque appel effectué par l'agent.
Ce chapitre explique comment travailler de cette manière sans prendre de risques. Il commence par la connexion de votre IDE (environnement de développement intégré), puis aborde les compétences dans l'éditeur, le fichier de projet qui enseigne les règles de la plateforme à l'outil, les deux compilateurs qui transforment le travail existant en code Nexus, la façon dont les commits indiquent quel outil les a écrits, et la manière dont je passe en revue ce que l'outil produit. Il se termine par six invites que je transmettrais volontiers à un collègue, chacune accompagnée du résultat attendu et du contrôle de validation qui le prouve.
Connecter votre IDE à Nexus
Chaque installation dispose d'une adresse Workbench unique pour les outils de codage basés sur l'IA. Vous la trouverez sur la page Connecter votre IDE sous Développeurs, et Claude Code s'y connecte en une seule commande :
claude mcp add workbench --transport http <workbench-address><workbench-address> est l'adresse affichée sur la page, accompagnée d'un bouton de copie. Les autres outils disposent de leurs propres commandes en une ligne sur la même page : codex mcp add workbench --url <workbench-address> pour Codex, un lien d'installation pour Cursor, et code --add-mcp avec un petit argument JSON pour VS Code avec Copilot. Tous communiquent via le protocole MCP (Model Context Protocol) avec cette même adresse.
Il n'y a aucune clé à coller. Le premier appel ouvre votre navigateur, qui affiche exactement l'origine de la demande : quel outil sur quel ordinateur, agissant pour le compte de qui, et demandant quels niveaux. Vous l'autorisez avec votre clé d'accès (passkey) ; dès lors, l'outil ne conserve aucun mot de passe de base de données ni aucun fichier kubeconfig, mais uniquement un laissez-passer temporaire. Derrière cette adresse, Nexus génère en votre nom un identifiant à courte durée de vie pour chaque magasin et pour chaque requête.
Un administrateur d'organisation peut également télécharger un fichier de paramètres gérés afin que chaque copie de Claude Code au sein de l'entreprise se connecte à ce serveur et à aucun autre :
{ "workbench": { "type": "http", "url": "<workbench-address>" } }Niveaux et laissez-passer
Chaque connexion au Workbench obtient un laissez-passer composé de niveaux nommés. Par défaut, un développeur dispose des niveaux Observe et Sandbox sur ses propres unités.
| Palier | Ce qu'il permet | Attribution |
|---|---|---|
| Observe | Lire vos unités, y compris les journaux et les métriques, et interroger la copie masquée | Défaut |
| Sandbox | Écrire dans votre propre espace : votre espace de développement et vos propres branches de données | Défaut |
| Propose | Ouvrir une demande de changement ; un pipeline l'applique après révision | Demandé lors de la première utilisation |
| Elevate | Une action limitée dans le temps sur une cible unique, approuvée par une personne nommée | Personnes uniquement, jamais par simple connexion |
| Break-glass | Accès d'urgence | Administrateurs de la plateforme uniquement, avec deux approbateurs |
Un agent agit toujours pour le compte d'une personne et apparaît sur sa propre ligne. Son laissez-passer n'est jamais plus étendu que le vôtre et n'inclut jamais le niveau Elevate ni les données non masquées. Il dure une heure et n'est renouvelé que tant que vous êtes actif dans Nexus ou dans l'IDE. Le laissez-passer d'une personne dure 8 heures. Ainsi, un outil que vous laissez tourner toute la nuit s'arrête de lui-même, et la révocation de votre propre laissez-passer met également fin à celui de votre agent. Chaque laissez-passer d'agent comporte également un budget de coût de modèle, estimé avant l'octroi du laissez-passer et affiché sous forme de jauge pendant son exécution.
La page Mes laissez-passer d'accès répertorie chaque laissez-passer détenu par vous et vos agents, avec ses niveaux et son coût cumulé jusqu'à présent, et vous permet de renouveler, de restreindre ou de révoquer chacun d'eux. La révocation d'un laissez-passer bloque immédiatement l'appel suivant ; l'enregistrement de chaque appel est conservé. Chaque laissez-passer comporte également des limites strictes qui, sur le nôtre, étaient de 200 lignes et 30 secondes par requête, et de 50 objets modifiés dans l'espace de développement par session.
La première session dans l'IDE
Une fois connecté, /mcp dans Claude Code répertorie les outils du Workbench regroupés par niveau. Le groupe Observe contient les outils de lecture : workbench.k8s.describe, workbench.k8s.events, workbench.logs.query, workbench.metrics.query, workbench.traces.get, workbench.db.schema, workbench.db.query sur la copie masquée, workbench.graph.query et workbench.vector.search. Sandbox ajoute workbench.devspace.deploy, workbench.branch.create et workbench.branch.reset. Propose ajoute les outils permettant d'ouvrir une demande de changement et de planifier une modification du graphe. Elevate ne figure pas du tout sur le laissez-passer ; vous devez en faire la demande dans la console.
Ma première vraie question a été de savoir pourquoi notre lecteur de télémétrie avait redémarré à Rotterdam pendant la nuit. Claude Code a décrit la charge de travail (deux redémarrages, mémoire insuffisante par rapport à une limite de 512 MiB), a interrogé les journaux (organisation définie par la passerelle, données personnelles expurgées) ainsi que la métrique de mémoire, et a découvert que le chargement nocturne avait regroupé toute une nuit de relevés en un seul lot. Ensuite, je lui ai demandé, à moitié pour tester, le mot de passe de base de données utilisé par le service. Le Workbench a refusé avec SECRET_NEVER_SHOWN. Il n'affiche que le nom d'un Secret et ses quatre derniers caractères, jamais la valeur, à qui que ce soit. La réponse de l'assistant était la bonne : il n'a pas besoin du mot de passe, car chaque requête qu'il effectue obtient son propre identifiant à courte durée de vie, un rôle en lecture seule créé pour cette unique requête.
Planifier, puis appliquer
Chaque outil qui modifie quelque chose affiche d'abord un plan. Le plan est un diff accompagné de décomptes et d'une empreinte numérique, et l'opération d'application exécute uniquement ce plan, à l'identique.
À l'intérieur de votre propre espace de développement, l'application s'exécute immédiatement. En dehors de celui-ci, une personne doit confirmer l'opération dans l'IDE, et la modification est envoyée au pipeline, qui l'applique après révision. Deux cas de refus en découlent, et je me suis heurté aux deux :
- Depuis un script sans personne au clavier, tel que
claude -pdans une tâche cron, il est impossible d'afficher la boîte de confirmation ; une modification en dehors du bac à sable est donc refusée avecCONFIRMATION_UNAVAILABLE. Rien ne se passe. Exécutez-la dans une session interactive. - Une application qui désigne un plan que cette session n'a jamais créé, ou un plan qui a été modifié, est refusée avec
PLAN_FINGERPRINT_MISMATCHavant même que quoi que ce soit ne s'exécute. Planifiez à nouveau.
Contamination par la lecture (Read-taint)
Le contenu client peut dissimuler des instructions destinées à un assistant. Par conséquent, dès qu'une session a lu un tel contenu, elle perd ses outils d'écriture et de communication vers l'extérieur de Nexus jusqu'à ce qu'une personne confirme une écriture ou démarre une nouvelle session.
J'ai rencontré ce cas sur un document de réclamation qui contenait un paragraphe adressé à « l'assistant », lui demandant de copier la table des réclamations vers une adresse externe. Claude Code l'a ignoré et l'a signalé. Lorsque je lui ai ensuite demandé d'ajouter l'excursion de température au graphe de ma branche, l'écriture a été refusée avec SESSION_TAINTED. Je pouvais soit confirmer cette écriture spécifique après avoir lu son plan, soit démarrer une nouvelle session n'ayant pas lu le document. Les journaux et les métriques ne contaminent pas une session. Les documents, les tickets, les e-mails et le texte source du graphe le font tous. Le texte caché a été comptabilisé dans mon journal d'activité comme instructions trouvées dans le contenu, sans en reproduire les mots.
Une autre organisation
Rien de ce que vous saisissez ne peut atteindre les données d'une autre organisation. Si vous les demandez, chaque magasin de données oppose un refus avec TENANT_BOUNDARY. Une valeur d'organisation glissée dans une requête de journaux est remplacée par la passerelle par la vôtre. Il ne s'agit pas d'une autorisation manquante. Chaque couche sur le chemin est cloisonnée à votre organisation, de sorte que personne ne pourrait accorder cet accès depuis votre position, et l'accès d'un administrateur de la plateforme n'y changerait rien non plus. Si deux organisations conviennent de partager des données, il s'agit d'un accord mis en place entre elles, et jamais d'une action effectuée par une session d'IDE.
Les compétences dans l'IDE et Claude Code
Les compétences du Skills Engine sont des dossiers SKILL.md, et Claude Code lit ces mêmes dossiers. La bibliothèque se synchronise vers ~/.claude/skills dans votre propre répertoire personnel, en lecture seule, avec vos brouillons à leurs côtés dans ~/.claude/skills/drafts. Ainsi, les compétences publiées par votre organisation sont disponibles dans votre éditeur sans aucune copie, et ce que vous écrivez localement repasse par les mêmes tests et la même approbation que tout ce qui est écrit dans la console.
Depuis le terminal, dans le dépôt qui contient la compétence, deux scripts npm la font passer de votre éditeur à la bibliothèque :
npm run skill:validate skills/check-a-customs-filing
npm run skill:upload skills/check-a-customs-filingLa validation vérifie le format et les cas de test. Le téléversement crée un brouillon et, si le contenu correspond à une version déjà publiée, il renvoie cette version à la place (CONTENT_HASH_ALREADY_PUBLISHED). La publication est mise en attente d'approbation lorsque la compétence l'exige, et vous ne pouvez pas approuver votre propre modification. Une exécution lancée depuis un script sans route de modèle est refusée avec SKILLS_ENGINE_BINDING_MISSING : le répartiteur (dispatcher) choisit la route et le moteur vérifie qu'elle a bien été fournie, sans jamais essayer d'en deviner une. Le chapitre 2.24, Construire un secteur vertical sur mesure de bout en bout, présente ces mêmes scripts au sein d'un projet complet.
Les agents et Claude Code accèdent également à la bibliothèque via MCP, au moyen de 13 outils au total. Parmi eux, list_skills et get_skill trouvent et lisent une compétence, match_prompt et discover_skills indiquent quelle compétence correspond à une tâche, invoke_skill en exécute une, et sync_skills_local copie la bibliothèque dans votre dossier de compétences. Chaque appel s'exécute au nom de la personne qui l'a lancé, dans les limites de sa liste d'autorisations (allow-list). Une compétence ne peut jamais étendre ses outils au-delà de la liste d'autorisations de la personne qui l'exécute.
Un fichier CLAUDE.md de projet qui intègre les règles de la plateforme
Claude Code lit un fichier CLAUDE.md à la racine du dépôt au début de chaque session. C'est la mesure de sécurité la plus économique dont vous disposiez, car elle place les règles de la plateforme sous les yeux du modèle avant même qu'il n'écrive quoi que ce soit. Les contrôles de validation du SDK (kit de développement logiciel) intercepteront de toute façon la plupart des erreurs, mais une règle lue d'emblée par le modèle vous évite un échec de build.
Rédigez-le sous forme de règles accompagnées de leurs raisons, et non comme des souhaits. Voici celui de notre dépôt de plugin Cold chain, légèrement raccourci :
# 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>.Trois éléments permettent à un tel fichier de fonctionner. Chaque règle nomme le mécanisme qui l'applique, de sorte que le modèle peut vérifier son propre travail par rapport à ce même contrôle que le pipeline utilisera. La définition de « terminé » (definition of done) est une liste de commandes avec des codes de sortie, et non une impression. Enfin, il interdit les raccourcis spécifiques auxquels un modèle a recours lorsqu'un build est dans le rouge, comme supprimer le test ou attribuer par défaut une valeur fictive (placeholder) à une organisation manquante.
Fournir le corpus du SDK comme contexte
La documentation du SDK est un ensemble de 28 volumes, rédigés pour permettre à un développeur ou à un LLM (grand modèle de langage) de construire un plugin de production complet à partir du seul corpus, sans accès au code privé de la plateforme. Chaque format d'échange sur le réseau (wire shape) et chaque code d'erreur qu'un plugin peut rencontrer figurent dans les documents eux-mêmes.
Cela en fait un contexte d'une qualité exceptionnelle. En pratique, je fournis à Claude Code les volumes concernés par la tâche plutôt que l'ensemble complet : les volumes relatifs au manifeste et à HTTP pour une nouvelle route, le volume relatif à la base de données pour une migration, le catalogue d'erreurs chaque fois qu'un refus est impliqué, et systématiquement la liste de contrôle de conformité, car elle résume tout le corpus sous forme de liste à cocher. Demandez au modèle de privilégier un fait observé plutôt que ses propres souvenirs du fonctionnement habituel d'un framework. Lorsque les deux divergent, c'est le corpus qui a raison concernant cette plateforme.
Pour le développeur frontend de votre équipe, générez un guide à partir du manifeste au lieu d'en rédiger un :
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin guide --manifest nexus.manifest.json --narrative docs/guide --out docs/GUIDE.mdIl répertorie chaque route que l'application web peut appeler ainsi que chaque refus qu'elle peut recevoir en retour, ce qui constitue également un bon contexte pour le modèle qui écrit l'application web. Validez-le (commit) et vérifiez-le dans la CI (intégration continue) avec --check --lint afin qu'il ne puisse pas diverger du manifeste.
Encapsuler un dépôt existant : /plugin-create
La compétence /plugin-create transforme un dépôt existant ou une spécification d'API (interface de programmation d'application) en un plugin Nexus. Indiquez-lui la source lorsque vous l'invoquez :
/plugin-create https://github.com/<owner>/<repo>
Elle fonctionne par phases. Elle clone et analyse d'abord la source, en déterminant le langage et le framework, la surface d'API, la base de données et ses migrations, ainsi que ce que fait réellement l'application. Elle affiche un rapport d'analyse et choisit une stratégie d'encapsulation (wrapping) à partir de ce qu'elle a trouvé :
| Source | Stratégie |
|---|---|
| API REST (transfert d'état représentationnel) en Node.js | Un wrapper Express autour des routes existantes |
| API REST en Python | Un wrapper FastAPI |
| Full-stack Node.js et React | Un wrapper backend avec un adaptateur d'interface utilisateur (UI) |
| Outil en ligne de commande | Une API Express qui exécute les commandes |
| Bibliothèque ou SDK | Une API Express exposant ses fonctions |
| Plateforme complexe | Un conteneur de plugin unique avec un proxy nginx en frontal |
Elle génère ensuite le backend et ses migrations, une interface utilisateur (UI), le manifeste et les tests. Traitez ce qu'elle produit comme un solide premier jet et soumettez-le aux mêmes exigences que le reste. Dans notre dépôt, cela s'est traduit par trois étapes avant même que quiconque ne le passe en revue. Nous avons mis à niveau son manifeste vers le contrat v2 avec create-nexus-plugin migrate --write, qui ajoute les phrases de règles (law sentences) et refuse d'inventer un point d'entrée. Nous avons ensuite fait en sorte qu'il réussisse create-nexus-plugin validate. Enfin, nous avons exécuté nexus-gates jusqu'à ce qu'il passe au vert, ce qui, dans notre cas, impliquait de remplacer les en-têtes de locataire (tenant) que le wrapper lisait lui-même par le garde de portée (scope guard) du SDK, et d'ajouter les trois axes à ses tables. Le déploiement reste géré par les canaux de publication de l'installation ; ignorez tous les fichiers de déploiement contenus dans le brouillon.
mockup-compiler : des écrans au code fonctionnel
Le second compilateur fonctionne dans le sens inverse. mockup-compiler prend les maquettes d'un projet, qui peuvent compter des milliers d'écrans, et les compile en une interface utilisateur (UI) fonctionnelle, des routes BFF (backend for frontend) et du code SQL, dont la fidélité est prouvée écran par écran au moyen de contrôles de validation avec codes de sortie. Il retrace chaque mot dessiné jusqu'à la ligne source qui l'a généré, relie chaque écran à sa spécification, détermine les modifications du domaine nécessaires aux écrans, et produit les contrats et les migrations ainsi qu'une spécification des données de démonstration requises par chaque écran.
Deux règles le distinguent d'une simple demande adressée à un modèle pour « construire ces écrans » :
- Le compilateur d'abord. Tout ce qui peut être connu est calculé de manière déterministe. Un modèle n'est utilisé que pour les emplacements typés (typed holes) : il écrit un artefact par rapport à un schéma, un vérificateur déterministe l'accepte ou nomme chaque défaut, et le modèle dispose d'au maximum 3 cycles de réparation alimentés par le rapport du vérificateur.
- Chaque contrôle de validation comporte un témoin négatif par défaut introduit volontairement (planted-defect). Lorsque
verifyexécute les contrôles de validation d'un projet pour un écran, une copie de l'arborescence reçoit un défaut introduit par contrôle et, si un contrôle valide malgré son défaut introduit, l'exécution entière est marquée comme non fiable. Un contrôle qui ne peut pas échouer interrompt l'exécution.
Le travail s'exécute par étapes, chacune ayant son propre mode et son propre contrôle de validation :
| Étape | Mode | Ce que prouve son contrôle de validation |
|---|---|---|
| Pin | pin |
Le dessin est identique sur deux builds, avec des identifiants d'écran uniques |
| Trace | trace |
Chaque mot dessiné est retracé jusqu'à une ligne source unique |
| Join | join |
Chaque emplacement compilé correspond à la source qui l'a dessiné |
| Spec | spec |
Chaque écran possède sa propre ligne dans la spécification |
| Domain change | domain |
La proposition couvre tout ce que les écrans lisent et écrivent, avec des codes issus du catalogue du SDK |
| Contracts | shape-check, emit-contracts |
Chaque champ lu possède une forme tirée de sa colonne ou déclarée |
| SQL and store | emit-sql, emit-store |
La migration s'applique à une véritable base Postgres, avec des tests échouant au préalable (fail-first) |
| World | world |
Les données de démonstration couvrent toutes les cellules de chaque écran |
| Bind | bind |
La partie résolue de chaque liaison, le reste étant répertorié sous forme d'emplacements nommés (named holes) |
| Verify | verify |
Les contrôles de validation propres au projet pour chaque écran, chacun ayant prouvé sa capacité à échouer |
La seule entrée spécifique au projet est .mockup-compiler.json, l'adaptateur. Il indique comment une page délimite un écran et quels idiomes SQL et de magasin de données doivent être émis. Il nomme également les axes de location (tenancy axes), en précisant celui qui figure en tête de chaque clé, ainsi que l'appel d'autorisation effectué par chaque écriture. mockup-compiler init --project <dir> écrit un squelette dans lequel chaque entrée non renseignée est refusée nommément. Un projet dépourvu de son propre compilateur d'UI ne peut pas utiliser compile, baseline-check, join ou world, et ces modes le signalent avec NO_PROJECT_COMPILER plutôt que d'échouer plus loin dans le processus.
La règle que j'en retiendrais, même si vous ne l'exécutez jamais : une règle d'écriture que la spécification n'énonce pas devient une erreur 501 explicite qui nomme ce qui manque, et jamais une supposition. C'est cette même règle que j'exige de tout modèle écrivant du code à partir d'écrans.
Attribution du générateur
Lorsqu'un outil écrit un commit, le commit doit l'indiquer. Le contrat d'attribution du générateur exige une ligne de métadonnées (trailer) à la fin du message de commit :
feat(excursions): page the nightly telemetry load
X-Generator: claude-code/<model>
L'identité est <harness>/<model>, en minuscules, avec une seule barre oblique : le harnais (harness) est l'outil qui s'est exécuté (claude-code), et le modèle est celui qu'il utilisait. Si le modèle a changé au cours du travail que le commit clôture, ajoutez X-Generator-Session avec chaque identité, de la plus ancienne à la plus récente, afin que le travail ne soit pas imputé au seul modèle qui se trouvait être actif au moment du commit. Un service qui encapsule le commit de quelqu'un d'autre, tel qu'une file d'attente de fusion (merge queue), conserve et transmet ces lignes de métadonnées.
Deux propriétés rendent ce mécanisme utile plutôt que purement décoratif. Une déclaration qu'un lecteur ne reconnaît pas est conservée et affichée sous unregistered/<harness> en préservant le texte exact, sans jamais être supprimée. Par ailleurs, cette ligne de métadonnées constitue une provenance auto-déclarée, et jamais une preuve : rien ne la signe, de sorte que chaque interface qui comptabilise ces déclarations affiche cet avertissement à côté des chiffres. La grammaire d'identité est publiée avec le SDK sous le nom @adverant-nexus/plugin-sdk/schema/generator-id. Il ne s'agit pas d'un champ du manifeste, car l'outil qui a écrit un commit est un fait relatif au commit, et non au plugin.
Réviser du code écrit par une IA
L'outil écrit rapidement et avec assurance, sur le même ton qu'il ait raison ou tort. Ma routine de révision pour ses modifications est courte et je n'en saute aucune étape :
- Lisez le diff, pas le résumé. Le résumé indique ce que le modèle avait l'intention de faire.
- Exécutez vous-même la définition de « terminé » (definition of done), à partir d'un état propre :
npm ci, les tests, le build,validateetnexus-gates. Citez les dernières lignes dans la révision. - Pour chaque nouveau test, vérifiez qu'il échoue sur l'arborescence avant la modification. Un test qui réussit dans les deux cas n'est que de la décoration.
- Recherchez les raccourcis. Un test supprimé ou ignoré, une nouvelle entrée sous
gates/sans justification, une valeur de locataire (tenant) lue depuis un corps de requête ou un en-tête, une organisation par défaut, uncatchqui étouffe un refus, un appel (fetch) vers une adresse que le manifeste ne déclare pas. - Comparez le manifeste avec la dernière version publiée. Toute nouvelle portée ou adresse sortante constitue un élargissement, et les élargissements nécessitent deux réviseurs.
- Vérifiez que les tests de refus valident l'intégralité du corps :
error,code,resolved[],missing[]ettroubleshooting[]. - Vérifiez que le commit comporte bien sa ligne de métadonnées
X-Generator.
Les contrôles de validation interceptent les défauts mécaniques. Ils ne peuvent pas vous dire si une route a sa place sur la liste non-CRUD, ni si un backend fait l'objet d'un blocage juridique, et le modèle ne le peut pas non plus ; ce jugement vous appartient. Si le même problème revient régulièrement, corrigez le fichier CLAUDE.md, et pas seulement le code.
Six invites détaillées
Chaque invite ci-dessous en est une que j'ai utilisée, légèrement nettoyée. Après chacune d'elles : ce que l'outil doit produire, et le contrôle de validation qui prouve qu'il l'a fait. Si le contrôle n'est pas au vert, le travail n'est pas terminé, quoi qu'en dise le résumé.
1. Une nouvelle compétence du Skills Engine
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.
Il doit produire skills/summarise-excursion/SKILL.md avec name, description, allowed-tools, triggers, capabilities et version dans l'en-tête (frontmatter), ses instructions dans le corps, et des cas de test qui incluent l'instruction introduite volontairement. La preuve est obtenue par npm run skill:validate skills/summarise-excursion avec zéro erreur, puis par npm run skill:upload skills/summarise-excursion --dry-run affichant le plan. La publication relève ensuite de la décision d'une personne, et une compétence qui effectue des écritures nécessite deux approbateurs nommés sur l'édition Enterprise.
2. Une route de plugin complète
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.
Il doit produire une migration numérotée qui ajoute la colonne à une table comportant les trois axes, les deux routes déclarées dans api.endpoints[] avec leurs auth et right, le droit dans le registre rights, des gestionnaires (handlers) placés derrière le garde de portée (scope guard), et des tests qui vérifient qu'une requête non authentifiée et une requête provenant d'une mauvaise organisation sont refusées avec des corps de réponse complets. La preuve est nexus-gates : scope-adherence, crud-adherence, api-contract, rights-register et migrations-are-scoped réussissent tous, et la sortie démontrant l'échec initial (failing-first) figure dans la transcription.
3. Une lentille (lens)
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.
Il doit utiliser nexus.create avec un plan que vous confirmez, puis façonner la lentille par rapport à sa base. S'il tente d'afficher quelque chose que la base ne fournit pas, le registre oppose un refus avec LENS_CANNOT_WIDEN, et l'outil doit le signaler plutôt que de chercher à contourner le problème. La preuve réside dans l'aperçu en tant que personne et, lors de la promotion, dans la vérification de politique du contrôle pilote attestant que la lentille ne fait que restreindre les données et maintient les champs personnels désactivés par défaut.
4. Un pack de domaine
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.
Il doit produire le plan de l'assistant, répertoriant le dépôt et sa première modification, les portées déclarées et les trois branches de données synthétiques, ainsi qu'un pack.json avec ses groupes de lentilles (lens clusters) et son lexique. Rien n'est créé tant que vous n'avez pas confirmé l'empreinte numérique. La preuve réside dans la réussite des tests du modèle sur les branches synthétiques, puis dans le contrôle de validation de préproduction (staging). Si le pack demande plus d'accès que lors de sa dernière version publiée, la publication est mise en attente avec MANIFEST_SCOPE_WIDENED jusqu'à ce que deux réviseurs l'acceptent.
5. Un connecteur de données
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.
Cela devrait produire une compétence plugin_queue dont le queueName est <plugin name>.<name> sans deux-points, un timeoutMs compris entre 1 seconde et 6 heures, un worker qui dépile la file d'attente, une migration pour la table des événements, l'adresse sortante dans le manifeste du pack (et non dans nexus.manifest.json, dont le schéma ne comporte pas ce champ), ainsi que le nom de la variable de l'identifiant dans scripts/ci/required-env. La preuve réside dans create-nexus-plugin validate, qui applique les propres règles de la synchronisation du registre sur les noms de files d'attente et les délais d'expiration, puis dans nexus-gates avec no-credentials et no-direct-compute au vert. À l'exécution, un appel vers toute adresse que le manifeste du pack n'a pas déclarée est bloqué à la périphérie avec EGRESS_NOT_DECLARED.
6. Un module Enterprise
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.
Cela devrait produire un RouteModule avec son id, son featureGroup, un bodies vide et un register qui monte un routeur sur l'application de l'hôte, avec la vérification d'habilitation au sein de chaque gestionnaire et le corps du refus au format standard. La preuve réside dans le contrôle de ligne de licence se terminant avec le code 0, puis dans la réussite de npm ci, npm test et npm run build dans chaque arborescence d'édition composée. Le chapitre 2.25, Construire pour chaque édition, présente le squelette du module et ce que le contrôle refuse.
Ce que cela coûte
Travailler de cette manière est plus rapide, mais cela a un coût. Chaque passe d'agent dispose d'un budget et d'une durée de vie d'une heure, et un long remaniement implique de la renouveler. Le marquage de lecture (read-taint) empêchera une session ayant lu un seul document client d'écrire quoi que ce soit jusqu'à votre confirmation, ce qui est irritant les premières fois mais parfaitement justifié. Un script ne peut jamais rien modifier en dehors de votre bac à sable ; ainsi, une automatisation qui doit atteindre l'environnement de préproduction passe par une demande de changement et deux réviseurs, comme tout le monde. Je préfère avoir ces limites plutôt que d'expliquer à Larkfield pourquoi un assistant a envoyé sa table de sinistres par e-mail quelque part.




