peach-doc-feature

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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가 테스트까지 자율 완결

将隐藏在现有功能代码中的隐性知识(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 직접 사용 (이 스킬 불필요)

场景B（现有功能改进，需变更规格）：
  /peach-doc-feature → 注入Context Pack文件夹作为上下文 → AI基于概述自动检索 → /peach-gen-spec → 开发

场景B（小规模）：
  /peach-doc-feature → Plan Mode → 直接开发

新功能请直接使用/peach-gen-spec（无需本技能）

핵심 개념

核心概念

이 스킬의 본질은 암묵지→명세서 변환이다. 코드에 명시적으로 드러나지 않는 설계 근거, 비즈니스 결정, 히스토리를 구조화한다.
AI 자동 분석 + 개발자 대화형 추출의 2단계 협업으로 동작한다. AI가 코드/Git에서 추출 가능한 것을 먼저 분석하고, 코드만으로 알 수 없는 것은 개발자에게 질문한다.
이 문서는 기존 기능의 현재 상태를 구조화한 유지보수용 컨텍스트 자산이다.
후속 세션에서는
```
docs/기능별설명/{카테고리명}/{기능명}/
```
폴더 자체를 컨텍스트로 주입하고, 개요.md의 문서 인덱스를 보고 작업에 필요한 문서만 선택 로드한다.
목적은 "코드를 대신하는 문서"가 아니라, 수정 범위 파악과 결정 맥락 보존, 테스트 완결을 빠르게 만드는 것이다.

本技能的本质是隐性知识→规范文档的转换。将未在代码中明确体现的设计依据、业务决策、历史信息进行结构化处理。
采用AI自动分析 + 开发者交互式提取的两步协作模式运行。AI先分析可从代码/Git中提取的信息，对于仅通过代码无法得知的内容，则向开发者提问。
本文档是对现有功能当前状态进行结构化处理的维护用上下文资产。
在后续会话中，将
```
docs/功能说明/{分类名}/{功能名}/
```
文件夹本身作为上下文注入，AI将根据
```
概述.md
```
的文档索引选择加载工作所需的文档。
目标并非“替代代码的文档”，而是快速实现修改范围确认、决策上下文留存、测试完整性保障。

When to use

使用时机

기존 기능 개선/수정 전 코드 위치와 내용을 as-is 문서화할 때 (주 용도)
신규 기능 구현 완료 후 재수정 가능성이 높은 핵심 기능을 선택적으로 문서화할 때
사용자가 "기능 문서화", "기능별 명세 만들어줘", "/peach-doc-feature" 요청 시

신규 기능 추가 시에는
/peach-gen-spec
를 먼저 사용. 이 스킬은 기존 코드를 분석할 수 있을 때 유효하다.

在现有功能改进/修改前，将代码位置和内容以as-is形式文档化时（主要用途）
新功能开发完成后，对后续修改可能性高的核心功能进行选择性文档化时
用户提出「功能文档化」「制作功能规格说明」「/peach-doc-feature」请求时

新增功能时，请先使用
/peach-gen-spec
。本技能仅在可分析现有代码时有效。

Input

输入

카테고리명: 상위 분류 폴더명 (예: 회원관리, 게시판, 결제)
기능명(한글): 기능 폴더명 (예: 로그인, 비밀번호-변경)
한 줄 설명(선택): 개요.md 요약에 사용

分类名：上级分类文件夹名称（示例：会员管理、论坛、支付）
功能名（韩文）：功能文件夹名称（示例：登录、密码-修改）
一句话说明（可选）：用于
```
概述.md
```
的摘要

Workflow — 3계층 암묵지 추출 파이프라인

工作流 — 三层隐性知识提取流水线

1단계: 폴더 생성

第一步：创建文件夹

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

— 카테고리 폴더가 없으면 자동 생성

docs/功能说明/{分类名}/{功能名}/

— 若分类文件夹不存在则自动创建

2단계: 1계층 — AI 자동 분석

第二步：第一层 — 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
```
는 단독 파일 유지 (테스트는 독립 관심사)

AI使用工具自动分析可从代码和历史中提取的信息。

代码静态分析

模块结构、文件依赖、模式识别（Glob/Grep/Read）
隐性知识检索清单检查（参考下方章节）

Git考古

核心文件的变更频率检查 (
```
git log --oneline {파일} | wc -l
```
)
共同变更模式确认 — 一起变更的文件 = 隐性耦合 (
```
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 기반)

第三步：第二层 — 开发者交互式提取（基于CDM/ACTA）

AI가 1계층 분석에서 "코드만으로 알 수 없다"고 판단한 항목을 개발자에게 질문한다. CDM 프로브 질문 세트(아래 섹션)를 활용하여 AskUserQuestion으로 질문한다.

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

AI将在第一层分析中判断“仅通过代码无法得知”的项向开发者提问。利用CDM探针问题集（下方章节）通过AskUserQuestion进行提问。

提问以3-5个为一组，高效推进
将开发者的回答反映到对应文档章节
“不知道”或“不适用”的回答也需记录（标记为未确认事项）

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

第四步：第三层 — 自我验证

AI가 생성된 문서를 재검토한다:

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

AI重新审核生成的文档：

验证问题：“仅阅读本文档能否修改功能？”
若识别到遗漏的隐性知识，向开发者追加提问
检查文档间相互引用的一致性

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

第五步：最终文档确认 + 后续步骤指引

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

保存最终主题文档
指引后续使用方法（关联gen-spec、Plan Mode等）

암묵지 탐색 체크리스트

隐性知识检索清单

1계층(AI 자동 분석)에서 점검할 항목. 발견 시 문서에 기록하고, 코드만으로 이유를 알 수 없으면 2계층에서 개발자에게 질문한다.

코드 레벨 (로직 문서용)

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

데이터 레벨 (명세 문서용)

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

이력 레벨 (Git 고고학)

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

第一层（AI自动分析）中需检查的项目。若发现则记录到文档中，若仅通过代码无法得知原因，则在第二层向开发者提问。

代码层级（逻辑文档用）

硬编码的常量/魔术数字 → 为何使用该值？
防御性代码（try-catch、仅处理特定错误）→ 是否源于经验？
注释中的TODO/FIXME/HACK → 是否为有意的技术债务？
直接导入其他模块 → 是否为未文档化的依赖关系？

数据层级（规范文档用）

未使用的列/状态值 → 是否为遗留项或预留项？
复杂的JOIN/子查询 → 是否出于性能或业务原因？

历史层级（Git考古）

变更频率高的文件 → 复杂度/风险集中点
一起变更的文件（co-change）→ 隐性耦合关系

CDM 프로브 질문 세트

CDM探针问题集

2계층(개발자 대화형 추출)에서 AskUserQuestion으로 물어볼 질문 템플릿:

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

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

第二层（开发者交互式提取）中通过AskUserQuestion提出的问题模板：

“该功能中最困难的决策是什么？”
“如果有与最初设计不同的部分，为什么会发生变更？”
“首次接触该代码的开发者可能会忽略的陷阱是什么？”
“是否存在不能删除的代码或设置？原因是什么？”
（动态问题） 基于AI在第一层分析中发现的异常点生成 — 示例：“如果[异常点]发生变更，会影响哪些部分？”

第5项并非固定问题，而是AI基于分析中发现的内容动态生成。若开发者回答“不知道”，则将对应项记录为文档中的“未确认事项”。

도구 사용

工具使用

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

Read/Glob/Grep：代码静态分析、模块结构识别
Bash：Git考古（git log、git blame等）
AskUserQuestion：第二层开发者交互式提取
Write：文档文件生成

개요 템플릿 ({기능명}-개요.md)

概述模板 ({功能名}-概述.md)

undefined

undefined

{기능명} — 개요

{功能名} — 概述

1. 요약

1. 摘要

{한 줄 설명}

{一句话说明}

2. 전체 흐름

2. 整体流程

(입력 → 검증 → 저장 등 단계 나열)

（输入→验证→保存等步骤列举）

3. 관련 파일 (코드)

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

分类	路径
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. 문서 인덱스

4. 文档索引

문서	핵심 내용	읽을 때
[{기능명}-처리흐름-xxx.md]	변환 N단계, 분기 조건	코드 수정 전
[{기능명}-에러코드.md]	N개 에러코드 목록	에러 처리 추가 시
[{기능명}-설계결정.md]	force_xxx 이유, yyy 배경	로직 변경 전 반드시
[{기능명}-매핑-테이블명.md]	필드 매핑	해당 테이블 수정 시
...	...	...
[{기능명}-TDD-가이드.md]	테스트 N개, 실행법	테스트 실행 시

undefined

文档	核心内容	阅读时机
[{功能名}-处理流程-xxx.md]	转换N步骤、分支条件	修改代码前
[{功能名}-错误代码.md]	N个错误代码列表	添加错误处理时
[{功能名}-设计决策.md]	force_xxx的原因、yyy的背景	修改逻辑前必须阅读
[{功能名}-映射-表名.md]	字段映射	修改对应表时
...	...	...
[{功能名}-TDD-指南.md]	N个测试、执行方法	执行测试时

undefined

주제별 문서 가이드

主题文档指南

주제별 문서 유형과 네이밍

主题文档类型与命名

유형	파일명 패턴	예시
처리 흐름	`처리흐름-{함수/기능명}.md`	`처리흐름-execConvert.md`
에러 코드	`에러코드.md`	-
설계 결정	`설계결정.md`	ADR 형식 유지
데이터 매핑	`매핑-{테이블명}.md`	`매핑-tang-order.md`
파싱 규칙	`파싱-{대상}.md`	`파싱-주문옵션.md`
상태/코드	`상태코드-매핑.md`	-
입력 데이터	`입력-{형식}.md`	`입력-JSON-샘플.md`
TDD	`TDD-가이드.md`	항상 단독 파일

类型	文件名模式	示例
处理流程	`处理流程-{函数/功能名}.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줄 초과 시 분리 고려

简单功能（3-4个文件）：概述 + 逻辑 + 规范 + TDD（可合并）
复杂功能（8-12个文件）：按主题细分
标准：单个文件超过100行时考虑拆分

설계 결정 기록 (ADR 형식)

设计决策记录（ADR格式）

설계결정.md 또는 해당 주제 문서에 포함. 코드만 보면 알 수 없는 "왜"를 기록한다.

결정	맥락(Context)	결정(Decision)	결과(Consequences)
예시	PG사 응답 평균 2.8초	timeout을 3초로 설정	간헐적 타임아웃 발생 시 재시도 필요

AI가 코드를 수정할 때 기존 결정의 맥락을 이해해야 로직을 망가뜨리지 않는다. 예를 들어 "강제 변환 모드가 존재하는 이유"를 모르면 해당 분기를 제거하거나 변경할 수 있다.

记录在

设计决策.md

或对应主题文档中。记录仅通过代码无法得知的“为什么”。

决策	上下文(Context)	决策(Decision)	结果(Consequences)
示例	PG公司响应平均2.8秒	将timeout设置为3秒	发生间歇性超时需重试

AI修改代码时，必须理解现有决策的上下文，才不会破坏逻辑。例如，若不知道“强制转换模式存在的原因”，可能会删除或修改对应的分支。

TDD-가이드 템플릿 ({기능명}-TDD-가이드.md)

TDD-指南模板 ({功能名}-TDD-指南.md)

섹션 구성:

테스트 파일 목록
실행 명령 (
```
bunx vitest run {경로}
```
)
샘플 데이터 위치
Quick reference 표

章节构成：

测试文件列表
执行命令 (
```
bunx vitest run {路径}
```
)
示例数据位置
Quick reference表

Reading existing feature docs (AI 지침)

阅读现有功能文档（AI指南）

진입:
```
{기능명}-개요.md
```
를 먼저 읽기
문서 인덱스 테이블에서 "읽을 때" 컬럼을 현재 작업과 비교
필요한 문서만 선택 로드
폴더 전체를 주입해도 AI가 개요 기반으로 자동 선택

入口：先阅读
```
{功能名}-概述.md
```
在文档索引表中对比“阅读时机”列与当前工作
仅选择加载所需文档
即使注入整个文件夹，AI也会基于概述自动选择

후속 활용 지침

后续使用指引

```
peach-agent-team
```
,
```
peach-agent-team-refactor
```
: 기존 기능 수정 맥락이면 해당 폴더를 작업 시작 컨텍스트로 선로드
gen-spec 연계 시: Context Pack 폴더를 컨텍스트로 주입하면 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개 이상이면 분리.

카테고리 폴더 예시:

회원관리

게시판

결제

상품

주문

정산

路径以仓库根目录为基准 (
```
api/src/modules/
```
、
```
front/src/modules/
```
等)。
分类名/功能名包含空格时，用连字符替换（示例：
```
密码 修改
```
→
```
密码-修改
```
）。

所有文件名必须采用
{功能名}-{主题}.md
格式（示例：

支付联动-概述.md

、

支付联动-TDD-指南.md

）。

必须生成
```
{功能名}-概述.md
```
（入口+索引）。
```
{功能名}-TDD-指南.md
```
始终为独立文件。
一个文件包含2个以上主题则拆分。

分类文件夹示例：

会员管理

、

论坛

、

支付

、

商品

、

订单

、

结算