TL;DR — 저는 harness-score를 공개했습니다: AI 개발을 위한 저장소의 **harness 성숙도 (maturity of the harness)**를 측정하는 오픈 소스 CLI (Command Line Interface)입니다. 단 하나의 명령 (npx harness-score), 36가지 검사, 6가지 차원, L0–L4 레벨을 제공합니다. LLM (Large Language Model)을 사용하지 않으며, 텔레메트리 (telemetry)도 없습니다. 이미 CLI, 가이드, GitHub Action 및 README용 배지 (badges)를 갖추고 있습니다.

harness란 무엇이며 왜 측정해야 하는가

Harness engineering은 모델을 제외하고 코드 에이전트 (agent)와 관련된 모든 것을 의미합니다: AGENTS.md, 규칙 (rules), 기술 (skills), 테스트 (tests), CI (Continuous Integration), hooks — 즉, 에이전트가 행동하기 _전_에 가이드를 제공하고 행동한 _후_에 결과를 확인하는 모든 요소입니다.

Cursor, Claude Code 또는 기타 에이전트 도구 (agentic tools)를 사용하는 팀들은 이미 깨닫고 있습니다: 모델은 거의 주요 변수가 아닙니다. 저장소 (repository)가 주요 변수입니다.

실질적인 질문은 이것입니다: 내 저장소에는 이 중 얼마나 갖춰져 있으며, 무엇이 부족한가?

harness-score는 저장소를 스캔하여 객관적인 항목들을 확인합니다: 내용이 포함된 AGENTS.md가 있는가? 유효한 프론트매터 (frontmatter)를 포함한 .cursor/rules/가 있는가? CI 워크플로 (workflow)가 있는가? .env 파일이 .gitignore에 포함되어 있는가? 36개 항목 각각이 통과(pass) 또는 실패(fail) 판정을 받으며, 보고서에는 무엇이 부족한지와 이를 수정하는 방법으로 연결되는 링크가 나열됩니다.

당신의 저장소 수준을 확인하는 방법

흐름은 간단합니다:

1. 로컬에서 실행 (설치 불필요):

npx harness-score

1. 결과 읽기 — 현재 레벨, 차원별 점수, 그리고 다음 레벨로 올라가기 위해 필요한 사항을 확인합니다:

  harness-score v0.3.0  ~/meu-app

  Maturity: L2 · Guided   Score: 66/108 (61%)
...

1. 실패한 항목 수정 — 통과하지 못한 각 검사 항목은 무엇이 부족한지 한 문장으로 보여주며, 가이드에서 수정 방법을 안내합니다.

2. 레벨이 올라갈 때까지 다시 실행합니다.

6가지 차원에 걸친 36가지 결정론적 검사 (deterministic checks) (총 108점)가 수행됩니다:

• Context & Guides (20점) — AGENTS.md, 범위가 지정된 규칙 (rules with scope)
• Skills & Commands (17점) — 스킬 (skills), 명령어 (commands), 서브에이전트 (subagents)
• Hooks & Guardrails (14점) — 세션 중 차단 및 피드백 (blocks and feedback during the session)
• Sensors & Feedback (20점) — 테스트 (tests), 린터 (linter), 타입 (types), 포맷터 (formatter)
• CI Feedback (14점) — 파이프라인 (pipeline), 프리커밋 (pre-commit)
• Hygiene & Safety (23점) — 비밀 정보 (secrets), .env, 락파일 (lockfile), 라이선스 (license)

수준 (level)은 단순한 백분율이 아닙니다. 문서화가 잘 되어 있고 테스트가 전혀 없는 저장소는 L3에 도달할 수 없습니다. 루브릭 (rubric)은 각 단계마다 특정 요구 사항을 요구하기 때문입니다.

JSON 또는 markdown 형식의 보고서 (자동화에 유용함):

harness-score --json
harness-score --md harness-report.md

L0–L4 스케일: 각 수준의 의미

계단은 5단계로 구성됩니다. 각 단계는 이전 단계를 및 차원별 최소 목표치를 요구합니다:

L0 · Unharnessed

시작점입니다. AGENTS.md가 없고, 규칙이 없으며, 자동 검사가 없습니다. 에이전트는 작동하며 — 항상 작동하지만 — 매 세션마다 프로젝트를 처음부터 다시 발견해야 하며, 모든 오류는 누군가가 수동으로 발견해야만 멈춥니다. 대부분의 저장소가 여기서 시작합니다.

L1 · Documented

요구 사항: Context & Guides ≥ 40%.

실질적인 내용이 담긴 AGENTS.md (또는 그에 상응하는 파일)가 존재합니다: 프로젝트가 무엇인지, 어떻게 빌드하고 테스트하는지, 어떤 컨벤션 (conventions)을 따라야 하는지 등이 포함됩니다. 이는 0에서 벗어날 때 가장 높은 수익을 주는 단계입니다 — 하나의 파일로 모든 미래 세션에 대한 가이드를 제공합니다.

L2 · Guided

요구 사항: Context ≥ 60% · (Skills ≥ 30% 또는 Hooks ≥ 30%) · Hygiene ≥ 50%.

가이드에 구조가 생깁니다: 유효한 프론트매터 (frontmatter)를 가진 .cursor/rules/ 규칙, 절차적 지식 (procedural knowledge, skill, command 또는 subagent)의 시작, 또는 구성된 훅 (hooks)이 포함됩니다. 기본적인 위생 (hygiene)이 확보됩니다 — .env가 .gitignore에 포함되어 있으며, harness 파일에 자격 증명 (credentials)이 없습니다. 이제 harness는 코드와 함께 버전 관리됩니다.

L3 · Sensing

요구 사항: L2 및 추가 사항: Sensors ≥ 60% · CI ≥ 50%.

피드백 루프(feedback cycle)가 존재합니다. 에이전트가 실행할 수 있는 테스트, 린터(linter), 타입 체크(type checking), 그리고 매 푸시(push)마다 재검증하는 CI가 포함됩니다. 진정한 자동 수정(automatic correction)은 바로 여기서 시작됩니다. 에이전트는 결정론적 도구(deterministic tools)를 사용하여 자신의 작업물을 스스로 확인할 수 있으며, 파이프라인(pipeline)은 에이전트가 놓친 부분을 잡아냅니다. 많은 팀에게 L3는 AI를 활용한 개발이 더 이상 위험하게 느껴지지 않는 단계입니다.

L4 · Self-correcting

L3 요구 사항에 더해: Hooks ≥ 70% · 총점(total score) ≥ 80% 필요.

세션 중에 루프가 완성됩니다. 차단 훅(blocking hooks)은 파괴적인 동작을 방지하며, 피드백 훅(feedback hooks)은 매 편집마다 린트(lint)와 포맷팅(formatting)을 실행합니다. 6가지 차원이 모두 커버됩니다. 이제 오류가 발생하면 규칙, 훅, 테스트, 타입 체커, CI, 그리고 차단 장치를 모두 통과해야 하며, 대부분의 과정은 수동 개입 없이 이루어집니다.

스캐너가 AI를 사용하지 않는 이유

스캐너는 모델을 호출하지 않습니다. 오직 파일을 읽고 설정을 해석할 뿐입니다. 따라서 동일한 커밋에 대해 두 번 실행하면 점수는 동일합니다. 이 덕분에 CI에서 --min-level을 사용할 수 있습니다. 실행 간의 예기치 않은 변동 없이, 레벨이 떨어지면 파이프라인이 실패하도록 설정할 수 있습니다.

프로젝트 자체 저장소도 이 도구를 스스로 사용하고 있습니다: 파이프라인에 --min-level 4를 적용하여 **L4 (108/108)**를 달성했습니다.

파이프라인에 추가하는 방법

옵션 1 — 워크플로우(workflow)에서 직접 CLI 사용

jobs:
  harness:
    runs-on: ubuntu-latest
...

--min-level 3을 사용하면 저장소가 L3 미만일 경우 작업(job)이 실패합니다. 머지(merge)를 차단하지 않고 보고서만 생성하려면 0을 사용하세요.

옵션 2 — GitHub Action (권장)

Action은 스캔을 수행하고, SVG 배지(badge)를 생성하며, 레벨이 최소 기준 미만일 경우 빌드를 실패하게 만들 수 있습니다:

jobs:
  harness:
    runs-on: ubuntu-latest
...

Job 요약에는 수준 (level)과 차원 테이블 (dimension table)이 표시됩니다. PR 워크플로우 (workflows)에서 comment: 'true'를 설정하면, Action이 스코어(score)를 베이스 브랜치 (base branch)와 비교하여 댓글을 게시(및 업데이트)합니다. 이는 "이 PR에서 L2에서 L3로 상승함"과 같은 내용을 확인하는 데 유용합니다.

Action 문서: github.com/paladini/harness-score/tree/main/action

머지 (merge) 차단을 시작해야 할 시점

처음에는 측정만 수행하며 (min-level: '0'), 몇 주 동안 팀의 수준을 모니터링한 후 최소 기준을 높이십시오. AI로 시작하는 팀은 L2, 대부분의 팀에게는 합리적인 목표로 L3, 일상적으로 실제 훅 (hooks)을 사용하는 팀은 L4를 권장합니다.

README의 배지 (Badges)

두 가지 형식의 배지가 있습니다:

자동으로 업데이트되는 배지

CI가 감지된 수준에 따라 실행할 때마다 SVG를 재생성합니다. 다음 명령어로 생성하십시오:

harness-score --badge harness-badge.svg

파일을 게시하고 ( badges 브랜치에 커밋, 아티팩트 (artifact), 또는 저장소에 직접 게시) README에서 참조하십시오:

<img alt="Harness Score" src="https://raw.githubusercontent.com/<사용자>/<저장소>/badges/harness-badge.svg" height="20">

같은 라인에 있는 shields.io 배지들과 정렬되도록 항상 height="20"을 사용하십시오.

수준별 고정 배지

CI에 의존하고 싶지 않다면, 가이드에 호스팅되어 있거나 저장소로 복사할 수 있는 수준별 정적 SVG (badge-l0.svg … badge-l4.svg)를 사용하십시오:

<img alt="Harness Score L3" src="https://paladini.github.io/harness-score/maturity/badge-l3.svg" height="20">

수준이 올라가면 수동으로 업데이트하거나, 파이프라인 (pipeline)이 가동되면 자동 배지로 전환하십시오.

공유 카드 (Share card)

더 큰 시각적 요소(전체 레벨 이름 포함)를 사용하려면 card-l0.svg … card-l4.svg를 사용하십시오. 갤러리 및 임베드 (embed) 예시 (Markdown, HTML, iframe, JSX): embed snippets

이미 출시된 기능

• CLI — npx harness-score, --json, --md, --badge, --min-level
• 가이드 (Guide) — 8개 장: paladini.github.io/harness-score
• GitHub Action — 스캔 (scan), 배지 (badge), 최소 레벨에 따른 차단, PR에 선택적 댓글 작성
• 배지 (Badges) — 자동 필(pill) 형태 + 정적 L0–L4 + 공유 카드 (share cards)

마켓플레이스 (Marketplace) 미출시: Cursor 플러그인 (/harness-audit)은 리포지토리 (repo)에 존재하지만 아직 목록에 올라와 있지 않습니다. 현재 지원되는 경로는 CLI + 가이드입니다.

체험하기

npx harness-score

여러분의 리포지토리 (repository)에서 실행하여 레벨을 확인하고, README에 배지를 추가하십시오. 그리고 팀의 상황에 맞을 때, 레벨이 최소 기준 미만으로 떨어지면 빌드 (build)를 거부하도록 CI를 설정하십시오.

테스트해 보셨다면, 어떤 레벨이 나왔는지, 그리고 이 루브릭 (rubric)이 여러분의 일상적인 업무에 적합한지 알려주세요. 피드백과 PR (Pull Request)은 언제나 환영합니다.

링크 (Links)

• Repo: github.com/paladini/harness-score
• 가이드 (Guide): paladini.github.io/harness-score
• 검증 (Verifications): Measure & Improve
• 배지 (Badges): embed snippets