功能文档拆分器

Overview

使用这个技能，将早期功能需求初稿整理成一组三份可落地文档：总览文档、前端实现文档和后端实现文档。

输出必须结合真实代码结构，明确拆分前端和后端职责，定义共享契约，补充必要 Mermaid 图，并把不确定点显式写入假设或待确认事项。涉及新增 UI 表面时，还要判断是否需要预留可选 Pencil 设计稿占位。

何时使用

当用户提出以下需求时使用本技能：

• 将初版功能需求文档拆分为总览、前端和后端实现文档。
• 把粗略产品说明整理成可直接开发的技术文档。
• 写功能实现文档前，需要先结合现有代码梳理模块和约定。
• 需要补充 Mermaid 业务流程图、交互流程图、时序图或接口契约索引。
• 需要先询问用户是否为新增前端 UI 表面预留可选 Pencil 设计稿占位。

不要使用

以下场景不要使用本技能：

• 直接实现功能代码。
• 只写一份不拆分的 PRD 或宣传说明。
• 在 Pencil 中绘制具体 UI 视觉稿。
• 只做后端 API 设计，且不需要拆成三份功能文档。
• 只做前端组件开发，且不需要总览和后端实现文档。

使用说明

按照以下流程执行，并始终按责任归属拆分三份输出文档。

必须输出

创建或更新三份文档：

• 总览文档：目标、背景、范围、非目标、业务对象、端到端流程、跨端契约、必需的 Mermaid 图、上线规划、风险和验收标准。
• 前端实现文档：仅描述前端路由、页面、区块、组件、状态、Hook、接口接入点、交互状态、Mermaid 流程图、测试，以及新增 UI 的可选 Pencil 设计稿占位。
• 后端实现文档：仅描述后端数据模型、迁移、接口路由、Schema、服务、校验规则、统计公式、任务、通知或事件创建、Mermaid 流程图、测试和验收标准。

总览文档必须用项目相对路径引用前端和后端实现文档，并且必须包含 Mermaid 代码块。

工作流程

1. 先读取仓库规则。

• 编辑前读取相关 AGENTS.md。
• 遵循本地文档风格、落位目录、命名和包管理约定。
• 保留与任务无关的用户改动。

1. 完整阅读初版需求文档。

• 识别用户目标、参与角色、业务名词、排行榜或统计规则、可见 UI、后端数据诉求、通知诉求和隐含权限。
• 不清楚的内容写入“假设”或“待确认事项”，不要在文档里静默编造。

1. 写文档前先梳理代码。

• 使用 rg 和定向文件阅读查找现有页面、路由、组件、Hook、生成 API 客户端、模型、Schema、服务、测试、通知代码、统计或排行逻辑。
• 优先复用现有模块和项目约定，不为单次需求创造多余抽象。
• 如果已有组件或模块可以复用，在文档中写清复用路径，不创建设计稿占位。

1. 定义文档集合。

• 三份文档使用一致命名。
• 链接统一使用项目相对路径。
• 前端和后端文档都必须能独立指导对应角色实现，不能依赖阅读对方内部细节。
• 共享契约放在总览文档；各实现文档只重复本端需要消费的那部分。

1. 编写总览文档。

• 包含总目标、业务背景、范围、非目标、术语、角色、数据归属、接口契约索引、分阶段计划、验收标准、风险和依赖。
• 总览文档始终至少包含一张 Mermaid 端到端业务流程图。
• 当涉及多角色或多系统协作时，补充 Mermaid 时序图或交互流程图。

1. 编写前端实现文档。

• 包含路由或入口、页面或面板变更、组件清单、状态模型、数据加载、API 客户端使用、空态/加载/错误态、权限、文案或国际化、必要埋点和测试。
• 包含一张 Mermaid 前端业务逻辑流程图和一张 Mermaid 用户交互流程图。
• 定义或创建任何 Pencil 占位前，先询问用户是否需要预留；如果用户已经明确需要或不需要，则按用户表达执行。
• 如果用户不需要 Pencil 占位，不创建 .pen 文件，并在文档中简要记录该决策。
• 如果用户需要 Pencil 占位，仅为真正新增的页面、视图、区块、面板、板块或组件定义。
• 对复用已有 UI 的部分明确标注“复用已有组件，不需要设计稿占位”。

1. 编写后端实现文档。

• 包含模型、迁移、接口端点、请求和响应 Schema、operationId、服务类、校验、去重或幂等、权限检查、统计公式、事件、任务和测试。
• 包含一张 Mermaid 后端业务或统计流程图。
• 当 API、服务、数据库、事件或通知系统存在协作时，补充 Mermaid 时序图。
• 如果项目使用生成式客户端，写明 OpenAPI 生成影响。

1. 只在用户确认需要后创建设计稿占位。

• 如果用户没有提前说明偏好，创建占位文件前先提出一个简洁的是/否问题。
• 如果用户拒绝或表示不需要占位，不创建 .pen 文件。
• 只有新增前端 UI 表面需要后续人工设计，且用户希望预留时，才创建 .pen 文件。
• 不要为复用已有组件、简单文案修改、已有列表行、已有标签页或已有入口按钮创建 .pen 文件。
• 占位文件放在功能文档附近，例如 docs/features/<feature>/pencil/<surface>.pen。
• 如果项目使用 Pencil .pen JSON 文件，空占位可以只包含：

{"version":"2.13","children":[]}

1. 验证结果。

• 检查链接、标题一致性、Mermaid 语法、文档职责边界，以及总览文档是否包含 Mermaid 代码块。
• 确认没有写入机器相关绝对路径，除非用户明确要求。
• 如果创建了 .pen 占位，校验 JSON 格式。
• 有仓库文档或技能校验命令时运行它们；否则至少运行 git diff --check。
• 最终说明已运行的检查。

职责拆分规则

• 前端文档不要写后端内部实现细节。
• 后端文档不要写前端组件和布局决策。
• 已有接口契约足够时，不要强行设计新后端 API。
• 确实需要新接口时，写清 method、path、operationId、鉴权、请求 Schema、响应 Schema、错误码、分页、排序和前端消费预期。
• 如果前端使用生成 API 代码，要求写明生成客户端路径和重新生成命令，避免散落手写 API 调用层。
• 文档中的路径统一使用项目相对路径。

Mermaid 要求

当 Mermaid 节点文案包含标点时，使用引号包裹节点标签。

最少图示：

• 总览：必需的端到端业务流程图。
• 总览：涉及多系统或多角色时，补充时序图或交互流程图。
• 前端：用户交互流程图。
• 前端：前端业务逻辑或状态流转图。
• 后端：后端接口/服务/数据流程图。
• 后端：涉及持久化、任务或事件时，补充时序图或统计流程图。

最终回复

简要说明创建或更新的文档，列出创建或明确删除的 Pencil 占位，并报告验证结果。