mspec体验：基于SDD的轻量AI工作流mspec 官方文档 mspec 是什么 mspec是基于规格驱动开发（SDD

mspec 是什么

mspec是基于规格驱动开发（SDD或者BDD） 的插件化轻量级AI工作流程序

由规格驱动开发方法、状态机引擎及代码校验程序CLI、工作流及Skill（或Subagent）组成
先写行为规格，再拆任务与实现，并用 CLI/锚点把代码和 FR （Function Requirement）对齐

implement 阶段任务循环

下图是单任务循环，用于展示mspec的基本工作原理：

anchor check 与 validate在全部任务完成后才由 Agent 在终端执行
触发 implement 的是你运行 /mspec-continue 或 /mspec-implement，Agent 经 continue 的 JSON 加载 Skill 并读 tasks.md

sequenceDiagram
  participant U as 人
  participant AG as Agent
  participant CO as mspec-continue Skill
  participant IM as mspec-implement Skill
  participant CLI as mspec CLI 子进程

  U->>AG: /mspec-continue 或 /mspec-implement
  AG->>CLI: continue --json 若走 continue
  CLI-->>AG: skill=mspec-implement main_prompt
  AG->>CO: 按 continue 规程加载 IM
  AG->>IM: 步骤 1-2 status 与读 tasks.md
  AG->>AG: 取下一个未勾 TNNN

  loop 每个任务 Skill 步骤 3
    AG->>AG: 改代码写测 可调 dev-kit 等
    AG->>CLI: test --expect-red 或 --expect-green
    CLI-->>AG: 退出码与输出
    AG->>AG: 按 IM 勾 tasks 与 checklist
  end

  Note over AG,CLI: 全部任务完成后 Skill 步骤 6
  AG->>CLI: anchor check
  AG->>CLI: validate
  CLI-->>AG: 通过或失败
  AG->>IM: 步骤 5 报告 checklist 步骤 7 block
  AG->>U: 请再次 /mspec-continue block_after

优势

SDD减少漏项、减少Agent实现漂移

有些技术虽然早已存在，但直到AI到来，才真正火热起来，比如git worktree

SDD（Spec-Driven Development）也类似，

Delta Spec + FR 编号：可测试、可 grep、可 checklist 逐条对照。

示例：

### Requirement: FR-001 — 首次进入示例场景展示引导

当用户安装后首次进入目标业务场景且上下文信息加载完成时，本系统 SHALL 展示操作引导……

#### Scenario: 首次进入出现引导
- GIVEN 满足「首次进入」且功能开关开启
- WHEN 当前场景上下文加载完成
- THEN 展示引导 overlay

design / design-rationale / architecture-overview 在写代码前把路由、失败策略、与现有路径（例如是否调用某换房 API）写清楚。

示例：

## Summary
为 ExampleFeatureViewController 增加场景上下文与手势识别；场景切换走既有 AppRouter + Room 与媒体 SDK 进退顺序，不切新协议。

## Technical Context
- 路由: +[AppRouter openSceneWithSceneID:hostID:extension:]
- 切换 = 同栈内换 sceneId，leave/join 顺序不变

## Non-Goals
- 非列表入口进入不启用切换
- 不改造既有进房/进场景协议或第三方 SDK 版本

规范文档、任务代码多重交叉验证

在多个步骤以及CLI执行中对规范、代码的规范性和准确性进行检测

        Specification
             │
      ┌ ─────┴──────┐
      ↓             ↓
  validate        check
      │             │
规范自身是否合法  spec ↔ Code/Test
                  是否保持一致

示例（tasks.md），文档中拆分任务，实现过程按任务自动勾选，并后续根据@mspec-delta锚点对代码和task.md进行验证：

- [ ] T010 新增 ExampleSwipeContext，列表入口 snapshot …
      anchor:
        @mspec-delta changes/<示例-change>/specs/<示例-capability>/spec.md
        Requirements implemented: FR-002, FR-006
        Change: example-feature-change

交互简单，嵌入现有 Agent

插件式 Skill + Command：mspec 以 Skill 形式嵌入 Cursor、Claude Code 等现有 Agent 环境
在工具里用固定 Command（如 /mspec-continue、/mspec-implement）驱动 workflow，少写「现在该写 design / 勾 tasks」类长自然语言——步骤边界清楚，推进更省 token、也更不易跳步或理解漂移。

示例：

其他设计技巧

不同任务类型使用定制化Agent

以Change为维度执行工作流

日常的改动除了开发新需求，还有做各种小的改动，bugfix等
mspec会将这些工作定义为一次Change，每次一个Change可以独立、并行跑流程
Change的定义更能准确描述每次任务

内置多种类型工作流

Mode	Skips	Forces	Typical use case
`typo`	`proposal`, `quickstart`	—	Pure text/comment edits, no behavior change.
`minor`	`proposal`, `quickstart`	—	Small UX or wording change with no logic impact.
`bugfix`	`proposal`, `quickstart`	`research`	A bug that needs a quick root-cause analysis but no full proposal.

劣势与成本

与工程 Skill 接不上（尤其 flow Skill） ：
- mspec 工作流只驱动 mspec-* 步骤 Skill，不会自动挂上 ios-build、ios-verify 等工程内/工作流 Skill；
- 要在 design 或 checklist 里显式点名，Agent 才会去读——规格流程和「怎么编包、怎么验」仍是两条线。
文档多、仓库显得碎：为减少实现漂移，每个步骤都要产出 md 并纳入仓库管理（change 里一串 proposal / delta / design / tasks…），工作区比「PRD + 直接改码」更显繁琐——换的是可对齐、可审计，成本是文件量和维护。

附录（workflow 对照表 · validate / anchor check）

读表说明：下表为简版 11 步（缺 visual-mock 行）。完整 12 步含 block 列、Delta 路径 changes/<name>/specs/...、visual-mock 见仓库 .mspec/workflow.yaml。delta / quickstart / checklist / archive 等 block: false 时，/mspec-continue 不会自动停等人确认——须在 continue 前人工 Review 或改 workflow。

#	Step	核心做什么	主要产出	人工 Review	Agent 参与方式	MSpec CLI / 其他工具
1	new	创建一次 Change，把最初需求确定为 Request、Mode、Capabilities	`readme.md`：Request / Mode / Capabilities	需要：确认需求意图、Mode、Capability 是否正确	当前会话 Agent：`/mspec:new` 加载 `mspec-new` Skill	`mspec new <name>` 创建 change；workflow block
2	proposal	明确为什么做这次变更，确定 Goals / Non-Goals / Scope	`proposal.md`：Why / Goals / Non-Goals / Capabilities / Constitution Check	重点 Review：确认 Why、Goals、Non-Goals 是否符合真实需求	当前会话 Agent：通过提问进一步澄清需求	Constitution Check；CLI 管理 workflow gate
3	delta	将需求正式转化为 Functional Requirements 和 Scenario，定义系统应该表现出的行为	Delta Spec：`changes/<name>/specs/<capability>/spec.md`（archive 前不写根 SoT），包含 `FR-NNN` + GIVEN/WHEN/THEN Scenario	重点 Review：这是最重要的需求确认点之一；Scenario 后续会成为测试契约	当前会话 Agent	CLI `enforce_fr_ids` 检查 FR ID、Scenario 等结构
4	research	调研实现方案、现有代码和外部资料，比较技术选择并解决未知问题	`research.md`：Decisions / Web References / Codebase Findings / Open Choices 等	轻 Review：重点确认 Decisions 和 Open Choices	独立 `mspec-researcher` Subagent	Subagent 搜索 Web + Codebase；Constitution Check；workflow block
5	design	根据需求和 Research 制定具体技术设计，包括模块、文件、函数、数据流和架构	`design.md` + `design-rationale.md` + `architecture-overview.md`	重点 Review `design.md`：确认技术方案合理；rationale 可按需阅读	当前会话 Agent	Constitution Phase 1 Check；Mermaid 架构图；workflow block
6	quickstart	从真实用户角度描述功能如何使用以及如何验证 Golden Path	`quickstart.md`	需要 Review / 后续亲自验证：确认 Golden Path 和 Verify 是否覆盖核心 FR	当前会话 Agent	无独立 Subagent；该步骤可 skip
7	checklist	在实现前检查需求覆盖率、回归风险、Constitution 和需要人工确认的事项	`checklist.md`：Delta Spec Coverage / SoT Regression / Constitution 等	针对性 Review：主要关注标记为 `verify: human` 的项目	独立 `mspec-checklist-auditor` Subagent	使用 `verify: fr-*` / `verify: human`；CLI 后续可自动完成机器验证项
8	self-review	独立重新检查前面所有 Artifact，寻找跨步骤矛盾、遗漏和不一致	在 `design.md` 追加 `## Self-Review`	通常只 Review 发现的问题；出现 contradiction 时需要人决策	独立 `mspec-self-reviewer` Subagent	修改 Artifact 后可通过 `mspec done <step>` 重新进行 gate
9	tasks	把已经确认的 Spec + Design 拆解成 Agent 可执行的任务，并建立 Scenario → E2E Task	`tasks.md`：Setup / Foundational / User Story / Polish；Task 带 FR anchor	轻 Review：重点确认 Scenario 是否都有 E2E Task，以及任务顺序是否合理	当前会话 Agent	CLI 在 `validate --strict` 时粗查 E2E/TDD 任务结构（默认 validate 不跑 enforce_*）
10	implement	执行 Tasks：先编写 E2E Test 并得到 RED，再实现代码，最后得到 GREEN，同时建立 Spec ↔ Code/Test Anchor	E2E Tests + Production Code + `@mspec-delta` anchors + Red/Green Evidence；同时更新 `tasks.md` / `checklist.md`	最终需要 Review：机器验证项自动检查，`verify: human` 必须由人确认	当前会话 Agent：编写 E2E Test 和 Implementation，不是独立 Subagent	MSpec CLI：`expect-red` / `expect-green`、`anchor check`；`enforce_tdd/anchor/e2e` 仅 `validate --strict`；默认 validate 主要查 md；另外须维护 `.mspec/config.yaml` Test Runner 并跑 `test --expect-green`
11	archive	将本次 Delta Spec 合并进长期 Source of Truth，并归档整个 Change	更新 `specs/<capability>/spec.md`；Change 移至 `changes/archive/`；`readme.md` 增加 Summary	最终确认，但较轻：重点确认 dry-run merge 结果	Slash Command 仍由当前会话 Agent 发起，但真正 Spec Merge 不使用 LLM	MSpec CLI Parser：`mspec archive --dry-run` → 确认 → deterministic merge；之后可运行 `mspec anchor check`

validate 与 anchor check

记忆口诀：validate = change 文件夹里的 md 规格是否「像样」；anchor check = 代码/测试声明的 FR 是否在 Delta Spec 里对得上。 （mspec CLI 0.1.8）

维度	mspec validate	mspec anchor check
主要对象	change 文档产物（workflow produces）	源码 /测试顶部 @mspec-delta
锚点 ↔ FR	❌ 默认不查；--strict 仅查「该 change 是否至少有一个锚点」	✅ 逐条：Delta 存在 + FR 在 spec 中
TDD 证据	仅 --strict（`.mspec/cache/*-evidence`）	❌

什么是SDD/BDD

BDD（Behavior-Driven Development）是用结构化的行为场景，把复杂需求细化成产品、研发、QA 都能共同理解、讨论和验证的规格。

SDD（Spec-Driven Development）是BDD的一种，且相比于BDD，SDD会更深入地考虑如何实现不同场景下的行为

示例

例如产品最开始可能只写：

用户连续登录失败多次后，需要锁定账号一段时间。

这句话其实隐藏了大量问题：

“多次”是多少次？
成功一次之后失败次数清零吗？
锁定多久？
锁定期间密码正确能登录吗？
锁定期间再次失败会重新计时吗？
不同设备上的失败次数是否累计？

BDD 会重点把它变成行为：

Feature: 登录安全

Scenario: 连续登录失败 5 次锁定账号
  Given 用户已经连续登录失败 4 次
  When 用户再次输入错误密码
  Then 用户账号被锁定

Scenario: 锁定 30 分钟后恢复
  Given 用户账号因为登录失败被锁定
  When 锁定时间已经超过 30 分钟
  Then 用户可以再次尝试登录

而 SDD 往往继续向下走：

Requirement
   │
   │ 连续失败5次锁定30分钟
   ↓
Specification
   │
   ├── FR-001 失败次数累计规则
   ├── FR-002 锁定规则
   └── FR-003 解锁规则
   ↓
Scenario
   │
   ├── 连续失败5次
   ├── 成功后计数清零
   └── 30分钟后解锁
   ↓
Design
   │
   ├── LoginService
   ├── AccountLockPolicy
   └── LockStateStore
   ↓
Task
   │
   ├── 实现 AccountLockPolicy
   ├── 修改 LoginService
   └── 增加状态持久化
   ↓
Implementation
   ↓
Verification
   ├── Unit Test
   ├── Integration Test
   └── E2E / BDD Scenario