peach-gen-feature-docs — 기능별 명세 생성

기존 기능의 코드에 숨어 있는 암묵지(tacit knowledge)를 구조화된 명세서로 변환하여 docs/기능별설명/{카테고리명}/{기능명}/ 폴더에 주제별 md 파일로 문서화한다. 개요.md가 인덱스 역할을 하여 AI가 필요한 문서만 선택 로드한다. 이 스킬의 핵심 산출물은 단순 문서 묶음이 아니라, 이후 계획 수립과 구현, QA 단계에서 재주입하는 **as-is Context Pack (암묵지→명세서)**이다.

주제 기반 분리의 장점 — AI가 코드만 읽는 것보다 구조화된 문서가 효과적인 이유:

파일명이 검색 인덱스 역할 → AI가 파일명만 보고 내용을 추정
개요.md의 문서 인덱스 테이블로 필요한 문서만 선택 로드
복잡도에 따라 파일 수를 유연하게 조절 (간단한 기능 3-4파일, 복잡한 기능 8-12파일)
TDD 가이드로 AI가 테스트까지 자율 완결

이 스킬의 위치 (워크플로우)

시나리오 B (기존 개선):
  /peach-gen-feature-docs → Context Pack 폴더를 컨텍스트로 주입 → AI가 개요 기반 자동 탐색 → /peach-gen-spec → 구현

시나리오 B (소규모):
  /peach-gen-feature-docs → Plan Mode → 직접 구현

신규 기능은 /peach-gen-spec 직접 사용 (이 스킬 불필요)

핵심 개념

이 스킬의 본질은 암묵지→명세서 변환이다. 코드에 명시적으로 드러나지 않는 설계 근거, 비즈니스 결정, 히스토리를 구조화한다.
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으로 물어볼 질문 템플릿:

"이 기능에서 가장 어려웠던 결정은 무엇인가요?"
"처음 설계와 달라진 부분이 있다면, 왜 바뀌었나요?"
"이 코드를 처음 보는 개발자가 놓칠 수 있는 함정은?"
"삭제하면 안 되는 코드나 설정이 있나요? 이유는?"
(동적 질문) AI가 1계층 분석에서 발견한 특이점을 기반으로 생성 — 예: "만약 [특이점]이 변경되면 어디에 영향이 가나요?"

5번은 고정 질문이 아니라, AI가 분석 중 발견한 것을 기반으로 동적 생성한다. 개발자가 "모르겠다"고 답하면 해당 항목을 문서에 "미확인 사항"으로 기록한다.

도구 사용

Read/Glob/Grep: 코드 정적 분석, 모듈 구조 파악
Bash: Git 고고학 (git log, git blame 등)
AskUserQuestion: 2계층 개발자 대화형 추출
Write: 문서 파일 생성

개요 템플릿 (개요.md)

# {기능명} — 개요

## 1. 요약
{한 줄 설명}

## 2. 전체 흐름
(입력 → 검증 → 저장 등 단계 나열)

## 3. 관련 파일 (코드)
| 구분 | 경로 |
|------|------|
| 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. 문서 인덱스
| 문서 | 핵심 내용 | 읽을 때 |
|------|----------|---------|
| [처리흐름-xxx.md] | 변환 N단계, 분기 조건 | 코드 수정 전 |
| [에러코드.md] | N개 에러코드 목록 | 에러 처리 추가 시 |
| [설계결정.md] | force_xxx 이유, yyy 배경 | 로직 변경 전 반드시 |
| [매핑-테이블명.md] | 필드 매핑 | 해당 테이블 수정 시 |
| ... | ... | ... |
| [TDD-가이드.md] | 테스트 N개, 실행법 | 테스트 실행 시 |

주제별 문서 가이드

주제별 문서 유형과 네이밍

유형	파일명 패턴	예시
처리 흐름	`처리흐름-{함수/기능명}.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)

섹션 구성:

테스트 파일 목록
실행 명령 (bunx vitest run {경로})
샘플 데이터 위치
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는 반드시 생성 (진입점 + 인덱스).
파일명은 주제를 담아 AI가 파일명만으로 내용 추정 가능하게 (예: 에러코드.md, 매핑-tang-order.md).
TDD-가이드.md는 항상 단독 파일.
하나의 파일에 주제가 2개 이상이면 분리.
카테고리 폴더 예시: 회원관리, 게시판, 결제, 상품, 주문, 정산