peach-gen-feature-docs

peach-gen-feature-docs — 按功能生成规格说明

将现有功能代码中隐藏的隐性知识（tacit knowledge）转换为结构化规格说明，并按主题整理为 Markdown 文件，存放在 docs/기능별설명/{카테고리명}/{기능명}/ 文件夹中。개요.md 充当索引，让 AI 只加载所需文档。 此技能的核心产出并非简单的文档集合，而是之后在规划、实现和 QA 阶段重新注入的 as-is Context Pack（隐性知识→规格说明）。

按主题拆分的优势——与只阅读代码相比，结构化文档更有效的原因：

• 文件名充当搜索索引 → 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 自动分析 + 与开发者对话式提取的两阶段协作运行。AI 先分析可从代码/Git 中提取的信息，再向开发者询问仅凭代码无法获知的内容。
• 此文档是将现有功能的当前状态结构化后的维护用上下文资产。
• 在后续会话中，将 docs/기능별설명/{카테고리명}/{기능명}/ 文件夹本身注入为上下文，并参照 개요.md 的文档索引，仅加载工作所需的文档。
• 目的不是“替代代码的文档”，而是加快了解修改范围、保留决策背景并完成测试。

适用场景

• 改进/修改现有功能前，将代码位置和内容整理为 as-is 文档时（主要用途）
• 新功能实现完成后，有选择地为可能需要再次修改的核心功能编写文档
• 用户提出“编写功能文档”“生成按功能划分的规格说明”“/peach-gen-feature-docs”请求时

添加新功能时，请先使用 /peach-gen-spec。此技能适用于可以分析现有代码的情况。

输入

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

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

第 1 步：创建文件夹

docs/기능별설명/{카테고리명}/{기능명}/ — 如果类别文件夹不存在，则自动创建

第 2 步：第一层 — AI 自动分析

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 {파일}）

生成按主题划分的 Markdown 文件草稿（根据复杂度灵活决定文件数量）——根据下方指南填写 AI 分析的内容

拆分规则：

• 一个文件包含 2 个以上主题 → 拆分
• 在文件名中体现主题，让 AI 仅凭文件名即可推测内容
• 必须生成 {기능명}-개요.md（作为索引）
• {기능명}-TDD-가이드.md 保持为独立文件（测试是独立关注点）

第 3 步：第二层 — 与开发者对话式提取（基于 CDM/ACTA）

对于 AI 在第一层分析中判断为“仅凭代码无法获知”的项目，向开发者提问。 使用 CDM 探测问题集（参见下方章节），通过 AskUserQuestion 提问。

• 每次将 3-5 个问题组合起来，高效推进
• 将开发者的回答反映到相应文档章节中
• 也要记录“我不知道”或“不适用”的回答（标记为未确认事项）

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

AI 重新检查生成的文档：

• 验证问题：“只阅读此文档，能否修改此功能？”
• 如果发现遗漏的隐性知识，则向开发者追加提问
• 确认文档间交叉引用的一致性

第 5 步：确认最终文档 + 说明后续步骤

• 最终保存按主题划分的文档
• 说明后续使用指南（与 gen-spec 联动、Plan Mode 等）

隐性知识探索清单

第一层（AI 自动分析）中检查的项目。发现后记录在文档中；如果仅凭代码无法获知原因，则在第二层向开发者提问。

代码层（用于逻辑文档）

• 硬编码常量/魔术数字 → 为什么是这个值？
• 防御性代码（try-catch、仅处理特定错误）→ 是否源于以往经验？
• 注释中的 TODO/FIXME/HACK → 是否为有意保留的技术债？
• 直接导入其他模块 → 是否存在未记录的依赖关系？

数据层（用于规格文档）

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

历史记录层（Git 考古）

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

CDM 探测问题集

第二层（与开发者对话式提取）中通过 AskUserQuestion 提问的问题模板：

1. “此功能中最困难的决策是什么？”
2. “如果有与最初设计不同的部分，为什么发生了变化？”
3. “初次接触这段代码的开发者可能会忽略什么陷阱？”
4. “有没有不能删除的代码或设置？原因是什么？”
5. （动态提问） 基于 AI 在第一层分析中发现的异常情况生成——例如：“如果 [异常情况] 发生变化，会影响到哪里？”

第 5 个问题不是固定问题，而是由 AI 根据分析过程中发现的内容动态生成。 如果开发者回答“我不知道”，则在文档中将该项目记录为“未确认事项”。

工具使用

• Read/Glob/Grep：代码静态分析、掌握模块结构
• Bash：Git 考古（git log、git blame 等）
• AskUserQuestion：第二层与开发者对话式提取
• 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 格式）

包含在设计决策文档或相关主题文档中。记录仅看代码无法得知的“原因”。

决策	上下文（Context）	决定（Decision）	结果（Consequences）
示例	PG 公司响应平均耗时 2.8 秒	将 timeout 设置为 3 秒	偶发超时时需要重试

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

TDD 指南模板（{功能名}-TDD-가이드.md）

章节组成：

1. 测试文件列表
2. 执行命令（bunx vitest run {경로}）
3. 示例数据位置
4. Quick reference 表

阅读现有功能文档（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 个或更多主题时，请拆分。
• 类别文件夹示例：회원관리、게시판、결제、상품、주문、정산