DEV Community: Fernando Paladini

Lancei o harness-score — descubra o nível de harness do seu repositório

Fernando Paladini — Tue, 14 Jul 2026 03:13:46 +0000

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

[Boost]

Fernando Paladini — Sun, 12 Jul 2026 03:25:27 +0000

Fernando Paladini

Jul 12

How Harnessed Is Your Repository? Measure AI Harness Maturity With One Command

#ai #opensource #aiops #maturity

5 min read

How Harnessed Is Your Repository? Measure AI Harness Maturity With One Command

Fernando Paladini — Sun, 12 Jul 2026 03:25:20 +0000

TL;DR — An AI coding agent is only as reliable as the harness around it: the rules, hooks, tests, and guardrails that steer and verify its work. harness-score is a free, open-source, 100% deterministic CLI (npx harness-score) that scans any repository, scores it across 6 dimensions, and reports a maturity level from L0 (Unharnessed) to L4 (Self-correcting). It ships with a full guide, a Cursor Marketplace plugin, and a GitHub Action — no model calls, no network, no telemetry.

The part of "AI coding" nobody measures

Every team using Cursor, Claude Code, or any agentic coding tool has quietly discovered the same thing: the model isn't the variable that determines whether an agent's output is trustworthy. The repository is.

Two engineers can point the same model at two different codebases and get wildly different results — not because one model tried harder, but because one repo told the agent what "correct" looks like (a real AGENTS.md, scoped rules, a fast test suite) and the other left it guessing.

In early 2026, Martin Fowler's site gave this practice a name: harness engineering — "building feedforward guides and feedback sensors" around a coding agent to make its output trustworthy. Around the same time, LangChain published a concrete case study: by improving only the harness around their coding agent — never touching the underlying model — they moved from outside the top 30 to the top 5 on Terminal Bench 2.0.

The conclusion both arrive at: reliability is a property of the model + harness + environment system, not of the model alone.

That raises an obvious question nobody had a straight answer to: how harnessed is my repository, actually?

What "harness engineering" means, concretely

A harness is everything around the model: the instructions it loads before acting, and the checks that verify what it did after. Fowler's framework splits this into two families:

	Guides (feedforward)	Sensors (feedback)
When	Before the agent acts	After the agent acts
Purpose	Steer toward good output	Catch and correct bad output
In Cursor	`AGENTS.md`, `.cursor/rules/`, skills, commands	tests, linters, type checkers, CI, hooks

Cursor, specifically, exposes more of this machinery than any other mainstream AI editor: AGENTS.md for project context, .cursor/rules/*.mdc for scoped conventions, .cursor/skills/ for on-demand procedures, .cursor/commands/ for human-triggered workflows, and .cursor/hooks.json for runtime gates that can literally deny a destructive command before it executes — not just ask the model nicely not to run it.

The problem is that none of this is measured. Teams either have all of it, some of it, or none of it, and there was no quick way to know which — until now.

Introducing harness-score

harness-score is a CLI that answers that question in seconds:

npx harness-score

  Maturity: L2 · Guided   Score: 61/100 (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%

It runs 33 checks across 6 dimensions — context & guides, skills & commands, hooks & guardrails, sensors & feedback, CI feedback, and hygiene & safety — and reports one of five maturity levels:

Level	Name	What it means
L0	Unharnessed	Agents rediscover the project every session; mistakes ship unless a human catches them
L1	Documented	A substantive `AGENTS.md` orients every session
L2	Guided	Scoped Cursor rules, skills/commands, basic hygiene
L3	Sensing	Tests, linter, types, and CI verify everything the agent does
L4	Self-correcting	Gate and feedback hooks close the loop at runtime

Every failed check comes with a one-sentence fix and a deep link into the full guide — so the output isn't just a grade, it's a to-do list.

The one design decision that matters most

The scanner never calls a model. No LLM, no network request, no telemetry — it reads your filesystem, parses config files, and applies a fixed rubric. Same repository in, same score out, every single time.

This was a deliberate trade-off. An AI-powered "does this repo look well-configured?" tool would be more flexible but non-reproducible — you couldn't gate CI on it, diff two runs, or trust that a score of 80% today means the same thing next month. A harness maturity score is exactly the kind of check Fowler's own framework calls computational rather than inferential — and computational checks are the ones you can actually put in a pipeline.

That determinism is also what makes it self-hosting: harness-score's own repository scores L4 · Self-correcting, 100/100 on itself, gated in its own CI, using the exact rules and hooks the tool checks for.

What you get

The guide — 8 chapters covering the Guides/Sensors framework, the full Cursor harness surface, and the maturity model rubric in detail, free on GitHub Pages.
The CLI — harness-score, with JSON/markdown/badge output and a --min-level flag to gate CI.
A Cursor Marketplace plugin — a /harness-audit command plus a skill that fixes the gaps it finds, following the guide's recipes.
A GitHub Action — run the scan on every push, emit a maturity badge for your README.

Try it

npx harness-score                          # no install
npm install -g harness-score               # or install it
harness-score --min-level 3                # gate CI: fail below L3

Also published on GitHub Packages and JSR for Deno/Bun users.

FAQ

What is harness engineering?
The discipline of designing everything around an AI coding agent — instructions, tools, tests, and guardrails — so its output is reliable in production. The term was popularized by Martin Fowler's site and LangChain's engineering blog in early 2026.

What is a "harness" in Cursor specifically?
The combination of AGENTS.md, .cursor/rules/, skills, commands, hooks, and MCP configuration that steers and verifies what the Cursor agent does in a given repository.

Does harness-score use AI to score my repository?
No. It is 100% deterministic — filesystem reads and config parsing only. No LLM calls, no network requests, no telemetry.

How is the maturity level calculated?
33 checks are grouped into 6 weighted dimensions (context, skills, hooks, sensors, CI, hygiene). Levels L0–L4 gate on which dimensions clear a threshold, not just the total score — so a repo full of documentation but zero tests can't accidentally look "mature."

Do I need to use Cursor to use this?
No. The CLI and the underlying practices apply to any AI-assisted repository; Cursor-specific artifacts (rules, skills, hooks) are simply scored alongside universal ones (tests, CI, types) because Cursor currently exposes the richest harness surface of any mainstream AI editor.

Is it free and open source?
Yes — MIT licensed, and the analysis runs entirely on your machine or in your CI.

Try it on your own repo

npx harness-score

Repo: github.com/paladini/harness-score
Guide: paladini.github.io/harness-score

If you find a gap in the rubric or want to add checks for another ecosystem, issues and PRs are open.

Harness Engineering for Cursor: Measure Your AI Coding Maturity With One Command

Fernando Paladini — Sat, 11 Jul 2026 15:33:26 +0000

TL;DR — An AI coding agent is only as reliable as the harness around it: the rules, hooks, tests, and guardrails that steer and verify its work. harness-score is a free, open-source, 100% deterministic CLI (npx harness-score) that scans any repository, scores it across 6 dimensions, and reports a maturity level from L0 (Unharnessed) to L4 (Self-correcting). It ships with a full guide, a Cursor Marketplace plugin, and a GitHub Action — no model calls, no network, no telemetry.

The part of "AI coding" nobody measures

The conclusion both arrive at: reliability is a property of the model + harness + environment system, not of the model alone.

That raises an obvious question nobody had a straight answer to: how harnessed is my repository, actually?

What "harness engineering" means, concretely

A harness is everything around the model: the instructions it loads before acting, and the checks that verify what it did after. Fowler's framework splits this into two families:

	Guides (feedforward)	Sensors (feedback)
When	Before the agent acts	After the agent acts
Purpose	Steer toward good output	Catch and correct bad output
In Cursor	`AGENTS.md`, `.cursor/rules/`, skills, commands	tests, linters, type checkers, CI, hooks

The problem is that none of this is measured. Teams either have all of it, some of it, or none of it, and there was no quick way to know which — until now.

Introducing harness-score

harness-score is a CLI that answers that question in seconds:

npx harness-score

  Maturity: L2 · Guided   Score: 61/100 (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%

Level	Name	What it means
L0	Unharnessed	Agents rediscover the project every session; mistakes ship unless a human catches them
L1	Documented	A substantive `AGENTS.md` orients every session
L2	Guided	Scoped Cursor rules, skills/commands, basic hygiene
L3	Sensing	Tests, linter, types, and CI verify everything the agent does
L4	Self-correcting	Gate and feedback hooks close the loop at runtime

Every failed check comes with a one-sentence fix and a deep link into the full guide — so the output isn't just a grade, it's a to-do list.

The one design decision that matters most

What you get

The guide — 8 chapters covering the Guides/Sensors framework, the full Cursor harness surface, and the maturity model rubric in detail, free on GitHub Pages.
The CLI — harness-score, with JSON/markdown/badge output and a --min-level flag to gate CI.
A Cursor Marketplace plugin — a /harness-audit command plus a skill that fixes the gaps it finds, following the guide's recipes.
A GitHub Action — run the scan on every push, emit a maturity badge for your README.

Try it

npx harness-score                          # no install
npm install -g harness-score               # or install it
harness-score --min-level 3                # gate CI: fail below L3

Also published on GitHub Packages and JSR for Deno/Bun users.

FAQ

Does harness-score use AI to score my repository?
No. It is 100% deterministic — filesystem reads and config parsing only. No LLM calls, no network requests, no telemetry.

Is it free and open source?
Yes — MIT licensed, and the analysis runs entirely on your machine or in your CI.

Try it on your own repo

npx harness-score

Repo: github.com/paladini/harness-score · Guide: paladini.github.io/harness-score

If you find a gap in the rubric or want to add checks for another ecosystem, issues and PRs are open.

FOSSAI: An Open-Source Manifesto Against Digital Inequality — v0.1

Fernando Paladini — Wed, 27 Aug 2025 02:44:26 +0000

Humanity's growth over the last 200 years is undeniable, with advancements that have brought wealth and comfort to countless lives. However, this progress comes hand-in-hand with a growing problem: inequality. The gap between the richest and the poorest widens every day, and the global economic balance tilts further, concentrating power and privilege in the hands of a minority, the 1%. The vast majority, the 99%, are caught in a relentless race for resources and opportunities.

Facing this, many turn to radical solutions, but I believe true change comes from within the system itself. My vision is to use the system's own tools against it. Not to destroy it, but to reshape it into something more just and accessible. The goal is clear: to make life difficult for the powerful and easier for those who need it most.

Inequality manifests at every level of our society. It begins with access to basics - water, food, health - and extends to knowledge, our most precious asset. Technology, which should be a force for progress and democratization, has become a new battlefield where knowledge is commoditized. Tech giants like Microsoft, Google, Meta, Anthropic, and OpenAI dominate the development of cutting-edge AI models and solutions. Tools like GitHub Copilot, which boost developer productivity, are becoming privileges for those who can afford them.

The costs of using AI services worldwide continue to rise, creating a glaring situation of digital inequality in access to information, tools, and technology. Professionals and developers globally face a stark disparity in the cost of accessing the internet and AI services. One dollar in the United States is not the same as one dollar in Brazil, the Congo, South Africa, India, or Pakistan.
And this is the core of this manifesto. Technology, especially AI, must be a common good available to every citizen on the planet, not a commodity.

The FOSSAI Vision

FOSSAI - Free and Open Source Artificial Intelligence - is our answer. It is a call to action for all hackers, developers, and tech thinkers: use your privilege and resources to build a more equitable future.
While we have access to cutting-edge tools through our personal, student, or work accounts, we must channel our energy to create open-source, free, user-friendly, and locally-run AI technologies. The reasons are simple and clear:
Open-Source: So that everyone can audit, understand, and contribute. Knowledge cannot be proprietary. We won't reinvent the wheel; we will share what we create.
Free: So that access is not a barrier. Knowledge must be free.
Local: So that autonomy is in the user's hands. Our creations should not depend on paid services or the cloud, which often force us to surrender our data in exchange for use, or to pay for resources.

I believe in a world where AI is used to create products that offer an incredible experience without the need for a constant internet connection, subscription plans, or any chains to corporations, institutions, or governments. In a world where dependency on recurring digital services is the rule, this attitude is an act of resistance. It's a path to free ourselves from the control of corporations that use technology to separate us from each other and consolidate power.

A Call to Action

I dream of a world where it isn't necessary to pay for essential services. I dream of a world where I have total control over the applications I use and the equipment I own. I dream of a world where AI isn't a sea of subscription plans, and where if you don't have money, you don't lose access to technology.
And this dream becomes a reality with every shared line of code, every free AI tool, and every solution we put into practice.
What can you do to change the scales?