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

#cursor #ai #opensource #productivity

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.