Skip to content

Engenharia de harness ​

Um harness é o conjunto de mecanismos ao redor do modelo — as checagens, os hooks, a estrutura travada — que pegam um erro no instante em que ele é cometido e dizem ao modelo como corrigi-lo. A tese do Kata é que esse harness não é ferramenta opcional parafusada depois. Ele é o produto. kata init o entrega em todo projeto.

A regra que governa é menos liberdade, melhor output. Um modelo com infinitas formas de estruturar uma route escreve uma estrutura diferente toda vez, e você revisa cada uma. Um modelo com exatamente uma estrutura legal escreve essa estrutura, e uma regra de lint rejeita qualquer outra coisa antes que você a veja. Restrições não são um imposto sobre o modelo — são o que torna o output dele previsível o suficiente para confiar. As mesmas restrições ajudam um humano: há um lugar onde uma coisa pode estar, então há um lugar onde olhar.

Esta página descreve as três camadas de feedback que o Kata conecta, por que elas são rápidas, e o que kata init escreve para ativá-las.

Três camadas de feedback ​

O harness roda o mesmo projeto por três loops em três velocidades. Cada camada falha fechando — uma checagem vermelha bloqueia em vez de avisar.

CamadaGatilhoComandoVelocidade
PreToolUseantes de escrever um arquivokata verify --json + regras de deny<100ms
PostToolUsedepois de escrever um arquivokata verify --json<100ms
Stopantes de o agente declarar prontopnpm testsegundos

As camadas de milissegundos (PreToolUse / PostToolUse) rodam a cada edição, então precisam ser rápidas o bastante para nunca interromper o fluxo do modelo. O portão Stop roda a suíte de testes real uma vez, quando o agente acha que terminou: kata verify é um motor de lint, não um runner de testes, então "pronto" é condicionado aos testes de verdade.

kata verify num hook PostToolUse ​

Depois que o agente escreve um arquivo, PostToolUse roda kata verify --json. O comando lê o projeto, roda as regras determinísticas e imprime um único objeto JSON no stdout — o formato que um hook PostToolUse do Claude Code consome.

Numa execução limpa o output é o objeto vazio, um resultado de hook no-op:

json
{}

Numa violação o hook emite decision: "block" e injeta o relatório completo como hookSpecificOutput.additionalContext, de modo que o agente é instruído a corrigir o problema no próximo turno, não apenas exposto a ele:

json
{
  "decision": "block",
  "reason": "kata verify found 1 violation.",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "kata verify found 1 violation. Fix it before continuing:\n\nERROR: ..."
  }
}

Por que --json sempre encerra com 0

No modo --json, kata verify sempre encerra com 0. A decisão viaja dentro do payload; um exit diferente de zero faria o harness expor o stderr em vez do JSON, e o agente nunca veria o feedback estruturado.

ERROR / WHY / FIX / EXAMPLE ​

Todo problema dentro de additionalContext é renderizado com o mesmo template de quatro partes. Esse é o formato que conduz a uma correção certa em vez de um chute: ele declara o que está errado, por que a regra existe (com o ADR que a decidiu), a remediação concreta e um par de código ruim/bom.

ERROR: route "createUser" is missing an output schema
  src/modules/users/users.route.ts:12:3  [kata/no-route-without-output-schema]

  WHY: every route declares input and output schemas so the contract is
  verifiable and the RPC client can infer types (ADR-0003).

  FIX: add an `output` schema to the defineRoute call.

  EXAMPLE:
    // Bad:
    defineRoute({ method: 'POST', path: '/users', input: { body: B }, handler })
    // Good:
    defineRoute({ method: 'POST', path: '/users', input: { body: B }, output: UserSchema, handler })

O mesmo renderizador alimenta o relatório humano no terminal (kata verify sem --json), então o agente e o desenvolvedor leem o texto idêntico.

As regras que kata verify impõe, cada uma ancorada no ADR que a justifica:

RegraVerificaADR
kata/no-route-without-output-schematodo defineRoute declara outputADR-0003
kata/no-route-without-input-schematodo defineRoute declara inputADR-0003
kata/inline-schemaschemas Zod vivem em *.schema.tsADR-0005
kata/context-key-not-registeredc.get('key') é uma chave de contexto registradaADR-0004
kata/scoped-slot-not-providedum c.get scoped tem um middleware que o fornece antes dele na cadeia — no use: da rota ou em createApp({ middlewares })ADR-0004
kata/scoped-read-outside-requestum c.get scoped só é lido dentro de um handler de requestADR-0004
kata/middleware-provides-mismatchprovides[] casa com o c.set do handler (avisa quando um slot de c.set é omitido de provides)ADR-0004
kata/jwt-auth-provides-slotum middleware jwtAuth({ slot }) declara provides: [slot]ADR-0013
kata/no-adhoc-error-shapeerros usam c.error(...), não c.json({ error }, 4xx/5xx) inlineADR-0008
kata/no-raw-boundary-castcasts as never de fronteira ficam contidos em hono-bridge.ts; um cast bruto as unknown em outro lugar carrega um marcador // kata-allow: hono-boundaryADR-0025
kata/schema-file-namingarquivos de um módulo são nomeados <domain>.{route,service,schema}.tsADR-0018
kata/no-decoratornenhuma sintaxe @decorator sob src/ADR-0002
kata/no-classnenhuma declaração class sob src/ADR-0002

Veja Bootstrap CLI para a superfície completa de comandos, incluindo kata verify --watch para um loop de re-checagem no terminal.

Quando uma regra não consegue provar uma checagem ​

Toda regra lê código-fonte, nunca tipos ou valores de runtime. Algumas expressões são portanto ilegíveis para ela — um middleware montado em runtime, um importado de um pacote cujo fonte ela não enxerga, um ...spread que pode contribuir com qualquer coisa. Diante de uma dessas, a regra tem três opções, e só uma é honesta:

  1. reprovar mesmo assim → falsos positivos, que te treinam a ignorar a ferramenta;
  2. pular em silêncio → um check verde que afirma algo que ninguém provou;
  3. dizer o que não conseguiu checar.

O Kata escolhe a terceira. O caso não checado é reportado como uma supressão: a regra, o motivo, a localização exata e quantas checagens ela engoliu.

✓ kata verify: no problems found (13 files checked)

⚠ 1 check suppressed — a rule could not prove its property here:
  kata/scoped-slot-not-provided: suppressed for 3 checks — could not resolve `authFactory()` in createApp({ middlewares })
    src/app.ts:17:18

A suppressed rule is not a passing rule. Re-run with --strict-coverage to fail on these.

Supressões também viajam no payload --json, num array suppressions e no contexto injetado, então o agente enxerga a lacuna em vez de ler um relatório limpo. Sozinhas elas não bloqueiam — o código pode estar perfeitamente correto — mas kata verify --strict-coverage sai com código diferente de zero em qualquer uma delas. O lefthook.yml gerado usa essa flag, então uma cadeia que se torna inverificável reprova o commit em vez de reduzir a cobertura silenciosamente.

Fechar uma supressão significa tornar a expressão legível:

  • Um middleware de um pacote npm. O pacote publica um manifesto provides.json descrevendo o que cada middleware exportado fornece e lê; o @katajs-framework/core gera o seu no build, que é por que cors(), secureHeaders() e bodyLimit() resolvem. Autores de middleware de terceiros podem publicar o mesmo arquivo.
  • Uma factory local. O kata verify segue a chamada até o return, então requireRole('admin') resolve desde que a factory retorne um defineMiddleware({ ... }) (ou um literal de middleware) que ele consiga ler.
  • Um spread ou uma lista computada. Escreva o array literalmente. use: [a, b] é checável; use: [...preset] não é.

Por que o harness é rápido ​

Um linter que precisa de um type-checker ou de um bundler para responder a uma pergunta não pode rodar a cada tecla. kata verify responde em menos de 100ms porque as três invariantes do Kata tornam toda checagem uma pergunta local e sintática — sem inferência de tipos, sem grafo entre arquivos para resolver em tempo de lint.

  1. DI estático. Toda dependência é declarada em um único defineContext({...}). Verificar que c.get('key') é legal é um teste de pertinência a conjunto contra as chaves parseadas de src/context.ts — não um percurso do grafo de tipos.
  2. Schemas obrigatórios. Toda route declara input e output. Checar que um schema está presente é ler o literal de objeto do defineRoute, não avaliá-lo.
  3. Layout de pastas travado.src/modules/<domain>/<domain>.{route,service,schema,hurl,test}.ts significa que toda route, schema e teste é encontrável por glob. O verificador sabe onde olhar sem resolver imports.

Como as regras são funções puras sobre arquivos parseados, elas também são trivialmente testáveis em unidade e carregam um viés de zero falso-positivo: quando o registry não pode ser determinado, as regras dependentes viram no-op em vez de chutar.

Não-objetivos: o que o kata verify deliberadamente não checa ​

Nem toda propriedade que vale a pena checar vira uma regra. Uma surgiu em revisão (issue #251): um módulo sob src/modules/<domain>/ cujas routes nunca são passadas para nenhum createApp({ modules }) é superfície morta — toda route dentro dele ainda passa em kata/no-route-without-output-schema e afins individualmente, porque essas regras escaneiam arquivos *.route.ts diretamente (veja a tabela acima) e nunca perguntam se o módulo chegou a algum app. Um "módulo órfão" deveria virar sua própria regra?

Decisão: um não-objetivo documentado, não uma regra.

Toda regra acima prova uma presença — um c.get('key') que existe e não está registrado, uma class que existe, um z.object(...) inline que existe. O caso ilegível (um spread, um valor computado em runtime) é seguro de pular, porque pular só abre mão da checagem daquela expressão específica; a invariante "sem grafo entre arquivos para resolver em tempo de lint" acima se sustenta porque a resposta de cada regra permanece local ao que ela consegue ler.

Uma regra de módulo órfão precisaria provar uma ausência: que nenhum createApp({ modules }) em lugar nenhum do projeto inclui esse módulo. Essa não é uma pergunta local:

  • Um projeto pode ter mais de um createApp — servers separados, um worker, apps de exemplo cada um conectando um subconjunto diferente. "Alcançável" precisa ser uma união sobre todo call site que o projeto tem, não um só.
  • modules: é exatamente a forma que o kata verify já trata como irresolvível quando aparece em middlewares: / use: — montada a partir de uma lista compartilhada, filtrada por uma flag de env, montada num harness de teste. Toda outra regra responde a uma expressão irresolvível com "pular" — e isso custa um call site não checado. Aqui custaria a única evidência que livraria o módulo de ser órfão: no instante em que um projeto usa uma indireção, um módulo corretamente conectado passaria a ler como órfão. O modo de falha que essa regra existiria para evitar é exatamente o que ela introduziria.
  • Nada manda fazer isso. createApp({ modules }) aceitar um subconjunto escolhido a dedo é a forma de trabalho normal — um módulo scaffoldado antes de ser conectado, um construído para um deployment que o app atual não é — então não há ADR para ancorar uma regra, diferente de toda regra na tabela acima. O epic do conjunto de regras (#164) se limitou a impor mecanicamente ADRs já existentes e já entregou todo o seu escopo (6/6 sub-issues); detecção de módulo órfão nunca fez parte dele.

Alcançabilidade através de um número arbitrário de entry points é uma pergunta de programa inteiro — do tipo que uma ferramenta dedicada de dead-code (ts-prune, knip) responde com informação de tipo completa, não um passe sintático de menos de 100ms sobre um arquivo por vez. Se isso um dia valer a pena ter, é uma ferramenta separada conectada no CI, não uma regra do kata verify.

O guard contra adulteração de config ​

A literatura de engenharia de harness nomeia dois reflexos que um modelo busca no instante em que uma checagem fica vermelha — ambos transformam um sinal de falha em verde sem tocar no código que falhou:

  1. Burlar o portão de commit — git commit --no-verify (ou -n), git push --no-verify, um prefixo de env SKIP=<hook>.
  2. Editar a própria regra — apagar uma regra do Oxlint, afrouxar tsconfig.json, esvaziar um workflow de CI, reescrever um script de hook. A checagem passa porque a checagem sumiu.

O ADR-0010 bane ambos, mecanicamente e de forma idêntica em todo harness. Esta é uma única fonte de verdade: os comandos banidos e o conjunto de arquivos protegidos são declarados uma vez e reproduzidos em todo projeto que kata init scaffolda.

Sem --no-verify ​

Os bypasses de verificação são negados de imediato. Num projeto gerado eles vivem em .claude/settings.json sob permissions.deny:

json
{
  "permissions": {
    "deny": [
      "Bash(git commit *--no-verify*)",
      "Bash(git commit *-n *)",
      "Bash(git push *--no-verify*)",
      "Bash(SKIP=*)"
    ]
  }
}

O Codex não tem um slot permissions.deny, então o hook PreToolUse dele impõe os mesmos bans de comando — paridade por construção, não por cópia.

O conjunto de configs protegidas ​

O mesmo ADR protege as configs de lint / format / build / framework e os próprios arquivos do harness contra escritas do agente:

tsconfig.json   tsconfig.*.json   biome.json   .oxlintrc*   lefthook.yml
kata.config.ts  pnpm-lock.yaml    pnpm-workspace.yaml       .github/workflows/**
.claude/settings.json             .codex/hooks.json

No Claude Code essas viram regras permissions.deny por ferramenta (uma para cada um de Edit, Write, MultiEdit), de modo que um projeto recém-scaffoldado fica protegido desde a primeira sessão — antes mesmo de qualquer conjunto de regras do kata verify ser construído. O hook PreToolUse é a segunda camada: ele carrega a explicação ancorada no ADR e é onde o Codex (sem slot de deny) impõe o conjunto idêntico.

Humanos ainda editam esses arquivos

O viés é sempre bloquear no fluxo do agente. Não há um discriminador humano/agente confiável dentro do hook, e o Kata não tenta construir um. Quando você precisar mudar uma config protegida, faça isso de um shell que não seja de agente.

Autoaplicado primeiro

O Kata aplica esse harness ao próprio repositório. O ADR-0007 fez um marco de harness autoaplicado bloquear todo trabalho de feature: o framework é seu próprio primeiro usuário, então o harness que kata init entrega é o mesmo que construiu o Kata.

O que kata init conecta ​

kata init escreve o harness num projeto. Ele é idempotente — um arquivo existente é deixado intacto a menos que você passe --force.

bash
kata init

Ele escreve seis arquivos:

.claude/settings.json    Hooks do Claude Code + bans de adulteração de config
.codex/hooks.json        Hooks do Codex → kata verify --json
.agents/hooks.json       Espelho neutro de fornecedor da mesma cadeia de hooks
AGENTS.md                Instruções canônicas de agente (Codex + Claude)
CLAUDE.md                Entrypoint do Claude → importa AGENTS.md
lefthook.yml             Pre-commit local do git: kata verify, Biome, oxlint, typecheck

O .claude/settings.json gerado carrega as listas permissions.deny acima mais o mapa de hooks de três eventos: PreToolUse e PostToolUse casados em Write|Edit|MultiEdit rodam kata verify --json; Stop roda pnpm test com um timeout de 180 segundos.

json
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Write|Edit|MultiEdit", "hooks": [{ "type": "command", "command": "kata verify --json" }] }
    ],
    "PostToolUse": [
      { "matcher": "Write|Edit|MultiEdit", "hooks": [{ "type": "command", "command": "kata verify --json" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "pnpm test", "timeout": 180 }] }
    ]
  }
}

.codex/hooks.json é o mesmo mapa de hooks com uma diferença: o matcher é Bash|apply_patch. O Codex casa por nomes de ferramentas e não tem ferramentas Write/Edit/MultiEdit, então as escritas de arquivo são detectadas a partir da ferramenta Bash/apply_patch. Os comandos, os eventos e o timeout do Stop são idênticos — essa paridade é o ponto. .agents/hooks.json é um terceiro espelho, byte a byte equivalente, para qualquer harness que leia a convenção emergente e neutra de fornecedor .agents/ em vez de .claude/ ou .codex/.

Por padrão, kata init faz o scaffold de um app completo e executável em cima destes arquivos do harness; --minimal escreve só o harness. Veja Bootstrap CLI para cada flag.

Rodando .hurl no CI ​

A camada Stop na tabela acima roda pnpm test — só Vitest. As suítes .hurl que cada módulo entrega (veja layout do projeto) são uma quarta camada separada, que o harness não conecta sozinho, porque precisam de algo que as outras três camadas não precisam: um servidor vivo. pnpm hurl contra um servidor que ninguém iniciou simplesmente falha com um erro de conexão, então é fácil deixar essa suíte fora de todo portão automatizado — validada uma vez à mão e nunca mais rodada.

O próprio CI do Kata fecha essa lacuna para os apps de exemplo do framework, e a mesma forma funciona para um app gerado: inicie o servidor, espere ele aceitar conexões, rode o Hurl, derrube o servidor. Este é o job de verdade em .github/workflows/ci.yml, que sobe examples/hello e examples/shop em portas separadas e roda as duas suítes contra eles:

yaml
- name: Install hurl
  run: |
    curl -fsSL -o /tmp/hurl.deb \
      "https://github.com/Orange-OpenSource/hurl/releases/download/${HURL_VERSION}/hurl_${HURL_VERSION}_amd64.deb"
    sudo dpkg -i /tmp/hurl.deb

- name: Run hurl E2E (hello + shop)
  run: |
    pnpm --filter=hello start &
    HELLO_PID=$!
    PORT=3001 pnpm --filter=shop start &
    SHOP_PID=$!
    trap 'kill "$HELLO_PID" "$SHOP_PID" 2>/dev/null || true' EXIT
    npx --yes wait-on tcp:3000 tcp:3001 --timeout 30000
    pnpm --filter=hello hurl
    pnpm --filter=shop run hurl --variable host=http://localhost:3001

Um app gerado tem um servidor só, não dois, então a receita encolhe para quatro linhas — exatamente o que o README.md scaffoldado documenta em "Continuous integration":

bash
pnpm start &
SERVER_PID=$!
trap 'kill "$SERVER_PID" 2>/dev/null || true' EXIT
npx --yes wait-on tcp:3000 --timeout 30000
pnpm hurl

Nada aqui é específico do GitHub Actions — são quatro linhas de shell, então o mesmo bloco funciona como um step em qualquer CI, ou como um script local de pre-push. O wait-on (buscado sob demanda com npx --yes, sem dependência para adicionar) faz polling da porta em vez de um sleep fixo, então o job roda assim que o servidor está de fato pronto e nunca corre risco de um boot lento. O trap garante que o servidor morre tanto se a suíte passar quanto se falhar — uma request que falha reprova o step (e portanto o job) sem deixar um processo vazando.

Veja também ​

  • Bootstrap CLI — a superfície completa de comandos kata.
  • ADR-0007 — autoaplicar o harness antes do trabalho de feature.
  • ADR-0010 — banir --no-verify e adulteração de config.

Código aberto — licença a definir. Feito com Hono + Zod.