1. O que é "harness"

Harness Engineering é a construção deliberada e contínua de mecanismos ao redor do LLM para aumentar a confiança nos resultados. Ele se divide em três famílias:

Frase-resumo: guias sugerem, sensores detectam, grades de proteção previnem.

Os sensores ainda se dividem por tipo de execução:

• Computacional — determinístico e rápido, roda na CPU: testes, lint, type check.
• Inferencial — análise semântica, roda em GPU/NPU: code review de IA, "LLM como juiz".

2. Os dois scores

Use o Maturity como métrica de time (é o que qualquer pessoa que clonar o repo recebe). Use o Effective para entender por que o seu ambiente parece melhor que o do colega.

3. As 6 dimensões (108 pontos)

4. Requisitos formais de cada nível

Os requisitos são cumulativos: cada nível exige todos os anteriores mais os seus próprios.

Consequência prática: não existe atalho por pontos. Dá para ter 85/108 e continuar em L2 se sensors ou ci estiverem abaixo do limiar. O nível é um conjunto de portões, não uma soma.

Passo a passo por nível

Antes de qualquer etapa, tire a foto inicial:

npx --yes harness-score .

E, para comparar depois:

npx --yes harness-score . --quiet --json > ../reports/before.json
# ... faz a mudança ...
npx --yes harness-score . --diff ../reports/before.json

L0 — Sem harness (Unharnessed)

O que caracteriza: o repositório não fornece nada ao agente. Cada nova sessão começa do zero: o agente precisa inferir arquitetura, comandos e invariantes lendo o código.

Como é na prática: só código-fonte + package.json. Sem AGENTS.md, sem rules, sem testes, sem CI, sem .gitignore.

Score de referência no tutorial: 14/108.

Sintomas de que você está aqui:

• Você repete as mesmas instruções em todo prompt.
• O agente inventa comandos que não existem.
• Não há como o agente provar que terminou — só afirmar.

L1 — Documentado (Documented)

Portão: context ≥ 40%.

O que cobre: feedforward global. Um arquivo de contexto na raiz que o agente carrega em toda tarefa.

Passo a passo

1. Crie AGENTS.md na raiz (ou CLAUDE.md / GEMINI.md, conforme a ferramenta).
2. Inclua apenas fatos verificáveis do repositório:
   • o que o produto faz;
   • a estrutura real de diretórios;
   • os comandos que realmente existem hoje;
   • invariantes de domínio derivados do código;
   • restrições de dependências e de módulos;
   • expectativas de validação e tratamento de erro;
   • limites de segurança e ações proibidas;
   • checklist de conclusão.
3. Meça: npx --yes harness-score . → deve virar L1 - Documented.
4. Commit + tag de checkpoint (git tag demo-l1).

Passo 1B — enxugar sem caçar pontos

O tutorial inclui uma etapa deliberada de redução: refatorar o AGENTS.md para remover repetições preservando todos os fatos. O score não muda (~21/108), mas o harness melhora, porque o arquivo é carregado em toda tarefa e consome contexto do modelo.

Regra prática: a melhor orientação é a menor orientação capaz de prevenir erros reais. O score é um mapa de sinais estruturais, não uma função objetivo para maximizar.

Limitação que permanece: o scanner verifica que o arquivo existe e tem estrutura mínima (checks CTX-01, CTX-02). Ele não prova que cada frase seja necessária ou semanticamente correta.

L2 — Orientado (Guided)

Portões: context ≥ 60%; skills ≥ 30% ou hooks ≥ 30%; hygiene ≥ 50%.

O que cobre: distribuir a instrução para o momento em que ela é necessária, em vez de carregar tudo sempre — e fechar as brechas básicas de higiene.

Score de referência: ~52/108 (o salto maior do tutorial).

Passo a passo

a) Rule com escopo de caminho — .agents/rules/

• Frontmatter YAML válido, com descrição útil.
• Escopo em src/** em vez de carregamento global.
• Só regras de domínio e arquitetura sustentadas pelo código.

b) Skill — .agents/skills/<nome>/SKILL.md

• Frontmatter com name e description.
• description com mais de 40 caracteres, escrita como condição de acionamento começando por "Use when..." — é isso que faz a skill ser carregada na hora certa.
• Conteúdo: o procedimento repetível completo, incluindo casos de borda e verificação.

c) Workflow / command — .agents/workflows/

• Ação explicitamente invocada pelo usuário.
• Só cite comandos que existem. Se testes/lint/typecheck ainda não existem, registre como pendentes em vez de inventar comandos.

d) Higiene (a dimensão de maior peso, 23 pts)

• .gitignore cobrindo node_modules, coverage, .env e .env.*, permitindo .env.example.
• LICENSE presente.
• Lockfile válido (package-lock.json) — instalação reproduzível.

Como cada peça é carregada

L3 — Com sensores (Sensing)

Portões: sensors ≥ 60%; ci ≥ 50%.

O que cobre: transformar afirmações sobre qualidade em evidências computáveis. É aqui que o agente para de dizer "está pronto" e passa a poder provar.

Score de referência: ~83/108.

Passo a passo

1. Testes — cobrindo caminho feliz, arredondamento, faixas inválidas e entradas não finitas. O test runner nativo do Node.js já basta.
2. Lint + formatter — ex.: Biome, com biome.json válido e versão fixada.
3. Type check estrito — tsconfig.json com strict e checkJs, sem emitir arquivos; tipos via JSDoc quando o código é JavaScript.
4. Scripts npm nomeados: test, lint, format, typecheck e check, com check executando lint + typecheck + testes. Nomes convencionais importam: é assim que o scanner reconhece os sensores.
5. CI — .github/workflows/ci.yml em pushes para main e pull requests:
   • Node.js 24;
   • npm ci, npm run lint, npm run typecheck, npm test como etapas explícitas;
   • permissão apenas de leitura de contents.
6. Atualize o AGENTS.md e o workflow de verificação para citar os comandos reais, sem duplicar detalhes procedurais.

O que cada sensor elimina

Dica do tutorial: use comandos explícitos como etapas separadas no workflow. Um único comando genérico esconde do scanner quais sensores realmente rodam.

L4 — Autocorretivo (Self-correcting)

Portões: hooks ≥ 70%; total ≥ 80%.

O que cobre: mover as regras críticas de prosa para mecanismos executados fora do modelo. Todo o harness passa a atuar junto: orienta, verifica, bloqueia e corrige continuamente.

Score de referência: ~97/108.

Passo a passo

Crie .cursor/hooks.json (ou o equivalente do seu runtime) com dois eventos:

a) Gate hook — beforeShellExecution

• Script Node.js sem dependências, commitado em .cursor/hooks/.
• Lê o payload JSON via stdin e devolve JSON válido em stdout.
• Permite comandos comuns.
• Nega npm publish, git push --force, git reset --hard, remoção recursiva de raiz ou home, e padrões destrutivos de Remove-Item.
• Retorna ask quando o payload não puder ser interpretado — nunca permita silenciosamente em caso de dúvida.

b) Feedback hook — afterFileEdit

• Lê o caminho do arquivo editado no payload.
• Roda o formatter local apenas para os tipos suportados.
• Mantém a formatação como orientação; a CI continua sendo a fonte da verdade.

c) Teste os próprios hooks — casos allow, deny e payload malformado. Hook sem teste é guardrail não verificado.

A diferença que define o nível

• Uma regra em prosa pede que o modelo evite uma ação.
• Um gate hook intercepta e bloqueia antes da execução.

L4 não é perfeição: é defesa em profundidade. Guias reduzem erros, sensores expõem erros, hooks bloqueiam classes conhecidas de ações perigosas e a CI verifica o resultado de novo.

Etapa extra — o ratchet (impedir regressão)

Chegar em L4 não mantém o repositório em L4. Adicione um workflow separado do CI do produto:

• .github/workflows/harness-score.yml, em pushes para main e PRs;
• actions/checkout + paladini/harness-score@v1;
• min-level: 4;
• permissão apenas de leitura de contents.

Equivalente local:

npx --yes harness-score . --min-level 4

Uma pipeline testa o produto; a outra testa o harness. Se alguém remover os hooks, a maturidade cai e o PR falha. O score deixa de ser uma fotografia e vira um ratchet: o repositório pode melhorar, mas não regride em silêncio.

Ciclo de trabalho para subir de nível

1. Meça o estado atual e salve o JSON fora do repositório.
2. Leia a lista de improvements da saída — ela já traz o ID do check (CTX-06, SKL-01, ...), os pontos que valem, a evidência e o link de remediação.
3. Ataque a dimensão que é portão do próximo nível, não a que dá mais pontos.
4. Faça uma mudança por vez, num escopo de arquivos definido.
5. Rode as verificações locais (npm run check).
6. Meça de novo com --diff e confira: mudou de nível? Qual dimensão subiu? Algum check regrediu?
7. Commit + tag de checkpoint.

Armadilhas comuns

Como escolher o que fazer depois

Trate os gaps restantes como perguntas, não como uma lista de tarefas:

• Existe um procedimento repetido que merece virar skill?
• Algum erro recorrente pode virar uma rule com escopo?
• Existe uma propriedade verificável que merece um novo sensor?
• Alguma ação de alto impacto precisa de confirmação ou bloqueio?
• Um subagente resolveria uma necessidade real de delegação?
• O projeto realmente precisa de MCP ou pre-commit?

Não adicione artefatos só para chegar a 108 pontos. Um harness menor e coerente com os riscos do projeto vale mais que uma coleção decorativa de arquivos.

Referências

• Harness Score: https://github.com/paladini/harness-score
• Catálogo de checks (PT-BR): https://paladini.io/harness-score/pt-BR/guide/measure-and-improve.html#the-check-catalog
• Modelo de maturidade: https://paladini.github.io/harness-score/guide/maturity-model
• Tutorial: https://github.com/thiagopbraga/harness-score-tutorial
• Showcase de maturidade: https://paladini.io/harness-maturity-showcase/