harness-module-edit

Harness-Module-Edit Skill — 모듈 CLAUDE.md 부분 수정 + drift 점검

이미 생성된 {path}/CLAUDE.md 를 git diff 기반으로 갱신하거나, diff 가 없을 때 전체 코드 ↔ 문서 drift 를 점검한다. 다른 섹션은 사용자가 명시 선택하지 않는 한 절대 건드리지 않는다.

트리거

• /harness-module-edit {모듈} — Gradle path (:feature:home) / iOS target 명 (Home) / 디렉토리 경로
• /harness-module-edit — 편집 가능한 모듈 목록 표시
• decay hook 알림에서 안내된 경우

---

Step 1: 모듈 감지 + 인자 처리

1. shared/harness/module/module-detect.md 를 실행해 modules 배열 확보.

2. {path}/CLAUDE.md 가 존재하는 모듈만 editable_modules 로 좁힘.

3. editable_modules 가 0 개면 종료:

   편집 가능한 모듈 CLAUDE.md 가 없습니다.
   먼저 /harness-module 을 실행하세요.
   

4. 인자 분기:

   • 누락 → 표 출력 후 번호 또는 모듈명 입력 받기.
   • 있음 → skills/harness-module/SKILL.md 의 Step 4 "인자 정규화 / 인자 검증" 로직을 그대로 적용. 매칭 실패 시 editable_modules 목록 표시 후 종료.

매칭된 모듈을 target_module 로 확정.

---

Step 2: git diff 추출

base=$(git log -1 --format='%H' -- {path}/CLAUDE.md)
git diff $base..HEAD -- {path}

케이스	처리
git log 결과 비어있음 (한 번도 commit 안 됨)	git diff HEAD -- {path} 로 working tree 비교
diff 결과 비어있음	Step 3b (drift 점검 제안) 로 진행
diff 있음	Step 3a (자동추천) 로 진행

기준 시점은 Step 6 리포트용으로 짧은 형태 (%h (%ar)) 보존.

---

Step 3a: diff 있음 — 자동추천 + Q3 위반 점검

Q1/Q4 자동추천

변경 신호	매핑 섹션
진입 파일 / public API (.kt: public interface|class, top-level interface|class. .swift: public func, open class, public struct|protocol)	역할 (Q1)
선언 파일 의존성 (build.gradle(.kts) 의 implementation|api|project(":...") / Package.swift target dependencies)	의존성 (Q4)

import 문 변경은 무시.

Q3 위반 점검 (항상 수행)

diff 유무와 무관하게 항상 수행:

1. {path}/CLAUDE.md 의 ## 절대 하면 안 되는 것 (Q3) 본문에서 금기 키워드 추출.
2. 각 키워드의 핵심 토큰을 {path}/**/*.kt 또는 {path}/**/*.swift 에서 Grep.
3. Grep 매칭이 있다면, 실제 안티 패턴 사용 사례인지 LLM 이 코드 컨텍스트를 보고 판정.
4. 진짜 위반 발견 시에만 Q3 를 갱신 후보로 추가. 오버스펙(Q3 항목이 코드와 무관)만으로는 갱신 후보로 자동 등록하지 않음.

분기

• Q1/Q4 후보 + Q3 후보 합쳐서 ≥ 1 → Step 4 자동 추천 흐름.
• 합쳐서 = 0 (변경은 있으나 미매칭) → Step 4 5 섹션 메뉴 흐름.

---

Step 3b: diff 없음 — drift 점검 제안

{모듈명} 의 코드 변경사항이 없습니다.

코드 ↔ 문서 drift 점검을 할까요? [y/N]
  y — Q1(역할) / Q3(금지) / Q4(의존성) 전체 스캔
  N — 5섹션 메뉴에서 수동 선택

y → 전체 스캔 모드

Q1 (역할 / 진입 파일):

• 모듈 내 public 시그니처 상위 5 개를 current_signatures 로 수집.
• Q1 본문의 역할 주장과 비교. 어긋남 감지 시 갱신 후보.

Q3 (절대 하면 안 되는 것):

• Step 3a 의 Q3 위반 점검과 동일 로직.

Q4 (의존성):

• module-detect.md 의 depends_on 추출 절차를 target_module 1 개에만 적용해 current_depends_on 산출.
• Q4 본문의 "의존하는 모듈" 목록과 집합 비교.
• 차집합이 비어있지 않으면 갱신 후보.

분기:

• 갱신 후보 ≥ 1 → Step 4 자동 추천 흐름.
• 갱신 후보 = 0 → "변경 불필요" 출력 후 종료.

{모듈명} CLAUDE.md 는 현행 유지해도 됩니다.

자동 점검 결과 — drift 없음:
- 역할 (Q1): public 시그니처와 일치
- 절대 하면 안 되는 것 (Q3): 코드에서 위반 사례 미발견
- 의존성 (Q4): build 그래프와 일치

Q2 (표준 작업 흐름) / Q5 (명시되지 않은 규칙) 수정이 필요하면
5섹션 메뉴에서 직접 선택하세요: /harness-module-edit {모듈}

N → 5 섹션 메뉴

수정할 섹션을 직접 선택하세요 (다중 선택 가능, 콤마 구분):
  1) 역할 (Q1)
  2) 표준 작업 흐름 (Q2)
  3) 절대 하면 안 되는 것 (Q3)
  4) 의존성 (Q4)
  5) 명시되지 않은 규칙 (Q5)

번호 입력 — 빈 입력 시 종료:

---

Step 4: 새 초안 제안 + 섹션별 [y/N]

후보 섹션마다 반복:

1. shared/harness/module/module-claude-template.md 의 해당 자동 추론 절차로 새 초안 생성.

   • 역할 (Q1) → ## 자동 추론 가이드 (Q1 / Q4) 의 Q1 절차.
   • 의존성 (Q4) → 같은 가이드의 Q4 절차.
   • Q3 → ## 자동 추론 가이드 (Q2 / Q3 / Q5) 의 Q3 절차.
   • Q2 / Q5 → 같은 가이드의 해당 절차.

2. 기존 / 새 초안 나란히 출력 후 [y/N]:

   ## {섹션명}
   
   [기존]
   {현재 CLAUDE.md 의 해당 섹션}
   
   [새 초안]
   {자동 추론 결과}
   
   이 섹션을 새 초안으로 갱신할까요? [y/N]
   

3. y → 적용 대상. 빈 입력 또는 N → skip.

순회 후 적용 대상이 0 개면 Step 6 (수정 없이 리포트).

---

Step 5: 부분 수정 (Edit 도구)

{target_module.path}/CLAUDE.md Read → Edit 으로 H2 블록 단위 교체.

• 블록 단위: 선택된 섹션의 ## ... 헤더부터 다음 H2 헤더 (또는 파일 끝) 직전까지.
• 다른 섹션은 절대 수정하지 않음.

수정 후 wc -l {path}/CLAUDE.md 측정. 51 줄 이상이면 shared/harness/module/module-claude-template.md 의 ## 50 줄 한도 압축 규칙 적용.

---

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

Step 5 에서 1 개 이상 섹션이 실제로 수정된 경우에만 실행한다 (모두 skip 된 경우 본 단계도 skip).

1. shared/harness/module/verify-module-docs.md 를 Read tool 로 읽는다.
2. 다음 변수로 호출한다.
   • target_modules: [target_module] (단일 모듈).
   • mode: "edit".
3. 검증 모듈의 출력 포맷 / 사용자 선택 처리 (1 / 2 / 3) 를 그대로 따른다. cross-file 비교 시 루트 CLAUDE.md, MODULE_MAP, 루트 docs 도 참조한다.
4. 결과 (수정 반영 여부, 남은 이슈 수) 를 Step 6 완료 리포트에 반영한다.

---

Step 6: 완료 리포트

## /harness-module-edit 완료 리포트
- 대상 모듈: {모듈명}
- 대상 파일: {path}/CLAUDE.md
- 모드: {diff 기반 / drift 점검 / 수동 선택}
- diff 기준: {짧은 hash + 상대 시간 / 또는 "drift 전체 스캔" / "수동"}
- 수정한 섹션: {섹션 헤더 목록 / 또는 "없음 — 사용자가 모두 skip"}
- 검증: {Verify-Module-Docs 결과 — 통과 / N 건 자동 수정 / N 건 남음 / skip}

다음 단계:
  IDE 에서 검토 후 직접 commit. (모듈 CLAUDE.md 는 Hook 차단 대상 아님)
  원복: git checkout -- {수정 파일} 로 되돌릴 수 있습니다.