JW's AI_Stash

SKILL

12 min read

기존 코드를 분석해 모듈 단위 기능명세서를 생성한다. Gemini CLI가 코드를 읽고 원시 데이터를 추출하면, Claude가 명세서 템플릿으로 정리한다. $ARGUMENTS에 대상 모듈 경로와 저장 경로(--path)를 지정할 수 있다.

STEP 1 — 대상 모듈 특정

  1. $ARGUMENTS 또는 사용자 메시지에서 대상 모듈 경로를 추출한다
    • 파일 경로, 폴더 경로, 클래스명, 모듈명 모두 가능
    • 명확하지 않으면 사용자에게 확인한다
  2. pwd로 현재 프로젝트 루트 확인
  3. 저장 폴더 = {프로젝트루트}/ai_history/code-spec/
  4. --path {경로} 인수가 있으면 해당 경로를 저장 폴더로 사용
  5. 저장 폴더가 없으면 mkdir -p로 생성

파일명 결정

  • 대상 모듈의 핵심 이름을 영문 kebab-case로 변환
  • 최종 파일명: {kebab-case-모듈명}.md
  • 이미 같은 이름의 파일이 존재하면 덮어쓰기 (최신 코드 기준으로 갱신)

대상 파일 목록 수집

  • 대상이 단일 파일이면 해당 파일 경로
  • 대상이 폴더면 Glob으로 내부 소스 파일 목록 수집 (*.ts, *.js, *.py, *.cs 등)
  • 수집된 파일 경로 목록을 STEP 2에서 Gemini CLI에 전달

STEP 2 — Gemini CLI로 코드 원시 분석

대상 모듈의 코드를 Gemini CLI에게 읽히고, 구조화된 원시 데이터를 추출한다.

모델 선택

기본: gemini-3.1-pro-preview (최신, 코드 분석에 최적) 실패 시: gemini-3-pro-preview → gemini-2.5-pro 순으로 폴백

실행 방법

대상 파일이 1~3개 (소규모):

gemini --model gemini-3.1-pro-preview --yolo -p \
  "아래 파일들을 읽고 분석해줘. 반드시 아래 출력 형식을 정확히 따라줘.
 
  대상 파일:
  $(for f in {파일경로1} {파일경로2}; do echo "- $f"; done)
 
  [분석 항목]
  1. 모듈 요약: 이 코드가 무엇을 하는가 (한 줄)
  2. 담당 도메인 / 비즈니스 영역
  3. 파일 구성: 각 파일의 역할 (한 줄씩)
 
  4. Public API 목록 (export/public 함수·메서드·클래스):
     각각: 이름 | 역할(한줄) | 파라미터(이름:타입) | 반환값 | 사이드이펙트(있으면)
 
  5. Internal 핵심 로직 (private/내부 함수 중 중요한 것):
     각각: 이름 | 역할(한줄) | 호출 조건
 
  6. 이벤트/훅 목록:
     각각: 이벤트명 | 발생 시점 | 핸들러 위치
 
  7. 호출 체인 (주요 시나리오별):
     - 정상 흐름: 함수A → 함수B → 함수C (각 단계 한줄 설명)
     - 에러 흐름: 함수A → 에러 → 처리 방식
 
  8. import 목록: 이 모듈이 가져오는 외부 모듈 (모듈명 | 용도 | import 위치)
 
  9. 공유 상태: 전역 변수, 이벤트 버스, DB 접근, 외부 API 호출 등
 
  10. 코드 패턴/규칙: 이 모듈에서 발견되는 암묵적 컨벤션이나 주의사항
 
  [출력 형식 — 반드시 이 구조로]
  ## RAW_SUMMARY
  (1~3번 내용)
 
  ## RAW_PUBLIC_API
  | 이름 | 역할 | 파라미터 | 반환값 | 사이드이펙트 |
  (4번 내용을 테이블로)
 
  ## RAW_INTERNAL
  | 이름 | 역할 | 호출 조건 |
  (5번 내용을 테이블로)
 
  ## RAW_EVENTS
  | 이벤트명 | 발생 시점 | 핸들러 위치 |
  (6번 내용을 테이블로, 없으면 '없음')
 
  ## RAW_CALL_CHAINS
  ### 정상 흐름
  (7번 정상 흐름)
  ### 에러 흐름
  (7번 에러 흐름)
 
  ## RAW_IMPORTS
  | 모듈명 | 용도 | import 위치 |
  (8번 내용을 테이블로)
 
  ## RAW_SHARED_STATE
  | 상태 | 종류 | 읽기/쓰기 |
  (9번 내용을 테이블로, 없으면 '없음')
 
  ## RAW_PATTERNS
  (10번 내용을 bullet으로)"

대상 파일이 4개 이상 (대규모 모듈):

# 파일 목록을 임시 파일로 생성
FILE_LIST=$(mktemp)
find {모듈경로} -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.cs" \) > "$FILE_LIST"
 
gemini --model gemini-3.1-pro-preview --yolo -p \
  "아래 파일 목록에 있는 모든 파일을 읽고 분석해줘.
  반드시 아래 출력 형식을 정확히 따라줘.
 
  파일 목록:
  $(cat $FILE_LIST)
 
  [분석 항목]
  (위와 동일한 10개 항목)
 
  [출력 형식]
  (위와 동일한 RAW_* 섹션 구조)"
 
rm "$FILE_LIST"

폴백: Gemini CLI 실패 시

Gemini CLI가 없거나 오류가 나면 Explore 에이전트로 전환한다. Explore 에이전트에게 위 10개 분석 항목을 전달하고 동일한 원시 데이터를 수집한다.

STEP 2-5 — 상위 의존자 탐색 (Claude 직접 수행)

Gemini CLI는 코드를 “읽는” 것에 특화되어 있으므로, 이 모듈을 import하는 외부 파일 탐색은 Claude가 Grep으로 직접 수행한다.

Grep: 모듈명 또는 파일명을 import/require하는 파일 탐색
→ 결과를 상위 의존자 테이블에 반영

이 작업은 STEP 2의 Gemini CLI 실행과 병렬로 수행할 수 있다.

STEP 3 — 명세서 작성 및 저장

STEP 2의 Gemini 원시 데이터 + STEP 2-5의 상위 의존자 정보를 합쳐 아래 템플릿으로 명세서를 작성한다.

date 명령으로 오늘 날짜를 확인한 뒤 Write로 파일을 생성한다.

작성 시 Claude의 역할:

  • Gemini의 원시 데이터를 검증하고 누락·오류를 보정
  • 수정 가이드(섹션 5)는 Claude가 원시 데이터를 바탕으로 직접 작성 (Gemini는 하지 않음)
  • Mermaid 다이어그램은 Claude가 호출 체인 데이터를 바탕으로 생성
  • Use Case 시나리오의 트리거/선행조건/결과는 Claude가 판단해서 보강
---
module: {모듈 경로}
generated: YYYY-MM-DD
generator: Claude Code + Gemini CLI (hybrid)
---
 
# {모듈명} 기능명세서
 
> {한 줄 요약}
 
---
 
## 1. 모듈 개요
 
| 구분 | 내용 |
|------|------|
| **경로** | `{모듈 경로}` |
| **도메인** | {담당 도메인} |
| **핵심 책임** | {이 모듈이 존재하는 이유} |
| **파일 구성** | {파일 목록 또는 구조 요약} |
 
---
 
## 2. 기능 명세
 
### 2.1 Public API
 
| 함수/메서드 | 역할 | 파라미터 | 반환값 | 사이드이펙트 |
|-------------|------|----------|--------|-------------|
| `functionName()` | 한 줄 설명 | `param: Type` | `ReturnType` | 없음 / 설명 |
 
### 2.2 Internal 핵심 로직
 
| 함수/메서드 | 역할 | 비고 |
|-------------|------|------|
| `_internalFn()` | 한 줄 설명 | 호출 조건 등 |
 
### 2.3 이벤트 / 훅
 
| 이벤트명 | 발생 시점 | 핸들러 위치 | 비고 |
|----------|-----------|------------|------|
| (없으면 이 섹션 생략) |
 
---
 
## 3. Use Case 시나리오
 
### 시나리오 1 — {정상 흐름 이름}
 
**트리거**: {어떤 상황에서 시작되는가}
**선행 조건**: {필요한 상태/데이터}
 
```mermaid
sequenceDiagram
    participant A as 호출자
    participant B as 이 모듈
    participant C as 의존 모듈
    A->>B: functionName(params)
    B->>C: dependency call
    C-->>B: result
    B-->>A: return value

결과: {최종 상태/출력}

시나리오 2 — {에러/예외 흐름 이름}

(동일 구조, 에러 케이스 기술)

4. 의존성 맵

4.1 하위 의존성 (이 모듈 → 외부)

모듈용도import 위치
module-name한 줄 설명파일명:라인

4.2 상위 의존자 (외부 → 이 모듈)

파일사용하는 기능호출 위치
파일명functionName()파일명:라인

4.3 공유 상태

상태종류읽기/쓰기비고
(전역 변수, 이벤트, DB 테이블 등 — 없으면 “없음”)
graph TD
    subgraph "상위 의존자"
        U1[파일1]
        U2[파일2]
    end
    subgraph "이 모듈"
        M[모듈명]
    end
    subgraph "하위 의존성"
        D1[의존1]
        D2[의존2]
    end
    U1 --> M
    U2 --> M
    M --> D1
    M --> D2

5. 수정 가이드

5.1 기능 추가 시

추가 유형수정 위치방법주의사항
새 public 메서드파일명{패턴 설명}{있으면 기재}
새 이벤트 핸들러파일명{패턴 설명}{있으면 기재}

5.2 기존 기능 변경 시

변경 대상영향 범위확인 필요 사항
functionName(){영향받는 파일/모듈}{깨질 수 있는 부분}

5.3 주의사항

  • {이 모듈에서 흔히 실수하기 쉬운 부분}
  • {암묵적 규칙이나 컨벤션}
  • {성능 민감 지점}

5.4 테스트 포인트

수정 영역확인해야 할 것방법
{영역}{확인 항목}{테스트 방법/명령}

---

## STEP 4 — 완료 보고

저장 후 사용자에게 다음을 알린다.

- 저장된 파일 전체 경로
- 모듈 한 줄 요약
- 주요 기능 수 (Public API N개, Internal M개)
- 상위 의존자 수 (이 모듈을 사용하는 파일 수)
- 수정 시 주의사항 핵심 1~2개
- 분석 방법: Gemini CLI / Explore 에이전트 (어느 쪽을 사용했는지)

---

## 참고 — work-plan 연동

이 스킬은 `work-plan` 스킬의 STEP 2-9에서 자동 호출될 수 있다.
자동 호출 시에는:
- STEP 1의 대상 모듈이 work-plan에서 전달됨
- STEP 4의 완료 보고는 생략 (work-plan이 통합 보고)
- 이미 `ai_history/code-spec/`에 해당 모듈 명세서가 존재하고,
  대상 모듈 파일의 최종 수정일보다 명세서가 최신이면 재생성하지 않고 기존 것을 사용

## ⛔ 중요 — 스킬 종료 규칙

명세서 작성 후 **반드시 여기서 멈춘다.**
코드를 수정하지 않는다. 명세서 파일 외에는 어떤 파일도 Edit/Write하지 않는다.

Graph View