---
name: harness-metrics
description: 에이전트 작업 효율 메트릭을 수집하고 분석합니다 — 차단 빈도, 패턴 분석, 개선 제안
---

<Purpose>
에이전트의 작업 패턴을 분석하여 하네스 효율을 개선합니다.
어떤 규칙이 자주 위반되는지, 에이전트가 어디서 막히는지 파악하여
컨벤션이나 스캐폴딩 개선에 활용합니다.
</Purpose>

<Use_When>
- "메트릭 보여줘", "harness metrics", "차단 통계"
- "에이전트 효율 분석", "어떤 규칙이 자주 위반돼?"
- "하네스 개선 포인트 알려줘"
</Use_When>

<Steps>
1. 로그 수집:
   - .ai-harness/logs/ 디렉토리에서 JSONL 파일들을 Read
   - 기간 지정 없으면 최근 7일 기본

2. 메트릭 계산:
   - **총 도구 사용 횟수**: 전체 이벤트 수
   - **차단 횟수/비율**: result가 'blocked'인 이벤트
   - **Hook별 차단 빈도**: 어떤 Hook이 가장 많이 차단했는지
   - **차단 패턴 TOP 5**: 가장 자주 차단된 명령/패턴
   - **시간대별 분포**: 언제 작업이 집중되는지
   - **재시도 성공률**: 차단 후 동일 도구 재시도 성공 비율

3. 트렌드 분석:
   - 일별 차단 비율 추이 (개선되고 있는지)
   - 새로 등장한 차단 패턴
   - 사라진 차단 패턴 (학습된 것)

4. 개선 제안:
   - 차단 비율 > 20%인 Hook → 규칙이 너무 엄격하거나, 컨벤션 문서 보강 필요
   - 동일 패턴 반복 차단 → 스캐폴딩/템플릿 추가 제안
   - 차단 0%인 Hook → 불필요한 Hook 정리 제안

5. 자동 컨벤션 개선 제안:
   - 동일 패턴 3회 이상 반복 차단 시:
     a. 해당 패턴의 올바른 사용법을 convention-{team}.md에 예시로 추가할 것을 제안
     b. 구체적인 추가 내용까지 작성하여 보여줌
     c. 사용자 승인 시 컨벤션 파일에 자동 반영
   - context-map.md가 30일 이상 미갱신 시:
     a. "컨텍스트 맵이 오래되었습니다. 갱신할까요?" 제안
   - 특정 레이어에서 반복 위반 시:
     a. /harness-scaffold 프리셋에 해당 레이어 예시 보강 제안

6. 출력 형식:
   ```
   [메트릭] 최근 7일 (2026-03-19 ~ 2026-03-25)

   도구 사용: 142회
   차단: 12회 (8.5%)
   재시도 성공: 9/12 (75%)

   [Hook별 차단]
     sql-review: 5회 (SELECT * 사용 3회, 바인딩 누락 2회)
     check-architecture: 4회 (Repository→Service 참조 4회)
     secret-scanner: 2회 (하드코딩 토큰)
     block-dangerous: 1회 (rm -rf)

   [트렌드]
     ✅ sql-review 차단 감소 추세 (일 3회 → 1회)
     ⚠ check-architecture 차단 증가 — 아키텍처 가이드 보강 권장

   [개선 제안]
     1. Repository→Service 참조가 반복됨 → 인터페이스 템플릿 추가 권장
     2. SELECT * 반복 차단 → convention-backend.md에 쿼리 예시 보강 권장
   ```
</Steps>