# Module Review

> 모듈·패키지 단위로 공개 인터페이스와 구조를 순차 점검한다. "구조 점검", "모듈 리뷰", "인터페이스 점검", "아키텍처 리뷰", "패키지별로 하나씩 살펴보자", "공개 API 점검", "설계 검토" 같은 요청에 사용한다. 변경분(diff)이 아니라 **모듈이 밖으로 내놓는 계약**이 대상이며, 발견은 메모 파일에 모으고 코드는 수정하지 않는다.

- Skill: `gagip/module-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add gagip/module-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gagip/module-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: gagip (https://skillmd.com/u/gagip)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gagip/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하고,
**사용자 확인을 받은 뒤** 다음 모듈로 넘어간다.

| 순서 | 점검 | 방법 | 철학 |
|---|---|---|---|
| ① | 공개 표면 열거 | 모듈이 밖으로 내보내는 것을 전부 나열 | — |
| ② | public 최소화 | 각 심볼을 grep — **운영 코드** 호출처 0건이면 제거·비공개 후보 | 8장 |
| ③ | 시그니처 자기설명 | 이름·타입만으로 방향·단위·의미가 유추되는가 | 9장 |
| ④ | 계약 프로그래밍 | 사전/사후조건이 **일관되게** 있는가 | 1·2장 |
| ⑤ | 실패 방식 통일 | 같은 모듈에서 예외/빈 값 반환이 섞이지 않는가 | 5장 |
| ⑥ | 테스트 가능한 구조 | 의존성을 주입받는가 내부에서 만드는가 | 10장 |
| ⑦ | 테스트 커버리지·정직성 | 미검증 분기 열거 + 가짜 테스트 색출 | 6·11장 |

### 판정 규칙

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

### 기록 규칙

지적마다 반드시 포함한다:
- `파일경로:라인`
- **실패 시나리오** — 어떤 입력·상태에서 어떤 잘못된 결과가 나오는가
- 수정 방향 (구현하지는 않는다)

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

## Step 4 — 독립 검증

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

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

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

## Step 5 — triage 후 종료 [STOP]

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

| 분류 | 기준 |
|---|---|
| **Tier 1 (핵심)** | 실제 손실·오동작을 유발하거나, 잘못된 안심을 주는 것 (실제 버그, 가짜 테스트, 검증 불가능한 구조) |
| **Tier 2 (일관성)** | 컨벤션 위반·계약 누락·시그니처 모호함 — 지금은 안 터지지만 다음 버그의 토양 |
| **보류** | 파급 범위가 커서 별도 작업이 필요한 설계 변경, 런타임 영향 없는 정리·스타일 |

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

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

---

## 행동 원칙

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