project-prd-doc-builder

基于项目目录构建完整 PRD 文档

本技能把一个现有项目目录转化为可信、层次清楚、可继续维护的产品需求文档（PRD）与综合文档站点。默认采用渐进式披露：先建立全局认知，再解释业务全景与场景，最后进入功能、规则、数据、交互、架构和验收细节。站点风格参考 VitePress，支持 Markdown、Mermaid、C4 图表、交互式流程、原型和独立页面嵌入。

Use When

• 用户要求依据现有代码库、项目文件夹、历史文档、用户故事、架构图或测试内容创建/重写完整 PRD。
• 用户希望把散落资料整理成易读、可检索、可交叉链接的综合文档站点。
• 需要从实现中识别现状，同时把目标行为、用户需求、业务规则、验收标准明确分开。
• 需要规划每个章节采用什么图，包括业务流程图、泳道图、用户旅程、用例关系图、时序图、状态图、数据模型和 C4 架构图。
• 需要交付既能静态阅读、评审和归档，又可以嵌入交互式流程或原型的文档。

Don't Use When

• 用户只要求修正文案、翻译某一段文字，且不涉及项目勘察或 PRD 结构。
• 用户明确只要单页摘要、营销文案或某一个具体接口文档；应缩小交付范围，不要自动生成整站。
• 用户要求凭空设计一个全新产品而没有项目目录依据；此时可采用产品规划流程，但必须把假设标记为假设。
• 用户要求直接改业务代码而不是产出文档；不要把 PRD 技能当成代码重构技能。

Workflow

1. 确认交付边界并检查已有结构

1. 先阅读仓库根目录、现有文档目录、README、项目说明、用户故事、架构图、数据模型、配置文件和测试。
2. 识别是否已有 VitePress、Docusaurus、MkDocs、Storybook、原型站点或文档发布流程。优先扩展现有体系，不覆盖已有配置。
3. 识别用户明确提出的范围、目标读者、产品阶段与交付形式。缺少非关键细节时采取保守默认值并记录假设，不要因小问题中断工作。
4. 将现有代码视为“当前实现证据”，不要直接把实现细节等同于“正确需求”。

2. 建立项目证据台账

1. 按 项目勘察与证据策略 盘点内容并建立证据清单。
2. 给每个重要结论标明来源、证据类型和置信度；区分已确认事实、合理推断、冲突项和待确认问题。
3. 优先使用仓库内的权威资料。没有证据的流程、业务规则、性能指标、权限行为和异常处理不得写成确定事实。
4. 不复制密钥、令牌、个人数据、生产凭证或不必要的敏感内容进文档。

3. 还原产品与业务模型

1. 先抽取产品目标、用户角色、核心对象、系统边界、外部系统、主要业务成果和非目标。
2. 编制端到端主业务流程，再拆分阶段流程、用户故事、用例、决策点、状态转换与异常路径。
3. 明确区分“现状（As-Is）”“目标（To-Be）”和“待决策（Open）”；如用户未指定，不要假定当前代码就是目标体验。
4. 让每个关键阶段都具有输入、处理、输出、责任角色、成功条件和异常出口。

4. 规划渐进式信息架构

按照 PRD 信息架构 安排章节：

1. 产品全景：让读者快速理解产品是什么、解决什么问题、为谁服务。
2. 业务全景：用一张端到端图讲清业务目标和阶段关系。
3. 核心场景：通过用户故事和用例说明谁在什么条件下做什么、得到什么结果。
4. 详细规范：再展开功能需求、业务规则、数据、状态、UX、接口、非功能需求。
5. 验收交付：明确验收条件、测试覆盖、需求追踪、风险与版本策略。

每页开头用简短的“本页解决什么问题”或摘要说明定位。避免在首页堆满实现细节，也避免所有内容塞进一篇超长 Markdown。

5. 为每章选择恰当图表

依据 图表与 Mermaid/C4 标准 建立图表清单，并按实际复杂度使用图表。每张图必须有目的、边界、图号、说明、相关需求 ID 和维护责任。

• 总体业务流程：提供独立可读的静态主流程；复杂流程可另提供可交互分层浏览器。
• 阶段/跨角色流程：采用泳道风格流程图或阶段职责表。
• 多角色目标：用户故事地图或用例图；简单场景用表格即可。
• 多系统交互：时序图；复杂实体生命周期：状态图。
• 领域对象和关系：ER 图或领域模型图。
• 系统边界：C4 System Context；系统部署单元：C4 Container；只有复杂容器才继续画 Component。
• 每图只表达一个主要问题，太复杂时拆图，不以“图很多”作为完整性的替代品。

6. 编写可执行的需求

1. 使用稳定、唯一的 ID：US-*、UC-*、FR-*、BR-*、DATA-*、STATE-*、FLOW-*、DIA-*、AC-*、NFR-*、API-*。
2. 用户故事表达用户价值；用例表达交互流程；功能需求表达系统可观察行为；业务规则表达决策/限制；验收标准表达可验证结果。不得把这些类型混成一句模糊描述。
3. 重要需求写出前置条件、触发、主路径、替代/异常路径、输入输出、权限、状态影响及可测试的验收标准。
4. 对算法、优化器、AI 或自动化能力，说明输入、输出、约束、目标、失败/超时回退、人工调整方式和可解释性要求；不要凭空承诺最优性或性能。
5. 详细格式参见 需求、用例与验收写法。

7. 建立文档站点与嵌入能力

1. 如果仓库已有文档站点，延续其技术栈和主题；如果没有且用户希望综合文档站，优先创建独立的 VitePress 文档目录，避免与应用构建配置冲突。
2. 采用 交互文档站点约定，统一目录、导航、侧边栏、页面模板和嵌入内容规范。
3. 普通文字/表格写 Markdown；原生图用 Mermaid；轻量交互写 Vue 组件；复杂原型或 3D 页面使用独立路由/HTML/iframe，保留静态摘要或备用链接。
4. 动态流程不能成为唯一真相：始终保留可独立阅读的静态主流程、文本化分支说明和可归档的源文件。

8. 建立追踪关系并进行自动校验

1. 将用户故事、用例、功能需求、业务规则、图表、页面/组件、测试场景和验收标准关联起来。
2. 将未知项放入“待确认问题”表，并标记会影响的需求和决策；不以“待确认”替代已经能从证据中得出的内容。
3. 运行 scripts/validate_prd.py <文档目录> 检查 Markdown 链接、重复 ID、未闭合 Mermaid 代码块、明显占位符和基本结构问题。
4. 若环境允许，执行文档站点安装/构建与 Mermaid 渲染检查；如果未执行，明确说明，不要声称构建通过。
5. 按 质量门禁与交付清单 完成评审。

9. 交付与总结

最终说明：文档输出位置、主要页面、图表和嵌入组件、证据覆盖范围、重要假设/冲突、自动校验结果、尚未验证的项目。不要只交一个目录树或计划；应真实创建文件并检查产物。

Rules

• 必须先勘察再写作。 不根据目录名猜整个产品，也不把第一份 README 当成唯一事实来源。
• 必须渐进式披露。 从全局到场景再到细节；重要流程提供主图，复杂逻辑通过子页/折叠/交互展开。
• 必须区分证据与设计建议。 对未知信息显式标记，不把推断伪装成事实。
• 必须同时照顾产品与技术读者。 产品读者能读懂业务价值和操作流程；研发读者能找到需求 ID、状态、数据、边界和验收依据。
• 必须将图表纳入文档治理。 每张关键图都有名称、目的、唯一 ID、来源、相关需求与更新条件。
• 必须支持静态阅读。 关键业务逻辑不能只存在于动画、交互组件或远程 iframe 中。
• 必须使用可验证的验收标准。 优先给定条件/动作/结果或明确的数值阈值；没有依据的阈值放入待确认项。
• 必须尊重既有工程。 不覆盖现有站点配置、不擅自安装依赖、不改动生产业务代码，不把文档生成和业务实现混在同一批改动中。
• 禁止生成虚假的完整性。 不编造接口、角色权限、SLA、算法精度、法规承诺或外部系统行为。
• 禁止只输出孤立长文。 除非用户明确要求单文件，否则采用有导航、交叉链接、附件和图表索引的多页结构。
• 禁止为每章机械加图。 当表格或文字更清晰时使用表格/文字；图表只在能减少理解成本时添加。
• 禁止把所有细节塞进 SKILL.md。 按需阅读下列参考文件，保持流程可执行并避免无谓占用上下文。

Examples

• “根据这个项目目录写一份完整 PRD” → 勘察代码与资料，创建多页 PRD 文档站、流程图、用例、需求和验收标准，并保留证据台账。
• “把用户故事、架构图和源码整理成一个 VitePress 文档” → 检查现有站点后扩展或创建独立 VitePress 站点，嵌入 Mermaid/C4 与交互组件。
• “先把总体业务流程做成可展开的动态图” → 同时交付静态主流程、阶段子流程、节点元数据和交互组件；保持静态/交互内容一致。
• “帮我从现有代码逆向补全需求” → 把源码和测试作为现状证据，列出与现有文档冲突的部分，区分已实现功能与目标需求。

Edge Cases

• 项目目录很大： 先用目录树、搜索和依赖清单定位高价值文件；按模块抽样，再对关键流程深入，不要无差别读取 node_modules、构建产物、二进制或生成文件。
• 文档与代码冲突： 保留冲突记录，说明分别支持什么结论；不要静默覆盖其中一方。
• 只有源码没有业务说明： 先形成“从实现推断的当前行为”及置信度，再将目标行为列为待产品确认。可以交付初稿，不得伪装为最终定稿。
• 只有业务文档没有源码： 依据业务材料写需求；将技术可行性、实现状态和接口细节标注为未验证。
• 项目里存在旧版本 PRD： 判断哪些章节仍有效、哪些过期；在变更记录里写清保留、替换和弃用，不默认旧文档完全正确。
• 某项信息缺失： 如果不阻止产出，就采用保守假设并进入假设台账；如果可能改变产品边界或核心工作流，优先给出带标注的最合理版本，而不是停止全部工作。
• 站点不适合加复杂前端： 以 Markdown + Mermaid + 静态导出为基线，把互动功能做成可选增强。
• 无法运行 Node 或 Python： 完成文件生成并进行可执行的静态审阅；准确报告没有执行的检查。
• 项目资料含敏感信息： 不把密钥、生产账户、客户个人信息、访问令牌、内部私有 URL 原样复制到公共文档；必要时抽象或脱敏。

References

按任务按需读取，不要求每次一次性加载所有参考文档：

• 项目勘察与证据策略：目录发现、证据分级、冲突与推断管理。
• PRD 信息架构：推荐目录、章节目的和渐进式披露顺序。
• 需求、用例与验收写法：ID 规则、模板、验收和追踪关系。
• 图表与 Mermaid/C4 标准：每章图表决策、流程分层、C4 使用边界。
• 交互文档站点约定：VitePress 组织方式、嵌入类别、安全与降级。
• 质量门禁与交付清单：可读性、覆盖度、发布与最终检查。

可复制模板位于 assets/。生成后使用 scripts/validate_prd.py 校验文档目录。