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

docs/기능별설명/{카테고리명}/{기능명}/

• 파일명이 검색 인덱스 역할 → 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 자동 분석

• 모듈 구조, 파일 의존성, 패턴 파악 (Glob/Grep/Read)
• 암묵지 탐색 체크리스트 점검 (아래 섹션 참조)

• 핵심 파일의 변경 빈도 확인 (

  git log --oneline {파일} | wc -l

  )
• co-change 패턴 확인 — 함께 변경되는 파일 = 암묵적 결합 (

  git log --format=format: --name-only | sort | uniq -c | sort -rn

  )
• 주요 변경 시점의 커밋 메시지에서 설계 근거 추출 (

  git log --all --oneline {파일}

  )

• 하나의 파일에 주제가 2개 이상 → 분리
• 파일명에 주제를 담아 AI가 파일명만으로 내용 추정 가능하게

• {기능명}-개요.md

  는 반드시 생성 (인덱스 역할)

• {기능명}-TDD-가이드.md

  는 단독 파일 유지 (테스트는 독립 관심사)

3단계: 2계층 — 개발자 대화형 추출 (CDM/ACTA 기반)

• 질문은 한 번에 3-5개씩 묶어서 효율적으로 진행
• 개발자 답변을 해당 문서 섹션에 반영
• "모르겠다" 또는 "해당 없음" 답변도 기록 (미확인 사항으로 표시)

4단계: 3계층 — 자기검증

• 검증 질문: "이 문서만 읽고 기능을 수정할 수 있는가?"
• 빠진 암묵지 식별 시 개발자에게 추가 질문
• 문서 간 상호참조 정합성 확인

5단계: 최종 문서 확정 + 후속 단계 안내

• 주제별 문서 최종 저장
• 후속 활용 지침 안내 (gen-spec 연계, Plan Mode 등)

암묵지 탐색 체크리스트

• 하드코딩된 상수/매직넘버 → 왜 그 값인가?
• 방어적 코드(try-catch, 특정 에러만 처리) → 경험에서 나온 것인가?
• 주석의 TODO/FIXME/HACK → 의도적 기술부채인가?
• 다른 모듈 직접 import → 문서화 안 된 의존관계인가?

• 사용되지 않는 컬럼/상태값 → 레거시인가, 예약인가?
• 복잡한 JOIN/서브쿼리 → 성능 이유인가, 비즈니스 이유인가?

• 변경 빈도가 높은 파일 → 복잡도/리스크 집중 지점
• 함께 변경되는 파일들(co-change) → 암묵적 결합 관계

CDM 프로브 질문 세트

1. "이 기능에서 가장 어려웠던 결정은 무엇인가요?"
2. "처음 설계와 달라진 부분이 있다면, 왜 바뀌었나요?"
3. "이 코드를 처음 보는 개발자가 놓칠 수 있는 함정은?"
4. "삭제하면 안 되는 코드나 설정이 있나요? 이유는?"
5. (동적 질문) 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

매핑-{테이블명}.md

매핑-tang-order.md

파싱-{대상}.md

파싱-주문옵션.md

상태코드-매핑.md

입력-{형식}.md

입력-JSON-샘플.md

TDD-가이드.md

분리 판단 기준

• 간단한 기능 (3-4파일): 개요 + 로직 + 명세 + TDD (합쳐도 됨)
• 복잡한 기능 (8-12파일): 주제별 세분화
• 기준: 하나의 파일이 100줄 초과 시 분리 고려

설계 결정 기록 (ADR 형식)

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개 이상이면 분리.
• 카테고리 폴더 예시:

  회원관리

  ,

  게시판

  ,

  결제

  ,

  상품

  ,

  주문

  ,

  정산