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.
| Camada | Gatilho | Comando | Velocidade |
|---|---|---|---|
PreToolUse | antes de escrever um arquivo | kata verify --json + regras de deny | <100ms |
PostToolUse | depois de escrever um arquivo | kata verify --json | <100ms |
Stop | antes de o agente declarar pronto | pnpm test | segundos |
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:
{}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:
{
"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:
| Regra | Verifica | ADR |
|---|---|---|
kata/no-route-without-output-schema | todo defineRoute declara output | ADR-0003 |
kata/no-route-without-input-schema | todo defineRoute declara input | ADR-0003 |
kata/inline-schema | schemas Zod vivem em *.schema.ts | ADR-0005 |
kata/context-key-not-registered | c.get('key') é uma chave de contexto registrada | ADR-0004 |
kata/scoped-slot-not-provided | um 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-request | um c.get scoped só é lido dentro de um handler de request | ADR-0004 |
kata/middleware-provides-mismatch | provides[] casa com o c.set do handler (avisa quando um slot de c.set é omitido de provides) | ADR-0004 |
kata/jwt-auth-provides-slot | um middleware jwtAuth({ slot }) declara provides: [slot] | ADR-0013 |
kata/no-adhoc-error-shape | erros usam c.error(...), não c.json({ error }, 4xx/5xx) inline | ADR-0008 |
kata/no-raw-boundary-cast | casts as never de fronteira ficam contidos em hono-bridge.ts; um cast bruto as unknown em outro lugar carrega um marcador // kata-allow: hono-boundary | ADR-0025 |
kata/schema-file-naming | arquivos de um módulo são nomeados <domain>.{route,service,schema}.ts | ADR-0018 |
kata/no-decorator | nenhuma sintaxe @decorator sob src/ | ADR-0002 |
kata/no-class | nenhuma 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:
- reprovar mesmo assim → falsos positivos, que te treinam a ignorar a ferramenta;
- pular em silêncio → um check verde que afirma algo que ninguém provou;
- 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.jsondescrevendo o que cada middleware exportado fornece e lê; o@katajs-framework/coregera o seu no build, que é por quecors(),secureHeaders()ebodyLimit()resolvem. Autores de middleware de terceiros podem publicar o mesmo arquivo. - Uma factory local. O
kata verifysegue a chamada até oreturn, entãorequireRole('admin')resolve desde que a factory retorne umdefineMiddleware({ ... })(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.
- DI estático. Toda dependência é declarada em um único
defineContext({...}). Verificar quec.get('key')é legal é um teste de pertinência a conjunto contra as chaves parseadas desrc/context.ts— não um percurso do grafo de tipos. - Schemas obrigatórios. Toda route declara
inputeoutput. Checar que um schema está presente é ler o literal de objeto dodefineRoute, não avaliá-lo. - Layout de pastas travado.
src/modules/<domain>/<domain>.{route,service,schema,hurl,test}.tssignifica 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 okata verifyjá trata como irresolvível quando aparece emmiddlewares:/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:
- Burlar o portão de commit —
git commit --no-verify(ou-n),git push --no-verify, um prefixo de envSKIP=<hook>. - 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:
{
"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.jsonNo 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.
kata initEle 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, typecheckO .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.
{
"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:
- 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:3001Um 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":
pnpm start &
SERVER_PID=$!
trap 'kill "$SERVER_PID" 2>/dev/null || true' EXIT
npx --yes wait-on tcp:3000 --timeout 30000
pnpm hurlNada 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-verifye adulteração de config.