Iniciar sessãoAgendar apresentação

Capítulo 2.26

Construir com ferramentas de programação de IA

Como construir extensões do Nexus em segurança com o Claude Code e outras ferramentas de programação com IA (inteligência artificial). Começa com a ligação do seu IDE (ambiente de desenvolvimento integrado) ao Workbench e um ficheiro CLAUDE.md de projeto que transporta as regras da plataforma, e termina com seis instruções práticas e a barreira de controlo que valida cada uma delas.

Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

24 minutos de leitura

A maior parte do pacote Cold chain no capítulo 2.24, Construir uma vertical personalizada de ponta a ponta, foi escrita com o Claude Code aberto no terminal ao meu lado. Isso é normal na Corrán Orbital agora, e o Nexus foi construído a contar com isso. A plataforma não trata uma ferramenta de programação de IA (inteligência artificial) como um preenchimento automático inteligente. Trata-a como um agente que atua em nome de uma pessoa identificada, com um passe que é sempre mais restrito do que o dessa pessoa, e regista cada chamada que o agente faz.

Este capítulo aborda como trabalhar dessa forma sem sofrer percalços. Começa com a ligação do seu IDE (ambiente de desenvolvimento integrado), depois aborda as competências no editor, o ficheiro de projeto que ensina à ferramenta as regras da plataforma, os dois compiladores que transformam o trabalho existente em código Nexus, como os commits indicam qual a ferramenta que os escreveu e como revejo o que a ferramenta produz. Termina com seis prompts que eu entregaria a um colega, cada um com o que deve ser devolvido e a gate que o comprova.

Ligar o seu IDE ao Nexus

Cada instalação tem um endereço Workbench para ferramentas de programação de IA. Pode encontrá-lo na página Ligar o seu IDE em Programadores, e o Claude Code liga-se com um comando:

claude mcp add workbench --transport http <workbench-address>

<workbench-address> é o endereço que a página mostra, com um botão de cópia ao lado. As outras ferramentas têm os seus próprios comandos de uma linha na mesma página: codex mcp add workbench --url <workbench-address> para o Codex, uma ligação de instalação para o Cursor e code --add-mcp com um pequeno argumento JSON para o VS Code com o Copilot. Todos eles comunicam por MCP (Model Context Protocol) para o mesmo endereço.

Ligar o seu IDE
Ligar o seu IDE
Ligar o seu IDE, com um comando por ferramenta e os níveis predefinidos à direita. O diagrama no rodapé mostra cada chamada a passar pelo Workbench, a obter a sua própria credencial de curta duração e a chegar apenas ao espaço próprio da organização em cada armazenamento.

Não há nenhuma chave para colar. A primeira chamada abre o seu navegador, que mostra exatamente o que está a pedir: qual a ferramenta e em que computador, em nome de quem está a atuar e que níveis pretende. Autoriza com a sua chave de acesso (passkey) e, a partir daí, a ferramenta não guarda nenhuma palavra-passe de base de dados nem kubeconfig, apenas um passe que expira. Por trás do endereço, o Nexus cria uma credencial de curta duração para cada armazenamento, para cada pedido, em seu nome.

Um administrador da organização também pode transferir um ficheiro de definições geridas para que cada cópia da empresa do Claude Code se ligue a este servidor e a nenhum outro:

{ "workbench": { "type": "http", "url": "<workbench-address>" } }

Níveis e passes

Cada início de sessão no Workbench obtém um passe composto por níveis nomeados. A predefinição para um programador é Observe e Sandbox nas suas próprias unidades.

Nível O que permite Quem o obtém
Observe Ler as suas unidades, incluindo registos e métricas, e consultar a cópia mascarada Predefinição
Sandbox Escrever no seu próprio espaço: o seu espaço de desenvolvimento e as suas próprias ramificações de dados Predefinição
Propose Abrir um pedido de alteração; um pipeline aplica-o após revisão Solicitado na primeira utilização
Elevate Uma ação com tempo limitado num único alvo, aprovada por uma pessoa identificada Apenas pessoas, nunca apenas por início de sessão
Break-glass Acesso de emergência Apenas administradores da plataforma, com dois aprovadores

Um agente atua sempre em nome de uma pessoa e aparece na sua própria linha. O passe dele nunca é mais abrangente do que o seu e nunca inclui o nível Elevate ou dados não mascarados. Dura uma hora, sendo renovado apenas enquanto estiver ativo no Nexus ou no IDE. O passe de uma pessoa dura 8 horas. Assim, uma ferramenta que deixe em execução durante a noite para por si só, e terminar o seu próprio passe termina também o do seu agente. Cada passe de agente tem também associado um orçamento de custo de modelo, estimado antes de o passe ser concedido e mostrado como um medidor enquanto está em execução.

A página Os meus passes de acesso lista todos os passes que você e os seus agentes detêm, com os respetivos níveis e o que custaram até ao momento, e permite-lhe renovar, restringir ou terminar cada um deles. Terminar um passe interrompe a chamada seguinte de imediato; o registo de cada chamada permanece. Cada passe inclui também limites rígidos que, no nosso caso, eram de 200 linhas e 30 segundos por consulta, e 50 objetos alterados no espaço de desenvolvimento por sessão.

A primeira sessão no IDE

Uma vez ligado, /mcp no Claude Code lista as ferramentas do Workbench agrupadas por nível. O grupo Observe contém as ferramentas de leitura: workbench.k8s.describe, workbench.k8s.events, workbench.logs.query, workbench.metrics.query, workbench.traces.get, workbench.db.schema, workbench.db.query na cópia mascarada, workbench.graph.query e workbench.vector.search. O Sandbox adiciona workbench.devspace.deploy, workbench.branch.create e workbench.branch.reset. O Propose adiciona as ferramentas que abrem um pedido de alteração e planeiam uma alteração no grafo. O Elevate não está de todo no passe; tem de o solicitar na consola.

No IDE: primeira sessão
No IDE: primeira sessão
Uma primeira sessão no Claude Code, com as ferramentas listadas por nível, um reinício rastreado até à sua causa e um pedido de palavra-passe da base de dados recusado. Cada resposta indica de onde veio e o que foi ocultado.

A minha primeira pergunta real foi por que motivo o nosso leitor de telemetria reiniciou em Roterdão durante a noite. O Claude Code descreveu a carga de trabalho (dois reinícios, falta de memória face a um limite de 512 MiB), consultou os registos (organização definida pelo gateway, dados pessoais ocultados) e a métrica de memória, e descobriu que o carregamento noturno reuniu uma noite inteira de leituras num único lote. Depois pedi-lhe, meio a título de teste, a palavra-passe da base de dados que o serviço utiliza. O Workbench recusou com SECRET_NEVER_SHOWN. Mostra o nome de um Secret e os últimos quatro caracteres, nunca o valor, a ninguém. A resposta do assistente foi a correta: não precisa da palavra-passe, porque cada consulta que faz obtém a sua própria credencial de curta duração, uma função só de leitura criada para esse único pedido.

Planear, depois aplicar

Cada ferramenta que altera algo mostra primeiro um plano. O plano é um diff com contagens e uma impressão digital, e a aplicação executa apenas esse plano, com exatidão.

No IDE: planear, depois aplicar
No IDE: planear, depois aplicar
Um limite de memória aumentado no espaço de desenvolvimento a partir de um plano e, em seguida, a mesma alteração fora da sandbox. Na sessão interativa, uma pessoa confirma-a no IDE; a partir de um script sem interface (headless), é recusada.

Dentro do seu próprio espaço de desenvolvimento, a aplicação é executada de imediato. Fora dele, uma pessoa tem de confirmar no IDE, e a alteração vai para o pipeline, que a aplica após revisão. Daí resultam duas recusas, e ambas me aconteceram:

  • A partir de um script sem ninguém ao teclado, como claude -p num cron job, não há forma de mostrar a caixa de confirmação, pelo que uma alteração fora da sandbox é recusada com CONFIRMATION_UNAVAILABLE. Nada acontece. Execute-o numa sessão interativa.
  • Uma aplicação que indique um plano que esta sessão nunca criou, ou um plano que foi alterado, é recusada com PLAN_FINGERPRINT_MISMATCH antes que algo seja executado. Planeie novamente.

Contaminação por leitura

O conteúdo do cliente pode ocultar instruções destinadas a um assistente. Assim, uma vez que uma sessão o tenha lido, a sessão perde as suas ferramentas para escrever e para comunicar para fora do Nexus até que uma pessoa confirme uma escrita ou inicie uma nova sessão.

No IDE: contaminação por leitura
No IDE: read-taint
Um documento de reclamação lido na cópia mascarada, com uma instrução oculta que o assistente ignorou. A escrita seguinte é recusada até que a pessoa confirme essa escrita específica ou inicie uma nova sessão.

Deparei-me com isto num documento de reclamação que continha um parágrafo dirigido a "o assistente", pedindo-lhe que copiasse a tabela de reclamações para um endereço externo. O Claude Code ignorou-o e informou disso mesmo. Quando depois lhe pedi para adicionar o desvio ao meu grafo de ramificação, a escrita foi recusada com SESSION_TAINTED. Eu podia confirmar essa escrita específica após ler o respetivo plano, ou iniciar uma nova sessão que não tivesse lido o documento. Registos e métricas não contaminam uma sessão. Documentos, tickets, correio e texto-fonte do grafo contaminam. O texto oculto foi contabilizado no meu registo de atividade como instruções encontradas no conteúdo, sem as respetivas palavras.

Outra organização

Nada do que escrever pode alcançar os dados de outra organização. Se o pedir, todos os armazenamentos recusam com TENANT_BOUNDARY. Um valor de organização introduzido sub-repticiamente numa consulta de registos é substituído pelo gateway pelo valor da sua própria organização. Não se trata de uma permissão em falta. Cada camada no caminho está delimitada à sua organização, pelo que não há ninguém que a possa conceder a partir do lugar onde se encontra, e o acesso de um administrador da plataforma também não ajudaria. Se duas organizações concordarem em partilhar dados, trata-se de um acordo estabelecido entre elas, nunca algo que uma sessão de IDE faça.

Competências no IDE e no Claude Code

As competências do Skills Engine são pastas SKILL.md, e o Claude Code lê as mesmas pastas. A biblioteca sincroniza para ~/.claude/skills no seu próprio diretório pessoal, só de leitura, com os seus rascunhos ao lado delas em ~/.claude/skills/drafts. Assim, as competências que a sua organização publicou estão disponíveis no seu editor sem qualquer cópia, e o que escreve localmente volta a passar pelos mesmos testes e aprovação que qualquer coisa escrita na consola.

Competências no IDE e no Claude Code
Competências no IDE e no Claude Code
Uma competência escrita e testada no editor, depois enviada pelo mesmo processo de aprovação que uma criada na consola. Repare na publicação retida porque o seu autor não pode aprovar a sua própria alteração.

A partir do terminal, no repositório que contém a competência, dois scripts npm levam-na do seu editor para a biblioteca:

npm run skill:validate skills/check-a-customs-filing
npm run skill:upload skills/check-a-customs-filing

A validação verifica o formato e os casos de teste. O carregamento cria um rascunho e, se o conteúdo corresponder a uma versão já publicada, devolve antes essa versão (CONTENT_HASH_ALREADY_PUBLISHED). A publicação fica retida para aprovação quando a competência o exige, e não pode aprovar a sua própria alteração. Uma execução iniciada a partir de um script sem uma rota de modelo é recusada com SKILLS_ENGINE_BINDING_MISSING: o expedidor escolhe a rota e o motor verifica se esta foi indicada, nunca adivinhando uma. O Capítulo 2.24, Construir uma vertical personalizada de ponta a ponta, mostra os mesmos scripts num projeto completo.

Os agentes e o Claude Code também acedem à biblioteca através de MCP, num total de 13 ferramentas. Entre elas, list_skills e get_skill encontram e leem uma competência, match_prompt e discover_skills indicam qual a competência que se adequa a uma tarefa, invoke_skill executa uma e sync_skills_local copia a biblioteca para a sua pasta de competências. Cada chamada é executada em nome da pessoa que a iniciou, dentro da respetiva lista de permissões. Uma competência nunca pode alargar as suas ferramentas para além da lista de permissões de quem a executa.

Um ficheiro CLAUDE.md de projeto que transporta as regras da plataforma

O Claude Code lê um CLAUDE.md na raiz do repositório no início de cada sessão. É a medida de segurança mais económica que tem, porque coloca as regras da plataforma perante o modelo antes que este escreva o que quer que seja. As gates do SDK (kit de desenvolvimento de software) irão detetar a maioria dos erros de qualquer forma, mas uma regra que o modelo leia à partida poupa-lhe uma compilação falhada.

Escreva-o como regras com as respetivas razões, não como aspirações. Eis o que está no nosso repositório do plugin Cold chain, ligeiramente resumido:

# 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>.

Três fatores fazem com que um ficheiro como este funcione. Cada regra indica o mecanismo que a aplica, para que o modelo possa verificar o seu próprio trabalho em relação ao mesmo critério que o pipeline irá utilizar. A definição de concluído é uma lista de comandos com códigos de saída, não uma sensação. E proíbe os atalhos específicos a que um modelo recorre quando uma compilação falha, tais como eliminar o teste ou atribuir por predefinição um marcador de posição a uma organização em falta.

Fornecer o corpus do SDK como contexto

A documentação do SDK é um conjunto de 28 volumes, escrito para que um programador ou um LLM (grande modelo de linguagem) construa um plugin de produção completo apenas a partir do corpus, sem acesso ao código privado da plataforma. Cada formato de comunicação e código de erro que um plugin encontra está nos próprios documentos.

Isso torna-o um contexto invulgarmente bom. Na prática, forneço ao Claude Code os volumes relevantes para a tarefa em vez do conjunto completo: os volumes de manifesto e HTTP para uma nova rota, o volume de base de dados para uma migração, o catálogo de erros sempre que está envolvida uma recusa e a lista de verificação de conformidade sempre, porque é todo o corpus sob a forma de uma lista de verificação. Diga ao modelo para dar preferência a um facto observado em detrimento da sua própria memória sobre como uma framework costuma funcionar. Quando os dois divergem, o corpus está certo relativamente a esta plataforma.

Para o programador de frontend da sua equipa, gere um guia a partir do manifesto em vez de escrever um:

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin guide --manifest nexus.manifest.json --narrative docs/guide --out docs/GUIDE.md

Lista todas as rotas que a aplicação web pode chamar com todas as recusas que pode receber de volta, pelo que também constitui um bom contexto para o modelo que escreve a aplicação web. Faça commit do mesmo e verifique-o na CI (integração contínua) com --check --lint para que não possa divergir do manifesto.

Encapsular um repositório existente: /plugin-create

A competência /plugin-create transforma um repositório existente ou uma especificação de API (interface de programação de aplicações) num plugin do Nexus. Indique-lhe a origem quando a invocar:

/plugin-create https://github.com/<owner>/<repo>

Funciona por fases. Primeiro clona e analisa a origem, identificando a linguagem e a framework, a superfície da API, a base de dados e as respetivas migrações, e o que aquilo realmente faz. Imprime um relatório de análise e escolhe uma estratégia de encapsulamento (wrapping) a partir do que encontrou:

Origem Estratégia
API REST (transferência de estado representacional) em Node.js Um wrapper Express em torno das rotas existentes
API REST em Python Um wrapper FastAPI
Node.js e React full-stack Um wrapper de backend com um adaptador de interface de utilizador (UI)
Ferramenta de linha de comandos Uma API Express que executa os comandos
Biblioteca ou SDK Uma API Express que expõe as suas funções
Plataforma complexa Um contentor de plugin com um proxy nginx à frente

Em seguida, gera o backend e as respetivas migrações, uma UI, o manifesto e os testes. Trate o que escreve como um primeiro rascunho sólido e exija-lhe o mesmo padrão de qualidade que a qualquer outra coisa. No nosso repositório, isso significou três passos antes de alguém o rever. Elevámos o seu manifesto para o contrato v2 com create-nexus-plugin migrate --write, que adiciona as frases de regras (law sentences) e se recusa a inventar um ponto de entrada. Depois fizemo-lo passar em create-nexus-plugin validate. E executámos nexus-gates até ficar verde, o que no nosso caso significou substituir os cabeçalhos de inquilino (tenant) que o wrapper lia por si próprio pela proteção de âmbito do SDK, e adicionar os três eixos às suas tabelas. A implementação mantém-se nos canais de lançamento da instalação; ignore quaisquer ficheiros de implementação que o rascunho contenha.

mockup-compiler: de ecrãs a código funcional

O segundo compilador funciona no sentido inverso. O mockup-compiler pega nas maquetas (mockups) de um projeto, que podem chegar a milhares de ecrãs, e compila-as numa UI funcional, rotas de backend para frontend (BFF) e SQL, com fidelidade comprovada ecrã a ecrã através de gates com códigos de saída. Rastreia cada palavra desenhada até à linha de código-fonte que a desenhou, junta cada ecrã à sua especificação, calcula as alterações de domínio de que os ecrãs necessitam e emite os contratos e migrações juntamente com uma especificação dos dados de demonstração de que cada ecrã precisa.

Duas regras distinguem-no de pedir a um modelo para "construir estes ecrãs":

  • Compilador primeiro. Tudo o que pode ser conhecido é calculado, de forma determinística. Um modelo é utilizado apenas para lacunas tipadas (typed holes): escreve um artefacto face a um esquema, um verificador determinístico aceita-o ou enumera cada defeito, e o modelo tem no máximo 3 rondas de reparação alimentadas com o relatório do verificador.
  • Cada gate tem um controlo negativo de defeito introduzido. Quando o verify executa as gates de um projeto para um ecrã, uma cópia da árvore recebe um defeito introduzido por gate e, se uma gate passar o seu defeito introduzido, toda a execução é marcada como não fidedigna. Uma gate que não possa falhar aborta a execução.

O trabalho decorre por etapas, cada uma com o seu próprio modo e a sua própria gate:

Etapa Modo O que a sua gate comprova
Pin pin O desenho é idêntico em duas compilações, com IDs de ecrã únicos
Trace trace Cada palavra desenhada é rastreada até exatamente uma linha de código-fonte
Join join Cada espaço (slot) compilado corresponde à origem que o desenhou
Spec spec Cada ecrã tem a sua linha da especificação
Alteração de domínio domain A proposta abrange tudo o que os ecrãs leem e escrevem, com códigos do catálogo do SDK
Contratos shape-check, emit-contracts Cada campo lido tem um formato retirado da sua coluna ou declarado
SQL e armazenamento emit-sql, emit-store A migração aplica-se a um Postgres real, com testes que falham primeiro (fail-first)
World world Os dados de demonstração abrangem as células de todos os ecrãs
Bind bind A parte decidida de cada associação (binding), com o restante listado como lacunas nomeadas
Verify verify As próprias gates do projeto por ecrã, cada uma comprovadamente capaz de falhar

A única entrada específica do projeto é .mockup-compiler.json, o adaptador. Indica como uma página marca um ecrã e quais as expressões idiomáticas de SQL e de armazenamento a emitir. Também nomeia os eixos de ocupação (tenancy), com aquele que encabeça cada chave, e a chamada de autorização que cada escrita faz. mockup-compiler init --project <dir> escreve um esqueleto no qual cada entrada não preenchida é recusada pelo nome. Um projeto sem o seu próprio compilador de UI não pode utilizar compile, baseline-check, join ou world, e esses modos indicam isso mesmo com NO_PROJECT_COMPILER em vez de falharem mais adiante.

A regra que eu retiraria disto, mesmo que nunca o execute: uma regra de escrita que a especificação não declare torna-se um 501 honesto que indica o que falta, nunca uma suposição. Essa é a mesma regra que pretendo de qualquer modelo que escreva código para ecrãs.

Atribuição do gerador

Quando uma ferramenta escreve um commit, o commit deve indicá-lo. O contrato de atribuição de gerador pede uma linha de rodapé (trailer) na mensagem de commit:

feat(excursions): page the nightly telemetry load

X-Generator: claude-code/<model>

A identidade é <harness>/<model>, em minúsculas, com uma barra: o harness é a ferramenta que foi executada (claude-code), e o modelo é aquele que estava em execução. Se o modelo mudou durante o trabalho que o commit encerra, adicione X-Generator-Session com cada identidade, a mais antiga primeiro, para que o trabalho não seja atribuído a qualquer que fosse o modelo que calhou estar ativo no momento do commit. Um serviço que envolva o commit de outra pessoa, como uma fila de fusão (merge queue), transporta estes rodapés consigo.

Duas propriedades tornam isto útil em vez de decorativo. Uma declaração que um leitor não reconheça é mantida e mostrada em unregistered/<harness> com o texto exato preservado, nunca descartada. E o rodapé é proveniência autodeclarada, nunca prova: nada o assina, pelo que todas as superfícies que contabilizam estas declarações mostram essa ressalva ao lado dos números. A gramática de identidade é publicada com o SDK como @adverant-nexus/plugin-sdk/schema/generator-id. Não é um campo do manifesto, porque a ferramenta que escreveu um commit é um facto sobre o commit, não sobre o plugin.

Rever código escrito por uma IA

A ferramenta escreve de forma rápida e confiante no mesmo tom, quer esteja certa ou errada. A minha rotina de revisão para as suas alterações é curta e não salto nenhuma parte:

  1. Leia o diff, não o resumo. O resumo diz o que o modelo tencionava fazer.
  2. Execute você mesmo a definição de concluído, a partir de um estado limpo: npm ci, os testes, a compilação, validate e nexus-gates. Cite as últimas linhas na revisão.
  3. Para cada novo teste, verifique se falha na árvore antes da alteração. Um teste que passa de ambas as formas é decorativo.
  4. Procure os atalhos. Um teste eliminado ou ignorado, uma nova entrada em gates/ sem motivo, um valor de inquilino lido a partir de um corpo ou de um cabeçalho, uma organização predefinida, um catch que oculta uma recusa, um fetch para um endereço que o manifesto não declara.
  5. Compare o manifesto com o último lançamento. Qualquer novo âmbito ou endereço de saída é um alargamento, e os alargamentos requerem dois revisores.
  6. Verifique se os testes de recusa validam todo o corpo: error, code, resolved[], missing[] e troubleshooting[].
  7. Verifique se o commit contém o seu rodapé X-Generator.

As gates detetam os defeitos mecânicos. Não lhe conseguem dizer se uma rota pertence à lista não-CRUD, ou se um backend está legalmente bloqueado, e o modelo também não o consegue fazer; esse discernimento continua a caber-lhe a si. Se o mesmo problema continuar a surgir, corrija o CLAUDE.md, não apenas o código.

Seis instruções práticas

Cada prompt abaixo é um que já utilizei, ligeiramente aperfeiçoado. Depois de cada um: o que a ferramenta deve produzir e a gate que comprova que o fez. Se a gate não estiver verde, o trabalho não está concluído, independentemente do que diga o resumo.

1. Uma nova competência do 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.

Deve produzir skills/summarise-excursion/SKILL.md com name, description, allowed-tools, triggers, capabilities e version no frontmatter, as respetivas instruções no corpo e casos de teste que incluam a instrução introduzida. A prova é npm run skill:validate skills/summarise-excursion com zero erros, seguido de npm run skill:upload skills/summarise-excursion --dry-run a mostrar o plano. A publicação é uma decisão de uma pessoa posteriormente, e uma competência que escreve necessita de dois aprovadores identificados no Enterprise.

2. Uma rota de plugin de serviço completo

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.

Deve produzir uma migração numerada que adicione a coluna a uma tabela que contenha os três eixos, ambas as rotas declaradas em api.endpoints[] com os seus auth e right, o direito no registo rights, processadores (handlers) protegidos pela proteção de âmbito e testes que validem que um pedido não autenticado e um pedido da organização errada são recusados com corpos completos. A prova é nexus-gates: scope-adherence, crud-adherence, api-contract, rights-register e migrations-are-scoped passam todos, e o resultado que falha primeiro (failing-first) está na transcrição.

3. Uma lente

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.

Deve utilizar nexus.create com um plano que você confirma e, em seguida, moldar a lente em função da sua base. Se tentar mostrar algo que a base não mostra, o registo recusa com LENS_CANNOT_WIDEN, e a ferramenta deve comunicar isso em vez de procurar uma forma de o contornar. A prova é a pré-visualização como uma pessoa e, no momento da promoção, a verificação de política da gate piloto de que a lente apenas restringe e mantém os campos pessoais desativados por predefinição.

4. Um pacote de domínio

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.

Deve produzir o plano do assistente, listando o repositório e a sua primeira alteração, os âmbitos declarados e as três ramificações de dados sintéticos, além de um pack.json com os seus grupos de lentes e léxico. Nada é criado até que confirme a impressão digital. A prova consiste na passagem dos testes do modelo nas ramificações sintéticas e, mais tarde, na gate de preparação (staging). Se o pacote pedir mais do que no seu último lançamento, o lançamento fica retido com MANIFEST_SCOPE_WIDENED até que dois revisores o aceitem.

5. Um conector de dados

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.

Deve produzir uma skill plugin_queue cujo queueName seja <plugin name>.<name> sem dois pontos, um timeoutMs entre 1 segundo e 6 horas, um worker que processa a fila, uma migração para a tabela de eventos, o endereço de saída no manifesto do pacote (e não em nexus.manifest.json, cujo esquema não tem esse campo) e o nome da variável da credencial em scripts/ci/required-env. A prova é create-nexus-plugin validate, que aplica as próprias regras de sincronização do registo aos nomes das filas e aos timeouts, seguido de nexus-gates com no-credentials e no-direct-compute a verde. Em tempo de execução, uma chamada para qualquer endereço que o manifesto do pacote não tenha declarado é bloqueada na periferia com EGRESS_NOT_DECLARED.

6. Um módulo 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.

Deve produzir um RouteModule com o respetivo id, featureGroup, bodies vazio e um register que monta um router na aplicação do anfitrião, com a verificação de concessão dentro de cada handler e o corpo de recusa no formato padrão. A prova é a gate da linha de licença sair com 0, seguida da aprovação de npm ci, npm test e npm run build em cada árvore de edição composta. O Capítulo 2.25, Compilar para cada edição, mostra o esqueleto do módulo e o que a gate recusa.

Quanto custa

Trabalhar desta forma é mais rápido e tem um custo. Cada passagem do agente tem um orçamento e uma hora de vida, pelo que uma refatorização longa implica renová-la. O read-taint impedirá que uma sessão que leu um documento de cliente escreva o que quer que seja até que o confirme, o que é irritante nas primeiras vezes e absolutamente correto. Um script nunca pode alterar nada fora da sua sandbox, pelo que a automação que precisa de chegar a staging passa por um pedido de alteração e por dois revisores, como tudo o resto. Prefiro ter esses limites a ter de explicar à Larkfield por que motivo um assistente enviou a tabela de sinistros deles por e-mail para algum lado.