harness-check

Harness-Check Skill — 하네스 문서 진단

사용자가 에이전트 작업 결과에 불만이 있을 때, 하네스 문서(루트 + 모듈)를 조사해서 문서의 어떤 부분이 부족/잘못 가이드하고 있는지 진단하고, 이슈 파일로 기록한다.

코드를 다시 수정하는 것이 아니라, 에이전트가 왜 그런 결과를 냈는지 문서 원인을 찾는 skill이다.

트리거

• /harness-check {불만 사항} — 자연어로 문제를 설명
• /harness-check — 인자 없이 호출하면 불만 사항 입력 요청

예시:

• /harness-check ViewModel에서 GlobalScope를 계속 써
• /harness-check Room Entity에 @Parcelize를 자꾸 붙여

---

Step 1: 인자 확인

• 인자가 있으면 complaint 로 확정.
• 인자가 없으면 사용자에게 불만 사항을 질문:

어떤 부분이 불만족스러웠나요? 자연어로 설명해 주세요.
예: "ViewModel에서 GlobalScope를 계속 써", "Room Entity에 @Parcelize를 자꾸 붙여"

---

Step 2: 작업 대상 모듈 특정

1. git diff --name-only HEAD~3..HEAD 로 최근 변경 파일 목록 확보.
2. 변경 파일 경로에서 모듈 디렉토리 추론:
   • {path}/CLAUDE.md 가 존재하는 가장 가까운 상위 디렉토리를 모듈로 간주.
   • 루트 CLAUDE.md 만 해당하면 모듈 없음 (루트만 진단).
3. 모듈이 여러 개 감지되면 complaint 키워드와 변경 파일명을 대조해 가장 관련 높은 1개 선택.
4. 추론 불가 시 사용자에게 질문:

최근 변경에서 관련 모듈을 특정할 수 없습니다.
어떤 모듈에서 문제가 발생했나요?

결과: target_module (경로) 또는 null (루트만).

---

Step 3: 관련 하네스 문서 수집

아래 문서를 Read tool 로 읽는다. 존재하지 않는 파일은 건너뛴다.

루트 (항상):

• CLAUDE.md
• docs/PRD.md
• docs/ARCHITECTURE.md
• docs/ADR.md
• docs/TESTING.md
• docs/CONVENTIONS.md
• docs/SESSION.md
• docs/UI_GUIDE.md (존재 시)

모듈 (target_module 이 있을 때):

• {target_module}/CLAUDE.md

---

Step 4: 불만 사항 ↔ 문서 대조 분석

수집한 문서들을 complaint 와 대조하여 아래 4가지 판정 중 하나를 각 문서/섹션에 부여한다.

판정	의미	조건
가이드 누락	해당 주제에 대한 가이드가 아예 없음	complaint 의 핵심 키워드 (예: GlobalScope, @Parcelize) 가 어떤 문서에도 언급되지 않음
가이드 모호	언급은 있으나 구체적 지시가 부족	관련 키워드가 존재하지만 "금지/사용/선호" 등 명확한 방향 없이 나열만 됨
가이드 오류	가이드가 있으나 잘못된 방향으로 유도	문서가 complaint 의 문제 행동을 오히려 권장하거나 허용하고 있음
문서 문제 아님	가이드가 명확하고 올바름	문서에 정확한 가이드가 있는데도 에이전트가 따르지 않은 경우

분석 절차

1. complaint 에서 핵심 키워드 추출 (예: "GlobalScope" → GlobalScope, viewModelScope, lifecycleScope, coroutine scope).
2. 각 문서의 전체 텍스트에서 키워드 검색.
3. 매칭된 섹션의 맥락을 읽고 판정 부여.
4. 매칭 없는 경우 "가이드 누락" 판정.

---

Step 5: 진단 보고서 출력

보고서 포맷

## /harness-check 진단 결과

**불만 사항**: {complaint}
**대상 모듈**: {target_module 또는 "루트"}

### 진단

| 문서 | 관련 섹션 | 판정 | 설명 |
|------|----------|------|------|
| {파일명} | {## 섹션 헤더} | {판정} | {구체적 설명} |
| ... | ... | ... | ... |

---

Step 5.5: 이슈 파일 생성

진단 결과를 팀 리뷰용 이슈 파일로 저장한다.

파일명 규칙

docs/harness-issues/{YYYY-MM-DD}-{git-user}-{주제 slug}.md

• git-user: git config user.name 의 값 (소문자, 공백은 하이픈으로 치환).
• 주제 slug: complaint 에서 핵심 키워드를 kebab-case 로 축약 (2-3 단어).

예: docs/harness-issues/2026-05-26-yunje-globalscope.md

파일 내용

# {주제 요약}

- **날짜**: {YYYY-MM-DD}
- **작성자**: {git-user}
- **불만 사항**: {complaint}
- **대상 모듈**: {target_module 또는 "루트"}

## 진단

| 문서 | 관련 섹션 | 판정 | 설명 |
|------|----------|------|------|
| {파일명} | {## 섹션 헤더} | {판정} | {구체적 설명} |

디렉토리 처리

• docs/harness-issues/ 가 없으면 생성한다.
• 팀 리뷰 후 하네스 수정이 완료되면 해당 이슈 파일을 삭제한다.

---

Step 6: 완료 리포트

## /harness-check 완료

- 진단 대상 문서: {N}개
- 발견 이슈: 가이드 누락 {n}, 가이드 모호 {n}, 가이드 오류 {n}, 문서 문제 아님 {n}
- 이슈 파일: docs/harness-issues/{파일명}.md 에 저장됨

이슈 파일을 저장했습니다.
팀원들과 협의 후 /harness-edit 또는 /harness-module-edit 로 수정하세요.
해결된 이슈 파일은 삭제하면 됩니다.