Pitch: Harness Score 1.5: medindo a maturidade do harness de agentes de código (sem LLM no scan)

Dois times. Mesmo modelo. Mesmo prompt.

Resultados completamente diferentes.

Na prática, a diferença quase nunca é só o modelo. É o que existe ao redor dele no repositório.

Um repo entrega instruções de verdade, rules com escopo, testes, linter, CI e hooks que barram comando perigoso. O outro entrega um README e torce.

Esse conjunto — guides, sensors, guardrails — é o que a galera de harness engineering chama de harness.

Eu construí o Harness Score pra medir isso de forma objetiva.

É um scanner open source, gratuito e determinístico: olha evidência no filesystem (não “vibe”), funciona com Cursor, Claude Code, Windsurf, Cline, Continue, Codex, Copilot e afins, e devolve:

nível de maturidade L0 → L4
score em 6 dimensões (até 108 pontos)
lista ranqueada do que consertar primeiro

Sem chamar LLM. Sem telemetria. Sem rede no scan. Mesmo commit = mesmo resultado. Dá pra gatear CI com isso.

A 1.0 fechou o modelo. A série 1.5 é o momento em que isso virou um ecossistema de verdade: config no repo, score dual, Action no Marketplace, docs em 5 idiomas, showcase público e um repo de pesquisa rodando o scanner em projetos reais.

TL;DR

Do 1.0 pro 1.5.1 entrou:

guia completo em EN, pt-BR, ES, zh-CN e hi-IN
.harness-score.json como contrato do repositório
scores maturity (só o que está no git) e effective (repo + harness local)
presets e regras por check — sem “desligar” check de secret vazado
Action no GitHub Marketplace
Showcase com evidência pública
Analysis reproduzível
vários bugs resolvidos

Pra rodar agora:

npx harness-score@1.5.1

Qual dor isso resolve

Modelo bom não sabe sozinho sua arquitetura, o que é release, o que é comando proibido, nem o que conta como “pronto”.

Times vão montando isso aos poucos:

AGENTS.md / CLAUDE.md
rules e skills
teste, typecheck, lint, format
CI
hooks de gate / feedback
MCP e secrets sem vazar key no repo

O problema é que ninguém enxerga o mapa inteiro. Sem medição, fica difícil saber o que falta — e pior: um PR pode apagar uma guardrail crítica e ninguém percebe.

O Harness Score transforma arquivo em diagnóstico:

Maturity: L3 · Sensing
Score: 86/108
To reach L4: add a gate hook and feedback hook

Importante: não julga se o código é bom, nem se a rule está certa. Mede se a infraestrutura que guia e verifica o agente existe. Escopo estreito de propósito — é o que torna o número confiável o bastante pra CI.

O que mudou de 1.0 pra 1.5

1. O guia fala a língua do time

Na 1.1: inglês, pt-BR e espanhol.

Na 1.2: chinês simplificado e hindi.

Não foi “traduziu a home e pronto”. Foi maturity model, catálogo de checks, multi-harness, sensors, guardrails e receita de remediação nos cinco locales.

Check que falha só ajuda se quem vai corrigir entende o porquê.

👉 Guia

2. `.harness-score.json` responde uma pergunta chata (e real)

Score só do repositório não responde:

O que o time commitou — e o que o agente nesta máquina realmente enxerga?

Agora tem duas leituras:

Score	O que conta	Pra quê
maturity	Só arquivos do repo	CI, badge, maturidade do time
effective	Repo + scopes user/system/extra	Diagnóstico local

Dá pra ligar o overlay local sem bagunçar o gate de CI:

{
  "scopes": {
    "user": true,
    "system": false
  },
  "gate": "maturity"
}

A 1.3.1 ainda expandiu os paths globais reais de Cursor, Claude Code, Windsurf, Cline, Continue, Codex, OpenCode, Zed etc.

3. Customização sem trapacear o score

Nem todo check serve pra toda empresa.

Exemplo clássico: política interna proíbe hooks locais no repo. Antes era aceitar penalidade eterna ou forkar o modelo. Agora o repo declara a decisão:

{
  "extends": ["no-hooks"],
  "rules": {
    "HYG-05": "off",
    "CI-01": "error"
  }
}

As regras do jogo:

check excluído some dos pontos ganhos e dos pontos possíveis (não ganha ponto de graça)
toda exclusão aparece no terminal, Markdown, JSON e na Action
se um preset derruba dimensão exigida pro próximo nível, o report marca o nível como capped e explica
HYG-03, HYG-04 e HYG-06 (credencial exposta) não dão pra desligar

Isso é política revisável no git — não é modo “inflar badge”.

👉 Release notes da 1.5.0

Action no Marketplace

A 1.5.1 foi a publicação inicial da Action no Marketplace.

Workflow mínimo:

name: Harness maturity
on:
  pull_request:
  push:
    branches: [main]
jobs:
  harness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: paladini/harness-score@v1
        with:
          min-level: "3"
          badge: "harness-badge.svg"

Dá pra exigir nível mínimo, jogar resumo no job summary, emitir Markdown/badge SVG e (opcional) comentário sticky no PR com o diff do score.

Se for produção séria: pin no SHA do commit.

Evidência pública (não só “confia no meu README”)

Scanner fica bem mais útil quando dá pra ver o resultado fora do repo do autor.

O Harness Maturity Showcase junta:

21 repos pinados com JSON completo gerado por harness-score@1.5.0
20 repos da comunidade só com badge pública

Ranking numérico só entra com report completo. Badge sozinha mostra o nível — não inventa pontuação.

Cada entrada ranqueada linka evidência + commit medido. Score baixo não é vergonha de time: descreve o harness commitado naquele repo, naquele commit.

Analysis: stress test do próprio modelo

O Harness Maturity Analysis é a camada de pesquisa atrás do showcase.

Pina repo + commit + versão do scanner, guarda report cru e gera leaderboard/findings a partir disso. Também caça falso positivo, falso negativo e buraco do modelo.

Phase 1 fechada: os 21 repos foram rescaneados com 1.5.0 e os primeiros findings estão públicos.

Ainda falta a fase de rating humano cego — então não estou vendendo “o nível automático = verdade absoluta”.

Na real, o analysis existe exatamente pra achar onde o modelo precisa mudar.

Bug real veio de repo real

Do 1.0 ao 1.5 teve muita correção “sem glamour”, mas que importa:

path de hook do Claude Code ($CLAUDE_PROJECT_DIR/...) não derruba mais HKS-05 à toa
binário em node_modules/.bin/ conta como dependência instalada
sensor Maven / Spotless passa a contar
user-scope acha path real de mais ferramentas (Windsurf, Cline…)
publish alinhado entre npm, JSR, CLI e Action
reporting honesto com applicable / capped em vez de % mentiroso
UI da docs (nav, dark mode, links) alinhada com o showcase

Loop que eu quero manter: escanear → olhar evidência → achar mismatch → corrigir regra determinística → rodar o corpus de novo.

Próximo passo: Product Hunt

Semana que vem pretendo lançar no Product Hunt.

Não é linha de chegada. É colocar a ferramenta na frente de mais gente, juntar evidência de repo real e descobrir onde o maturity model ainda erra.

Se testar antes, o feedback que mais ajuda é concreto:

repo + check ID + path do arquivo + por que é falso positivo/negativo

Roda aí e me conta

npx harness-score@1.5.1

Links:

Qual nível saiu no seu repo — e qual check que falhou te pegou de surpresa? Manda os dois nos comentários.