moai-workflow-spec

SPEC 工作流管理

快速参考

使用 GEARS 记法（当前）进行 SPEC 工作流编排，并由 EARS 旧版向后兼容窗口提供支持，以便系统化定义需求并集成 Plan-Run-Sync 工作流。

Lint 行为已根据 GEARS 迁移策略规范化。

核心能力：

• GEARS 格式规范（当前）：五种需求模式，使用统一的复合从句 [Where ...][While ...][When ...] The <subject> shall <behavior>，并采用通用的 <subject>（不限于“the system”）
• EARS 旧版参考：根据 lint 引擎的向后兼容策略，保留所有 EARS 模式，以便仍可读取 v3 之前的 SPEC（即 GEARS 成为规范之前编写的 SPEC）
• 需求澄清：包含假设分析的四步系统化流程
• SPEC 文档模板：标准化的 3 文件结构（spec.md / plan.md / acceptance.md）
• Plan-Run-Sync 集成：无缝衔接工作流
• 并行开发：基于 Git Worktree 隔离 SPEC
• 质量门禁：TRUST 5 框架验证

GEARS 五种模式（当前记法）：

模式	GEARS 形式（当前）	EARS 形式（旧版）	说明
普遍模式	"The shall "	"The system shall "	<subject> 可以是任何名词：system、component、service、agent、function、artifact
事件驱动	"When , the shall "	"WHEN , the system shall "	触发语义不变
状态驱动	"While , the shall "	"WHILE , the system shall "	不变——提升为一等模式
能力门控	"Where <capability / feature flag / static config>, the shall "	"WHERE , the system shall "	重新定义——表示能力门控／功能标志／静态配置（不再称为“Optional”）
事件检测（替代 IF/THEN）	"When , the shall "	IF <condition> THEN <action> [DEPRECATED — use WHEN ]	已移除 IF/THEN 模式；将相同意图描述为检测到的事件

统一复合从句：**Where** <precondition> **While** <state> **When** <event> the <subject> shall <behavior>——三个修饰语中的任意子集均可串联使用。

参见 GEARS 记法参考。

IF/THEN 弃用提示：过去的编写指南使用 IF <condition> THEN <action> 描述受状态条件约束的行为。在 GEARS 中，这一意图通过 When <condition-detected>（事件检测形式）表达。对于新 SPEC 中残留的 IF/THEN，lint 引擎会发出 LegacyEARSKeyword 警告（非严格模式）或错误（moai spec lint --strict）。针对旧版 SPEC 的 6 个月向后兼容窗口仍然有效。

通用主语替换：GEARS 将硬编码的主语“the system”替换为 <subject>，它可以是任何名词。编写新 SPEC 的作者可以使用通用形式。以下是有效的非“the system”主语示例：

• “The skill shall present GEARS as the primary notation.”（普遍模式，<subject> = skill）
• “The agent shall return a blocker report instead of prompting the user.”（普遍模式，<subject> = agent）
• “When a SPEC author opens the file, the component shall display the deprecation banner.”（事件驱动，<subject> = component）

v3 之前的 SPEC（即 GEARS 成为规范之前编写的 SPEC）继续默认使用“The system”作为主语，以便阅读；现有读者无需重新熟悉规范用语。

EARS 五种模式（旧版——6 个月向后兼容窗口）：

模式	格式	用途
普遍性	"The system shall always X"	始终生效
事件驱动	"WHEN event THEN action"	触发响应
状态驱动	"WHILE state, the system shall ..."	条件行为（使用 WHILE，而非旧版 IF/THEN）
非期望	"The system shall not X"	禁止行为
可选	"Where possible, provide X"	有则更佳

旧版 IF/THEN 模态已由 GEARS 的 When <event-detected> 取代 — 参见上方提示框。

适用场景：

• 功能规划与需求定义
• 创建和维护 SPEC 文档
• 协调并行功能开发
• 质量保证与验证规划
• 从用户故事叙述中收集需求

快捷命令：

/moai plan "user authentication system"                   # Create new SPEC
/moai plan "login" "signup"                              # Parallel SPECs
/moai plan "payment processing" --branch                  # New branch
/moai plan SPEC-001 "add OAuth support"                   # Update existing

---

实施指南

核心概念

SPEC 优先开发理念：

• EARS 格式确保需求明确无歧义
• 需求澄清可防止范围蔓延
• 通过测试场景进行系统化验证
• 与 DDD 工作流集成以指导实施
• 质量关卡确保满足完成标准
• 参考 Constitution 确保项目范围内的一致性

Constitution 参考（SDD 2025 标准）

Constitution 定义了所有 SPEC 都必须遵循的项目 DNA。创建任何 SPEC 之前，请确认其符合 .moai/project/tech.md。

Constitution 组件：技术栈、命名约定、禁用库、架构模式、安全标准、日志标准。

Constitution 验证：所有 SPEC 的技术选型均与 Constitution 的技术栈版本一致，不使用禁用库，遵循命名约定，并保留架构边界。

原因：Constitution 可防止架构偏移并确保可维护性。

SPEC 工作流阶段

阶段	活动
1	用户输入分析 — 解析自然语言功能描述
2	需求澄清 — 4 步系统化流程
3	应用 EARS 模式 — 使用五种模式组织需求
4	定义成功标准 — 建立完成指标
5	生成测试场景 — 创建验证测试用例
6	生成 SPEC 文档 — 输出标准化 Markdown

GEARS 格式（当前）

GEARS（通用化 EARS）是 v3.0.0 起的标准 SPEC 表示法。它保留了普遍性、When（事件驱动）和 While（状态驱动），并将 Where 重新定义为能力门控。旧版 IF/THEN 模态已由 When <event-detected> 取代。

GEARS 表示法的完整说明见 docs-site GEARS 表示法参考 和规范的 GEARS 迁移政策记录。

复合子句示例（主语不是“the system”）：

Where the project is initialized While strict mode is active When a SPEC author runs moai spec lint, the lint engine shall emit a LegacyEARSKeyword finding for every residual IF/THEN modality.

此示例串联了全部三种 GEARS 修饰符（Where、While、When），并使用 <subject> = "lint engine" 而非 "the system"。

EARS 格式（旧版 — 6 个月向后兼容期）

五种模式涵盖所有需求类型。每种模式都有特定的适用场景和测试策略。v3 之前的 SPEC（即 GEARS 成为标准之前编写的 SPEC）继续使用 EARS 表示法，并根据 lint 引擎的向后兼容政策保持有效。

参见包含各模式示例的 EARS 深入指南，了解普遍性、事件驱动、状态驱动、非期望和可选需求的适用场景、示例及测试策略。

需求澄清流程

5 步系统化流程：

• 第 0 步：假设分析（哲学家框架）——梳理技术、业务、团队和集成方面的假设
• 第 0.5 步：根因分析（五个为什么）——针对问题驱动的 SPEC，将问题追溯至根因
• 第 1 步：范围定义——支持的方法、验证规则、故障处理、会话管理
• 第 2 步：约束提取——性能、安全性、兼容性、可扩展性
• 第 3 步：成功标准——覆盖率目标、响应时间百分位数、功能完成情况、质量门禁
• 第 4 步：测试场景创建——正常、错误、边缘和安全场景

请参阅需求澄清详细工作流，了解假设文档模板和五个为什么的应用方法。

[NEEDS CLARIFICATION] 标记约定

[NEEDS CLARIFICATION: ] 标记用于标识 plan.md 和 research.md 中尚未解决的问题，这些问题 MUST 在实施启动批准（plan→run HUMAN GATE）前解决。

位置：仅限 plan.md 和 research.md（绝不能出现在 spec.md 或 acceptance.md 中）。

格式：

• [NEEDS CLARIFICATION: <specific topic>] —— 用于未解决问题的内联标记
• 每个标记 MUST 能够通过编排器的 question-channel 功能处理，并在进入 run 阶段前解决
• plan-auditor 会检测未澄清的标记，并将其标记为“澄清门禁”问题

三层区分：

• [NEEDS CLARIFICATION: <topic>] —— 计划/研究文档阻塞项（需要向用户提问）
• TODO —— 代码级实现待办（无需向用户提问）
• @MX:TODO —— 用于未经测试/未完成代码的代码级注释

处理流程：

• plan-auditor 会在审计期间扫描 [NEEDS CLARIFICATION] 标记
• 如果仍有标记，plan-auditor 会建议在实施启动批准前解决
• 编排器会通过 question-channel 轮次解决每个标记主题（如果运行环境不具备该功能，应将尚未解决的标记保留在阻塞报告中，而不能让门禁悄然通过）
• 只有在所有澄清问题都已解决后，才能继续实施启动批准（强制人工门禁）

计划-运行-同步工作流集成

计划（/moai plan）：manager-spec 分析输入 → EARS 需求 → 澄清 → 在 .moai/specs/ 中创建 SPEC → 可选的 --branch。

运行（/moai run）：manager-develop 加载 SPEC → 根据 quality.yaml 中的 constitution.development_mode 采用 ANALYZE-PRESERVE-IMPROVE（DDD）或 RED-GREEN-REFACTOR（TDD）→ 参考 moai-workflow-testing → 为每次派生的 Agent(general-purpose) 分配领域任务 → 质量门禁验证（Stop hook / /moai gate）。

同步（/moai sync）：manager-docs 同步文档 → 根据 SPEC 编写 API 文档 → 更新 README 和架构 → 更新 CHANGELOG → 提交版本控制。

使用 Git Worktree 并行开发

Worktree 为每个 SPEC 提供隔离的工作目录，支持并行开发且无需切换分支。优点：并行开发、明确的归属边界、依赖隔离、降低风险。

请参阅 worktree 工作流模式，了解创建命令和团队协作示例。

---

资源

SPEC 文件组织

制品集并非固定不变，而是由 SPEC 的层级决定，该层级会在编写开始前的计划阶段进行分类。请从规范表（.claude/rules/moai/workflow/spec-workflow.md § SPEC Complexity Tier）中查看层级，而不要在此处通过统计文件数量来判断。

• .moai/specs/SPEC-{ID}/spec.md — GEARS 规格说明（在旧版过渡期内接受 EARS）。适用于所有层级。
• .moai/specs/SPEC-{ID}/plan.md — 实施计划、里程碑和技术方案。适用于所有层级。
• .moai/specs/SPEC-{ID}/acceptance.md — 验收标准、Given-When-Then 场景。适用于 M 层级及以上；在 S 层级，标准以内嵌方式写在 spec.md §3 中。
• .moai/specs/SPEC-{ID}/design.md 和 .moai/specs/SPEC-{ID}/research.md — 系统设计和代码库调研。仅适用于 L 层级。

[HARD] SPEC 目录必须包含其所属层级要求的所有制品，不得因缺少该层级未要求的制品而判定其不完整。仅包含 spec.md 和 plan.md 的 S 层级目录即为完整；在其中添加 acceptance.md 会重复已写在 spec.md §3 中的标准，而防止这种偏差正是本条款的目的。

状态文件：.moai/state/last-session-state.json。生成的文档：.moai/docs/api-documentation.md。

SPEC 元数据架构

规范的 12 个必填字段（由 SPEC frontmatter lint 规则强制执行）：id、title、version、status、created、updated、author、priority、phase、module、lifecycle、tags。

状态枚举（8 个值）：draft → in-progress → implemented → completed | superseded | archived | rejected。（planned 保留在枚举中，作为旧版可选值，不属于当前流程；没有 Agent 会编写 draft → planned 转换。参见 .claude/rules/moai/development/spec-frontmatter-schema.md § Status Enum。）

可选字段：issue_number、depends_on、lint.skip、bc_id、tier（S/M/L LEAN 层级）。

完整架构见 .claude/rules/moai/development/spec-frontmatter-schema.md（SSOT）。

SPEC 生命周期管理

三个生命周期级别：

级别	描述	维护
spec-first	实施后废弃 SPEC	无
spec-anchored	在实施过程中持续维护 SPEC	每季度审查
spec-as-source	SPEC 是唯一真实来源，仅由人类编辑 SPEC	变更会重新生成实现

转换：生产环境的关键功能采用 spec-first → spec-anchored；需要合规或重新生成工作流时采用 spec-anchored → spec-as-source。降级必须提供明确理由。

质量指标

SPEC 质量指标：需求清晰度（使用所有 EARS 模式）、测试覆盖率（所有需求均有场景）、约束完整性、成功标准的可衡量性。

验证清单：所有 EARS 需求均可测试；不使用模糊措辞（“应该”“可能”“通常”）；记录所有错误情况；量化性能目标；安全要求符合 OWASP 标准。

Token 管理

阶段	Token 预算
PLAN	~30%
RUN	~60%
SYNC	~10%

上下文优化：SPEC 文档保存在 .moai/specs/ 中。会话状态保存在 .moai/state/ 中。通过引用 SPEC ID 尽量减少上下文传递。Agent 委派可降低 Token 开销。

---

SPEC 范围与分类

.moai/specs/ 中应包含的内容

.moai/specs/ 目录专门用于存放定义待实施功能的 SPEC 文档。

有效的 SPEC 内容：采用 EARS 格式的功能需求、包含里程碑的实施计划、包含 Given/When/Then 场景的验收标准、新功能的技术规格说明，以及交付内容明确的用户故事。

SPEC 特征：面向未来（描述将要构建的内容）、可执行、可测试、有结构（EARS）。

不属于 .moai/specs/ 的内容

文档类型	为什么不属于 SPEC	正确位置
安全审计	分析现有代码	.moai/reports/security-audit-{DATE}/
性能报告	记录当前指标	.moai/reports/performance-{DATE}/
依赖项分析	审查现有依赖项	.moai/reports/dependency-review-{DATE}/
架构概览	记录当前状态	.moai/docs/architecture.md
API 参考	记录现有 API	.moai/docs/api-reference.md
会议记录	记录已作出的决定	.moai/reports/meeting-{DATE}/
回顾总结	分析过去的工作	.moai/reports/retro-{DATE}/

范围外分类规则

这些路由规则用于判断哪些内容不属于 SPEC 文档的范围（以及应该放在哪里）。编写 SPEC 自身的排除项章节时，请将每个排除项写成 ### Out of Scope — <topic> H3 子标题，并使用 - 项目符号，以满足 OutOfScopeRule lint 的要求。

[HARD] 报告分析已存在的内容 → .moai/reports/。SPEC 定义将要构建的内容 → .moai/specs/。

[HARD] 文档说明如何使用 → .moai/docs/。SPEC 定义要构建什么 → .moai/specs/。

---

配合使用效果良好

• moai-foundation-core：SPEC 优先的 DDD 方法论和 TRUST 5 框架
• moai-workflow-testing：DDD 实现和测试自动化
• moai-workflow-project：项目初始化和配置
• moai-workflow-worktree：用于并行开发的 Git Worktree 管理
• manager-spec：SPEC 创建和需求分析 Agent
• manager-develop：基于 SPEC 需求的 DDD/TDD 实现
• /moai gate 技能（或 sync-phase-quality-gate.sh Stop hook）：TRUST 5 质量验证和门禁执行（原 manager-quality 职责）

有关迁移场景和验证脚本，请参阅：references/migration-guide.md。

---

版本：1.3.1（技能正文压缩轮次） 集成状态：已完成 - 采用具备 SDD 2025 功能的 Plan-Run-Sync 工作流

常见的自我安慰

自我安慰	实际情况
“SPEC 很明显，我可以跳过 EARS 格式”	EARS 之所以存在，是因为看似明显的需求最容易被误解。该格式能强制消除歧义。
“验收标准与需求重复了”	需求描述意图。验收标准描述可观察的证据。两者都不可或缺。
“我会在实现过程中完善 SPEC”	延后完善意味着浪费实现工作。SPEC 是改变想法成本最低的地方。
“调研可做可不做，不会阻碍进度”	跳过调研会导致 SPEC 与现有代码冲突。research.md 能避免返工。
“注释周期只会给用户添麻烦”	注释能在编写代码前发现误解。它是流程中成本最低的反馈循环。
“这个 SPEC 很小，不需要单独的文件”	每个 SPEC 都是持久化的契约。消息中的 SPEC 无法通过 /moai run SPEC-XXX 引用。

危险信号

• 需求使用祈使句，而非 EARS 格式（WHEN X, SHALL Y）
• 验收标准使用主观判断来表述（“感觉很快”“看起来干净”）
• 修改现有代码时，SPEC 文档缺少同级的 research.md
• 跳过注释周期，或将其缩减为单轮“看起来不错”
• 需求在表示强制要求时使用 “should”，造成可选与强制之间的歧义
• SPEC-ID 未在 .moai/specs/ 目录中登记

验证

• .moai/specs/SPEC-XXX/spec.md 中存在 SPEC 文件，且 ID 唯一
• 每项需求都使用 EARS 关键词（WHEN、WHILE、WHERE、IF、SHALL）
• 每项验收标准都可观察（测试输出、文件是否存在、指标阈值）
• AC 验证命令遵循纯命令格式——参见 worktree-integration.md § 工作树隔离会话中的拒绝命令（测量得出的防护边界 + 编写规则）
• 当 SPEC 涉及现有代码时，存在 research.md
• 注释周期已完成，并带有明确的用户批准标记
• SPEC 引用了其所依赖或取代的现有 SPEC-ID
• 存在范围外内容一节以防止范围蔓延——至少包含一个 ### Out of Scope — <topic> H3 子标题，并带有一条 - 列表项（满足 OutOfScopeRule lint 要求）