Module Review

이 스킬의 성격

• 대상: 변경분이 아니라 모듈이 밖으로 내놓는 공개 계약. 오래 방치된 설계 부채를 찾는 용도다.
• 속도보다 순서: 한 번에 전부 훑지 않는다. 모듈 하나씩, 사용자 확인을 받으며 나아간다.
• 수정하지 않는다: 리뷰 중 코드를 고치면 판단이 흐려지고 되돌리기 어려워진다. 발견은 전부 메모에 쌓고, 실제 수정은 리뷰가 끝난 뒤 별도 작업으로 한다.

판정 기준은 현재 SKILL.md 디렉터리의 references/coding-philosophy.md를 로드해 적용한다 (특히 8~11장). 이 스킬은 "무엇을 보는가"의 순서만 정하고, "무엇이 결함인가"는 철학 문서가 정한다.

Step 1 — 리뷰 대상과 순서 결정 [STOP]

1. 호출과 함께 경로가 주어졌으면 그 경로를, 없으면 레포 루트의 소스 디렉토리를 대상으로 삼는다.
2. 모듈·패키지를 나열하고 의존 방향 또는 데이터 흐름 순서로 정렬한다. (파이프라인이면 흐름 순, 계층 구조면 하위 계층부터. 의존이 없는 쪽에서 있는 쪽으로.)
3. 프로젝트에 아키텍처 문서가 있으면 읽고, 실제 디렉토리 구조와 어긋나는지도 함께 확인한다.
4. 순서를 사용자에게 제시하고 합의한다. 여기서 멈춘다.

Step 2 — 메모 파일 생성

저장 위치는 하드코딩하지 않는다. 프로젝트에 보고서 저장 규약이 있으면 그 위치, 없으면 {git 루트}/.private/(기존 private/(점 없음)가 있으면 그 폴더를 계속 쓰고, 둘 다 없으면 mkdir -p). 루트는 git rev-parse --show-toplevel로 판별. 파일명은 <저장위치>/module-review-{YYYYMMDD}.md.

문서 상단에 다음을 적는다:

• 리뷰 대상과 합의된 순서
• 적용할 공통 원칙 요약 (references/coding-philosophy.md 8~11장)
• "리뷰 중에는 수정하지 않는다. 전체 리뷰가 끝나면 여기 모인 항목을 실제 작업으로 진행한다."

Step 3 — 모듈 하나씩 점검 (반복)

각 모듈마다 아래 ①~⑦을 순서대로 본다. 결과를 메모에 append하고, 사용자 확인을 받은 뒤 다음 모듈로 넘어간다.

판정 규칙

• ②의 기준은 운영 코드 호출처 하나뿐이다. 테스트에서만 쓰인다는 것은 공개 유지의 근거가 되지 않는다. 반환 타입처럼 이미 출력 계약인 것만 예외. 하위 모듈만 보고 최상위·루트 패키지의 재노출을 놓치지 않는다.
• ④에서 비대칭이 곧 결함이다. 형제 요소(같은 인터페이스 구현체, 같은 모듈의 동급 함수) 중 하나만 검증이 빠져 있으면 취향 차이가 아니라 결함으로 기록한다.
• 검증 수단은 대상 레포의 관례를 먼저 찾아 따른다. 프로젝트가 전용 검증 유틸을 정해뒀다면 그것을 기준으로 삼고, 특정 언어의 문법을 강요하지 않는다.
• ⑥에서 테스트가 0개인 모듈은 구조적 원인을 먼저 찾는다. "테스트 추가 필요"로 끝내지 않는다. 조건부로 skip되는 테스트(자격증명·외부 환경 의존)는 있어도 없는 것으로 센다.
• ⑦에서 각 테스트가 프로덕션 코드를 실제로 호출하는지 확인한다. 공식을 복붙해 자기 자신과 비교하는 테스트는 통과해도 아무것도 증명하지 못하므로 결함으로 기록한다.

기록 규칙

지적마다 반드시 포함한다:

• 파일경로:라인
• 실패 시나리오 — 어떤 입력·상태에서 어떤 잘못된 결과가 나오는가
• 수정 방향 (구현하지는 않는다)

실패 시나리오를 쓸 수 없으면 그 지적은 취향이므로 뺀다. "이미 잘 되어 있다" 같은 확인 항목도 넣지 않는다 — 메모는 나중에 실행할 항목의 목록이다.

Step 4 — 독립 검증

전 모듈 리뷰가 끝나면 독립적인 두 번째 읽기 패스로 두 가지를 수행한다. 서브에이전트 위임이 가능하면 메모 전체와 리뷰 대상을 넘겨 맡기고, 불가능하면 같은 체크리스트로 직접 다시 읽는다:

1. 기존 지적의 사실관계 재확인 — 인용한 파일·라인·동작이 실제와 맞는지, 과장이 없는지
2. 같은 방법론(①~⑦)으로 새 발견 추가 — 원 리뷰가 놓친 범위(최상위 패키지, 공용 인프라 모듈 등)

결과를 메모 상단에 별도 섹션으로 붙인다. 새 발견은 심각도를 표시한다.

Step 5 — triage 후 종료 [STOP]

메모 항목 전체를 아래 기준으로 분류해 사용자에게 제시하고 멈춘다.

메모의 모든 항목을 고치는 것이 목표가 아니다. 무엇을 안 할지 정하는 것도 리뷰의 결과다. 보류로 분류한 항목은 메모에 그렇게 표시해 다음 세션이 이어받게 한다.

수정 범위가 크면 성격별 독립 단위(PR 등)로 나누는 안을 함께 제시한다. 한 덩어리 변경은 리뷰가 불가능하다.

행동 원칙

• 모듈 하나를 마칠 때마다 멈추고 사용자 확인을 받는다 — 한 번에 전부 훑지 않는다
• 리뷰 중에는 코드를 수정하지 않는다. 발견은 전부 메모 파일로 간다
• 지적마다 파일경로:라인과 실패 시나리오를 쓴다. 못 쓰면 뺀다
• "잘 되어 있다"는 확인 항목은 메모에 넣지 않는다
• 판정 기준은 references/coding-philosophy.md를 로드해 적용한다 — 이 스킬이 기준을 새로 만들지 않는다
• 검증 수단·테스트 관례는 대상 레포의 것을 따른다 — 특정 언어·프레임워크를 전제하지 않는다
• Step 5에서 triage까지만 하고 멈춘다 — 수정은 별도 작업이다