두 명의 엔지니어. 동일한 모델. 동일한 작업.

한 리포지토리(repo)에는 AGENTS.md, 범위가 지정된 규칙(scoped rules), CI 내의 테스트, 그리고 에이전트가 실행하기 전에 rm -rf를 차단하는 훅(hooks)이 있습니다. 다른 리포지토리에는 지난 3월에 작성된 .cursorrules 파일과 감(vibes)뿐입니다.

결과는 판이하게 달랐습니다 — 모델은 변수가 아니었습니다.

2026년 초, Martin Fowler의 사이트는 이 관행에 이름을 붙였습니다: harness engineering (하네스 엔지니어링) — 코딩 에이전트가 운 좋게 결과물을 내는 것이 아니라 신뢰할 수 있는 결과물을 낼 수 있도록 적절한 컨텍스트(context), 규칙, 테스트 및 가드레일(guardrails)로 에이전트를 감싸는 것입니다. LangChain의 엔지니어링 블로그에서도 동일한 교훈을 정량적으로 보여주었습니다: 모델이 아니라 하네스(harness)를 개선하면 벤치마크 점수가 올라갑니다.

2026년 모든 팀이 직면한 실질적인 질문은 다음과 같습니다:

Cursor, Claude Code, Windsurf가 모두 서로 다른 설정 트리(config trees)를 읽고 있는 상황에서, 내 리포지토리는 얼마나 잘 하네싱(harnessed) 되어 있는가?

그것이 바로 harness-score가 답하는 내용입니다. 그리고 오늘 이 도구는 1.0.0 버전에 도달했습니다.

요약 (TL;DR)

• npx harness-score — 무료, 오픈 소스, MIT 라이선스, 런타임 의존성 없음
• 6가지 차원에 걸쳐 모든 리포지토리를 L0–L4 단계로 점수화 (108개 포인트, 36개 체크 항목)
• 멀티 하네스 (Multi-harness): Cursor, Claude Code, Windsurf, Cline, Continue, Codex, Copilot 등을 지원 — 단 한 번의 스캔으로 OR 의미론(OR semantics) 적용
• 100% 결정론적 (deterministic): LLM 미사용, 네트워크 미사용, 텔레메트리(telemetry) 미사용 — CI 게이트(CI-gateable) 적용 가능
• 1.0 = 안정적인 API: 유의적 버전(semver)에 따른 안정적 API (ID, JSON 형태, CLI 플래그 확인)
• CLI + 전체 가이드 + GitHub Action + README 배지 형태로 제공

1.0이 실제로 의미하는 것

이번 주요 업데이트는 파괴적 변경(breaking change)이 아닙니다. 만약 v0.6.0을 사용 중이었다면, 1.0.0으로 업그레이드해도 동일한 점수와 출력이 생성됩니다.

변경된 것은 **계약(contract)**입니다:

성숙도 모델의 진화(새로운 체크 항목, 총점)는 마이너 (minor) 버전에서 배포되며, --diff의 maturityModelChanged 플래그로 표시됩니다. 이를 통해 스키마가 조용히 깨지는 일에 대한 두려움 없이 CI를 제어할 수 있습니다.

세 개가 아닌 하나의 하네스: 멀티 툴 OR 의미론 (multi-tool OR semantics)

제가 처음 harness-score를 출시했을 때는 Cursor 우선 방식이었습니다. Cursor가 가장 풍부한 하네스 표면(.mdc 규칙, hooks, skills, subagents, MCP)을 노출했기 때문입니다. 그것은 올바른 시작점이었습니다.

하지만 실제 팀들은 도구 하나만을 선택하지 않습니다. 누군가는 Cursor를 사용하고, 누군가는 Claude Code를 사용하며, 누군가는 Windsurf를 사용합니다. 동일한 저장소(repo)에 세 개의 설정 트리(config trees)가 존재하는 셈입니다.

v0.4.0부터 스캐너는 **OR 의미론 (OR semantics)**을 사용합니다. 각 체크 항목은 "Cursor가 이것을 제공하는가?"가 아니라, "인식된 도구 중 어느 하나라도 이것을 제공하는가?"라고 묻습니다.

예시:

당신은 **하나의 하네스 (one harness)**를 구축하게 됩니다. 모든 도구는 자신이 이해할 수 있는 부분들을 상속받습니다.

그리고 v0.5.0부터는 두 번째 도구를 추가한다고 해서 점수가 낮아지는 일은 절대 없습니다. 여러 개의 hooks 설정이 존재하는 경우, 가장 많은 이벤트가 등록된 설정이 승리합니다.

보고서는 감지된 도구가 무엇인지 알려줍니다:

  harness-score v1.0.0  ~/my-app

  Maturity: L2 · Guided   Score: 70/108 (65%)
...

동일한 저장소. 두 개의 도구. 하나의 점수. 하나의 격차(gap) 목록.

성숙도 사다리 (The maturity ladder)

레벨은 단순히 총 퍼센트가 아니라 **차원 임계값 (dimension thresholds)**에 따라 결정됩니다. 테스트가 전혀 없는 아름다운 문서가 실수로 성숙한 것처럼 보일 수는 없습니다.

실패한 모든 체크 항목은 무엇이 누락되었는지 명시하며, 가이드에 있는 해결 방법(remediation recipe)으로 연결됩니다.

10초 만에 시도하기

npx harness-score

어떤 경로든 스캔하세요:

npx harness-score ./path/to/repo

기계 판독 가능 출력 (Machine-readable output):

harness-score --json > report.json

Markdown 보고서:

harness-score --md harness-report.md

README 배지 (README badge):

harness-score --badge harness-badge.svg

CI 게이트 (L3 미만일 경우 exit 1):

harness-score --min-level 3

시간에 따른 진행 상황 추적:

harness-score --json > baseline.json
# ... harness 개선 ...
harness-score --diff baseline.json

성숙도가 계속 상승하도록 CI 게이트 설정하기

최소한의 워크플로우 (Minimal workflow):

# .github/workflows/harness.yml
name: Harness Score
on: [push, pull_request]
...

PR 코멘트 포함 (선택 사항 — pull-requests: write 권한 필요):

      - uses: paladini/harness-score/action@main
        with:
          min-level: '3'
...

이 Action은 점수 변화량(예: L2 → L3)을 보여주는 고정 코멘트(sticky comment)를 PR에 직접 게시하고 업데이트합니다.

스캐너에 AI를 포함하지 않음 (의도적 설계)

스캐너는 파일 시스템을 읽고 설정을 파싱합니다. 그게 전부입니다.

LLM 호출 없음. 네트워크 요청 없음. 텔레메트리 (Telemetry) 없음. 당신의 노트북에서든 CI에서든, 동일한 레포지토리, 동일한 커밋, 동일한 점수가 영원히 보장됩니다.

AI 기반의 "이 레포지토리가 잘 설정된 것처럼 보이나요?"와 같은 도구는 더 똑똑하게 느껴질 수 있지만, 재현 불가능 (non-reproducible) 할 것입니다. 이를 통해 파이프라인을 제어하거나, 두 실행 결과를 비교(diff)하거나, 오늘의 80%가 다음 달에도 같은 의미를 갖는다고 신뢰할 수 없게 됩니다.

Harness 성숙도는 Fowler가 설명한 범주, 즉 파이프라인에 배치할 수 있는 계산 가능한 체크 (computational checks) 에 속해야 합니다.

이 프로젝트는 자체 모델을 직접 사용(dogfooding)합니다. harness-score 레포지토리는 L4 · 108/108 점수를 기록하며, CI에서 해당 레벨을 게이트로 설정합니다.

구성 요소 (What's in the box)

npm, GitHub Packages (@paladini/harness-score), 그리고 JSR에 게시되었습니다 — 모두 v1.0.0 릴리스부터 제공됩니다.

FAQ

Cursor가 필요한가요?
아니요. v0.4.0부터 Cursor, Claude Code, Windsurf, Cline, Continue, Codex, Copilot 등을 아우르는 동등한 아티팩트 (artifacts)들이 모두 계산에 포함됩니다. 유니버설 아티팩트 (Universal artifacts: 테스트, CI, 타입, .gitignore, lockfiles)는 도구와 관계없이 동일하게 점수가 매겨집니다.

코드 품질을 평가하나요?
아니요. 이 도구는 에이전트의 작업을 유도하고 검증하는 파일 및 설정인 **하네스 인프라스트럭처 (harness infrastructure)**를 측정합니다. 오래된 규칙은 새로운 규칙과 동일한 점수를 받습니다. 이것이 모든 결정론적 스캐너 (deterministic scanner)가 가진 정직한 한계입니다.

무료인가요?
네. MIT 라이선스입니다. 사용자의 로컬 머신이나 CI에서 실행할 수 있습니다.

다른 생태계를 위한 체크 항목을 기여할 수 있나요?
언제든 환영합니다 — 이슈 및 PR을 환영합니다. 체크 ID는 안정적인 공개 API이며, 새로운 체크 항목은 마이너 업데이트를 통해 배포됩니다.

실행해보고 당신의 레벨을 알려주세요

npx harness-score

댓글에 당신의 레벨을 남겨주세요 — 얼마나 많은 L0 레포지토리들이 "AI-native"인 척하고 있는지 궁금하네요.

링크:

• Repo: github.com/paladini/harness-score
• Guide: paladini.github.io/harness-score
• Multi-harness deep dive: guide/multi-harness
• Release notes: v1.0.0