cs-build-create-prd

在 CodeSpring 中创建 PRD

PRD 能让 CodeSpring 全面、准确地了解某项功能，让新功能建立在现有功能之上，而不是重复实现后端、重新创建共享 API 路由或另起炉灶重做设计系统。此技能会根据真实代码，为所选功能编写 Frontend 和／或 Backend PRD。

这是创建 PRD 的唯一事实来源——其他技能（例如 cs-build-import-codebase）会调用此技能，而不是重新实现相关流程。

共享知识位于 codespring 技能的参考资料中：references/analyze-codebase.md、references/mindmap-structure.md、references/prd-management.md、references/pitfalls.md、references/codespring-docs.md。

0. 先连接

运行 codespring auth status（如有需要，先登录），再运行 codespring status。使用本地 .codespring/config.json 中的 projectId；并将其打印出来。如果代码库尚未导入 CodeSpring，先运行 cs-build-import-codebase。此技能只读取代码，并且只向 CodeSpring 写入内容——绝不修改代码库。

1. 询问要生成什么（交互式）

向用户展示其核心功能（来自 codespring features／思维导图中的 node-features 项），然后询问：

1. 要选择哪个功能？（一个、多个或全部）
2. Frontend、Backend，还是两者都要？ 除非用户已经说明，否则等待用户选择。

2. 深入分析真实代码

读取该功能的实际代码（不要猜测）。参照 analyze-codebase.md §8–9 的深度要求。涵盖以下内容：

Backend PRD——记录共享契约（这是添加新功能时风险最高的部分）

• 架构与结构——该功能的代码如何组织，以及遵循哪些约定。
• 路由器／API 路由／端点——路径、方法、请求／响应；并标明所有由多个功能共享的路由。
• 数据模型——表和枚举、关键列、关系；读取与写入操作。
• 可复用的服务端代码——已有且应复用而非重新实现的 actions／services／queries／hooks。
• 共享后端系统——明确列出以下内容，因为新功能可能与它们冲突：
  • 托管／部署目标（AWS、Vercel、Fly 等）及任何平台限制
  • 积分发放／用量计量系统；支付、订阅和退款系统
  • 后台 jobs／pipelines／queues／cron；长时间运行或异步生成任务
  • 存储：S3 约定／存储桶、文件路径、签名 URL 模式
  • 媒体／渲染管线（例如 Remotion／视频合成，如有）
  • 数据库、迁移
  • 身份验证和行级安全（RLS）
  • 必须使用或可复用的环境变量名称
  • Webhook（及签名验证）
• 安全性——身份验证与授权、所有权检查、验证、密钥、RLS、Webhook 签名。
• 复用与依赖关系图——列出“复用此项，不要重新构建”的内容，并指出依赖此功能的内容，避免后续更改无意间破坏其他功能。

Frontend PRD——记录设计系统和导航

• 设计令牌——颜色／品牌、圆角、间距比例、排版、阴影（来自 Tailwind 配置／CSS 变量／主题）。
• 组件与 UI 样式——UI 库，以及按钮／卡片／输入框／模态框的样式，包括各种状态。
• 布局、定位与间距——网格／弹性布局、列、断点、间隙；各元素相对位置。描述要具体。
• 用户可见内容——页眉、分区、卡片、表格、空状态／加载状态、提示消息。
• 导航／交互图——具体路径：哪个导航项／按钮会打开该页面 → 路由 → 页面展示内容 → 每项交互的作用；并列出与其他功能之间的链接。

先将内容写入该功能的说明（这是生成器的上下文）

codespring mindmap note <coreFeatureId> --title "How it works — <Feature>" --text "$(cat note.txt)"   # redirect output to /dev/null

3. 生成（参见 prd-management.md）

POST /prds/generate  { projectId, bridgeNodeId: "bridge-feature-<featureId>", prdType: "frontend" | "backend" }

超时设置为 ≥120s（客户端中止请求仍会创建记录 → 导致重复）。对于“Both”，发起两次调用。生成后，读回 PRD（codespring prd <id>），并确认上文所述的共享系统细节确实已写入；如果内容不够充分，就补充说明并重新生成，或用 prd sync 同步更完善的版本。

4. 附加到画布（参见 mindmap-structure.md）

添加 prdBridge → prdFrontend/prdBackend 节点，并调用 PUT /mindmaps/project/<projectId>。对于核心功能，prdBridge.data.featureId = "node-features"；对于子功能，它是该功能的子功能组节点 ID。itemId = 所选功能 ID。如果该功能已有 prdBridge，就把 PRD 节点添加到其中，而不是新建第二个桥接节点。

用户也可以在 CodeSpring Web 应用中生成 PRD（右键点击该功能的 PRD 桥接节点 → 添加并生成）。如果用户更愿意这样做，请指引他们查看 references/codespring-docs.md。

5. 按需去重 + 验证

超时导致重复时 → 先创建检查点，再删除多余项（prd-management.md）。进行验证（pitfalls.md）：PRD 内容真实，并包含共享系统细节；画布显示 prdBridge + PRD 节点，且 prdId 有效；node-features 中仍有正确数量的核心功能（将任何被展平的子功能重新设为子节点）。向用户提供其项目链接。

良好效果示例

• Backend PRD 应像一份共享系统契约，说明路由（标明共享路由）、数据模型、身份验证/RLS、作业/cron、存储/存储桶、支付/额度/退款、环境变量，以及清晰的“复用此项／不要破坏此项”依赖关系图。
• Frontend PRD 应涵盖设计系统和具体导航路径。
• 两份 PRD 都应关联到该功能的桥接节点，并以实际代码为依据。