peach-doc-feature — 기존 기능 문서화
기존 기능의 코드에 숨어 있는 암묵지(tacit knowledge)를 구조화된 명세서로 변환하여 docs/기능별설명/{카테고리명}/{기능명}/ 폴더에 주제별 md 파일로 문서화한다. 개요.md가 인덱스 역할을 하여 AI가 필요한 문서만 선택 로드한다. 이 스킬의 핵심 산출물은 단순 문서 묶음이 아니라, 이후 계획 수립과 구현, QA 단계에서 재주입하는 as-is Context Pack (암묵지→명세서)이다.
주제 기반 분리의 장점 — AI가 코드만 읽는 것보다 구조화된 문서가 효과적인 이유:
- 파일명이 검색 인덱스 역할 → AI가 파일명만 보고 내용을 추정
- 개요.md의 문서 인덱스 테이블로 필요한 문서만 선택 로드
- 복잡도에 따라 파일 수를 유연하게 조절 (간단한 기능 3-4파일, 복잡한 기능 8-12파일)
- TDD 가이드로 AI가 테스트까지 자율 완결
이 스킬의 위치 (워크플로우)
시나리오 B (기존 개선, 변경 Spec 필요):
/peach-doc-feature → Context Pack 폴더를 컨텍스트로 주입 → AI가 개요 기반 자동 탐색 → /peach-gen-spec → 구현
시나리오 B (소규모):
/peach-doc-feature → Plan Mode → 직접 구현
신규 기능은 /peach-gen-spec 직접 사용 (이 스킬 불필요)핵심 개념
- 이 스킬의 본질은 암묵지→명세서 변환이다. 코드에 명시적으로 드러나지 않는 설계 근거, 비즈니스 결정, 히스토리를 구조화한다.
- AI 자동 분석 + 개발자 대화형 추출의 2단계 협업으로 동작한다. AI가 코드/Git에서 추출 가능한 것을 먼저 분석하고, 코드만으로 알 수 없는 것은 개발자에게 질문한다.
- 이 문서는 기존 기능의 현재 상태를 구조화한 유지보수용 컨텍스트 자산이다.
- 후속 세션에서는
docs/기능별설명/{카테고리명}/{기능명}/폴더 자체를 컨텍스트로 주입하고, 개요.md의 문서 인덱스를 보고 작업에 필요한 문서만 선택 로드한다. - 목적은 "코드를 대신하는 문서"가 아니라, 수정 범위 파악과 결정 맥락 보존, 테스트 완결을 빠르게 만드는 것이다.
When to use
- 기존 기능 개선/수정 전 코드 위치와 내용을 as-is 문서화할 때 (주 용도)
- 신규 기능 구현 완료 후 재수정 가능성이 높은 핵심 기능을 선택적으로 문서화할 때
- 사용자가 "기능 문서화", "기능별 명세 만들어줘", "/peach-doc-feature" 요청 시
신규 기능 추가 시에는 /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형식 (예:결제연동-개요.md,결제연동-TDD-가이드.md). {기능명}-개요.md는 반드시 생성 (진입점 + 인덱스).{기능명}-TDD-가이드.md는 항상 단독 파일.- 하나의 파일에 주제가 2개 이상이면 분리.
- 카테고리 폴더 예시:
회원관리,게시판,결제,상품,주문,정산