compare-harness-effectiveness

name	compare-harness-effectiveness
description	baseline-report.json과 하네스 적용 후 작업 결과를 비교하여 하네스 효과를 수치화한다.
allowed-tools	Read Grep Glob Bash

하네스 효과 비교 분석

이 스킬의 목적

동일 작업의 before(baseline) / after(하네스 적용) 결과를 수치적으로 비교하여 하네스 도입 효과를 증명한다.

입력

• docs/harness-evaluation/baseline-report.json (collect-baseline-data 산출물)
• 하네스 적용 후 재작업된 PR/브랜치 정보
• 재작업 시 Claude Code 세션 정보 (아래 중 하나 이상):
  • 세션 ID (UUID 형식)
  • 세션 이름
  • 해당 작업의 프로젝트 경로

비교 절차

Step 1: 동일 작업 매칭

baseline의 각 task에 대해 하네스 적용 후 재작업 결과를 1:1 매칭한다. 매칭 기준: 동일한 original_request, 동일 base commit.

Step 1.5: after 세션 JSONL 파싱

재작업 세션 ID가 제공되면, baseline과 동일한 방식으로 after 세션 JSONL을 파싱하여 대화 흐름 데이터를 수집한다.

세션 데이터 위치: ~/.claude/projects/{프로젝트경로인코딩}/{sessionId}.jsonl

after 세션에서 추출할 항목:

• 사용자 메시지 수 (대화 턴 수)
• 추가 지시 횟수 (최초 요청 이후 사용자 메시지 중 추가 작업 지시)
• 재수정 요청 횟수 ("다시", "수정", "고쳐" 등 패턴 매칭)
• 에이전트 완료 선언 후 재수정 횟수
• 에이전트 질문 수

추출 명령은 collect-baseline-data Step 4의 JSONL 파싱 방법과 동일하다.

Step 2: 항목별 비교

각 task pair에 대해 아래를 계산한다.

출력 품질 지표:

지표	계산식	해석
리뷰 지적 감소율	(before 지적수 - after 지적수) / before 지적수 x 100	양수 = 개선
하네스 예방 적중률	before에서 "하네스 예방 가능"이었던 항목 중 after에서 실제로 발생하지 않은 비율	하네스가 실제로 문제를 예방했는가
fix 커밋 비율 변화	(before fix비율 - after fix비율)	양수 = 시행착오 감소
빌드 실패 감소율	(before 실패수 - after 실패수) / before 실패수 x 100	양수 = 개선
암묵적 제약 위반 제거율	before에서 발견된 implicit_constraints 중 after에서 위반하지 않은 비율	하네스가 암묵 지식을 명시화한 효과

운영 효율 지표 (세션 데이터가 있는 경우):

지표	계산식	해석
세션 수 변화	after 세션수 - before 세션수	음수 = 더 적은 세션으로 완료
사용자 거부/수정 감소율	(before - after) / before x 100	양수 = 에이전트 출력이 더 정확
방향 수정 감소율	(before - after) / before x 100	양수 = 에이전트가 올바른 방향 유지

대화 효율 지표 (세션 JSONL 파싱 기반):

지표	계산식	해석
대화 턴 절감률	(before 턴수 - after 턴수) / before 턴수 x 100	양수 = 더 적은 대화로 완성
추가 지시 제거율	(before 추가지시수 - after 추가지시수) / before 추가지시수 x 100	양수 = 최초 요청만으로 작업 완성에 가까워짐
재수정 요청 제거율	(before 재수정수 - after 재수정수) / before 재수정수 x 100	양수 = 에이전트가 한 번에 올바른 출력
완료후재수정 제거율	(before - after) / before x 100	양수 = "완료" 선언이 실제 완료와 일치
불필요질문 감소율	(before 불필요질문수 - after) / before x 100	양수 = 하네스가 사전 정보를 제공하여 질문 불필요

Step 3: 카테고리별 심층 분석

리뷰 코멘트 카테고리별로 before/after를 비교하여, 하네스가 어떤 유형의 문제를 잘 잡고, 어떤 유형에 효과가 없는지 파악한다.

카테고리	before 건수	after 건수	변화	하네스 기여 요인
convention_violation	N	M	-K	어떤 rule/skill이 예방했는가
architecture_violation	N	M	-K	어떤 rule이 예방했는가
...	...	...	...	...

"하네스 기여 요인"은 실제로 어떤 CLAUDE.md 항목, rule, skill이 해당 문제 예방에 기여했는지를 구체적으로 기록한다. 기여 요인이 없는데 개선된 경우, 모델 자체 능력 향상 가능성을 명시한다.

Step 4: 하네스 공백 분석

after에서도 여전히 발생한 리뷰 지적을 분석하여, 현재 하네스에서 커버하지 못하는 영역을 식별한다.

출력:

• 하네스가 예방하지 못한 문제 목록
• 각 문제에 대해 "어떤 종류의 rule/skill/hook을 추가하면 예방 가능한가" 제안
• "하네스로는 예방 불가능한 문제" (도메인 판단 필수) 목록

이 출력은 propose-next-harness-step skill의 입력으로 활용 가능하다.

출력

docs/harness-evaluation/comparison-report.json에 저장한다.

{
  "generated_at": "ISO 8601 timestamp",
  "task_comparisons": [
    {
      "task_id": "task-001",
      "original_request": "요청 원문",
      "difficulty": "moderate",
      "quality_metrics": {
        "review_comments": { "before": 8, "after": 2, "change_rate": -75 },
        "harness_prevention_hit_rate": 85.7,
        "fix_commit_ratio": { "before": 0.4, "after": 0.13, "change": -0.27 },
        "ci_failures": { "before": 2, "after": 0, "change_rate": -100 },
        "implicit_constraint_violation_eliminated": 100
      },
      "efficiency_metrics": {
        "sessions": { "before": 3, "after": 1, "change": -2 },
        "user_rejections": { "before": 3, "after": 0, "change_rate": -100 },
        "direction_corrections": { "before": 1, "after": 0, "change_rate": -100 }
      },
      "conversation_efficiency_metrics": {
        "total_turns": { "before": 24, "after": 8, "change_rate": -66.7 },
        "follow_up_instructions": { "before": 5, "after": 1, "change_rate": -80 },
        "revision_requests": { "before": 3, "after": 0, "change_rate": -100 },
        "completion_then_revised": { "before": 2, "after": 0, "change_rate": -100 },
        "unnecessary_questions": { "before": 3, "after": 0, "change_rate": -100 }
      },
      "category_breakdown": {
        "convention_violation": {
          "before": 3, "after": 0,
          "harness_contributor": ".claude/rules/swift-conventions.md"
        },
        "architecture_violation": {
          "before": 1, "after": 0,
          "harness_contributor": "Modules/Player/CLAUDE.md"
        }
      },
      "remaining_gaps": [
        {
          "issue": "에러 핸들링 누락",
          "harness_suggestion": "error-handling-policy rule 추가",
          "preventable": true
        }
      ]
    }
  ],
  "summary": {
    "total_tasks_compared": 0,
    "avg_review_comment_reduction": 0,
    "avg_harness_prevention_hit_rate": 0,
    "avg_fix_commit_ratio_improvement": 0,
    "avg_turn_reduction_rate": 0,
    "avg_follow_up_elimination_rate": 0,
    "avg_revision_elimination_rate": 0,
    "harness_coverage_gaps": [],
    "top_contributing_harness_files": []
  }
}

세션 데이터 가용성별 비교 전략

양쪽 세션 모두 있음 (최선)

3개 지표 카테고리 모두 비교한다:

• 출력 품질 지표 (PR/리뷰 기반)
• 운영 효율 지표 (세션 메타 기반)
• 대화 효율 지표 (세션 JSONL 파싱 기반)

before만 세션 있음 / after만 세션 있음

세션이 있는 쪽의 데이터만 절대값으로 기록하고, 없는 쪽은 git 기반 간접 추정값(data_source: "inferred_from_git")을 사용한다.

비교 가능한 항목만 비교하고, 비교 불가 항목은 "change_rate": null로 표기한다. 간접 추정값끼리의 비교는 "confidence": "low"를 명시한다.

양쪽 세션 모두 없음

conversation_efficiency_metrics 전체를 생략하고, 아래 대체 지표로 간접 비교한다:

대체 지표	계산식	해석
fix 커밋 비율 변화	(before fix비율 - after fix비율)	양수 = 시행착오 감소
총 커밋 수 변화	(before - after) / before x 100	양수 = 더 적은 커밋으로 완성
PR 작업 기간 변화	(before 기간 - after 기간)	양수 = 더 빠르게 완료
force push 변화	(before - after)	양수 = 큰 방향 수정 감소

이 경우 리포트에 아래를 명시한다:

• "session_data_available": false
• "comparison_mode": "git_proxy_only"
• "대화 효율 지표는 세션 데이터 없이 측정 불가. git 기반 간접 지표만 사용됨."

중요 규칙

• before 데이터가 null인 항목은 비교하지 않고 "데이터 없음"으로 표기한다.
• 간접 추정값(data_source: "inferred_from_git")과 직접 파싱값을 명확히 구분한다.
• 개선이 하네스 때문인지 모델 능력 때문인지 구분할 수 없는 경우, "하네스 기여 요인"에 구체적 파일을 매핑할 수 없으면 "불명확"으로 기록한다.
• 숫자를 부풀리지 않는다. 보수적으로 측정한다.