두 팀이 동일한 모델을 사용하고 동일한 프롬프트(Prompt)를 작성하더라도 완전히 다른 결과를 얻을 수 있습니다.

그 차이는 종종 모델 때문이 아닙니다. 모델을 둘러싼 저장소(Repository) 때문입니다.

한 저장소는 에이전트에게 내구성 있는 지침, 범위가 지정된 규칙, 테스트, 린터(Linter), CI 피드백, 그리고 위험한 동작을 차단하는 훅(Hook)을 제공합니다. 반면 다른 저장소는 에이전트에게 README 파일 하나만 던져주고 결과가 좋기를 바랄 뿐입니다.

이러한 주변 제어 시스템이 바로 **하네스(Harness)**입니다.

Harness Score는 저장소가 실제로 그러한 시스템을 얼마나 갖추고 있는지 측정하는 무료 오픈 소스 결정론적 스캐너(Deterministic scanner)입니다. 이 도구는 Cursor, Claude Code, Windsurf, Cline, Continue, Codex, Copilot 및 기타 도구 전반에 걸쳐 파일 시스템 증거를 확인합니다. 그런 다음 L0에서 L4까지의 성숙도 단계, 6개 차원에 걸친 점수, 그리고 다음에 개선해야 할 사항에 대한 순위 목록을 반환합니다.

LLM 호출 없음. 텔레메트리(Telemetry) 없음. 스캔 중 네트워크 액세스 없음. 동일한 커밋의 동일한 저장소는 동일한 결과를 생성합니다.

버전 1.0은 해당 모델을 안정화했습니다. 1.5 릴리스 시리즈는 이를 사용자 정의 가능한 점수 산정, 5가지 문서 언어, GitHub Marketplace Action, 공개 쇼케이스, 그리고 실제 오픈 소스 프로젝트를 대상으로 스캐너를 테스트하는 재현 가능한 연구 저장소를 갖춘 더 넓은 생태계로 변모시킵니다.

요약 (TL;DR)

1.0 이후, Harness Score에 추가된 사항은 다음과 같습니다:

• 영어, 브라질 포르투갈어, 스페인어, 중국어 간체, 힌디어로 제공되는 전체 가이드
• .harness-score.json을 통한 리포지토리 레벨 (Repository-level) 설정
• 리포지토리 및 로컬 하네스 (Harness)를 위한 성숙도 (Maturity) 및 효과성 (Effective) 점수의 이중 산출
• 보호된 보안 체크를 포함한 커스텀 프리셋 (Presets) 및 체크별 규칙
• 출시된 GitHub Marketplace Action
• 증거 기반의 Harness Maturity Showcase
• 재현 가능한 Harness Maturity Analysis
• 실제 환경의 훅 (Hook) 경로, 생태계 탐지, 게시, 보고 및 UI 문제 수정

현재 릴리스를 사용해 보세요:

npx harness-score@1.5.1

Harness Score가 해결하는 문제

AI 코딩 도구들은 코드를 생성하는 능력이 점점 더 좋아지고 있습니다. 하지만 유능한 모델이라 할지라도, 당신이 해당 지식을 인코딩(Encode)하지 않는 한 당신의 아키텍처, 릴리스 프로세스, 위험한 명령어, 또는 "완료"에 대한 정의를 알지 못합니다.

팀들은 보통 다음과 같은 요소들을 점진적으로 추가합니다:

• AGENTS.md, CLAUDE.md 또는 그에 상응하는 컨텍스트 (Context)
• 범위가 지정된 규칙 (Scoped rules) 및 재사용 가능한 기술 (Skills)
• 테스트 (Tests), 타입 체크 (Type checking), 린팅 (Linting) 및 포매팅 (Formatting)
• CI 게이트 (CI gates)
• 안전하지 않은 명령어를 차단하거나 즉각적인 피드백을 제공하는 훅 (Hooks)
• 안전한 비밀값 (Secret) 및 MCP 설정

문제는 가시성 (Visibility)입니다. 측정 도구가 없다면, 팀은 어떤 부분이 존재하는지, 무엇이 누락되었는지, 또는 풀 리퀘스트 (Pull request)가 중요한 가드레일 (Guardrail)을 조용히 제거했는지 여부를 알 수 없습니다.

Harness Score는 이러한 파일들을 결정론적인 진단 결과로 변환합니다:

Maturity: L3 · Sensing
Score: 86/108
To reach L4: add a gate hook and feedback hook

이 도구는 당신의 코드가 좋은지 또는 모든 규칙이 올바른지를 판단한다고 주장하지 않습니다. 대신 에이전트 (Agent)를 가이드하고 검증하는 인프라가 존재하는지를 측정합니다. 이러한 좁은 범위 덕분에 결과는 CI에서 사용할 수 있을 만큼 충분히 재현 가능합니다.

1.0에서 1.5로: 변경 사항

1. 가이드가 이제 5개 언어를 지원합니다

Version 1.1에서는 영어, 브라질 포르투갈어, 라틴 아메리카 스페인어로 전체 가이드를 출시했습니다.

Version 1.2에서는 중국어 간체와 힌디어가 추가되었습니다.

이는 단순히 랜딩 페이지(landing page)만을 위한 번역이 아니었습니다. 가이드에는 성숙도 모델 (maturity model), 체크 카탈로그 (check catalog), 멀티 하네스 지원 (multi-harness support), 센서 (sensors), 가드레일 (guardrails), 그리고 조치 레시피 (remediation recipes)가 5개 언어 모두에 포함되어 있습니다.

하네스 엔지니어링 (Harness engineering)은 팀 단위의 관행입니다. 체크에 실패했을 때, 이를 수정할 책임이 있는 사람들이 그 이유를 이해할 수 있어야만 해당 실패가 의미를 갖습니다.

다국어 가이드 열기

2. .harness-score.json이 리포지토리 계약 (repository contract)이 되었습니다

Version 1.3에서는 리포지토리 전용 점수 (repository-only score)로는 정직하게 답할 수 없었던 질문에 대한 설정을 도입했습니다:

팀은 무엇을 커밋하며, 이 머신 위의 에이전트 (agent)는 실제로 무엇을 보고 있는가?

이제 스캐너는 두 가지 관점을 보고합니다:

리포지토리는 보수적인 CI 기본값을 변경하지 않고도 해당 스코프들을 활성화할 수 있습니다:

{
  "scopes": {
    "user": true,
...

Version 1.3.1에서는 Cursor, Claude Code, Windsurf, Cline, Continue, Codex, OpenCode, Zed 및 기타 지원되는 도구들이 사용하는 문서화된 글로벌 경로 전반에 걸쳐 사용자 스코프 (user-scope) 탐색 기능을 확장했습니다.

3. Version 1.5는 정직한 팀 맞춤 설정 (team customization)을 추가합니다

모든 체크 항목이 모든 조직에 적용되는 것은 아닙니다.

예를 들어, 회사의 정책이 리포지토리 로컬 훅 (repository-local hooks)을 금지할 수 있습니다. 이전에는 팀이 영구적인 페널티를 받아들이거나 성숙도 모델을 포크 (fork)해야 했습니다. 1.5 버전에서는 리포지토리가 해당 결정을 명시적으로 설명할 수 있습니다:

{
  "extends": ["no-hooks"],
  "rules": {
...

중요한 부분은 맞춤 설정이 어떻게 작동하느냐 하는 것입니다:

• 제외된 체크 항목은 획득 점수(earned points)와 가용 점수(available points) 모두에서 제거됩니다. 이는 무료 크레딧을 부여하지 않습니다.
• 모든 제외 사항은 터미널(terminal), 마크다운(Markdown), JSON, 그리고 액션(Action) 출력에 나타납니다.
• 프리셋(preset)이 다음 성숙도 단계(maturity level)에 필요한 차원(dimension)을 제거하는 경우, 보고서는 해당 단계를 **제한됨 (capped)**으로 표시하고 그 이유를 설명합니다.
• 노출된 자격 증명(credentials)을 탐지하는 체크 항목인 HYG-03, HYG-04, HYG-06은 절대 비활성화할 수 없습니다.

맞춤 설정(Customization)은 점수를 부풀리기 위한 숨겨진 방법이 아니라, 투명하고 검토 가능한 저장소 정책(repository policy)입니다.

v1.5.0 릴리스 노트를 읽어보세요.

GitHub Action이 이제 마켓플레이스에 출시되었습니다

현재 패치인 v1.5.1은 GitHub Marketplace에 해당 액션(Action)이 처음으로 게시되었음을 의미합니다.

최소한의 워크플로우(workflow)는 다음과 같습니다:

name: Harness maturity

on:
...

이 액션(Action)은 최소 성숙도 단계를 제한(gate)하고, GitHub 작업 요약(job summary)을 작성하며, 마크다운(Markdown) 및 SVG 배지(badge) 출력을 생성할 수 있습니다. 또한 선택적으로 점수 변경 사항이 포함된 고정된 풀 리퀘스트(pull request) 댓글을 유지할 수 있습니다.

공급망(supply-chain)의 안정성을 극대화하려면 액션(Action)을 전체 커밋 SHA(commit SHA)로 고정(pin)하십시오.

점수가 이제 공개된 증거를 바탕으로 뒷받침됩니다

스캐너(scanner)는 사람들이 자체 저장소 외부에서도 스캐너가 생성한 결과물을 검사할 수 있을 때 더욱 유용해집니다.

Harness Maturity Showcase는 공개된 증거를 바탕으로 하는 리더보드(leaderboard)입니다. 현재 다음 항목들을 포함하고 있습니다:

• harness-score@1.5.0으로 생성된 완전하고 재현 가능한 JSON 보고서가 포함된 21개의 고정된 저장소 (pinned repositories)
• 공개된 Harness Score 배지를 사용하는 20개의 커뮤니티 저장소 (community repositories)

숫자 순위는 전체 보고서가 포함된 항목만 포함합니다. 배지만 있는 항목은 성숙도 단계는 표시하지만, 임의의 숫자 점수를 만들어내지는 않습니다.

순위에 오른 모든 항목은 해당 증거와 측정된 커밋(commit)으로 연결됩니다. 목표는 낮은 점수를 받은 프로젝트를 비난하는 것이 아닙니다. 점수는 특정 저장소에 적용된 하네스(harness)를 설명하는 것이지, 그 뒤에 있는 사람이나 회사의 역량을 설명하는 것이 아닙니다.

Analysis 저장소는 모델 자체를 테스트합니다

Harness Maturity Analysis는 쇼케이스(showcase)의 이면에 있는 연구 계층(research layer)입니다.

이 저장소는 각 저장소(repository)를 특정 커밋(commit)에 고정하고, 스캐너(scanner) 버전을 고정하며, 원시 보고서(raw reports)를 저장하고, 해당 아티팩트(artifacts)로부터 리더보드(leaderboard)와 조사 결과(findings)를 생성합니다. 또한 자동화된 결과와 저장소 수준의 증거(evidence)를 비교하여 거짓 양성(false positives), 거짓 음성(false negatives)을 식별하고, 성숙도 모델(maturity model)이 잘 나타내지 못하는 범주를 분류합니다.

1단계(Phase 1)가 완료되었습니다. 21개의 모든 저장소가 harness-score@1.5.0으로 재스캔되었으며, 증거에 기반한 첫 번째 조사 결과가 공개되었습니다.

블라인드 인간 평가(blind human-rating) 단계가 여전히 계획되어 있으므로, 이 프로젝트는 모든 자동화된 수준이 인간의 판단과 일치한다고 아직 주장하지 않습니다.

그 차이가 중요합니다. Harness Score는 자신의 출력값을 정답(ground truth)으로 취급하지 않습니다. 분석 저장소는 모델이 변화해야 할 지점을 찾기 위해 존재합니다.

실제 저장소에서 실제 버그를 발견했습니다

1.0에서 1.5로 가는 과정에는 덜 화려하지만 중요한 수정 사항들도 포함되었습니다:

• Hook path resolution (훅 경로 해석): $CLAUDE_PROJECT_DIR/.claude/hooks/setup.sh와 같은 Claude Code 명령어가 참조된 스크립트가 커밋되어 있는 경우 더 이상 HKS-05 오류를 발생시키지 않습니다.
• Installed hook binaries (설치된 훅 바이너리): node_modules/.bin/ 아래의 명령어들이 누락된 저장소 파일이 아닌, 설치된 의존성 (dependencies)으로 인식됩니다.
• Ecosystem sensors (생태계 센서): Maven 테스트 및 Spotless 설정이 이제 카운트에 포함됩니다.
• Global harness paths (글로벌 하네스 경로): 사용자 범위 스캐닝 (User-scope scanning)이 Windsurf 및 Cline 별칭 (aliases)을 포함하여 더 많은 도구에서 사용되는 실제 위치를 인식합니다.
• Release reliability (릴리스 신뢰성): npm, JSR, CLI 및 Action이 일치하도록 패키지 메타데이터와 버전 동기화가 수정되었습니다.
• Reporting honesty (리포팅 정직성): 구성된 차원 (dimensions) 및 도달할 수 없는 성숙도 단계 (maturity levels)가 오해의 소지가 있는 백분율 대신, 적용 가능하고 제한된 메타데이터를 생성합니다.
• Documentation UI (문서 UI): 탐색, 다크 테마 대비, 제품 간 링크가 수정되었으며 쇼케이스와 일치하도록 조정되었습니다.

이러한 수정 사항 중 여러 개는 실제 프로젝트를 스캐닝하는 과정에서 직접 도출되었습니다. 이것이 제가 이 프로젝트를 통해 원하는 피드백 루프입니다: 스캔하고, 증거를 조사하고, 불일치를 찾아내고, 결정론적 규칙 (deterministic rule)을 수정하고, 코퍼스 (corpus)를 다시 실행하는 것입니다.

Screenshot: Harness Score 스캐닝 자체

Harness Score 저장소는 성숙도 모델 (maturity model)을 자체적으로 테스트 (dogfoods)하고 있으며, 현재 L4 · Self-correcting (자기 수정) 단계에 도달했습니다.

분석 저장소에서 다음 명령어를 실행하여 스크린샷 출력을 생성했습니다:

npx harness-score@1.5.1 D:\code\harness-score

결과:

harness-score v1.5.1  D:\code\harness-score

Maturity: L4 · Self-correcting   Score: 108/108 (100%)   scopes: repo
...

다음 단계: Product Hunt

저는 다음 주에 Product Hunt에서 Harness Score를 출시할 계획입니다.

Product Hunt 출시는 결승선이 아닙니다. 이는 더 많은 팀에게 도구를 선보이고, 더 많은 실제 저장소 증거를 수집하며, 성숙도 모델이 여전히 잘못되었거나 불완전한 부분을 발견하기 위한 방법입니다.

출시 전에 테스트한다면, 가장 가치 있는 피드백은 구체적이어야 합니다. 저장소(repository)를 공유하고, ID, 파일 경로를 확인하며, 결과가 왜 거짓 양성(false positive) 또는 거짓 음성(false negative)인지 공유해 주세요.

직접 사용해 보고 결과를 공유해 주세요

npx harness-score@1.5.1

그 다음 생태계를 탐색해 보세요:

• Harness Score repository
• Documentation
• GitHub Marketplace Action
• Harness Maturity Showcase
• Harness Maturity Analysis
• v1.5.1 release notes

여러분의 저장소는 어떤 레벨을 받았나요? 그리고 어떤 실패한 체크 항목이 가장 놀라웠나요? 두 가지 모두 댓글로 남겨주세요.