harness-module

Harness Module Skill — 모듈 단위 코드베이스 맵

루트 하네스가 이미 세팅된 프로젝트에서 모듈 단위 CLAUDE.md 를 생성하고, 전체 모듈을 한눈에 보는 docs/MODULE_MAP.md 인덱스를 만든다. 감지된 전체 모듈에 대해 full harness 문서를 일괄 생성한다. 중간 중단/재개를 progress 파일로 지원한다.

트리거

• /harness-module — 감지된 전체 모듈에 대해 full 초안 일괄 생성 → 요약표 → 승인
• /harness-module {모듈} — 지정 모듈만 처리 (단일 모듈 full 초안 + 카드 + 승인)

---

Step 1: 플랫폼 자동 감지

프로젝트 루트에서 아래 파일을 스캔한다.

• build.gradle 또는 build.gradle.kts 존재 → PLATFORM=Android
• *.xcodeproj 또는 *.xcworkspace 존재 → PLATFORM=iOS
• 둘 다 없으면 "Android / iOS 중 어떤 프로젝트인가요?" 질문

감지된 플랫폼을 이후 모든 단계에서 사용한다.

하네스 부재 확인은 Step 2 에서 자체적으로 수행한다.

---

Step 2: 하네스 부재 확인

Glob tool 로 핵심 7 종의 존재 여부를 확인한다.

• CLAUDE.md
• docs/PRD.md
• docs/ARCHITECTURE.md
• docs/ADR.md
• docs/TESTING.md
• docs/CONVENTIONS.md
• docs/SESSION.md

하나라도 부재하면 아래 메시지를 출력하고 즉시 종료한다.

모듈 맵을 만들기 전에 하네스 문서가 먼저 있어야 합니다.

먼저 /harness 를 실행해 하네스 문서를 생성하세요.
누락된 파일:
  - {실제 누락 파일 경로}

7 종 모두 존재하면 Step 3 으로 진행.

---

Step 3: 모듈 후보 자동 감지

shared/harness/module/module-detect.md 를 Read tool 로 읽고, 그 모듈의 ## 플랫폼별 모듈 감지 와 ## 모듈 메타정보 수집 절차를 순서대로 실행한다.

결과는 modules 배열로 들고 있는다. 각 항목은 { name, path, file_count, has_namespace, depends_on, dependents, has_readme, commit_count_3m, legacy_pair } 형태 — 이 필드들은 module-detect.md 가 정의한다. 본 SKILL 에서 다시 정의하지 않는다.

---

Step 4: 모듈 확인 + 사용자 확인

인자 분기

/harness-module 호출 시 인자가 있으면 단일 모듈 모드로 진입한다.

인자 정규화

입력값을 아래 순서로 정규화한다.

• Android: :feature:home 같은 Gradle path 형태를 정규형으로 사용.
  • 매칭 실패 시 feature/home, feature:home, :feature/home 등을 : 구분 정규형 (:feature:home) 으로 변환 시도.
• iOS: Home 같은 target 명을 정규형으로 사용.
  • 매칭 실패 시 디렉토리 경로 (Sources/Home) 의 마지막 컴포넌트를 target 명으로 변환 시도.

인자 검증

정규화된 인자가 Step 3 의 modules 배열의 name 필드와 매칭되는지 확인.

• 매칭 성공 → selected_modules = [매칭된 1 개] 로 확정. 아래 기본 흐름의 모듈 표 출력을 skip 하고 Step 5 로 진행.

• 매칭 실패 → 아래 메시지 출력 후 즉시 종료.

  '{입력값}' 모듈을 찾지 못했습니다.
  
  감지된 모듈:
    - :feature:home
    - :feature:profile
    - :core:network
    ...
  
  위 목록에서 모듈명을 다시 입력해 주세요.
  

인자 없음 (기본 흐름)

selected_modules 는 Step 3 에서 감지된 전체 모듈 이다.

사용자에게 모듈 표를 출력한다.

| # | 모듈 | 파일 | 수정3m | 의존 → | 의존 ← |
|---|------|------|--------|--------|--------|
| 1 | :core:core_socket   | 32 | 12 | 2 | 5 |
| 2 | :feature:home       | 42 | 14 | 3 | 1 |
| 3 | :core:util          |  3 |  0 | 0 | 0 |

전체 {n} 개 모듈에 대해 full harness 를 생성합니다.
진행할까요? [Y/n]

• Y (또는 빈 입력) → Step 5 로 진행.
• n → 즉시 종료.

---

Step 5~6: Progress 관리 + 초안 생성

shared/harness/module/module-draft.md 를 Read tool 로 읽고, 그 문서의 절차를 순서대로 실행한다.

• Progress 파일 관리 — progress 파일 생성/resume 처리. 인자 모드와 인자 없음 분기를 따른다.
• Batch Draft 생성 + 승인 — 전체 초안 일괄 생성 → 요약표 + 모듈 카드 → 사용자 선택 (Y/e/q/n) → 승인된 모듈 저장.

---

Step 7: 인덱스 생성

진입 조건은 두 가지다.

• (a) Step 5~6 의 모든 selected_modules 가 완료된 직후 → Step 7 자동 진행.

• (b) Interactive Fallback 에서 사용자가 N 으로 중단했고 1 개 이상 완료된 상태 → 중단 직후 한 번 묻는다.

  지금까지 완료된 모듈로 인덱스를 생성할까요? [y/N]
  

  y → Step 7 진행. 빈 입력 또는 N → Step 7 skip 하고 그대로 종료 (다음 /harness-module 호출 시 resume 분기에서 이어서 진행).

1. shared/harness/module/module-claude-template.md 의 ## docs/MODULE_MAP.md 인덱스 양식 대로 docs/MODULE_MAP.md 를 Write tool 로 생성/덮어쓰기 한다. 위험도와 문서 상태 컬럼을 포함한다. 행 정렬은 shared/harness/module/module-detect.md 가 반환한 모듈 순서를 그대로 보존한다.

---

Step 7.5: Verify-Module-Docs 자동 호출

Step 7 이 진행된 경우 (인덱스 생성 완료) 검증을 1 회 실행한다.

1. shared/harness/module/verify-module-docs.md 를 Read tool 로 읽는다.
2. 다음 변수로 검증 모듈을 호출한다.
   • target_modules: 이번 실행에서 생성/덮어쓴 모든 모듈 (Step 5~6 에서 - [x] 로 갱신된 항목).
   • mode: "create".
3. 검증 모듈의 출력 포맷 / 사용자 선택 처리 (1 / 2 / 3) 를 그대로 따른다.
4. 검증이 끝나면 결과 (수정 반영 여부, 남은 이슈 수) 를 Step 8 완료 리포트에 반영한다.

Step 7 이 skip 된 경우 (사용자가 인덱스 생성을 거절) 본 단계도 skip 한다.

---

Step 8: 완료 리포트

## /harness-module 완료 리포트
- 플랫폼: {Android / iOS / General}
- 감지 모듈: {n} 개
- 생성: {모듈 CLAUDE.md 경로 목록}, docs/MODULE_MAP.md
- 중단된 모듈: {있다면 목록 — 다음 /harness-module 호출 시 이어서 진행}
- 검증: {Verify-Module-Docs 결과 — 통과 / N 건 자동 수정 / N 건 남음 / skip}

다음 단계:
  사용자가 IDE 에서 검토 후 직접 commit/push 하세요.
  ※ 모듈 CLAUDE.md 와 docs/MODULE_MAP.md 는 자동 commit 차단 대상이 아닙니다 (후속 spec).
  원복: git checkout -- {생성 파일} 로 되돌릴 수 있습니다.