The tacit knowledge hidden in the code of existing features tacit knowledge into a structured specificationand thereby docs/기능별설명/{카테고리명}/{기능명}/ document it as topic-based md files in the folder. Overview.md serves as an index so the AI selectively loads only the documents it needs.
The core output of this skill is not a simple collection of documents, but an **as-is Context Pack (tacit knowledge→specification)** that is re-injected in later planning, implementation, and QA stages.
Advantages of topic-based separation — Why structured documents are more effective than the AI reading only code:
- Filenames serve as a search index → the AI infers content just by looking at filenames
- Selectively load only the needed documents via the document index table in Overview.md
- Flexibly adjust the number of files according to complexity (3-4 files for simple features, 8-12 files for complex features)
- With the TDD guide, the AI autonomously completes everything through testing
Position of this skill (workflow)
시나리오 B (기존 개선):
/peach-gen-feature-docs → Context Pack 폴더를 컨텍스트로 주입 → AI가 개요 기반 자동 탐색 → /peach-gen-spec → 구현
시나리오 B (소규모):
/peach-gen-feature-docs → Plan Mode → 직접 구현
For new features, use /peach-gen-spec directly (this skill is unnecessary)
## 핵심 개념
- 이 스킬의 본질은 **암묵지→명세서 변환**이다. 코드에 명시적으로 드러나지 않는 설계 근거, 비즈니스 결정, 히스토리를 구조화한다.
- **AI 자동 분석 + 개발자 대화형 추출**의 2단계 협업으로 동작한다. AI가 코드/Git에서 추출 가능한 것을 먼저 분석하고, 코드만으로 알 수 없는 것은 개발자에게 질문한다.
- 이 문서는 기존 기능의 현재 상태를 구조화한 **유지보수용 컨텍스트 자산**이다.
- 후속 세션에서는 `docs/기능별설명/{카테고리명}/{기능명}/` 폴더 자체를 컨텍스트로 주입하고, 개요.md의 문서 인덱스를 보고 작업에 필요한 문서만 선택 로드한다.
- 목적은 "코드를 대신하는 문서"가 아니라, 수정 범위 파악과 결정 맥락 보존, 테스트 완결을 빠르게 만드는 것이다.
## When to use
- 기존 기능 개선/수정 전 코드 위치와 내용을 as-is 문서화할 때 (주 용도)
- 신규 기능 구현 완료 후 재수정 가능성이 높은 핵심 기능을 선택적으로 문서화할 때
- 사용자가 "기능 문서화", "기능별 명세 만들어줘", "/peach-gen-feature-docs" 요청 시
> **신규 기능 추가** 시에는 `/peach-gen-spec`를 먼저 사용. 이 스킬은 기존 코드를 분석할 수 있을 때 유효하다.
## Input
- **카테고리명**: 상위 분류 폴더명 (예: 회원관리, 게시판, 결제)
- **기능명(한글)**: 기능 폴더명 (예: 로그인, 비밀번호-변경)
- **한 줄 설명**(선택): 개요.md 요약에 사용
## Workflow — 3계층 암묵지 추출 파이프라인
### 1단계: 폴더 생성
`docs/기능별설명/{카테고리명}/{기능명}/` — 카테고리 폴더가 없으면 자동 생성
### 2단계: 1계층 — AI 자동 분석
AI가 도구를 사용하여 코드와 이력에서 추출 가능한 정보를 자동 분석한다.
**코드 정적 분석**
- 모듈 구조, 파일 의존성, 패턴 파악 (Glob/Grep/Read)
- 암묵지 탐색 체크리스트 점검 (아래 섹션 참조)
**Git 고고학**
- 핵심 파일의 변경 빈도 확인 (`git log --oneline {파일} | wc -l`)
- co-change 패턴 확인 — 함께 변경되는 파일 = 암묵적 결합 (`git log --format=format: --name-only | sort | uniq -c | sort -rn`)
- 주요 변경 시점의 커밋 메시지에서 설계 근거 추출 (`git log --all --oneline {파일}`)
**주제별 md 파일 초안 생성** (복잡도에 따라 파일 수 유연 결정) — 아래 가이드 기반으로 AI가 분석한 내용을 채움
**분리 규칙:**
- 하나의 파일에 주제가 2개 이상 → 분리
- 파일명에 주제를 담아 AI가 파일명만으로 내용 추정 가능하게
- `{기능명}-개요.md`는 반드시 생성 (인덱스 역할)
- `{기능명}-TDD-가이드.md`는 단독 파일 유지 (테스트는 독립 관심사)
### 3단계: 2계층 — 개발자 대화형 추출 (CDM/ACTA 기반)
AI가 1계층 분석에서 "코드만으로 알 수 없다"고 판단한 항목을 개발자에게 질문한다.
CDM 프로브 질문 세트(아래 섹션)를 활용하여 AskUserQuestion으로 질문한다.
- 질문은 한 번에 3-5개씩 묶어서 효율적으로 진행
- 개발자 답변을 해당 문서 섹션에 반영
- "모르겠다" 또는 "해당 없음" 답변도 기록 (미확인 사항으로 표시)
### 4단계: 3계층 — 자기검증
AI가 생성된 문서를 재검토한다:
- **검증 질문**: "이 문서만 읽고 기능을 수정할 수 있는가?"
- 빠진 암묵지 식별 시 개발자에게 추가 질문
- 문서 간 상호참조 정합성 확인
### 5단계: 최종 문서 확정 + 후속 단계 안내
- 주제별 문서 최종 저장
- 후속 활용 지침 안내 (gen-spec 연계, Plan Mode 등)
## 암묵지 탐색 체크리스트
1계층(AI 자동 분석)에서 점검할 항목. 발견 시 문서에 기록하고, 코드만으로 이유를 알 수 없으면 2계층에서 개발자에게 질문한다.
**코드 레벨 (로직 문서용)**
- 하드코딩된 상수/매직넘버 → 왜 그 값인가?
- 방어적 코드(try-catch, 특정 에러만 처리) → 경험에서 나온 것인가?
- 주석의 TODO/FIXME/HACK → 의도적 기술부채인가?
- 다른 모듈 직접 import → 문서화 안 된 의존관계인가?
**데이터 레벨 (명세 문서용)**
- 사용되지 않는 컬럼/상태값 → 레거시인가, 예약인가?
- 복잡한 JOIN/서브쿼리 → 성능 이유인가, 비즈니스 이유인가?
**이력 레벨 (Git 고고학)**
- 변경 빈도가 높은 파일 → 복잡도/리스크 집중 지점
- 함께 변경되는 파일들(co-change) → 암묵적 결합 관계
## CDM 프로브 질문 세트
2계층(개발자 대화형 추출)에서 AskUserQuestion으로 물어볼 질문 템플릿:
1. "이 기능에서 가장 어려웠던 결정은 무엇인가요?"
2. "처음 설계와 달라진 부분이 있다면, 왜 바뀌었나요?"
3. "이 코드를 처음 보는 개발자가 놓칠 수 있는 함정은?"
4. "삭제하면 안 되는 코드나 설정이 있나요? 이유는?"
5. **(동적 질문)** AI가 1계층 분석에서 발견한 특이점을 기반으로 생성 — 예: "만약 [특이점]이 변경되면 어디에 영향이 가나요?"
> 5번은 고정 질문이 아니라, AI가 분석 중 발견한 것을 기반으로 동적 생성한다.
> 개발자가 "모르겠다"고 답하면 해당 항목을 문서에 "미확인 사항"으로 기록한다.
## 도구 사용
- **Read/Glob/Grep**: 코드 정적 분석, 모듈 구조 파악
- **Bash**: Git 고고학 (git log, git blame 등)
- **AskUserQuestion**: 2계층 개발자 대화형 추출
- **Write**: 문서 파일 생성
## 개요 템플릿 ({기능명}-개요.md)
1. Summary
{one-line description}
2. Overall flow
(list steps such as input → validation → save)
3. Related files (code)
| Category | Path |
|---|---|
| Controller (Koa) | api/src/modules/... |
| Service | api/src/modules/... |
| DAO | api/src/modules/... |
| Type | api/src/modules/.../types.ts |
| Store (Pinia) | front/src/modules/.../store.ts |
| Component (Vue) | front/src/modules/.../*.vue |
4. Document index
| Document | Key content | When to read |
|---|---|---|
| [{feature name}-processing-flow-xxx.md] | N conversion steps, branch conditions | Before modifying code |
| [{feature name}-error-codes.md] | List of N error codes | When adding error handling |
| [{feature name}-design-decisions.md] | Reason for force_xxx, background of yyy | Always before changing logic |
| [{feature name}-mapping-table-name.md] | Field mapping | When modifying the relevant table |
| ... | ... | ... |
| [{feature name}-TDD-guide.md] | N tests, how to run | When running tests |
## 주제별 문서 가이드
### 주제별 문서 유형과 네이밍
| 유형 | 파일명 패턴 | 예시 |
|------|-----------|------|
| 처리 흐름 | `처리흐름-{함수/기능명}.md` | `처리흐름-execConvert.md` |
| 에러 코드 | `에러코드.md` | - |
| 설계 결정 | `설계결정.md` | ADR 형식 유지 |
| 데이터 매핑 | `매핑-{테이블명}.md` | `매핑-tang-order.md` |
| 파싱 규칙 | `파싱-{대상}.md` | `파싱-주문옵션.md` |
| 상태/코드 | `상태코드-매핑.md` | - |
| 입력 데이터 | `입력-{형식}.md` | `입력-JSON-샘플.md` |
| TDD | `TDD-가이드.md` | 항상 단독 파일 |
### 분리 판단 기준
- 간단한 기능 (3-4파일): 개요 + 로직 + 명세 + TDD (합쳐도 됨)
- 복잡한 기능 (8-12파일): 주제별 세분화
- 기준: 하나의 파일이 100줄 초과 시 분리 고려
### 설계 결정 기록 (ADR 형식)
설계결정.md 또는 해당 주제 문서에 포함. 코드만 보면 알 수 없는 "왜"를 기록한다.
| 결정 | 맥락(Context) | 결정(Decision) | 결과(Consequences) |
|------|-------------|---------------|-------------------|
| 예시 | PG사 응답 평균 2.8초 | timeout을 3초로 설정 | 간헐적 타임아웃 발생 시 재시도 필요 |
AI가 코드를 수정할 때 기존 결정의 맥락을 이해해야 로직을 망가뜨리지 않는다. 예를 들어 "강제 변환 모드가 존재하는 이유"를 모르면 해당 분기를 제거하거나 변경할 수 있다.
## TDD-가이드 템플릿 ({기능명}-TDD-가이드.md)
섹션 구성:
1. 테스트 파일 목록
2. 실행 명령 (`bunx vitest run {경로}`)
3. 샘플 데이터 위치
4. Quick reference 표
## Reading existing feature docs (AI 지침)
- 진입: `{기능명}-개요.md`를 먼저 읽기
- 문서 인덱스 테이블에서 "읽을 때" 컬럼을 현재 작업과 비교
- 필요한 문서만 선택 로드
- 폴더 전체를 주입해도 AI가 개요 기반으로 자동 선택
## 후속 활용 지침
- `peach-agent-team`, `peach-agent-team-refactor`: 기존 기능 수정 맥락이면 해당 폴더를 작업 시작 컨텍스트로 선로드
- gen-spec 연계 시: Context Pack 폴더를 컨텍스트로 주입하면 AI가 개요를 진입점으로 필요한 문서를 자동 선택
- 수동 구현/분석: 관련 코드 전체를 다시 펼치기 전에 문서 폴더를 먼저 읽어 범위를 좁힘
## 규칙
- 경로는 저장소 루트 기준 (`api/src/modules/`, `front/src/modules/` 등).
- 카테고리명/기능명에 공백이 있으면 하이픈으로 대체 (예: `비밀번호 변경` → `비밀번호-변경`).
- **모든 파일명은 `{기능명}-{주제}.md` 형식** (예: `결제연동-개요.md`, `결제연동-TDD-가이드.md`).
- `{기능명}-개요.md`는 반드시 생성 (진입점 + 인덱스).
- `{기능명}-TDD-가이드.md`는 항상 단독 파일.
- 하나의 파일에 주제가 2개 이상이면 분리.
- 카테고리 폴더 예시: `회원관리`, `게시판`, `결제`, `상품`, `주문`, `정산`