从产品构思到代码实现，一体化 AI 工作流

SoftJob 是一套面向 AI 编码助手（GitHub Copilot / VS Code Agent） 的 Skill 与 Agent 体系，将「产品构思 → 需求分析 → 竞品调研 → PRD → 原型设计 → Figma 设计稿 → SRS 交付 → 架构 → 实施计划 → 逐批编码 → 部署交付 → 维护迭代」串联成可复用的自动化流水线。

目录

核心概念

概念 说明
Skill 一组领域知识、工作流程和输出模板，告诉 AI 怎么做某类任务
Agent 一个可独立执行任务的 AI 子代理，拥有专属的工具集、约束和行为规则 
用户想法 ──→ prodforge (Skill) ──→ 产品文档
                                       ├──→ requirements-review (Skill/Agent) ──→ 文档质量门禁（四标准 + 19 项清单）
                                       ├──→ design-forge (Skill) ──→ Figma 设计令牌 + 原型 Prompt
                                       ├──→ srs-forge (Skill) ──→ 客户交付 SRS 文档
                                       └──→ 编码实现 ──→ 可运行代码
                                              ├─ 小型/单模块：build-from-product-docs (Agent)
                                              └─ 大型/多模块：orchestrate-build (Agent)
                                                    ├─ 派发 → build-from-product-docs（worker）
                                                    ├─ 质检 → review-implementation（独立 QA）
                                                    └─ UI 质检 → ui-review（界面/视觉/可访问性）
   ↑                    ↑                        ↑                                    ↑
 模糊需求         结构化产物               设计 / 交付 / 编码                     逐批实现、可验证

可运行代码 ──→ deploy (Agent) + deploy-forge (Skill) ──→ Docker / CI / IaC / 部署文档
                                                            └─ 人工门禁：部署 / 合并 / 密钥
上线后 ──→ learn (Skill) ──→ 更新指令 / 记忆 / 待办，新需求回路由到编码

Skills

Skill 选择速查

💡 先看这里：按场景选 Skill

你的处境 / 想做的事 用谁
有产品想法或客户需求，想产出规范的产品文档 prodforge
产品文档已生成，想复核质量再进入实现 requirements-review
需要 Figma 设计原型 / 设计令牌 / 组件规格（无需设计师） design-forge
要给客户交付 SRS 需求规格说明书（合同 / 签批） srs-forge
代码已过质量验收，想生成部署产物与 runbook deploy-forge（通常由 deploy agent 执行）
里程碑 / 交付完成，想把经验固化进指令与记忆 learn
想把本次工作写成文章发布到 KnowFlow（对外分享） work-experience-summary
想了解 / 搭建七阶段流程的门禁与续跑协议 delivery-workflow

Skill 与 Agent 的关系：

  • Skill 是「领域知识 + 工作流程 + 输出模板」，告诉 AI 怎么做；Agent 是「可独立执行的子代理」，负责执行任务。
  • 你可以直接在 Copilot Chat 中触发 skill；许多 skill 也会被 agent 自动消费，无需手动调用：
Skill 被谁自动消费
delivery-workflow 所有 agent（阶段门禁、状态文件、续跑协议）
requirements-review requirements-review agent（执行依据）
deploy-forge deploy agent（部署产物协议）
design-forge build-from-product-docs（Day-1 接入令牌）+ ui-review（合规基线）
learn delivery-coordinator（阶段 7 自动调用）

delivery-workflow

定位： 为七阶段交付流程提供统一的状态文件、阶段门禁、批处理循环和跨会话续跑协议。

适用场景：

  • 需要建立或检查「需求 → 架构 → 初始化 → 开发 → 质量 → 部署 → 维护」交付流程
  • 需要创建或维护产品的 .github/delivery/<slug>.md
  • 需要定义阶段门禁、验证证据、阻塞升级和继续执行规则

典型应用场景：

场景 说明
🏁 首次启用交付流程 为产品创建 .github/delivery/<slug>.md，初始化阶段与里程碑状态
🚦 定义 / 调整门禁 定制阶段门禁的通过条件、验证证据要求与阻塞升级规则
🔎 审查流程本身 检查现有状态文件是否完整、可续跑，门禁是否被绕过
🔁 设计续跑协议 定义批次大小、验证记录格式、继续 断点恢复语义

大多数情况下由 agent 自动遵循（delivery-coordinator / build-from-product-docs / orchestrate-build 均以其为准）；直接触发主要用于搭建或审查流程本身。

核心约定：

约定 说明
状态职责 08-build-plan.md 管任务与里程碑；.github/delivery/<slug>.md 管跨阶段恢复信息
批次大小 默认每批 1-3 个强关联任务
验证规则 记录可复现命令或流程，不接受“看起来没问题”作为证据
重试上限 局部修复最多尝试 3 次；安全、数据损坏、密钥泄露等严重问题立即暂停
人工门禁 需求、架构、生产变更、密钥、部署、合并和发布必须人工确认

状态文件： 每个产品首次启用时创建 .github/delivery/<slug>.md。它记录当前阶段、里程碑、冻结决策、阻塞项、最近验证和下一步动作，不重复产品计划中的任务队列。

prodforge

定位： 将模糊的产品想法转化为结构化、可交付给编码 Agent 的产品文档。

触发场景：

  • 有一个产品 idea，不知道从哪里开始
  • 已和客户沟通并整理了需求文本，需要将其结构化为规范文档
  • 需要竞品分析来找到差异化方向
  • 需要多个产品方案（MVP / 完整版 / 差异化版）供决策
  • 需要一份 Agent 能直接读懂并实现的 PRD + 原型概要 + 架构设计

典型应用场景与提示词：

场景 示例提示词
💡 从想法开始 我有一个产品想法：<一句话描述>。帮我用 prodforge 完整分析，生成 01-08 规范文档。
📋 已有客户需求 先把需求文本放 docs/product/<slug>/00-client-requirements.md，再：读取 00-client-requirements.md，基于此运行 prodforge 完整流程，生成 01-08 规范文档。
🔎 只做竞品分析 用 prodforge 对 <产品方向> 做竞品分析，输出功能矩阵与市场缺口。
⚖️ 方案对比决策 用 prodforge 为 <产品> 生成 MVP / 完整版 / 差异化版三套方案并对比。
🧭 只做技术选型 用 prodforge 为 <产品> 推荐 2-3 个技术栈选项，附对比表。

💡 已有客户需求？ 将需求文本放在 docs/product/<slug>/00-client-requirements.md，在 prompt 中引用它："读取 00-client-requirements.md，这是我和客户沟通后整理的需求，基于此运行 prodforge 完整流程，生成 01-08 规范文档。" prodforge 会在现有需求基础上做结构化、补充和校验，而非从零发明需求，最终文档更贴合客户实际。

核心能力：

步骤 内容
1. 需求澄清 一句话产品描述 → 目标用户 → 痛点 → 平台 → 市场 → 约束
2. 需求分析 用户画像、Jobs-to-be-Done、功能需求（Must/Should/Could/Won't）、非功能需求
3. 竞品分析 5-8 个竞品、功能矩阵、市场缺口、差异化机会
4. 方案生成 3 套方案：MVP → 完整版 → 差异化版，含范围、复杂度、时间线、风险
5. 技术选型 根据平台/团队/市场推荐 2-3 个技术栈选项，附对比表
6. 产物输出 8 份标准化文档写入 docs/product/<product-slug>/

输出产物：

docs/product/<product-slug>/
├── 01-overview.md              # 产品概览：定位、用户、合规清单、Vision Anchor
├── 02-competitor-analysis.md   # 竞品分析：竞品档案、功能矩阵、市场缺口
├── 03-prd-options.md           # 方案选项：MVP / 完整版 / 差异化版
├── 04-selected-prd.md          # 确认 PRD：权限矩阵、状态机、Given-When-Then 验收标准、NFR、RTM（设计层）
├── 05-prototype-brief.md       # 原型概要：页面清单、用户流、空态/错误态、无障碍
├── 06-architecture.md          # 技术架构：数据模型、API 契约（OpenAPI + 统一错误体）、数据生命周期、部署方案
├── 07-implementation-backlog.md # 实施待办：Epic、任务、优先级、依赖
└── 08-build-plan.md            # 构建计划：里程碑、冻结决策、任务队列、RTM（实现与验证层）

关键设计： 08-build-plan.md 是 prodforge 与 build-from-product-docs agent 之间的交接协议。prodforge 生成它，agent 读它来执行实现。

文档质量门禁（Step 5f）： 产出 01-08 前，prodforge 内置一道硬门禁，按《AI 需求文档指南》的四标准（可验证 / 无歧义 / 全覆盖 / 可追溯）+ 19 项交付前清单自检，FAIL 不产出。独立的 requirements-review 复核由 delivery-coordinator 在阶段 1 门禁触发。

requirements-review

定位： 文档侧独立质检——按《AI 需求文档指南》四标准 + 10 模块 + 19 项交付前清单，审查产品文档是否达到「AI 能据此交付高质量产品」的底线，与代码侧 review-implementation 对应。

触发场景：

  • 阶段 1 门禁：进入架构设计前复核需求文档
  • prodforge 产出 01-08 后，独立复核其内置质量门禁结论
  • 手写 / 外部 PRD / SRS 交付前评估

典型应用场景与提示词：

场景 示例提示词
🚦 阶段 1 门禁 由 delivery-coordinator 自动调用；手动触发：使用 requirements-review，审查 docs/product/<slug> 的文档质量。
🔁 复核 prodforge 产物 使用 requirements-review，复核 prodforge 刚为 <slug> 生成的 01-08 文档，确认内置质量门禁结论可信。
📄 外部文档评估 使用 requirements-review，审查 docs/product/<slug>/SRS.md，评估是否达到可交付客户的标准。

审查内容：

维度 检查
四标准 可验证 / 无歧义 / 全覆盖 / 可追溯
关键契约 权限矩阵、状态机（含非法流转 + 错误码）、NFR-XXX 量化、统一错误体、OpenAPI、RTM
交付前清单 19 项逐条核对
原型质量 05-prototype-brief.md 必备章节 + visual fit / interaction 评分（≥ 4.0，无单项 < 3）

产出： pass / conditional pass / fail 裁决 + 按 critical / major / minor 排序的必修项。由 delivery-coordinator 在阶段 1 门禁自动调用，也可直接触发。

design-forge

定位： 将 PRD + 原型概要转换为 Figma AI 就绪的设计资产，无需设计师即可在 Figma 中生成 UI 原型。

触发场景：

  • 产品文档已生成，需要视觉原型用于客户演示或设计评审
  • 需要一套可直接导入 Figma 的设计令牌（Tokens Studio 格式）
  • 需要组件规格清单来指导 Figma 组件库搭建
  • 为非设计师提供「复制粘贴即可用」的 Figma Make Prompt

典型应用场景与提示词：

场景 示例提示词
🎨 全套设计资产 帮我对 docs/product/<slug> 用 design-forge 生成 Figma 原型 prompt、设计令牌和组件规格。
🎛️ 品牌定制 用 design-forge 生成设计资产，主色 #0F766E、字体 Inter，其余按产品风格推断。
📐 只要组件规格 用 design-forge 为 <slug> 生成组件规格清单，指导 Figma 组件库搭建。

核心能力：

步骤 内容
1. 输入验证 检查 04-selected-prd.md + 05-prototype-brief.md 是否存在
2. 设计系统推断 基于产品风格关键词推断色彩/字体/间距/圆角/阴影系统
3. Figma Prompt 生成 逐页生成自包含的 Figma AI prompt 块，含布局、组件、状态、交互
4. 设计令牌生成 输出 Tokens Studio v2 兼容 JSON，一键导入 Figma
5. 组件规格生成 含变体、状态、尺寸的组件清单，映射 Figma 组件属性

输出产物：

docs/product/<product-slug>/
├── 09-figma-prompts.md       # Figma AI 逐页设计 Prompt
├── 09-design-tokens.json     # Tokens Studio 设计令牌 JSON（实现的单一事实来源）
├── 09-component-spec.md      # 组件规格清单
└── 09-design-system.md       # 实现侧设计系统交接（供 build + ui-review 消费）

前置依赖： 需要 prodforge 已生成 04-selected-prd.md 和 05-prototype-brief.md。 实现侧消费： 09-design-tokens.json 是代码实现的单一事实来源，由 build-from-product-docs 在 Day-1 接入；ui-review 在阶段 5 校验渲染 UI 是否与其一致。

srs-forge

定位： 将 8 份产品文档整合为一份面向客户的《软件需求规格说明书》(SRS)，适用于甲方交付、合同附件或干系人签批。

触发场景：

  • 需要向外部客户交付正式的需求文档
  • 合同签订前需要一份可签批的功能范围说明
  • 需要将内部 AI 实现文档转译为业务语言
  • 需要带有版本控制、术语表和签批清单的专业文档

典型应用场景与提示词：

场景 示例提示词
📃 客户交付 帮我把 docs/product/<slug> 的产品文档整合成一份客户可签批的 SRS。
✍️ 合同附件 用 srs-forge 为 <slug> 生成 SRS，作为合同附件的功能范围说明。
🌐 业务语言转译 把 <slug> 的 AI 实现文档转译成业务语言，供非技术干系人评审。

核心能力：

步骤 内容
1. 输入验证 检查 01-07 号产品文档是否存在
2. 内容映射 将 8 份 AI 实现文档映射到 14 章 SRS 结构
3. 缺失补充 生成文档控制、非功能需求（NFR-ID）、术语表、验收标准汇总等客户所需章节
4. 质量门 完整性 / 可读性 / 可追溯性 / RTM / NFR / 范围清晰度 / 文档控制 / 术语表 八项检查
5. 输出 SRS 生成单份 SRS.md（14 章），15-30 页，含签批区

输出产物：

docs/product/<product-slug>/
└── SRS.md                     # 客户交付级软件需求规格说明书（14 章）

SRS 章节结构：

# 章节 来源
0 文档控制（版本/审批/修订历史） 生成
1 项目概述 01-overview.md
2 目标用户、角色与权限矩阵 01-overview.md + 04-selected-prd.md
3 市场背景 02-competitor-analysis.md
4 功能需求 04-selected-prd.md
5 核心用户流程与状态机 04-selected-prd.md
6 UI/UX 规格 05-prototype-brief.md
7 技术架构 06-architecture.md
8 数据模型 06-architecture.md
9 非功能需求 生成 + 04-selected-prd.md
10 交付计划与里程碑 07-implementation-backlog.md
11 术语表 生成
12 验收标准汇总 04-selected-prd.md
13 范围边界与假设 04-selected-prd.md + 生成
14 需求追踪矩阵 04-selected-prd.md + 生成

前置依赖： 需要 prodforge 已生成 01-07 号产品文档。

deploy-forge

定位： 将已通过质量门禁的实现转化为可部署产物（阶段 6），覆盖 Dockerfile、环境变量、CI/CD、IaC 与部署文档，并在部署/合并/密钥处设置人工门禁。

触发场景：

  • 阶段 5 质量检查已通过，准备上线
  • 需要生成多阶段 Dockerfile、.env.example、CI/CD 流水线或 IaC
  • 需要一份从干净环境一键部署的 runbook 与回滚方案

典型应用场景与提示词：

场景 示例提示词
🚢 全套部署产物 用 deploy-forge 为 <slug> 生成 Dockerfile、.env.example、CI/CD、IaC 和部署文档。
📦 只要部分产物 只生成 Dockerfile 和 docker-compose.yml，其他先不要。
🧭 部署 runbook 为 <slug> 写一份从干净环境一键部署的 runbook，含密钥清单与回滚方案。

通常无需手动触发：deploy agent 遵循此协议自动执行；直接触发适用于只想要产物、不走 agent 的场景。

核心产物：

Dockerfile                    # 多阶段构建，构建依赖与运行时分离
.env.example                  # 全量环境变量分组 + 注释，仅占位符
.github/workflows/ci.yml      # 构建 + 测试
.github/workflows/deploy.yml  # 部署流水线（平台允许处加人工审批）
docker-compose.yml 或 IaC     # 本地编排或云端模板
docs/deployment.md            # 一键部署 runbook + 密钥清单 + 回滚方案

硬门禁： 产物准备与本地 build/up + smoke 可自动；实际部署、合并、发布、真实密钥必须人工批准，绝不写入真实密钥。

learn

定位： 阶段 7 维护迭代——把已完成里程碑的经验沉淀为稳定约定，并将新 Bug / 新需求路由回阶段 4。

触发场景：

  • 一个里程碑或整条交付完成后，需要复盘沉淀
  • 反复出现的约定需固化进 copilot-instructions.md
  • 构建命令、坑点、架构事实需写入仓库记忆
  • 审查中发现的新 Bug / 新需求需要回到待办

典型应用场景与提示词：

场景 示例提示词
📈 里程碑复盘 对 docs/product/<slug> 跑一次 learn，把已验证的经验写进 copilot-instructions.md 和仓库记忆。
🐞 新需求回路由 跑 learn，把 review 发现的新 Bug / 新需求写回 07-implementation-backlog.md，重新进入阶段 4。
🧰 固化构建约定 把 <slug> 反复出现的构建/启动命令和坑点固化进指令与记忆。

阶段 7 由 delivery-coordinator 自动调用；也可在里程碑完成后手动触发。

核心动作：

动作 目标
更新项目指令 copilot-instructions.md 固化命名、构建/测试/启动命令、安全红线
更新记忆 /memories/repo/ 记录构建命令、坑点、架构事实
沉淀 Skill 为重复流程补写或新增 Skill
回路由待办 新 Bug / 新需求写入 07-implementation-backlog.md，重新进入阶段 4

规则： 只沉淀已验证事实；优先更新现有文件而非新建；条目精简；不改动 04-selected-prd.md / 06-architecture.md 范围。

work-experience-summary

定位： 把一次「agent 编码 / 修 bug / 解决问题」的工作沉淀为一篇结构化复盘文章，并发布到 KnowFlow 的 SmartWingTech 空间（对外分享），与 learn（对内沉淀）互补。

触发场景：

  • 想总结本次会话 / 一个里程碑的工作经验
  • 想把踩坑与解决方案写成文章发布到 KnowFlow
  • 想对外分享可复用的工程经验

典型应用场景与提示词：

场景 示例提示词
📝 会话总结 用 work-experience-summary 总结本次会话的工作（改了哪些代码、修了哪些 bug），发布到 KnowFlow。
📤 里程碑复盘发布 总结 <slug> M2 的实现经验并发布到 KnowFlow，tags 用 <slug>、部署、复盘。
✍️ 只写草稿不发布 先按复盘模板生成草稿存到 artifacts/，发布前给我确认。

核心流程：

步骤 内容
1. 收集事实 会话工作 + 交付文件（.github/delivery/<slug>.md、08-build-plan.md、git log），只采信可核实事实
2. 成稿 按「背景 → 产出 → 踩坑与修复（现象/根因/修复/经验四段式）→ 结论」模板生成 Markdown
3. 落盘 写入 artifacts/<YYYY-MM-DD>-<主题>.md
4. 发布 knowflow publish <file.md> --space smartwingtech --title "..." --tags <tags>（CLI 从环境变量读密钥）

输出： 草稿文件 + KnowFlow 文章绝对 URL。发布前默认等用户确认；用户说「直接发布」才跳过。

与 learn 的区别： learn 对内沉淀（更新 copilot-instructions.md / 记忆 / 待办）；本 skill 对外发布文章。如需两者都做：先跑本 skill 发布，再跑 learn 更新内部资产。

Agents

Agent 选择速查

💡 先看这里：按场景选 Agent

你的处境 / 想做的事 用谁
刚有一个产品想法，想全流程推进（需求 → 架构 → 代码 → 部署） delivery-coordinator（总协调，替你路由各入口）
已有想法或需求文本，想先产出规范的产品文档 prodforge skill
文档写完了，想确认质量是否达到「可交付实现」的底线 requirements-review
产品文档就绪，准备开始写代码（单模块 / 小项目） build-from-product-docs
产品文档就绪，但系统很大（多服务 / 多平台 / 多模块） orchestrate-build
开发中断了，想接着做 直接回复「继续」，或让 delivery-coordinator 恢复
一批代码写完，想独立验收（防「自己写自己验」偏差） review-implementation
本批改了页面，想独立验收视觉 / 交互 / 响应式 / 无障碍 ui-review
阶段 5 验收通过，准备部署上线 deploy
上线 / 里程碑完成，想沉淀经验、处理新 Bug learn skill
要给客户交付需求文档 / 设计稿 srs-forge / design-forge skill

一句话原则：

  • 不确定下一步 → 问 delivery-coordinator
  • 写代码 → build-from-product-docs（小）/ orchestrate-build（大）
  • 查质量 → requirements-review（文档）/ review-implementation（代码）/ ui-review（界面）
  • 交付 → deploy（部署）/ srs-forge + design-forge（文档与设计）

build 与 orchestrate 怎么选：

判断维度 build-from-product-docs orchestrate-build
可部署单元 1 个 2 个以上
模块数 < 3 ≥ 3（3-5 个可用 Lite Mode）
平台 单一平台 多平台（Web + 小程序 + App…）
独立质检 仅自检，可手动追加 review-implementation 每批独立审查（全模式）/ 里程碑全量（Lite）

delivery-coordinator

定位： 从零到一交付流程的总协调 Agent，负责判断当前阶段、选择执行入口、推进批次、运行门禁并维护可续跑状态。它不直接编写业务功能。

触发场景：

  • 从产品想法推进到可交付软件
  • 恢复之前中断的交付流程
  • 检查当前处于哪个阶段或里程碑
  • 执行质量门禁、准备部署交付或更新进度

典型应用场景与提示词：

场景 示例提示词
🆕 从零到一推进 使用 delivery-coordinator，从 docs/product/<slug> 开始，推进到下一道人工门禁。
🔁 中断恢复 直接回复 继续（或 使用 delivery-coordinator，继续推进 <slug>。），它会重读状态文件执行下一步，无需重复原始提示词
📍 状态查询 使用 delivery-coordinator，检查 <slug> 当前处于哪个阶段、有哪些阻塞，下一步该做什么。
🚦 执行门禁 使用 delivery-coordinator，对 <slug> 跑阶段 5 质量门禁。
🔀 入口不明 不确定下一步该用哪个 agent 时，先问它：「 接下来该做什么、走哪个入口？」

路由规则：

场景 使用入口
阶段 1 文档质量门禁 requirements-review（独立复核，fail 不进阶段 2）
单一可部署单元、小型项目 build-from-product-docs
多服务、多平台或多模块项目 orchestrate-build
实现完成后的独立验收 review-implementation
UI 批次 / 里程碑的视觉验收 ui-review（在 review-implementation 之后）
部署交付（阶段 6） deploy（遵循 deploy-forge 协议）
维护迭代（阶段 7） learn skill

协作规则：

  • 每次开始先读取产品的 .github/delivery/<slug>.md、产品文档、08-build-plan.md 和项目指令
  • 每批完成后同步状态、记录验证证据和下一步动作
  • 维护需求追踪矩阵（RTM）：每个发布范围 REQ/NFR 在 08-build-plan.md 有实现位置与验收证据，阶段 5 前无空缺
  • 用户回复「继续」时，重新读取状态文件并执行下一项，不要求重复原始提示词
  • 里程碑门禁未完全通过时，不进入下一里程碑
  • 需求/架构确认、部署、生产数据、密钥、合并和发布始终保留人工审批

requirements-review

定位： 独立的需求文档审查 / QA Agent，对抗「文档作者自评合格」的偏差。只审查、复检、报告，不写需求、不改文档。

触发场景：

  • 需求文档进入实现前需要独立质量复核
  • 阶段 1 门禁（由 delivery-coordinator 委派）

典型应用场景与提示词：

场景 示例提示词
🔍 实现前把关 prodforge 产出 01-08 后、交给 build agent 前：使用 requirements-review，审查 docs/product/<slug> 的文档质量，给出 pass/fail 和必修项。
📄 外部文档评估 客户 / 外包提供的 PRD 或 SRS，签批或交付前评估：使用 requirements-review，审查 docs/product/<slug>/SRS.md，评估是否达到可交付客户的标准。
🧾 手写文档复核 自己手写需求后，检查权限矩阵、状态机、NFR、RTM 是否齐全、可测试、可追溯

核心行为：

  • 盘点 10 大模块结构，逐项核对 19 项交付前清单
  • 抽查 ID 稳定性、验收可测试性、状态机 / 权限矩阵 / NFR / RTM 落地性
  • 按四标准归类发现，给 pass / conditional pass / fail + must-fix

边界： 只读审查；修复由 prodforge 或文档作者完成，之后复检。

build-from-product-docs

定位： 基于产品文档，按里程碑逐批实现代码，确保每一步都可验证、可暂停、可调整。

触发场景：

  • prodforge 已生成完整产品文档，准备开始编码
  • 有一个已有的 docs/product/<slug>/ 目录，需要开始实现
  • 需要监督式自动推进：每批 1-3 个任务，完成后自动验证并等待确认

典型应用场景：

场景 说明
🏗️ 新项目开工 文档就绪，从 08-build-plan.md 的 Current Milestone 开始，先过脚手架 Day-1 工程闸门
🔁 日常推进 每批完成后回复「继续」，自动读 build plan 执行下一批，无需重复提示词
🎯 指定批次 可指定只做某几个任务：只实现当前 milestone 中的 T-12、T-13。
🔧 修复审查反馈 修复 review-implementation 对本批提出的 major 必修项，并重跑验证。
🧪 Mock 先行 外部服务（AI / 支付 / 存储）先以 mock 适配器推进，不被真实接入阻塞
🚀 全自动跑完 说「一口气完成」（可加「到 M3」），连续推进批次并跨里程碑自动门禁，硬阻断才停

核心行为约束：

规则 说明
🔒 不跨里程碑 只实现 Current Milestone，绝不跳到下一个
📦 逐批实现 每批 1-3 个强关联任务，不试图一次写完整个产品
✅ 每批验证 完成后运行 typecheck / lint / build / test
📝 持续记录 更新 08-build-plan.md 的任务状态、完成记录、验证结果
🛑 关键决策暂停 遇到重大产品/架构/安全/支付/部署决策时，停下来让用户决策
🔄 免重复提示 用户只需说「继续」，agent 自动读取 08-build-plan.md 执行下一批
🚀 全自动构建 用户说 一口气完成，连续推进批次并跨里程碑自动门禁；遇硬阻断停下，继续全自动 恢复
🧪 Mock 优先 外部服务（AI、天气、支付、存储）先用 mock 适配器，不阻塞进度

契约型输入消费： 04 文档中的权限矩阵 → 越权测试；状态机（含非法流转）→ FSM 测试；NFR-XXX → NFR 验证；RTM → 每批更新实现与验证层。API 统一错误体为 { code, message, details?, trace_id }。

默认技术栈（当架构文档未明确时）：

场景 默认选择
前端 Web Next.js + TypeScript + Tailwind CSS
后端 API Hono + TypeScript
本地数据库 SQLite + Prisma
生产数据库 PostgreSQL
外部存储 本地文件系统 / mock 适配器 → 后续升级云存储
AI 服务 mock 适配器 → 后续接入真实模型

环境策略（Day 1 起）：

环境 日志级别 CORS 限流 错误详情 数据库
Development debug localhost:* 关闭 完整堆栈 本地
Test silent/warn 测试源 关闭 最小化 隔离测试库
Production info 严格白名单 开启 脱敏 生产库

代码架构标准（非协商项）：

  • 按功能模块组织代码（feature-based），非按文件类型
  • 严格三层架构：Controller → Service → Repository
  • 所有外部服务走 Adapter 接口（先 mock，后真实）
  • TypeScript 严格模式、禁止 any、公开函数显式返回类型
  • API 统一错误格式、OpenAPI 文档自动生成

Day-1 工程闸门（脚手架阶段强制）：

  • CI workflow（.github/workflows/ci.yml）：typecheck / lint / test / build / 依赖审计
  • 供应链：依赖审计 + 锁文件入库 + SAST 基线 + pre-commit hook

设计令牌闭环： 若 docs/product/<slug>/ 存在 09-design-tokens.json / 09-component-spec.md，agent 在 Day-1 即把设计令牌接入代码（按平台映射主题），冲突时以令牌文件为准。

平台规范按需加载： 默认 Web 栈（TS 后端 + Next.js）规范内置；其他平台（微信小程序 / Flutter / uni-app / Python FastAPI / Dart Frog）的规范与脚手架抽到 .github/agents/references/platform-*.md，实现前按需读取，保持 agent 精简。

里程碑集成闸门（DoD）： 单个任务的逐批验证之外，里程碑收尾需通过集成闸门——主用户流端到端跑通、跨特性集成、空库迁移回读、基线全绿、上一里程碑回归——通过后才能进入下一里程碑。

如何使用：

模式 触发 行为
监督式逐批 直接传入产品文档目录 每批 1-3 个任务，完成后询问「继续 / 暂停 / 调整」
全自动构建 说 一口气完成（可加 到 M3） 连续推进批次并跨里程碑自动门禁，不再逐个询问

示例：

  • 开始：使用 build-from-product-docs，读取 docs/product/ai-wardrobe 的产品文档，从 08-build-plan.md 的 Current Milestone 开始。
  • 继续下一批：回复 继续
  • 一口气跑完：回复 一口气完成
  • 中断后恢复 / 退出：回复 继续全自动 / 暂停

适用 / 不适用：

  • ✅ 单一可部署单元、单一技术栈、模块 < 3、无需跨模块并行
  • ❌ 多服务 / 多平台 / 模块 ≥ 3 → 交给 orchestrate-build

边界： 只做当前 milestone 内的批次；不写真实密钥、不部署、不跨模块；独立质检需由 orchestrate-build 派发（单 agent 模式仅自检）。

orchestrate-build

定位： 面向大型 / 多模块 / 多服务产品的构建编排器，用于单一线性循环顶不住的复杂项目。

触发场景：

  • 系统包含多个可独立部署的模块（如 Web + 移动端 + 后端，或多个微服务）
  • 跨模块依赖复杂、里程碑多、需要并行实现
  • 需要把架构拆成模块并按依赖顺序推进

典型应用场景：

场景 说明
🏢 多服务系统 前端 + 后端 + 定时任务等多个可部署服务
📱 多平台产品 Web + 微信小程序 + App + API 同时交付
🧩 多模块 monorepo 3 个以上可独立推进的模块，单一线性循环顶不住
🏗️ 大型单仓库 里程碑多、依赖复杂，需要任务 DAG 编排与并行实现
⚡ 中型项目 Lite 3-5 个模块时用 Lite Mode，里程碑边界做全量审查，降低开销

核心行为：

能力 说明
🧩 模块拆分 将系统拆为模块，把共享契约（API/类型/Schema）提为一等节点
🔗 任务 DAG 按依赖构建有向无环图，分波次拓扑派发
⚙️ 派发 worker 把模块工作交给 build-from-product-docs 实现，安全处并行
🔍 独立质检 每波后调用 review-implementation 复核；UI 模块追加 ui-review 视觉审查
🚪 集成闸门 里程碑级集成/E2E 闸门通过后才推进（含统一错误体 + RTM 跨模块一致性）
🚀 全自动编排 说 一口气完成 连续派发批次并跨里程碑自动门禁，硬阻断停下后 继续全自动 恢复
🗂️ 编排索引 在 08-build-plan.md 维护模块表 + Mermaid DAG，模块计划放 build-plans/<module-id>.md

如何使用：

模式 触发 行为
监督式编排 直接传入产品文档目录 按 DAG 派发 worker，每波独立审查，milestone 边界询问
全自动编排 说 一口气完成 连续派发批次并跨里程碑自动门禁，硬阻断停下后 继续全自动 恢复

示例：

  • 开始：使用 orchestrate-build，读取 docs/product/<slug> 的产品文档，拆分模块并编排当前 milestone 的实现。
  • 一口气跑完：回复 一口气完成；中断后回复 继续全自动，退出回复 暂停

它自己写码吗？ 不写。orchestrate-build 只拆分、派发、验收；代码由它派发的 build-from-product-docs worker 写，独立质检由 review-implementation（UI 模块再加 ui-review）做。

Lite Mode（3-5 模块中型项目）： 每批跳过独立审查，只在 milestone 边界做全量 review-implementation + ui-review；涉及安全 / 支付 / 数据迁移 / 共享契约时仍用全模式（每批审查）。

review-implementation

定位： 独立的 QA / 审查 Agent，用于抵消「自己写、自己验」的自验证偏差。只复核，不写码。

触发场景：

  • 一批代码实现完成后，需要独立验收
  • 编排构建中每波实现完成后的质检环节

典型应用场景与提示词：

场景 示例提示词
🧪 批次验收 使用 review-implementation，审查 <slug> 最近一批实现，对照 08-build-plan.md 的 Feature Verification Matrix 和 04-selected-prd.md 的验收标准。
🔎 单 agent 追加复核 用 build-from-product-docs 单跑时，手动追加独立复核，抵消自检偏差
🔒 高风险模块 鉴权 / 支付 / 数据删除 / 共享契约模块：使用 review-implementation，专项审查 <slug> 的 auth 模块越权测试与状态机非法流转测试。
🕵️ 编排质检 orchestrate-build 每波（或里程碑边界）自动派发，无需手动触发

审查流程：

步骤 内容
1 需求可追溯性：实现是否覆盖对应 REQ
2 独立重跑验证（typecheck / lint / test / build / audit）
3 审计 Feature Verification Matrix 证据真实性
4 验收标准行为核对（含错误体 / 状态码 / 幂等）
5 安全 / 隐私基线检查
6 边界 / 共享契约完整性（编排构建场景）
7 标准遵循度
8 越权与非法流转测试（权限矩阵 / 状态机存在时）
9 NFR 证据与 RTM 覆盖

产出： pass / fail 裁决 + 按严重度（critical / major / minor）排序的必修项清单。

ui-review

定位： 独立的 UI/UX 审查 Agent，把视觉与交互质量变成可打分、可复现的检查，对抗「看起来不错」的自证偏差。只审查、截图、报告，不修代码、不重设计。

触发场景：

  • 一批涉及用户可见 UI 的改动完成后，需要独立视觉 / 交互验收
  • 里程碑边界对 UI 模块做设计一致性 / 响应式 / 可访问性复核

典型应用场景与提示词：

场景 示例提示词
🎨 UI 批次验收 使用 ui-review，审查 <slug> 最近一批 UI 改动，对照 05-prototype-brief.md 与 09-design-tokens.json，输出三档截图证据。
📐 里程碑 UI 走查 里程碑边界对全部 UI 模块做设计一致性 / 响应式 / 可访问性全面走查
🎯 设计令牌审计 检查业务组件是否硬编码色值 / 间距 / 圆角 / 阴影，是否忠于 09-design-tokens.json
♿ 可访问性专项 使用 ui-review，对 <slug> 的登录与注册页面做可访问性专项审查。

审查维度：

维度 检查
视觉契合 / 交互质量 按 prototype-quality-gate.md 各 8 项打分（均分 ≥ 4.0，无单项 < 3）
设计令牌合规 业务组件不硬编码色值 / 间距 / 圆角 / 阴影，渲染值来自 09-design-tokens.json
组件一致性 单一图标库、复用共享组件、组件覆盖全交互状态
状态覆盖 loading / empty / error / disabled / success / partial 六态齐备
响应式 桌面 / 平板 / 移动三档无重叠溢出，移动端主操作可达
可访问性 WCAG 2.2 AA：键盘、focus、label、对比度、弹窗焦点管理
视觉资产 文字 logo、头像 initials、空态插画、无灰矩形占位

产出： pass / fail 裁决 + 按严重度排序的必修项 + 可审查证据（三档截图、对比度数值、硬编码 grep 结果）。major 未解决即 fail（硬门禁）；主观项无法取证时标 unverified，要求人工 walkthrough。

deploy

定位： 阶段 6 部署执行者，按 deploy-forge 协议生成部署产物、本地构建 + 冒烟验证，并在部署/合并/密钥处暂停交人工。

触发场景：

  • 阶段 5 验收通过，准备部署交付
  • 需要生成 Dockerfile、CI/CD、IaC 并本地验证

典型应用场景与提示词：

场景 示例提示词
🚢 上线准备 使用 deploy agent，读取 docs/product/<slug> 的产品文档，生成部署产物并在本地完成 build/up + 冒烟验证。
📦 多目标部署 使用 deploy agent，为 <slug> 生成 Kubernetes 部署清单和 CI/CD 流水线。
🧪 本地预演 本地 docker build + compose up + 冒烟，验证部署产物可用后暂停等人工批准
🔑 密钥梳理 产出完整密钥清单与 .env.example 占位符，供人工在部署前配置

职责边界：

可自动 必须人工
生成 Dockerfile / .env.example / CI/CD / IaC / 文档 部署到 staging / production
本地 docker build + compose up + smoke git push / merge / tag / release
记录验证证据并更新 08-build-plan.md、.github/delivery/<slug>.md 使用或写入真实密钥

硬边界： 不写业务代码；不部署、不推送、不合并、不碰真实密钥；不执行破坏性命令。

常见组合用法

目标 推荐组合
全流程交付 delivery-coordinator 总协调 → prodforge → requirements-review → build-from-product-docs / orchestrate-build → review-implementation → ui-review → deploy → learn
只想快速出代码 prodforge → build-from-product-docs（关键批次手动追加 review-implementation）
大型项目交付 prodforge → orchestrate-build（内部自动派发 worker + review-implementation + ui-review）
对外文档 / 设计交付 prodforge → srs-forge + design-forge → requirements-review 复核
维护迭代 learn → 更新指令 / 记忆 / 待办 → 新需求回到 build-from-product-docs（阶段 4）

完整工作流

flowchart TB
    A[💡 产品想法] --> B[prodforge Skill]
    B --> C{需求澄清}
    C --> D[竞品分析]
    D --> E[生成 3 套方案]
    E --> F{用户确认方案}
    F --> G[技术选型]
    G --> H[生成 8 份产品文档]
    H --> I1[design-forge Skill]
    H --> I2[srs-forge Skill]
    H --> SCALE{项目规模?}
    SCALE -->|小型/单模块| I3[build-from-product-docs Agent]
    SCALE -->|大型/多模块| ORCH[orchestrate-build Agent]
    I1 --> J1[Figma 设计令牌 + Prompt + 组件规格]
    I2 --> J2[客户交付 SRS 文档]
    ORCH --> DAG[模块拆分 + 任务 DAG]
    DAG --> I3
    I3 --> J3[读取 08-build-plan.md]
    J3 --> K[执行当前批次 1-3 个任务]
    K --> L[运行验证]
    L --> M{验证通过?}
    M -->|是| N[更新 build plan]
    M -->|否| O[修复 → 重验证]
    N --> REV[review-implementation 独立质检]
    REV --> UIREV[ui-review UI 审查（涉及界面时）]
    UIREV --> P{里程碑完成?}
    P -->|否| Q[询问: 继续/暂停/调整]
    Q -->|继续| J3
    P -->|是| GATE[里程碑集成闸门]
    GATE --> R[汇报结果，询问下一里程碑]
    R -->|进入阶段 6| DEP[deploy Agent + deploy-forge Skill]
    DEP --> DEPGATE{部署 / 合并 / 密钥}
    DEPGATE -->|人工批准| DEPLOYED[部署产物 + 上线]
    DEPLOYED -->|进入阶段 7| LRN[learn Skill]
    LRN --> BACK[更新指令 / 记忆 / 待办，新需求回路由]
    BACK --> J3

全自动模式：编码阶段（build-from-product-docs / orchestrate-build）说 一口气完成，图中「询问：继续/暂停/调整」与「询问下一里程碑」改为自动推进；部署（DEPGATE）与密钥 / 支付 / 数据删除等硬阻断仍保留人工门禁，中断后回复 继续全自动 恢复。

项目结构

softjob/
├── .github/
│   ├── agents/
│   │   ├── delivery-coordinator.agent.md    # 七阶段交付总协调器
│   │   ├── requirements-review.agent.md       # 独立需求文档质检 Agent（阶段 1 门禁）
│   │   ├── build-from-product-docs.agent.md   # 编码实现 Agent（单模块 / worker）
│   │   ├── orchestrate-build.agent.md         # 大型/多模块构建编排器
│   │   ├── review-implementation.agent.md     # 独立 QA / 质检 Agent
│   │   ├── ui-review.agent.md                 # 独立 UI/UX 审查 Agent（视觉/响应式/可访问性）
│   │   ├── deploy.agent.md                    # 部署执行 Agent（阶段 6）
│   │   └── references/                         # 按需加载的平台规范 + 脚手架
│   │       ├── platform-wechat-miniprogram.md
│   │       ├── platform-flutter.md
│   │       ├── platform-uniapp.md
│   │       ├── platform-python-fastapi.md
│   │       └── platform-dart-frog.md
│   └── skills/
│       ├── delivery-workflow/
│       │   └── SKILL.md                        # 状态文件、阶段门禁、续跑协议
│       ├── prodforge/
│       │   ├── SKILL.md                        # 产品构思 → 8 份产品文档
│       │   └── references/
│       │       ├── output-templates.md         # 8 份产品文档模板
│       │       └── prototype-quality-gate.md   # 原型质量门检查清单
│       ├── requirements-review/
│       │   └── SKILL.md                        # 文档质量门禁（四标准 + 19 项清单）
│       ├── design-forge/
│       │   ├── SKILL.md                        # PRD + 原型 → Figma 设计资产
│       │   └── references/
│       │       └── output-templates.md         # Figma Prompt / 令牌 / 组件模板
│       ├── srs-forge/
│       │   ├── SKILL.md                        # 产品文档 → 客户交付 SRS
│       │   └── references/
│       │       └── srs-template.md             # 14 章 SRS 模板
│       ├── deploy-forge/
│       │   └── SKILL.md                        # 部署产物 → Docker / CI / IaC / 部署文档
│       ├── learn/
│       │   └── SKILL.md                        # 经验沉淀 + 新需求回路由
│       └── work-experience-summary/
│           └── SKILL.md                        # 工作总结 → KnowFlow 文章发布
│   ├── copilot-instructions.md                 # 仓库级稳定约定（阶段 3 固化，阶段 7 精炼）
├── docs/
│   └── product/
│       ├── ai-wardrobe/                        # 示例：AI 衣橱
│       ├── followfocus/                        # 示例：FollowFocus（含 design-forge 产物）
│       │   ├── 01-overview.md ~ 08-build-plan.md
│       │   ├── 09-figma-prompts.md
│       │   ├── 09-design-tokens.json
│       │   ├── 09-component-spec.md
│       │   └── 09-design-system.md
│       └── leadforge/                          # 示例：LeadForge
└── README.md

快速上手

不确定用哪个 skill / agent？先看 Skill 选择速查 和 Agent 选择速查。

第一步：从想法（或已有需求）到产品文档

场景 A：从模糊想法开始

在 VS Code 中打开 Copilot Chat，输入你的产品想法，并触发 prodforge skill：

我有一个产品想法：做一个 AI 衣橱管理 app，用户可以拍照上传衣服，AI 自动识别分类，并推荐每日穿搭。帮我用 prodforge 分析一下。

prodforge 会引导你完成需求澄清 → 竞品分析 → 方案选项 → 确认 PRD → 生成全套 8 份文档。

场景 B：已有客户需求文本

如果你已和客户沟通并整理了一份需求文档，先把它放入 docs/product/<slug>/：

docs/product/<slug>/
└── 00-client-requirements.md   # 客户沟通整理的需求文本

然后在 Copilot Chat 中：

读取 docs/product//00-client-requirements.md，这是我和客户沟通后整理的需求，基于此运行 prodforge 完整流程，生成 01-08 规范文档。

区别在于：prodforge 会从你的需求文本中提取信息（澄清问题更少），跳过「从零发明」，直接进入结构化、竞品分析、方案对比、可行性评审环节，最终输出的文档质量更高、更贴合客户实际。

场景 A：模糊想法 场景 B：已有需求文本
Step 1 澄清问题 可能需要 4 个 通常 0-2 个
需求分析 依赖 AI 推断 更精准，偏差更小
竞品分析 / 方案对比 同左（均为核心价值） 同左
整体流程 需要更多来回确认 更快

文档质量门禁： prodforge 产出 01-08 前会内置自检（四标准 + 19 项清单）。如需独立复核（推荐交付前），触发 requirements-review："审查 docs/product/ 的文档质量。" 走 delivery-coordinator 流程时，阶段 1 门禁会自动委派它。

第二步（可选）：生成 Figma 设计资产

产品文档生成后，如需视觉原型用于客户演示或设计评审，触发 design-forge skill：

帮我对 docs/product/ai-wardrobe 用 design-forge 生成 Figma 原型 prompt 和设计令牌。

design-forge 会生成：09-figma-prompts.md（逐页 prompt）、09-design-tokens.json（Tokens Studio，实现侧单一事实来源）、09-component-spec.md（组件规格）、09-design-system.md（实现侧设计系统交接）。

第三步（可选）：生成客户交付 SRS

如需向客户交付正式需求文档，触发 srs-forge skill：

帮我把 docs/product/ai-wardrobe 的产品文档整合成一份客户可签批的 SRS。

srs-forge 会生成一份 13 章的 SRS.md，含文档控制、术语表、验收标准签批清单。

第四步：从文档到代码

文档就绪后，推荐先使用 delivery-coordinator 统一判断当前阶段和执行入口：

使用 delivery-coordinator，读取 docs/product/ 和当前交付状态，继续推进项目；只在需求、架构、部署或发布门禁处暂停。

如果不需要总协调，也可以按项目规模直接选择实现方式（速查见 Agent 选择速查）：

小型 / 单模块——在 Copilot Chat 中触发 build-from-product-docs agent：

使用 build-from-product-docs agent，读取 docs/product/ai-wardrobe 下的产品文档，从 08-build-plan.md 的 Current Milestone 开始执行。

大型 / 多模块 / 多服务——触发 orchestrate-build agent，由它拆分模块、构建 DAG、派发 worker 并质检：

使用 orchestrate-build agent，读取 docs/product/ 下的产品文档，拆分模块并编排当前里程碑的实现。

Agent 会：

  1. 读取所有产品文档和 build plan
  2. 选择下一批任务（1-3 个）
  3. 实现代码
  4. 运行验证
  5. 更新 build plan（编排场景下调用 review-implementation 独立质检；UI 批次追加 ui-review）
  6. 询问：继续下一批 / 暂停 / 调整任务

你只需回复「继续」，agent 就会自动推进，无需重复输入提示词。

全自动完成： 想在编码阶段一口气跑完，直接说 一口气完成（可加目标，如 一口气完成到 M3）。agent 会连续推进批次并跨里程碑自动跑门禁，不再逐个询问；只有硬阻断（部署 / 合并 / 发布、真实密钥与付费外部服务、支付 / 数据删除等高风险模块、critical 失败、验证熔断）才停下。中断后回复 继续全自动 即可从断点恢复，暂停 / 退出全自动 则退出该模式。

跨会话状态： 启用 delivery-coordinator 后，每个产品的进度保存在 .github/delivery/<slug>.md；产品任务和里程碑仍以 docs/product/<slug>/08-build-plan.md 为准。两者会在每批或每波完成后同步。

第五步：部署交付（阶段 6）

阶段 5 质量验收通过后，触发 deploy agent（遵循 deploy-forge 协议）：

使用 deploy agent，读取 docs/product/ 的产品文档，生成 Dockerfile、.env.example、CI/CD 和部署文档，并在本地验证。

deploy 会自动生成部署产物并本地 build/up + 冒烟验证；实际部署、合并、发布、真实密钥会在人工门禁处暂停，由你确认。

第六步：维护迭代（阶段 7）

上线或里程碑完成后，触发 learn skill 做经验沉淀：

对 docs/product/ 跑一次 learn，把已验证的经验写进 copilot-instructions.md 和仓库记忆，并把新 Bug/新需求路由回待办。

learn 会更新项目指令、仓库记忆、既有 Skill，并把新需求写回 07-implementation-backlog.md 重新进入阶段 4。

持续迭代

  • 每批完成后检查代码变更
  • 里程碑完成后确认是否进入下一个
  • 如需调整需求，回到 prodforge 更新文档
  • 新 Bug / 新需求经 learn 回路由后，从阶段 4 的对应批次继续

设计原则

原则 说明
文档驱动 产品文档是唯一真相源，代码从文档派生
逐批推进 每批小而可验证，降低风险、提高可控性
Mock 优先 外部依赖不阻塞核心开发，接口先行、实现后置
环境分离 dev / test / prod 从 Day 1 隔离，敏感信息不入库
监督式自动 Agent 自动推进但不失控，关键决策留给人
全自动构建 说 一口气完成 连续跑批次并跨里程碑自动门禁，硬阻断（部署/密钥/支付/数据删除等）仍暂停待确认
交接协议 Skill ↔ Agent 通过 08-build-plan.md 标准化交接
阶段状态 delivery-coordinator + .github/delivery/<slug>.md 记录跨阶段进度和人工门禁
规模自适应 小型单 agent 线性推进，大型由 orchestrate-build 拆模块并行
独立质检 review-implementation 只复核不写码，抵消自验证偏差
UI 质量门禁 ui-review 独立评审界面 / 视觉 / 可访问性，major 未解决不 pass
文档质量门禁 prodforge 内置自检 + requirements-review 独立复核，确保文档可验证、无歧义、全覆盖、可追溯
集成闸门 里程碑需过端到端/集成 DoD 才能推进
部署门禁 部署产物自动生成，部署/合并/密钥保留人工审批
经验沉淀 learn 把已验证经验固化进指令/记忆/Skill，持续改进