TL;DR — Publiquei o harness-score: CLI open source que mede a maturidade do harness do repositório para desenvolvimento com IA. Um comando (npx harness-score), 36 verificações, seis dimensões, nível L0–L4. Sem LLM, sem telemetria. Já tem CLI, guia, GitHub Action e badges para o README.
O que é harness e por que medir
Harness engineering é tudo que envolve o agente de código além do modelo: AGENTS.md, regras, skills, testes, CI, hooks — o que orienta o agente antes de agir e confere o resultado depois.
Times com Cursor, Claude Code ou qualquer ferramenta agentica já perceberam: o modelo raramente é a variável principal. O repositório é.
A pergunta prática: quanto disso meu repo já tem — e o que falta?
O harness-score varre o repositório e checa coisas objetivas: existe AGENTS.md com conteúdo? Há .cursor/rules/ com frontmatter válido? Tem workflow de CI? O .env está no .gitignore? Cada um dos 36 itens passa ou falha — e o relatório lista o que falta, com link para como corrigir.
Como descobrir o nível do seu repositório
O fluxo é simples:
- Rode localmente (sem instalar nada):
npx harness-score
- Leia o resultado — nível atual, pontuação por dimensão e o que falta para o próximo nível:
harness-score v0.3.0 ~/meu-app
Maturity: L2 · Guided Score: 66/108 (61%)
Context & Guides ████████████████░░░░ 80%
Skills & Commands █████████████░░░░░░░ 67%
Hooks & Guardrails ░░░░░░░░░░░░░░░░░░░░ 0%
Sensors & Feedback ████████████░░░░░░░░ 58%
CI Feedback ██████████░░░░░░░░░░ 50%
Hygiene & Safety ██████████████░░░░░░ 70%
To reach L3: sensors ≥ 60%; ci ≥ 50%
Corrija o que falhou — cada verificação reprovada mostra em uma frase o que falta e aponta para a correção no guia.
Rode de novo até subir de nível.
São 36 verificações determinísticas em seis dimensões (108 pontos no total):
-
Context & Guides (20 pts) —
AGENTS.md, regras com escopo - Skills & Commands (17 pts) — skills, commands, subagents
- Hooks & Guardrails (14 pts) — bloqueios e feedback durante a sessão
- Sensors & Feedback (20 pts) — testes, linter, types, formatter
- CI Feedback (14 pts) — pipeline, pre-commit
-
Hygiene & Safety (23 pts) — secrets,
.env, lockfile, license
O nível não é só porcentagem. Um repo com documentação bonita e zero testes não chega em L3 — a rubrica exige requisitos específicos em cada degrau.
Para relatório em JSON ou markdown (útil em automação):
harness-score --json
harness-score --md harness-report.md
A escala L0–L4: o que cada nível significa
A escada tem cinco degraus. Cada um exige os anteriores e metas mínimas por dimensão:
L0 · Unharnessed
O ponto de partida. Sem AGENTS.md, sem regras, sem verificações automáticas. O agente funciona — sempre funciona — mas cada sessão redescobre o projeto do zero e cada erro só para se alguém pegar manualmente. A maioria dos repositórios começa aqui.
L1 · Documented
Requer: Context & Guides ≥ 40%.
Existe um AGENTS.md (ou equivalente) com conteúdo de verdade: o que é o projeto, como buildar e testar, quais convenções seguir. É o passo de maior retorno saindo do zero — orientação para toda sessão futura em um arquivo.
L2 · Guided
Requer: Context ≥ 60% · (Skills ≥ 30% ou Hooks ≥ 30%) · Hygiene ≥ 50%.
A orientação ganha estrutura: regras .cursor/rules/ com frontmatter válido, começo de conhecimento procedural (skill, command ou subagent) ou hooks configurados. Higiene básica segura — .env no .gitignore, sem credenciais em arquivos de harness. O harness passa a ser versionado junto com o código.
L3 · Sensing
Requer L2, mais: Sensors ≥ 60% · CI ≥ 50%.
O ciclo de feedback existe. Testes que o agente pode rodar, linter, type checking e CI que revalida a cada push. É aqui que a correção automática começa de verdade: o agente consegue conferir o próprio trabalho com ferramentas determinísticas, e a pipeline pega o que ele perde. Para muitos times, L3 é onde desenvolvimento com IA deixa de parecer arriscado.
L4 · Self-correcting
Requer L3, mais: Hooks ≥ 70% · score total ≥ 80%.
O ciclo fecha durante a sessão. Hooks de bloqueio impedem ações destrutivas; hooks de feedback rodam lint e formatação a cada edição. As seis dimensões estão cobertas. Um erro agora precisa passar pelas regras, pelos hooks, pelos testes, pelo type checker, pela CI e pelos bloqueios — na maior parte sem intervenção manual.
| Nível | Nome | Em uma linha |
|---|---|---|
| L0 | Unharnessed | Agente começa do zero a cada sessão |
| L1 | Documented |
AGENTS.md orienta o trabalho |
| L2 | Guided | Regras, skills, higiene básica |
| L3 | Sensing | Testes, linter, types e CI verificam o output |
| L4 | Self-correcting | Hooks fecham o ciclo na sessão |
Rubrica completa: modelo de maturidade
Por que o scanner não usa IA
O scanner nunca chama um modelo. Só lê arquivos e interpreta configs — se você rodar duas vezes no mesmo commit, a pontuação é idêntica. Por isso dá para usar --min-level na CI: o pipeline falha se o nível cair, sem surpresa entre uma execução e outra.
O próprio repositório do projeto usa a ferramenta nele mesmo: L4 (108/108) com --min-level 4 na pipeline.
Como adicionar na sua pipeline
Opção 1 — CLI direto no workflow
jobs:
harness:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npx -y harness-score --min-level 3
--min-level 3 faz o job falhar se o repositório estiver abaixo de L3. Use 0 se quiser só gerar o relatório, sem bloquear o merge.
Opção 2 — GitHub Action (recomendado)
A Action faz o scan, gera o badge SVG e pode falhar o build se o nível estiver abaixo do mínimo:
jobs:
harness:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: paladini/harness-score/action@main
with:
min-level: '3'
badge: harness-badge.svg
report: harness-report.md
O resumo do job mostra nível e tabela de dimensões. Com comment: 'true' em workflows de PR, a Action posta (e atualiza) um comentário comparando o score com a branch base — útil para ver “subiu de L2 para L3 neste PR”.
Docs da Action: github.com/paladini/harness-score/tree/main/action
Quando passar a bloquear o merge
Comece só medindo (min-level: '0'), acompanhe o nível do time por algumas semanas, e só então suba o mínimo — L2 para times começando com IA, L3 como alvo razoável para a maioria, L4 para quem já usa hooks de verdade no dia a dia.
Badges no README
Há dois formatos de badge:
| Formato | Tamanho | O que mostra | Quando usar |
|---|---|---|---|
| Badge pill | 112×20 |
harness · L4
|
Linha de shields no README |
| Share card | 860×240 | Nome completo do nível | Posts, docs, landing |
Badge que atualiza automaticamente
A CI regenera o SVG a cada execução com o nível detectado. Gere com:
harness-score --badge harness-badge.svg
Publique o arquivo (commit em branch badges, artifact, ou direto no repo) e referencie no README:
<img alt="Harness Score" src="https://raw.githubusercontent.com/<você>/<repo>/badges/harness-badge.svg" height="20">
Use sempre height="20" para alinhar com badges shields.io na mesma linha.
Badge fixo por nível
Se preferir não depender de CI, use os SVGs estáticos por nível (badge-l0.svg … badge-l4.svg), hospedados no guia ou copiados para o seu repo:
<img alt="Harness Score L3" src="https://paladini.github.io/harness-score/maturity/badge-l3.svg" height="20">
Atualize manualmente quando subir de nível — ou migre para o badge automático quando a pipeline estiver rodando.
Share card
Para um visual maior (com o nome completo do nível), use card-l0.svg … card-l4.svg. Galeria e exemplos de embed (Markdown, HTML, iframe, JSX): embed snippets
O que já está publicado
-
CLI —
npx harness-score,--json,--md,--badge,--min-level - Guia — 8 capítulos: paladini.github.io/harness-score
- GitHub Action — scan, badge, bloqueio por nível mínimo, comentário opcional em PR
- Badges — pill automático + estáticos L0–L4 + share cards
Ainda não no Marketplace: plugin Cursor (/harness-audit) existe no repo, mas ainda não está listado. Hoje o caminho suportado é CLI + guia.
Experimente
npx harness-score
Rode no seu repositório, veja o nível, coloque o badge no README e, quando fizer sentido para o time, configure a CI para reprovar o build se o nível ficar abaixo do mínimo.
Se testarem, me contem em que nível ficaram — e se a rubrica faz sentido para o dia a dia de vocês. Feedback e PRs são bem-vindos.
Links
- Repo: github.com/paladini/harness-score
- Guia: paladini.github.io/harness-score
- Verificações: Measure & Improve
- Badges: embed snippets
Top comments (0)