企业官网建设流程全解析

• CMS
• 后端
• 前端

本文介绍 Webiny 仓库内置的prd-to-planClaude Skill（.claude/skills/prd-to-plan/SKILL.md）：它定义了一套"PRD → 多阶段实施计划"的标准工作流，核心思想是用tracer-bullet（曳光弹）垂直切片把产品需求逐层打穿 schema、API、UI 与测试，最终产出可独立演示、可逐阶段验收的本地 Markdown 计划文件。读完本文，你将掌握这套技能的六步操作流程、垂直切片的分割原则、与用户的评审方法、计划文件的模板结构，并能结合仓库中真实的 PRD 与计划实例（如 ai-context/plans/admin-list-module.md）直接上手使用。

一、技能定位：它解决什么问题

在 Webiny 这类大型 TypeScript 单体仓库中，一次功能开发往往横跨 GraphQL API、数据访问、React 前端与测试等多层代码。如果没有统一方法，PRD 很容易被直接翻译成一长串"水平切片"式任务清单（如"先做数据库表"、"再做 API"、"最后做 UI"），导致：

• 每一层完成时都无法独立验证，问题被推迟到集成阶段才暴露；
• 阶段性交付物不可演示，用户与开发者对进度认知脱节；
• 计划中过早写死文件名、函数名等易变细节，后续阶段一改就大面积失效。

prd-to-plan技能的触发条件写在它的 frontmatter 中：当用户想要"把 PRD 拆解成实施计划（implementation plan）"、"按阶段规划（plan phases from a PRD）"，或提到"tracer bullets"时，应调用本技能。它的产出是一份保存在./ai-context/plans/（SKILL 正文第 8 行声明）下的本地 Markdown 文件。

二、六步工作流总览

SKILL.md 的 Process 一节给出了完整流程，共六个步骤：

下面逐步骤展开。

1. 确认 PRD 在上下文中

技能明确要求："The PRD should already be in the conversation. If it isn't, ask the user to paste it or point you to the file."

即：不允许在 PRD 缺席的情况下直接开拆。如果 PRD 不在当前对话中，应请用户粘贴文本或指明文件路径。这一步保证了后续所有切片都有明确的需求来源，避免凭空发挥。

2. 探索代码库

"如果尚未探索过代码库，请先探索，以理解当前架构、既有模式和集成层。"

Webiny 仓库本身就为此提供了结构化资料，例如 ai-context/prds/admin-list-module/list-module-prd.md 这类 PRD 文档，以及 ai-context/code-style 下的编码规范（如 one-class-per-file、no-stateless-private-methods 等）。探索的目标不是通读全部代码，而是回答三个问题：

• 新增功能要穿过哪些集成层（GraphQL schema、repository/数据层、React 视图、测试）？
• 仓库中有哪些既有模式可复用（如 Webiny 的 presenter/repository 分层、react-properties 配置模式）？
• 哪些边界接口（第三方服务、权限系统）会约束实现？

这直接服务于下一步的"持久决策"识别。

3. 识别 durable architectural decisions（持久架构决策）

在动手切片之前，先识别"贯穿整个实现过程、不太可能改变的高层决策"。SKILL.md 给出的清单是：

• Route structures / URL patterns（路由结构 / URL 模式）
• Database schema shape（数据库 schema 形态）
• Key data models（关键数据模型）
• Authentication / authorization approach（认证 / 授权方案）
• Third-party service boundaries（第三方服务边界）

这些决策之所以重要，是因为它们"go in the plan header so every phase can reference them"——会被写入计划头部，供每个阶段引用。如果切片阶段发现某条决策被反复推翻，说明该决策本身还不够 durable，值得在进入实现前先定死。

仓库实例可以佐证这一点：ai-context/plans/admin-list-module.md 的"Architectural decisions"一节就列出了包归属（packages/app-admin）、状态管理（MobXmakeAutoObservable）、DI 方案（React Context +createListModule()工厂）、UI 声明方式（JSX + react-properties）、关键模型名（ListGateway<TDto, TParams>、ListMapper<TDto, TEntity>、ListViewModel<TEntity>、ListActions<TParams>）以及分页方案（cursor-based）。这些都是后续 7 个阶段共同依赖的"地基"。

4. 起草垂直切片（tracer bullet 阶段）

这是整个技能的灵魂。SKILL.md 用一段可复用的规则块（<vertical-slice-rules>）约束切片质量：

• 每个切片是一条狭窄但完整的端到端路径，穿过所有集成层（schema、API、UI、tests）——是垂直切片，不是某一层的水平切片；
• 完成的切片可以独立演示或验证（demoable or verifiable on its own）；
• 宁多切薄片，不切厚片（Prefer many thin slices over few thick ones）；
• 不要包含具体文件名、函数名或实现细节——这些很可能在后续阶段构建时变化；
• 一定要包含持久决策：路由路径、schema 形态、数据模型名称。

换句话说，tracer bullet 的精神是：第一个阶段就用最窄的路径把"数据从 GraphQL 一路流到 React 组件"这件事跑通并点亮，之后再逐步叠加搜索、排序、筛选、分页等功能。每个阶段完成时，用户都能看到或验证一个真实可用的东西，而不是一堆半成品中间件。

5. 与用户评审（Quiz the user）

起草完成后，必须把拆分方案呈现给用户评审，不能直接写文件。呈现方式是编号列表，每个阶段展示两项：

• Title：简短描述性名称
• User stories covered：该阶段覆盖 PRD 中的哪些用户故事

随后向用户提出评审问题：

• 粒度是否合适？（太粗 / 太细）
• 某些阶段应该合并或进一步拆分吗？

迭代直到用户批准拆分方案（"Iterate until the user approves the breakdown"）。这一步把"计划"从单向产出变成双向共识过程，也是技能名中 quiz（盘问/评审）一词的由来。

6. 写出计划文件

评审通过后落地成文：

• 如./plans/不存在则创建；
• 计划文件命名为功能名，例如./plans/user-onboarding.md；
• 使用下方模板。

需要指出的是，SKILL.md 内部存在两处目录表述：正文开头的"Output is a Markdown file in./ai-context/plans/"，与步骤 6 的"Create./plans/"。在仓库中，两个目录都实际存在且都在存放计划类文档：根级 plans 目录下有 plans/breadcrumbs.md、plans/command-palette.md 等，而 ai-context/plans 目录下则有 20 余份与ai-context/prds对应的计划文件。使用时以团队约定的目录为准，保持 PRD（ai-context/prds/）与计划（ai-context/plans/或plans/）配套存放即可。

三、计划模板逐字段拆解

SKILL.md 内嵌了<plan-template>模板，结构如下：

# Plan: <Feature Name> > Source PRD: <brief identifier or link> ## Architectural decisions （跨所有阶段生效的持久决策：Routes / Schema / Key models ...） --- ## [ ] Phase 1: <Title> **User stories**: <list from PRD> ### What to build （描述这条垂直切片的端到端行为，而非逐层实现细节） ### Acceptance criteria - [ ] Criterion 1 - [ ] ... --- ## [ ] Phase 2: <Title> ...

各要素的含义：

• # Plan: <Feature Name>：计划标题，直接以功能命名；
• > Source PRD：以引用形式标注来源 PRD（标识符或链接），保证需求可回溯；
• ## Architectural decisions：计划头部，固化步骤 3 识别的持久决策，供所有阶段引用；
• ## [ ] Phase N: <Title>：每个阶段是一个待办复选框，标题为简短描述名；
• **User stories**：列出该阶段覆盖的 PRD 用户故事；
• ### What to build：描述这条垂直切片的端到端行为（"Describe the end-to-end behavior, not layer-by-layer implementation"）——刻意避免逐层展开；
• ### Acceptance criteria：可勾选的验收标准清单，是阶段完成的客观判据；
• 末尾以注释<!-- Repeat for each phase -->提示为每个阶段重复该结构。

四、仓库实例：模板的真实落地

ai-context/plans/admin-list-module.md 是该模板在仓库中的真实实例（共 200 行，7 个阶段），其头部完整复刻了模板：

Source PRD:ai-context/plans/list-module/list-module-plan.md

（对应 PRD 文档可参见 ai-context/prds/admin-list-module/list-module-prd.md。）随后是 Architectural decisions（包归属、MobX、DI、UI shape、关键模型、cursor 分页、BaseListParams基础类型），然后按模板展开 7 个 tracer-bullet 阶段：

注意每个阶段的 "What to build" 都采用端到端行为描述，而不写死具体文件路径；Acceptance criteria 全部是可勾选、可验证的行为断言（如 Phase 1 的"createListModule({ name, gateway, mapper, config })无需其他配置即返回可用 hook"、"卸载组件即 dispose presenter（无内存泄漏）"）。这正是 SKILL.md 中"不要包含易变文件名/函数名、要包含持久决策"两条规则的直接体现。

五、tracer-bullet 原则的仓库佐证

Webiny 仓库中能观察到这一方法论在真实功能上的痕迹：

• plans/breadcrumbs.md记录了面包屑功能从"DIBreadcrumb抽象"回退到 React Config API 的决策过程——它明确写到 DI 方案"being root-resolved + synchronous, couldn't produce dynamic labels ... which was the whole wall"，最终确认 Config API 才是正确方案。这正说明 durable 决策（这里指"面包屑是纯展示、走 Config API 而非 DI"）在实现前就应被识别并固化，避免后期推倒重来。
• ai-context/plans/admin-list-module.md的 Phase 1 先打通 "GraphQL response → React component" 全链路（gateway → mapper → repositories → presenter → hook → 组件），正是 tracer bullet 的教科书式切片：第一步就以最窄路径打穿所有集成层。
• 配套技能.claude/skills/write-a-prd/SKILL.md在 PRD 阶段就刻意"不包含具体文件路径或代码片段（They may end up being outdated very quickly）"，与 prd-to-plan 的"切片不含易变实现细节"一脉相承，两条规则共同保证文档的时效性。

从源码结构看，这种"小而完整、可独立验证"的切片原则也与 Webiny 各包分层（GraphQL API 包、数据访问包、前端 app 包、配套测试）天然匹配：每个切片都落在同一水平上对应包之间，因而任何阶段都可独立演示。

六、技能协作闭环：write-a-prd → prd-to-plan → grill-me

prd-to-plan并不是孤立的，它处于 Webiny 的 AI 开发技能流水线中段：

1. write-a-prd：通过用户访谈 + 代码库探索 + 模块设计产出 PRD，落盘到./ai-context/prds/（其中明确要求只写用户故事、实现决策、测试决策与 Out of Scope，不写具体文件路径）；
2. prd-to-plan（本文主题）：消费上一步的 PRD，产出多阶段实施计划；
3. grill-me：对已有计划/设计进行"拷问式评审"——"一次只问一个问题，沿决策树的每个分支逐条解决依赖，并为每个问题给出推荐答案；如果一个问题能通过探索代码库回答，就先去探索"。

这三个技能恰好构成"写需求 → 拆计划 → 评审打磨"的闭环，也是 SKILL.md 步骤 5（quiz the user）与 grill-me 一脉相承的"以对话收敛设计"的方法论底色。仓库中还有 preflight、tester 等技能可在计划执行的不同环节继续接力。

七、使用要点与最佳实践

综合 SKILL.md 与仓库实例，落地使用时有几点值得注意：

1. PRD 先于计划：没有 PRD 就不要开拆，第一步就是确认需求在上下文中；PRD 存放于ai-context/prds/，计划存放于ai-context/plans/（或plans/），两者通过计划头部的> Source PRD建立回溯关系。
2. 持久决策先行：路由、schema、数据模型、认证授权、第三方服务边界这五类决策在切片前定死，写入计划头部；阶段内部只讨论行为，不写将过时的实现细节。
3. 薄切片优于厚切片：宁可多切几个"一个功能点 + 全链路打通"的薄片，也不要一个"跨多层的大阶段"；每个切片结束时都应有可演示或可验证的产出。
4. 评审是流程的一部分：把拆分方案以"Title + User stories covered"的编号列表呈现，明确询问粒度是否合适、是否需要合并/拆分，迭代到用户批准为止——不要跳过评审直接写文件。
5. 验收标准可勾选：每个阶段的 Acceptance criteria 必须是客观、可验证的行为断言（如某状态为true/false、某调用产生可观察结果），并配合仓库既有的测试策略落地（如__tests__目录下的单元/集成测试）。

遵循这套流程，一个 PRD 会被拆成一组彼此独立、端到端可验证、且每个阶段都有明确用户故事和验收标准的实施计划——这正是 Webiny 大规模多包仓库中保持功能迭代节奏与质量可控的关键工作方法。

• CMS
• 后端
• 前端