# Feature Doc Splitter Cn > 当用户需要把粗略功能需求拆成总览、前端和后端实现文档，并结合代码梳理契约时使用。 - Skill: `yangsonhung/feature-doc-splitter-cn` (Agent Skill) - Install (CLI): `npx skillmds add yangsonhung/feature-doc-splitter-cn` - Raw SKILL.md: https://api.skillmd.com/api/skills/yangsonhung/feature-doc-splitter-cn/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: yangsonhung (https://skillmd.com/u/yangsonhung) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/yangsonhung/feature-doc-splitter-cn --- # 功能文档拆分器 ## Overview 使用这个技能，将早期功能需求初稿整理成一组三份可落地文档：总览文档、前端实现文档和后端实现文档。 输出必须结合真实代码结构，明确拆分前端和后端职责，定义共享契约，补充必要 Mermaid 图，并把不确定点显式写入假设或待确认事项。涉及新增 UI 表面时，还要判断是否需要预留可选 Pencil 设计稿占位。 ## 何时使用 当用户提出以下需求时使用本技能： - 将初版功能需求文档拆分为总览、前端和后端实现文档。 - 把粗略产品说明整理成可直接开发的技术文档。 - 写功能实现文档前，需要先结合现有代码梳理模块和约定。 - 需要补充 Mermaid 业务流程图、交互流程图、时序图或接口契约索引。 - 需要先询问用户是否为新增前端 UI 表面预留可选 Pencil 设计稿占位。 ## 不要使用 以下场景不要使用本技能： - 直接实现功能代码。 - 只写一份不拆分的 PRD 或宣传说明。 - 在 Pencil 中绘制具体 UI 视觉稿。 - 只做后端 API 设计，且不需要拆成三份功能文档。 - 只做前端组件开发，且不需要总览和后端实现文档。 ## 使用说明 按照以下流程执行，并始终按责任归属拆分三份输出文档。 ## 必须输出 创建或更新三份文档： - 总览文档：目标、背景、范围、非目标、业务对象、端到端流程、跨端契约、必需的 Mermaid 图、上线规划、风险和验收标准。 - 前端实现文档：仅描述前端路由、页面、区块、组件、状态、Hook、接口接入点、交互状态、Mermaid 流程图、测试，以及新增 UI 的可选 Pencil 设计稿占位。 - 后端实现文档：仅描述后端数据模型、迁移、接口路由、Schema、服务、校验规则、统计公式、任务、通知或事件创建、Mermaid 流程图、测试和验收标准。 总览文档必须用项目相对路径引用前端和后端实现文档，并且必须包含 Mermaid 代码块。 ## 工作流程 1. 先读取仓库规则。 - 编辑前读取相关 `AGENTS.md`。 - 遵循本地文档风格、落位目录、命名和包管理约定。 - 保留与任务无关的用户改动。 2. 完整阅读初版需求文档。 - 识别用户目标、参与角色、业务名词、排行榜或统计规则、可见 UI、后端数据诉求、通知诉求和隐含权限。 - 不清楚的内容写入“假设”或“待确认事项”，不要在文档里静默编造。 3. 写文档前先梳理代码。 - 使用 `rg` 和定向文件阅读查找现有页面、路由、组件、Hook、生成 API 客户端、模型、Schema、服务、测试、通知代码、统计或排行逻辑。 - 优先复用现有模块和项目约定，不为单次需求创造多余抽象。 - 如果已有组件或模块可以复用，在文档中写清复用路径，不创建设计稿占位。 4. 定义文档集合。 - 三份文档使用一致命名。 - 链接统一使用项目相对路径。 - 前端和后端文档都必须能独立指导对应角色实现，不能依赖阅读对方内部细节。 - 共享契约放在总览文档；各实现文档只重复本端需要消费的那部分。 5. 编写总览文档。 - 包含总目标、业务背景、范围、非目标、术语、角色、数据归属、接口契约索引、分阶段计划、验收标准、风险和依赖。 - 总览文档始终至少包含一张 Mermaid 端到端业务流程图。 - 当涉及多角色或多系统协作时，补充 Mermaid 时序图或交互流程图。 6. 编写前端实现文档。 - 包含路由或入口、页面或面板变更、组件清单、状态模型、数据加载、API 客户端使用、空态/加载/错误态、权限、文案或国际化、必要埋点和测试。 - 包含一张 Mermaid 前端业务逻辑流程图和一张 Mermaid 用户交互流程图。 - 定义或创建任何 Pencil 占位前，先询问用户是否需要预留；如果用户已经明确需要或不需要，则按用户表达执行。 - 如果用户不需要 Pencil 占位，不创建 `.pen` 文件，并在文档中简要记录该决策。 - 如果用户需要 Pencil 占位，仅为真正新增的页面、视图、区块、面板、板块或组件定义。 - 对复用已有 UI 的部分明确标注“复用已有组件，不需要设计稿占位”。 7. 编写后端实现文档。 - 包含模型、迁移、接口端点、请求和响应 Schema、operationId、服务类、校验、去重或幂等、权限检查、统计公式、事件、任务和测试。 - 包含一张 Mermaid 后端业务或统计流程图。 - 当 API、服务、数据库、事件或通知系统存在协作时，补充 Mermaid 时序图。 - 如果项目使用生成式客户端，写明 OpenAPI 生成影响。 8. 只在用户确认需要后创建设计稿占位。 - 如果用户没有提前说明偏好，创建占位文件前先提出一个简洁的是/否问题。 - 如果用户拒绝或表示不需要占位，不创建 `.pen` 文件。 - 只有新增前端 UI 表面需要后续人工设计，且用户希望预留时，才创建 `.pen` 文件。 - 不要为复用已有组件、简单文案修改、已有列表行、已有标签页或已有入口按钮创建 `.pen` 文件。 - 占位文件放在功能文档附近，例如 `docs/features//pencil/.pen`。 - 如果项目使用 Pencil `.pen` JSON 文件，空占位可以只包含： ```json {"version":"2.13","children":[]} ``` 9. 验证结果。 - 检查链接、标题一致性、Mermaid 语法、文档职责边界，以及总览文档是否包含 Mermaid 代码块。 - 确认没有写入机器相关绝对路径，除非用户明确要求。 - 如果创建了 `.pen` 占位，校验 JSON 格式。 - 有仓库文档或技能校验命令时运行它们；否则至少运行 `git diff --check`。 - 最终说明已运行的检查。 ## 职责拆分规则 - 前端文档不要写后端内部实现细节。 - 后端文档不要写前端组件和布局决策。 - 已有接口契约足够时，不要强行设计新后端 API。 - 确实需要新接口时，写清 method、path、operationId、鉴权、请求 Schema、响应 Schema、错误码、分页、排序和前端消费预期。 - 如果前端使用生成 API 代码，要求写明生成客户端路径和重新生成命令，避免散落手写 API 调用层。 - 文档中的路径统一使用项目相对路径。 ## Mermaid 要求 当 Mermaid 节点文案包含标点时，使用引号包裹节点标签。 最少图示： - 总览：必需的端到端业务流程图。 - 总览：涉及多系统或多角色时，补充时序图或交互流程图。 - 前端：用户交互流程图。 - 前端：前端业务逻辑或状态流转图。 - 后端：后端接口/服务/数据流程图。 - 后端：涉及持久化、任务或事件时，补充时序图或统计流程图。 ## 最终回复 简要说明创建或更新的文档，列出创建或明确删除的 Pencil 占位，并报告验证结果。