Back to Details

peach-gen-feature-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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

peach-gen-feature-docs — 功能别规格生成

기존 기능의 코드에 숨어 있는 암묵지(tacit knowledge)를 구조화된 명세서로 변환하여 
docs/기능별설명/{카테고리명}/{기능명}/
폴더에 주제별 md 파일로 문서화한다. 개요.md가 인덱스 역할을 하여 AI가 필요한 문서만 선택 로드한다. 이 스킬의 핵심 산출물은 단순 문서 묶음이 아니라, 이후 계획 수립과 구현, QA 단계에서 재주입하는 **as-is Context Pack (암묵지→명세서)**이다.
주제 기반 분리의 장점 — AI가 코드만 읽는 것보다 구조화된 문서가 효과적인 이유:
  • 파일명이 검색 인덱스 역할 → AI가 파일명만 보고 내용을 추정
  • 개요.md의 문서 인덱스 테이블로 필요한 문서만 선택 로드
  • 복잡도에 따라 파일 수를 유연하게 조절 (간단한 기능 3-4파일, 복잡한 기능 8-12파일)
  • TDD 가이드로 AI가 테스트까지 자율 완결
将隐藏在现有功能代码中的隐性知识(tacit knowledge)转换为结构化规格说明书，并以按主题分类的md文件形式归档到
docs/功能别说明/{分类名}/{功能名}/
文件夹下。概述.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 직접 사용 (이 스킬 불필요)
场景B（现有功能优化）：
  /peach-gen-feature-docs → 注入Context Pack文件夹作为上下文 → AI基于概述自动检索内容 → /peach-gen-spec → 开发实现

场景B（小规模修改）：
  /peach-gen-feature-docs → 计划模式 → 直接开发实现

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

핵심 개념

核心概念

  • 이 스킬의 본질은 암묵지→명세서 변환이다. 코드에 명시적으로 드러나지 않는 설계 근거, 비즈니스 결정, 히스토리를 구조화한다.
  • AI 자동 분석 + 개발자 대화형 추출의 2단계 협업으로 동작한다. AI가 코드/Git에서 추출 가능한 것을 먼저 분석하고, 코드만으로 알 수 없는 것은 개발자에게 질문한다.
  • 이 문서는 기존 기능의 현재 상태를 구조화한 유지보수용 컨텍스트 자산이다.
  • 후속 세션에서는 
    docs/기능별설명/{카테고리명}/{기능명}/
    폴더 자체를 컨텍스트로 주입하고, 개요.md의 문서 인덱스를 보고 작업에 필요한 문서만 선택 로드한다.
  • 목적은 "코드를 대신하는 문서"가 아니라, 수정 범위 파악과 결정 맥락 보존, 테스트 완결을 빠르게 만드는 것이다.
  • 本技能的本质是隐性知识→规格说明书的转换，将代码中未明确体现的设计依据、业务决策、迭代历史进行结构化梳理。
  • 采用AI自动分析 + 开发者交互提取的两步协作模式运行：AI先分析可从代码/Git中提取的内容，再向开发者询问仅通过代码无法获知的信息。
  • 生成的文档是对现有功能当前状态进行结构化梳理的可复用维护上下文资产。
  • 后续会话中可直接将
    docs/功能别说明/{分类名}/{功能名}/
    文件夹作为上下文注入，AI会根据概述.md的文档索引选择性加载工作所需的文档。
  • 本技能的目标不是「替代代码的文档」，而是帮助开发者快速确认修改范围、留存决策上下文、完成测试闭环。

When to use

适用场景

  • 기존 기능 개선/수정 전 코드 위치와 내용을 as-is 문서화할 때 (주 용도)
  • 신규 기능 구현 완료 후 재수정 가능성이 높은 핵심 기능을 선택적으로 문서화할 때
  • 사용자가 "기능 문서화", "기능별 명세 만들어줘", "/peach-gen-feature-docs" 요청 시
신규 기능 추가 시에는 
/peach-gen-spec
를 먼저 사용. 이 스킬은 기존 코드를 분석할 수 있을 때 유효하다.
  • 对现有功能进行优化/修改前，需要对代码位置和内容进行as-is文档化时（核心用途）
  • 新增功能开发完成后，对后续修改概率较高的核心功能进行选择性文档化时
  • 用户提出「功能文档化」、「帮我生成功能别规格」、「/peach-gen-feature-docs」请求时
新增功能开发时请先使用
/peach-gen-spec
，本技能仅在可分析现有代码的场景下有效。

Input

输入参数

  • 카테고리명: 상위 분류 폴더명 (예: 회원관리, 게시판, 결제)
  • 기능명(한글): 기능 폴더명 (예: 로그인, 비밀번호-변경)
  • 한 줄 설명(선택): 개요.md 요약에 사용
  • 分类名：上级分类文件夹名（例如：会员管理、公告板、支付）
  • 功能名（韩文）：功能文件夹名（例如：登录、密码-修改）
  • 一句话说明（可选）：用于概述.md的摘要内容

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

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

1단계: 폴더 생성

第1步：创建文件夹

docs/기능별설명/{카테고리명}/{기능명}/
— 카테고리 폴더가 없으면 자동 생성
自动生成
docs/功能别说明/{分类名}/{功能名}/
路径，若分类文件夹不存在则自动创建

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

第2步：第一层 — 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 기반)

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

AI가 1계층 분석에서 "코드만으로 알 수 없다"고 판단한 항목을 개발자에게 질문한다. CDM 프로브 질문 세트(아래 섹션)를 활용하여 AskUserQuestion으로 질문한다.
  • 질문은 한 번에 3-5개씩 묶어서 효율적으로 진행
  • 개발자 답변을 해당 문서 섹션에 반영
  • "모르겠다" 또는 "해당 없음" 답변도 기록 (미확인 사항으로 표시)
AI将第一层分析中判定为「仅通过代码无法获知」的内容向开发者提问，使用CDM探针问题集（参考下文对应章节）通过AskUserQuestion发起询问。
  • 每次提问合并3-5个问题，提升沟通效率
  • 开发者的回答将同步更新到对应文档章节
  • 「不知道」或「不适用」的回答也会记录（标注为未确认事项）

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

第4步：第三层 — 自我校验

AI가 생성된 문서를 재검토한다:
  • 검증 질문: "이 문서만 읽고 기능을 수정할 수 있는가?"
  • 빠진 암묵지 식별 시 개발자에게 추가 질문
  • 문서 간 상호참조 정합성 확인
AI重新审查生成的文档：
  • 校验问题：「仅阅读这份文档是否可以修改对应功能？」
  • 识别到缺失的隐性知识时向开发者追加提问
  • 确认文档间相互引用的一致性

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

第5步：确认最终文档 + 后续使用指引

  • 주제별 문서 최종 저장
  • 후속 활용 지침 안내 (gen-spec 연계, Plan Mode 등)
  • 最终保存所有主题别文档
  • 告知后续使用说明（关联gen-spec、计划模式等）

암묵지 탐색 체크리스트

隐性知识探索清单

1계층(AI 자동 분석)에서 점검할 항목. 발견 시 문서에 기록하고, 코드만으로 이유를 알 수 없으면 2계층에서 개발자에게 질문한다.
코드 레벨 (로직 문서용)
  • 하드코딩된 상수/매직넘버 → 왜 그 값인가?
  • 방어적 코드(try-catch, 특정 에러만 처리) → 경험에서 나온 것인가?
  • 주석의 TODO/FIXME/HACK → 의도적 기술부채인가?
  • 다른 모듈 직접 import → 문서화 안 된 의존관계인가?
데이터 레벨 (명세 문서용)
  • 사용되지 않는 컬럼/상태값 → 레거시인가, 예약인가?
  • 복잡한 JOIN/서브쿼리 → 성능 이유인가, 비즈니스 이유인가?
이력 레벨 (Git 고고학)
  • 변경 빈도가 높은 파일 → 복잡도/리스크 집중 지점
  • 함께 변경되는 파일들(co-change) → 암묵적 결합 관계
第一层（AI自动分析）阶段需要检查的事项，发现后记录到文档中，若仅通过代码无法获知原因则在第二层向开发者提问。
代码级别（逻辑文档用）
  • 硬编码的常量/魔法数字 → 为什么使用该数值？
  • 防御性代码（try-catch、仅处理特定错误） → 是否来自过往经验？
  • 注释中的TODO/FIXME/HACK → 是否为刻意留存的技术债务？
  • 直接导入其他模块 → 是否为未文档化的依赖关系？
数据级别（规格文档用）
  • 未使用的字段/状态值 → 是遗留内容还是预留内容？
  • 复杂的JOIN/子查询 → 是出于性能原因还是业务原因？
历史级别（Git考古）
  • 修改频率高的文件 → 复杂度/风险集中点
  • 共改文件集合 → 隐性依赖关系

CDM 프로브 질문 세트

CDM探针问题集

2계층(개발자 대화형 추출)에서 AskUserQuestion으로 물어볼 질문 템플릿:
  1. "이 기능에서 가장 어려웠던 결정은 무엇인가요?"
  2. "처음 설계와 달라진 부분이 있다면, 왜 바뀌었나요?"
  3. "이 코드를 처음 보는 개발자가 놓칠 수 있는 함정은?"
  4. "삭제하면 안 되는 코드나 설정이 있나요? 이유는?"
  5. (동적 질문) AI가 1계층 분석에서 발견한 특이점을 기반으로 생성 — 예: "만약 [특이점]이 변경되면 어디에 영향이 가나요?"
5번은 고정 질문이 아니라, AI가 분석 중 발견한 것을 기반으로 동적 생성한다. 개발자가 "모르겠다"고 답하면 해당 항목을 문서에 "미확인 사항"으로 기록한다.
第二层（开发者交互提取）阶段通过AskUserQuestion提问的模板：
1.「这个功能中最困难的决策是什么？」 2.「如果有和最初设计不同的部分，为什么要修改？」 3.「第一次接触这段代码的开发者容易踩到的坑是什么？」 4.「有没有不能删除的代码或配置？原因是什么？」 5. （动态问题） 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/...
Serviceapi/src/modules/...
DAOapi/src/modules/...
Typeapi/src/modules/.../types.ts
Store (Pinia)front/src/modules/.../store.ts
Component (Vue)front/src/modules/.../*.vue
分类路径
Controller (Koa)api/src/modules/...
Serviceapi/src/modules/...
DAOapi/src/modules/...
Typeapi/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）

섹션 구성:
  1. 테스트 파일 목록
  2. 실행 명령 (
    bunx vitest run {경로}
    )
  3. 샘플 데이터 위치
  4. Quick reference 표
章节构成：
  1. 测试文件列表
  2. 运行命令（
    bunx vitest run {路径}
    ）
  3. 示例数据位置
  4. 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个以上主题时必须拆分。
  • 分类文件夹示例：
    会员管理
    、
    公告板
    、
    支付
    、
    商品
    、
    订单
    、
    结算