feature-guide

name	feature-guide
description	生成功能使用指导文档（人性化、可执行、与代码实现对齐）。强制包含背景、流程图、泳道图、模块关系、页面/接口步骤、前后置依赖、验证与排障。

功能使用指导文档技能（Feature Guide）

适用场景

当你需要为某个功能编写“可直接落地执行”的指导文档时使用本技能。典型场景：

• 新功能上线，需要给研发/测试/运维一份可照着操作的手册。
• 功能已实现，但文档过于技术化、难读、步骤不连贯。
• 需要明确“页面操作 + 后台接口 + 代码落点 + 验证方式”的完整闭环。

目标

输出一份人性化 + 可执行 + 可追溯的文档，满足：

1. 先讲清楚“为什么有这个功能”（业务背景/痛点）。
2. 再讲清楚“它跟哪些模块相关”。
3. 给出“从 0 到跑通”的步骤（页面、接口、命令、预期结果）。
4. 所有关键行为都能追溯到代码实现（文件路径 + 函数/路由）。
5. 包含图示（流程图 + 泳道图）帮助非开发角色理解。

必须遵守的文档结构（强制）

最终文档必须按以下顺序组织章节：

1. 功能背景与目标
2. 角色与适用范围（谁看、在什么环境下用）
3. 整体架构与模块关系（含模块关系图）
4. 核心流程（含流程图）
5. 跨角色协作流程（含泳道图）
6. 前置条件与依赖（配置、权限、数据、开关）
7. 操作步骤（按场景拆分）
   • 页面操作步骤
   • 接口调用步骤
   • 本地命令步骤
8. 预期结果与验收标准
9. 代码实现映射（路由/服务/配置/测试文件）
10. 常见问题与排障
11. 回滚与风险控制
12. 变更记录（版本、日期、责任人）

图示规范（强制）

1) 流程图（必须）

• 使用 Mermaid flowchart LR 或 flowchart TD
• 节点要包含“输入/处理/输出/失败分支”
• 至少体现 1 个失败分支与回退路径

2) 泳道图（必须）

• 使用 Mermaid flowchart LR + subgraph 模拟泳道
• 至少包含 3 条泳道（示例：前端、插件后端、宿主/外部系统）
• 必须标明跨泳道的调用方向与返回结果

写作风格规范（强制）

• 先说结论，再说细节。
• 每个步骤必须有：
  • 动作（做什么）
  • 命令/入口（在哪做）
  • 预期结果（看到什么算成功）
  • 失败处理（失败后看哪里）
• 面向使用者写法：避免只写内部术语，不假设读者了解全部上下文。
• 禁止脱离代码实现：文档中的每个关键行为都要能在代码里找到对应落点。

代码对齐检查清单（发布前必过）

• 路由路径与文档一致（含版本前缀）。
• 配置项名称与默认值一致（config.yaml 优先级说明准确）。
• 页面入口与按钮文案与当前 UI 一致。
• 接口请求/响应示例与当前 DTO 一致。
• 文档中提到的 feature flag / env / manifest 均存在。
• 至少 1 条测试命令可直接验证主链路。

执行步骤（建议流程）

1. 收集上下文

   • 读取 spec/plan/tasks/quickstart（如果存在）
   • 读取路由注册、配置结构、主服务入口、关键 service

2. 梳理“功能地图”

   • 功能入口（页面、接口、命令）
   • 核心处理链路（handler -> service -> integration）
   • 输出与观测（日志、指标、事件、状态）

3. 先画图再写步骤

   • 先输出模块关系图、主流程图、泳道图
   • 再填充逐步操作（避免步骤断裂）

4. 补齐验收与排障

   • 每个场景给“成功判定”
   • 列出最常见 3~5 个失败场景与定位命令

5. 做代码映射表

   • 文档每个关键点至少映射一个代码路径

输出模板

• 使用模板：templates/feature-guide-template.md
• 允许按功能微调章节名，但不得删除“流程图、泳道图、代码映射、验收、排障”章节。

默认输出路径规范（强制）

未被用户显式指定输出路径时，必须使用以下默认规则：

1. 输入为 specs/<feature-id>/...（例如 specs/001-match-data-ingestion/...）时：
   • 默认输出目录：docs/guides/features/<feature-id>/
   • 默认主文档：guide.md（总览/索引）
   • 完整路径示例：docs/guides/features/001-match-data-ingestion/guide.md
2. 若目标目录不存在，必须自动创建目录后再写入。
3. 若目标文件已存在，默认执行“覆盖更新”（保留文档结构，按最新代码实现刷新内容）。
4. 只有在用户明确要求时，才写入 specs/ 下的临时文档。

Use Case 拆分规则（强制）

必须根据实际功能场景自动判断是否拆分多文档，禁止写死固定数量与固定文件名：

1. 若仅有 1 条独立主链路：输出 guide.md 单文档。
2. 若有多条可独立验收链路（例如多个 User Story / 场景）：输出
   • guide.md（总览：背景、模块关系、依赖、验收总则、文档索引）
   • usecase-<slug>.md（每条链路一份）
3. <slug> 生成规则：
   • 优先用稳定标识（如 us1、m1-f01、scenario-a）+ 语义短名
   • 仅使用小写字母、数字、连字符
   • 禁止把具体业务名硬编码到技能中
4. guide.md 必须包含“Use Case 文档索引表”（文件名 + 适用角色 + 独立验收口径）。

示例要求（最少）

文档中至少包含以下示例：

• 1 个页面操作示例（带路径、按钮、预期提示）
• 1 个接口调用示例（curl + 响应片段）
• 1 个本地联调示例（启动命令 + 指标/日志检查）

完成定义（DoD）

满足以下条件才算“文档完成”：

• 新同学不看代码，可按文档独立跑通一次主流程。
• QA 可按文档复现“成功 + 失败”各至少 1 条路径。
• 文档中的路径、参数、接口在当前分支可找到对应实现。
• 流程图与泳道图能覆盖主链路，不与实现冲突。