harness-check

Harness Check Skill

개발 중간에 하네스 상태를 점검한다. 메인 Claude가 직접 진단하지 않는다 — 편향 방지를 위해 반드시 서브에이전트에게 위임한다.

실행 순서

0단계: 호출 방식 파악

스킬 호출 시 상황 설명(args)이 있는지 확인한다.

• args 없음: 표준 하네스 상태 점검만 수행
• args 있음 (예: /harness-check "연속 실패가 반복되고 있다"):
  • tasks/lessons.md를 읽어 "하네스 관련 패턴" 섹션을 확인한다
  • 섹션이 비어 있으면: 상태 점검만 수행하고 "아직 축적된 하네스 패턴이 없습니다" 안내
  • 섹션에 데이터가 있으면: 상황과 패턴을 매칭해 추천 후보를 메모해둔다 (3단계에서 출력)

---

1단계: harness-inspector 서브에이전트 진단

assets/agents/harness-inspector.md를 읽어 Agent 도구로 harness-inspector 서브에이전트를 생성한다.

서브에이전트에게 아래 정보를 함께 전달한다:

• 현재 프로젝트 루트 경로
• docs/ 경로
• .claude/ 경로
• 훅 스크립트 경로 (알고 있다면)
• 0단계에서 파악한 상황 설명 (있을 경우)

서브에이전트가 보고서를 반환하면 사용자에게 그대로 출력한다.

판정에 따른 분기:

• ✅ 정상 → "하네스 이상 없음. 개발 계속 진행 가능합니다." 출력 후 종료
• ⚠️ 또는 ❌ → 2단계 진행

---

2단계: 정밀 분석 + Upstream 수정 레포트

1단계에서 ⚠️ 또는 ❌가 나왔을 때 실행한다.

2-1. 정밀 분석

아래 두 에이전트를 병렬로 호출한다:

에이전트 A — claude-code-guide 에이전트 1단계 보고서를 전달하며 아래를 요청한다:

• 발견된 문제의 근본 원인이 무엇인지
• Claude Code 아키텍처 관점에서 올바른 수정 방향
• 유사한 패턴에서 알려진 best practice

에이전트 B — 서브에이전트 (general-purpose) 1단계 보고서와 현재 프로젝트의 관련 파일들을 전달하며 아래를 요청한다:

• 문제가 이 프로젝트에서만 발생하는 일회성인지, 템플릿 구조 문제인지 판단
• 수정이 필요한 경우: 어떤 파일의 어느 부분을 어떻게 바꿔야 하는지 구체적으로

2-2. Upstream 수정 레포트 작성

두 에이전트의 분석을 종합해서 아래 형식의 레포트를 docs/harness_fix_report.md에 저장한다.

이 레포트는 claude_skills 레포지토리에 그대로 적용 가능한 수준으로 작성한다. 추상적인 제안이 아니라 "어떤 파일의 몇 번째 줄을 어떻게 바꾼다"까지 명시한다.

# 하네스 수정 레포트

- **프로젝트**: [프로젝트명]
- **점검일**: YYYY-MM-DD (KST)
- **판정**: ⚠️/❌

---

## 발견된 문제 요약

| # | 문제 | 심각도 | 유형 |
|---|------|--------|------|
| 1 | | ❌/⚠️ | 일회성/템플릿 구조 |

---

## Upstream 수정 대상 (claude_skills 레포지토리)

> 아래 문제는 템플릿 구조에서 비롯된 것으로, claude_skills 레포에서 수정해야 한다.

### [문제 #N] 문제 제목

**영향 파일 (claude_skills 레포 기준)**
- `plugins/.../파일.md`

**현재 코드**
\```
[현재 코드]
\```

**수정 방향**
\```
[수정 후 코드]
\```

**수정 이유**: 한 줄 요약

---

## 이 프로젝트 내 즉시 조치 사항

> 템플릿 수정과 별개로 이 프로젝트에서 당장 해야 할 것들

- [ ] 조치 항목

---

3단계: 완료 보고

사용자에게 아래를 안내한다:

• 1단계 판정 결과 요약
• 2단계에서 도출된 upstream 수정 항목 수 (해당 시)
• docs/harness_fix_report.md 생성 위치 (해당 시)
• "claude_skills 레포지토리에 반영하려면 이 레포트를 가져가서 수정하시면 됩니다."

상황 기반 추천이 있을 경우 추가 출력:

## 하네스 추천 (lessons.md 기반)

상황: [사용자가 전달한 상황 설명]

매칭된 패턴:
- [날짜] [상황 유형]: [추가했던 하네스] → [효과]

추천:
- [구체적인 하네스 추가 제안]

※ tasks/lessons.md의 "하네스 관련 패턴" 섹션에 이번 결과도 기록해두세요.

패턴이 없거나 매칭이 불분명하면 추천 섹션을 출력하지 않는다.

---

주의사항

• 메인 Claude가 직접 파일을 읽고 판단하지 않는다 — 모든 진단은 서브에이전트가 수행
• harness-inspector는 발견만 한다. 수정은 하지 않는다
• Upstream 수정 레포트는 현재 프로젝트 docs/에 저장하되, claude_skills 레포 기준으로 작성
• 판정이 ✅면 2단계를 실행하지 않는다