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 逐条对照。
示例：
markdown
### Requirement: FR-001 --- 首次进入示例场景展示引导
当用户安装后首次进入目标业务场景且上下文信息加载完成时，本系统 SHALL 展示操作引导......
#### Scenario: 首次进入出现引导
- GIVEN 满足「首次进入」且功能开关开启
- WHEN 当前场景上下文加载完成
- THEN 展示引导 overlay- design / design-rationale / architecture-overview 在写代码前把路由、失败策略、与现有路径（例如是否调用某换房 API）写清楚。
示例：
markdown
## Summary
为 ExampleFeatureViewController 增加场景上下文与手势识别；场景切换走既有 AppRouter + Room 与媒体 SDK 进退顺序，不切新协议。
## Technical Context
- 路由: +[AppRouter openSceneWithSceneID:hostID:extension:]
- 切换 = 同栈内换 sceneId，leave/join 顺序不变
## Non-Goals
- 非列表入口进入不启用切换
- 不改造既有进房/进场景协议或第三方 SDK 版本规范文档、任务代码多重交叉验证
- 在多个步骤以及CLI执行中对规范、代码的规范性和准确性进行检测
css
Specification
│
┌ ─────┴──────┐
↓ ↓
validate check
│ │
规范自身是否合法 pec ↔ Code/Test
是否保持一致示例（tasks.md），文档中拆分任务，实现过程按任务自动勾选，并后续根据@mspec-delta锚点对代码和task.md进行验证：
typescript
- [ ] 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 才会去读------规格流程和「怎么编包、怎么验」仍是两条线。
- mspec 工作流只驱动
-
文档多、仓库显得碎：为减少实现漂移，每个步骤都要产出 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 会重点把它变成行为：
vbnet
Feature: 登录安全
Scenario: 连续登录失败 5 次锁定账号
Given 用户已经连续登录失败 4 次
When 用户再次输入错误密码
Then 用户账号被锁定
Scenario: 锁定 30 分钟后恢复
Given 用户账号因为登录失败被锁定
When 锁定时间已经超过 30 分钟
Then 用户可以再次尝试登录而 SDD 往往继续向下走：
arduino
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