规格驱动的多 Agent 协同工作流框架
SuperSpec 融合了 Superpowers 的技能执行引擎与 Spec Kit 的规格模板体系，为数字人团队打造了一套完整的项目协同工作流。
它的核心理念是：规格不是代码的附属品 —— 代码是规格的表达。
当你启动一个项目时，SuperSpec 不会让 Agent 直接跳进实现。它会先退一步，帮你搞清楚你真正要做什么，然后一步步推进到设计、拆解、实现、验收、复盘 —— 每一步都有质量门禁把关，每一步都有专门的 Agent 角色主导。
# Claude Code 插件安装
claude plugin add /path/to/superspec安装后，启动新会话会看到：
SuperSpec v1.0 已加载。使用 /orchestrate 查看项目状态，或 /discover 开始新项目。
启动一个新会话，输入 /orchestrate。如果看到项目列表（或提示你新建项目），说明安装成功。Skills 会自动触发 —— 你不需要做任何额外配置。
/discover # 有个新想法？从这里开始
/orchestrate # 不确定进度？让编排引擎告诉你claude plugin update superspec每个项目经过 6 个阶段，每个阶段有明确的输入、输出和质量门禁。阶段之间不能跳跃 —— 这不是建议，是强制规则。
/discover → /define → /design → /deliver → /verify → /reflect
│ │ │ │ │ │
│ [门禁审查] [门禁审查] [门禁审查] │ │
▼ ▼ ▼ ▼ ▼ ▼
业务澄清 需求规格 技术设计 任务执行 验收评审 复盘沉淀
| 阶段 | 命令 | 做什么 | 不做什么 | 产出 |
|---|---|---|---|---|
| Discover | /discover |
从模糊想法提炼出明确方向 | 不讨论技术实现 | discover.md |
| Define | /define |
将方向转化为结构化需求规格 | 不做技术选型 | spec.md |
| Design | /design |
生成技术设计方案和 Agent 分工 | 不开始写代码 | design.md |
| Deliver | /deliver |
拆解任务并执行实现 | 不超出 Spec 范围 | tasks.md + 实现产出 |
| Verify | /verify |
端到端验收 | 不修改需求 | verify-report |
| Reflect | /reflect |
项目复盘与知识沉淀 | 不跳过 | retrospective.md |
受 Spec Kit 启发，每个项目在初始化时会生成一份 constitution.md，定义不可违反的治理原则：
- 质量标准（如 "所有需求必须有可验证的验收标准"）
- 文档规范（如 "使用中文，专有名词保留英文"）
- Agent 行为底线（如 "不允许跳过门禁"）
- 审批权限规则
Constitution 是所有阶段 Skill 的顶层约束 —— 类似 Spec Kit 中的 "Nine Articles"。
阶段之间有自动质量门禁（HARD-GATE），必须通过才能进入下一阶段：
| 门禁 | 位置 | 检查什么 |
|---|---|---|
| review-spec | Define → Design | 需求可验证性、范围明确性、无歧义 |
| review-design | Design → Deliver | 需求覆盖度、YAGNI、Agent 分工合理性 |
| review-delivery | Deliver → Verify | 交付物齐全、任务全部完成 |
门禁结论：
| 结论 | 含义 | 后续 |
|---|---|---|
PASS |
通过 | 自动进入下一阶段 |
PASS_WITH_NOTES |
有条件通过 | 进入下一阶段，备注跟进 |
REVISE |
需修改 | 回退当前阶段，给出具体修改建议 |
BLOCKED |
阻塞 | 暂停流程，等待人工决策 |
连续 2 轮 REVISE 会触发升级机制（联合复核或人工介入）。第 3 轮强制暂停。
和 Superpowers 一样，SuperSpec 的 Skills 自动触发 —— 你不需要手动调度 Agent 或记住内部流程。执行 /discover 时，框架自动派发产品策略 Agent 主导、方案架构 Agent 辅助、文档治理 Agent 校验。
优先级规则（与 Superpowers 一致）：
- 你的显式指令（CLAUDE.md、直接要求）— 最高优先级
- SuperSpec Skills — 覆盖默认行为
- 系统默认行为 — 最低优先级
以 "数字员工管理平台" 为例，演示完整的 6 阶段流程。
/discoverAgent 会逐个提问（每次只问一个问题，优先使用选择题）：
产品策略 Agent: 这个数字员工管理平台主要解决什么问题？
A) 内部团队的 AI Agent 协同管理
B) 面向客户的数字员工服务平台
C) Agent 的全生命周期管理（创建、配置、监控、下线）
D) 其他
你: A
产品策略 Agent: 目标用户是谁？
A) 研发团队（技术人员）
B) 业务运营团队（非技术人员）
C) 两者都有，但以研发为主
D) 两者都有，但以运营为主
你: C
... (更多澄清问题)
产品策略 Agent: 根据以上讨论，我建议以下 3 个方向：
方案 A（推荐）: 以 Agent 协同编排为核心...
方案 B: 以知识库管理为核心...
方案 C: 以监控看板为核心...
你: 方案 A
产出：docs/specs/001-digital-employee-platform/discover.md
文档末尾有确认签字区，你确认方向后 user_confirmed 置为 true。
/defineHARD-GATE: 此阶段不允许讨论技术选型。保持技术无关。
Agent 读取 Discover 文档，将需求转化为结构化规格：
## 用户故事
### US-001: 创建数字员工
**优先级**: P1
**描述**: 作为研发团队成员，我希望通过配置界面创建新的数字员工，以便快速组建 Agent 团队
**验收场景**:
- Given 用户已登录管理平台
- When 填写员工名称、角色、技能配置并提交
- Then 系统创建数字员工实例并显示在员工列表中
## Agent 协同设计
| 环节 | 责任 Agent | 自动化程度 | 人工确认点 |
|------|-----------|-----------|-----------|
| 员工创建 | 配置 Agent | 全自动 | 否 |
| 权限分配 | 安全 Agent | 半自动 | 是 |产出：docs/specs/001-digital-employee-platform/spec.md
完成后自动触发 review-spec 门禁：
质量评审 Agent: Spec Review R1 结论: PASS_WITH_NOTES
检查清单:
✅ 目标可追溯性 — 所有目标来自 Discover 文档
✅ 需求可验证性 — 每个用户故事有 Given/When/Then
⚠️ 人机协同边界 — "权限分配"的人工确认触发条件未明确
允许进入 Design，建议在 Design 阶段补充权限确认的触发规则。
/design方案架构 Agent 读取 Spec，生成技术设计：
## Agent 分工设计
### 配置 Agent
- 输入: 用户的创建请求
- 输出: 数字员工实例
- 决策权限: 可自动选择默认配置模板
- 与安全 Agent 的交互: 创建后触发权限分配请求产出：docs/specs/001-digital-employee-platform/design.md
完成后自动触发 review-design 门禁。
/deliver分两个阶段自动进行：
阶段 1 — 项目规划 Agent 拆解任务：
| ID | 任务 | 责任Agent | 前置依赖 | 并行标记 | 输出 | 验收条件 |
|---|---|---|---|---|---|---|
| T-001 | 创建项目脚手架 | executor | - | | 项目目录结构 | 目录存在且可运行 |
| T-002 | 实现数据模型 | executor | T-001 | | 数据模型文件 | 模型定义完整 |
| T-003 | 实现员工创建 API | executor | T-002 | [P] | API 端点 | 通过单元测试 |
| T-004 | 实现员工列表 API | executor | T-002 | [P] | API 端点 | 通过单元测试 |阶段 2 — 实施执行 Agent 逐任务执行：
支持 Superpowers 风格的子代理驱动开发（SDD）—— 每个任务派发独立子代理，完成后由 spec-reviewer + code-quality-reviewer 双重审查。标记 [P] 的无依赖任务可并行执行。
执行过程中，数据看板 Agent 按需汇总进度：
## 项目状态看板
### 任务进度
| 状态 | 数量 | 占比 |
|------|------|------|
| 已完成 | 8 | 67% |
| 进行中 | 2 | 17% |
| 待开始 | 2 | 17% |产出：docs/specs/001-digital-employee-platform/tasks.md + 实现产出
完成后自动触发 review-delivery 门禁（检查交付完整性）。
/verify三方联合验收：
- 质量评审 Agent：端到端一致性检查（Spec → Design → 实现）
- 产品策略 Agent：业务视角 — 用户故事是否被正确实现
- 方案架构 Agent：技术视角 — 架构决策是否被遵守
验收结论: PASS
SC-001 ✅ 数字员工可通过配置界面创建
SC-002 ✅ 创建后自动触发权限分配流程
SC-003 ✅ 员工列表正确显示所有已创建员工
/reflect运营复盘 Agent 分析全流程：
## 偏差分析
| 偏差项 | 预期 | 实际 | 根因 |
|--------|------|------|------|
| Spec Review 轮次 | 1 轮 | 2 轮 | 人机协同边界定义不够清晰 |
## 可沉淀资产
| 资产类型 | 描述 |
|---------|------|
| 模板改进 | discover-template 应增加"人机协同边界"专项章节 |
| 决策记录 | 权限分配采用"先创建后审批"模式 |知识库 Agent 将可复用资产归档，供后续项目参考。
至此，项目完成。 orchestrate 将状态更新为 Done。
| 命令 | 说明 | 前置条件 | 主导 Agent |
|---|---|---|---|
/discover |
启动业务澄清 | 无 | 产品策略 |
/define |
需求规格化 | Discover 完成且已确认 | 产品策略 |
/design |
技术方案设计 | Spec Review 通过 | 方案架构 |
/deliver |
任务拆解与执行 | Design Review 通过 | 项目规划 → 实施执行 |
/verify |
评审与验收 | Delivery Review 通过 | 质量评审 |
/reflect |
复盘与知识沉淀 | 验收通过 | 运营复盘 |
/orchestrate |
查看状态 / 自动推进 | 无 | 流程调度 |
不是所有项目都要从 /discover 开始：
| 你已有的东西 | 推荐入口 | 需要确认 |
|---|---|---|
| 一个模糊想法 | /discover |
无 |
| 结构化需求文档 | /define |
orchestrator 确认 |
| 完整设计方案 | /design |
用户 + orchestrator 双重确认 |
| 不确定从哪开始 | /orchestrate |
自动判断 |
| 角色 | Skill 名 | 主导阶段 | 核心职责 | 决策权限 |
|---|---|---|---|---|
| 产品策略 | product-strategist | Discover, Define | 目标澄清、需求归纳、价值判断 | 可决定优先级排序，不可决定技术选型 |
| 方案架构 | solution-architect | Design | 系统设计、模块划分、技术取舍 | 可决定技术选型，不可变更需求范围 |
| 项目规划 | project-planner | Deliver（拆解） | 任务拆解、里程碑、依赖识别 | 可决定任务粒度，不可变更技术方案 |
| 实施执行 | executor | Deliver（执行） | 按任务落地实现 | 可决定实现细节，不可新增功能 |
| 质量评审 | quality-reviewer | Verify + 门禁 | 质量检查、验收评审 | 可决定 review 结论，不可豁免检查项 |
| 运营复盘 | retrospector | Reflect | 复盘分析、知识沉淀 | 可提出改进建议，不可直接修改模板 |
| 角色 | Skill 名 | 作用范围 | 核心职责 |
|---|---|---|---|
| 文档治理 | doc-governance | 全流程 | 格式校验、命名规范、模板合规 |
| 流程调度 | orchestrator | 全流程 | 状态机管理、阶段流转、升级处理 |
| 知识库 | knowledge-base | 全流程 | 历史查询、复用建议、资产归档 |
| 数据看板 | dashboard | Deliver, Verify | 进度汇总、阻塞识别 |
Discover Define Design Deliver Verify Reflect
策略Agent ●主导 ●主导 ○辅助
架构Agent ○辅助 ●主导 ○辅助
规划Agent ○辅助 ●主导(拆)
执行Agent ●主导(做)
评审Agent ●主导
复盘Agent ●主导
──────────────────────────────────────────────────────────
治理Agent ○校验 ○校验 ○校验 ○校验 ○校验 ○校验
调度Agent ○编排 ○编排 ○编排 ○编排 ○编排 ○编排
知识Agent ○查询 ○查询 ○查询 ○查询 ○查询 ○归档
看板Agent ○追踪 ○汇总 ○回看
● = 主导 ○ = 辅助/被动
- Agent 无状态 — 每次派发都是全新子代理，不依赖会话历史（与 Superpowers SDD 一致）
- 文档即接口 — Agent 之间不直接通信，文档是唯一共享介质
- 平台 Agent 被动触发 — 由阶段 Skill 按需派发，不主动介入
- orchestrator 唯一决策权 — 只有流程调度 Agent 可以决定阶段流转
| # | 检查项 | 判定标准 |
|---|---|---|
| 1 | 目标可追溯性 | 每个目标在 Discover 中有来源 |
| 2 | 需求可验证性 | 每个用户故事有 Given/When/Then |
| 3 | 范围明确性 | 有"不在范围"章节且内容具体 |
| 4 | 无歧义性 | 没有未解决的 [NEEDS CLARIFICATION] |
| 5 | 验收标准完整性 | 每个 FR 关联至少一个验收标准 |
| 6 | 人机协同边界 | Agent 参与点明确 |
| # | 检查项 | 判定标准 |
|---|---|---|
| 1 | 需求覆盖度 | 每个 FR 有对应 Design 模块 |
| 2 | YAGNI | 无 Spec 未要求的"预留"设计 |
| 3 | Agent 分工 | 无职责重叠、无遗漏 |
| 4 | 接口明确 | 数据模型和接口可直接用于实现 |
| 5 | 异常处理 | 每个模块有兜底方案 |
| # | 检查项 | 判定标准 |
|---|---|---|
| 1 | 任务完成度 | 所有任务标记为已完成 |
| 2 | 实现说明 | 每个任务有完成备注 |
| 3 | 交付物齐全 | Design 列出的交付物都已产出 |
| 4 | 测试说明 | 有测试方法和结果 |
review-delivery 做交付完整性检查，Verify 做功能正确性验收。两者互补。
第 1 轮 REVISE → 回退修改，给出具体建议
第 2 轮 REVISE → 升级：联合复核 / 拉回上一阶段 / 人工介入
第 3 轮 REVISE → 强制暂停，等待人工决策
docs/specs/
001-digital-employee-platform/ # 项目目录（自动编号）
.status.md # 项目状态（orchestrator 自动维护）
constitution.md # 项目宪法（治理原则）
discover.md # Discover 产出
spec.md # Define 产出
design.md # Design 产出
tasks.md # Deliver 产出（任务清单）
reviews/
review-spec-r1.md # Spec Review 第 1 轮
review-spec-r2.md # Spec Review 第 2 轮（如有）
review-design-r1.md
review-delivery-r1.md
retrospective.md # Reflect 产出
项目 ID 格式：{三位数字}-{kebab-case-名称}，如 001-digital-employee-platform
状态文件 .status.md 结构：
## Project Status
- id: 001-digital-employee-platform
- name: 数字员工管理平台
- current_phase: In Design
- created: 2026-03-24
- last_updated: 2026-03-24
- user_confirmed: true
## Phase History
| 阶段 | 进入时间 | 完成时间 | Review 结论 | 轮次 |
|------|---------|---------|------------|------|
| Discover | 2026-03-24 | 2026-03-24 | - | - |
| Define | 2026-03-24 | 2026-03-24 | PASS_WITH_NOTES | 1 |
## Open Issues
## Decisions LogDraft
→ In Discover → Discover Reviewed
→ In Define ──→ [review-spec] ──→ Spec Reviewed
→ In Design ──→ [review-design] ──→ Design Reviewed
→ In Delivery ──→ [review-delivery] ──→ Delivery Reviewed
→ In Verification → Verified
→ In Retrospective → Done
特殊状态：Rejected / On Hold（任意阶段可进入）
回退：Review REVISE → 回退当前阶段
升级：连续 2 轮 REVISE → 联合复核或人工介入
模板文件在 templates/ 目录下，纯 Markdown，不含流程逻辑。你可以自由调整字段和结构。
templates/
discover-template.md # Discover 阶段输出模板
constitution-template.md # 项目宪法模板
spec-template.md # 需求规格模板
design-template.md # 技术设计模板
tasks-template.md # 任务清单模板
review-spec-template.md # Spec Review 报告模板
review-design-template.md # Design Review 报告模板
review-delivery-template.md # Delivery Review 报告模板
verify-report-template.md # 验收报告模板
retrospective-template.md # 复盘报告模板
模板优先级（受 Spec Kit 启发）：已有项目使用创建时的模板内容，新项目使用最新版本。修改模板不影响进行中的项目。
流程规则在 skills/workflow/orchestrate/SKILL.md 中定义：
- 调整门禁检查项 → 修改
skills/gates/review-*/SKILL.md - 修改升级规则（如允许更多 REVISE 轮次）
- 将 Reflect 阶段设为可选
- 调整入口判断规则（如允许所有项目从 Define 开始）
每个 Agent 的行为在 skills/agents/{role}/SKILL.md 中定义：
## 决策权限
### 可以决定
- ...
### 不可以决定（需升级）
- ...
## 反模式
| 不要这样做 | 应该这样做 |你可以调整每个 Agent 的决策权限边界、工作方式和反模式。
- 创建
skills/agents/{new-role}/SKILL.md - 遵循角色 Skill 标准结构（身份定义、决策权限、输入输出契约、反模式）
- 在相关阶段 Skill 中添加调度规则
- 创建
skills/gates/{new-gate}/SKILL.md - 定义检查清单和判定规则
- 在 orchestrate Skill 的流转规则中引用
- Skills 自动触发 — 不需要手动调度，框架根据上下文自动选择合适的 Skill
- HARD-GATE — 关键检查点不可跳过，防止 Agent 跳过纪律
- 子代理驱动开发（SDD） — 每个任务派发独立子代理，新鲜上下文，双重审查
- 反模式表 — 每个 Skill 预测 Agent 可能的 "偷懒" 行为并明确禁止
- YAGNI 原则 — 只做当前需要的，不为假想的未来需求设计
- 规格即源码 — 规格不是代码的附属品，代码是规格的表达
- Constitution — 项目级不可违反的治理原则，所有决策的顶层约束
- 阶段分离 — WHAT（Define）和 HOW（Design）严格分离
- 结构化模板 — 用模板约束 LLM 行为，防止跑偏
[NEEDS CLARIFICATION]标记 — 强制标注歧义，不允许 Agent 自行假设
- 6 阶段流水线 — 比 Superpowers 多 Discover 和 Reflect，比 Spec Kit 多 Verify 和 Reflect
- 10 个 Agent 角色 — 一等公民，每个角色有独立的 Skill 定义和决策权限
- 三层门禁 — review-spec、review-design、review-delivery 三道关卡
- 编排引擎 — 统一的状态机管理，自动流转、升级、回退
- 文档即接口 — Agent 间零直接通信，通过文档传递所有信息
SuperSpec 是一个独立框架，不依赖 Superpowers 或 Spec Kit 运行。它融合了两者的精华：
| 能力 | 来源 | SuperSpec 中的体现 |
|---|---|---|
| Skill 执行引擎 | Superpowers | Skills 自动触发、HARD-GATE、反模式表 |
| 子代理驱动开发 | Superpowers | Deliver 阶段的 SDD 执行模式 |
| 结构化模板 | Spec Kit | 10 个文档模板、占位符标记 |
| Constitution | Spec Kit | 项目宪法、治理原则 |
| 阶段分离 | Spec Kit | Define（WHAT）与 Design（HOW）分离 |
| 多 Agent 协同 | 原创 | 10 个角色 Skill、协作矩阵、调度机制 |
| 编排引擎 | 原创 | 状态机、门禁、升级、回退 |
| Discover / Reflect | 原创 | 前端业务澄清 + 后端复盘沉淀 |
Q: 一定要从 Discover 开始吗？
不一定。如果你已有结构化需求，可以从 /define 开始；已有设计方案，可以从 /design 开始。但需要 orchestrator 确认，确保跳过的阶段不会留下隐患。
Q: 门禁一直不通过怎么办？
第 1 轮 REVISE 会给出具体修改建议。第 2 轮升级处理（联合复核、拉回上一阶段、或人工介入）。第 3 轮强制暂停。这个设计是为了防止 Agent 在错误方向上无限循环。
Q: 可以同时进行多个项目吗？
可以。每个项目有独立的 .status.md，orchestrator 按 project-id 隔离。用 /orchestrate 查看所有项目列表。
Q: 模板可以改吗？
可以。模板在 templates/ 下，纯 Markdown，随意修改。已有项目不受影响。
Q: 能和 Superpowers 同时使用吗？
可以。SuperSpec 的 Skill 命名空间是 superspec:，不会与 Superpowers 的 superpowers: 冲突。两者可以共存。
Q: Deliver 阶段支持 TDD 吗？
支持。实施执行 Agent 在子代理驱动模式下，遵循 Superpowers 的 TDD 流程（写失败测试 → 运行确认失败 → 写最小实现 → 运行确认通过 → 提交）。
Q: 如何查看某个阶段的详细 Skill 定义？
每个 Skill 文件都在 skills/ 目录下，可以直接阅读：
- 阶段 Skill:
skills/phases/{phase}/SKILL.md - 角色 Skill:
skills/agents/{role}/SKILL.md - 门禁 Skill:
skills/gates/{gate}/SKILL.md - 编排 Skill:
skills/workflow/orchestrate/SKILL.md
Q: 如何贡献或反馈？
欢迎提交 Issue 或 PR。新增 Skill 请遵循 skills/agents/ 下已有 Skill 的标准结构。
MIT