peachsolution/peach-doc-feature

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으로 물어볼 질문 템플릿:

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 | ADR 형식 유지 | | 데이터 매핑 | 매핑-{테이블명}.md | 매핑-order-item.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-team-dev, peach-team-3a: 기존 기능 수정 맥락이면 해당 폴더를 작업 시작 컨텍스트로 선로드
• gen-spec 연계 시: Context Pack 폴더를 컨텍스트로 주입하면 AI가 개요를 진입점으로 필요한 문서를 자동 선택
• 수동 구현/분석: 관련 코드 전체를 다시 펼치기 전에 문서 폴더를 먼저 읽어 범위를 좁힘

규칙

• 경로는 저장소 루트 기준 (api/src/modules/, front/src/modules/ 등).
• 카테고리명/기능명에 공백이 있으면 하이픈으로 대체 (예: 비밀번호 변경 → 비밀번호-변경).
• 모든 파일명은 {기능명}-{주제}.md 형식 (예: 결제연동-개요.md, 결제연동-TDD-가이드.md).
• {기능명}-개요.md는 반드시 생성 (진입점 + 인덱스).
• {기능명}-TDD-가이드.md는 항상 단독 파일.
• 하나의 파일에 주제가 2개 이상이면 분리.
• 카테고리 폴더 예시: 회원관리, 게시판, 결제, 상품, 주문, 정산