/moai plan

把与 AI 的对话转化为永久的需求文档。自然语言请求成为结构化的 SPEC 文档,这份文档将成为后续所有阶段的基准。

信息

斜杠命令: 在 Claude Code 中输入 /moai:plan 即可直接执行此命令。仅输入 /moai 会显示所有可用子命令列表。

/moai plan 是 MoAI-ADK 工作流的 Phase 1 (Plan) 命令。它将自然语言形式的功能请求转换为 EARS (Easy Approach to Requirements Syntax) 格式的结构化 SPEC 文档。内部由 manager-spec 智能体分析需求,生成没有歧义的规格说明书。

在 v3 令牌经济学设计中,计划阶段是投入推理最多的阶段 — 需求在这里越清晰,后续实现阶段的返工和令牌浪费就越少。因此 MoAI-ADK 遵循"计划要深,实现要省"的分配原则,并且生成的 SPEC 由 plan-auditor 独立审计。创建它的智能体不会自行检查。

信息

为什么需要 SPEC?

氛围编程 (Vibe Coding) 最大的问题是 上下文丢失。

与 AI 对话时会话一旦中断,之前讨论的内容全部消失。超过令牌上限时,旧对话会最先被截断。第二天恢复工作时,AI 不记得昨天决定的事项。

SPEC 文档解决了这个问题。

将需求 保存为文件 永久留存。以 EARS 格式 毫无歧义地 结构化。即使会话中断,只要读取 SPEC 就能 继续工作。

在 Claude Code 对话框中如下输入:

> /moai plan "想要实现的功能描述"

使用示例:

# 简单功能
> /moai plan "用户登录功能"

# 详细功能描述
> /moai plan "基于 JWT 的用户认证: 登录、注册、令牌刷新 API"

# 重构请求
> /moai plan "将遗留认证系统重构为基于 JWT"

指定多个标志时,按以下顺序应用:

1. –branch: 创建传统 feature 分支
2. 无标志 (默认): 仅生成 SPEC,由用户选择是否创建分支

plan 不再创建工作空间。若要在隔离环境中规划,请先进入 worktree,再执行 plan:

moai cc -w payment          # 就地进入 worktree
> /moai plan "实现支付系统"

若要在新的 tmux 窗口中打开并保留当前会话,加上 --spawn:

moai cc -w payment --spawn

信息

同时开发多个功能 时,为每个功能分配各自的 worktree 即可互不冲突。进入由启动器 负责,plan 在其中照常运行。

SPEC 文档以 EARS (Easy Approach to Requirements Syntax) 格式定义需求。共有 5 种模式,manager-spec 智能体会自动将自然语言转换为合适的模式。

信息

无需背诵 EARS 格式。manager-spec 智能体会将自然语言 自动 转换。您只需自然地描述想要的功能即可。

/moai plan 在内部执行的过程如下:

flowchart TD
    A["用户请求
/moai plan '功能描述'"] --> B{是否明确?}
    B -->|否| C["Explore 子智能体
分析项目"]
    B -->|是| D["调用 manager-spec 智能体"]
    C --> D
    D --> E["分析需求
评估功能范围、复杂度"]
    E --> F{"需要澄清?"}
    F -->|是| G["向用户提问
确认细节"]
    G --> E
    F -->|否| H["转换为 EARS 格式
应用 5 种模式"]
    H --> I["定义验收标准
Given-When-Then"]
    I --> J["生成 SPEC 文档
spec.md, plan.md, acceptance.md"]
    J --> K{"用户批准"}
    K -->|批准| L["设置 Git 环境"]
    K -->|请求修改| E
    K -->|取消| M["结束"]
    L --> N{"检查标志"}
    N -->|--branch| P["创建分支"]
    N -->|无标志| Q["用户选择"]
    P --> R["完成"]
    Q --> R

核心要点:

• 请求不明确时,Explore 子智能体 会分析项目
• 需求不清晰时,manager-spec 智能体会 向用户追加提问
• 为所有需求自动生成 Given-When-Then 格式的验收标准
• 生成的 SPEC 文档在获得用户 批准之后 才最终确定

/moai plan 遵循由 15 个 Phase 与 2 个 Decision Point 构成的结构化工作流。Phase 1-3 是上下文发现,Phase 4-7 是深度访谈,Phase 8 之后才是正式的 SPEC 组装。

当请求模糊或需要把握项目状况时执行 Phase 1-3。明确的请求可在 Phase 3 跳过。

在明确度分数为 4-10 时执行:

manager-spec 智能体执行以下工作:

• 分析项目文档 (product.md, structure.md, tech.md)
• 提出并命名 1-3 个 SPEC 候选
• 检查重复 SPEC (.moai/specs/)
• 设计 GEARS 结构(也允许 EARS 遗留格式)
• 识别实现计划与技术约束条件
• 确认库版本(仅稳定版,排除 beta/alpha)

Phase 8 完成后,用户必须明确批准才能进入下一阶段。有 4 个选项:

在生成 SPEC 之前防止常见错误:

Step 1 - 文档类型分类:

• 检测 SPEC、Report、Documentation 关键词
• Report 路由到 .moai/reports/
• Documentation 路由到 .moai/docs/

Step 2 - SPEC ID 验证(必须通过所有检查):

• ID 格式: SPEC-域-编号 模式(例: SPEC-AUTH-001)
• 域名称: 已批准的域列表 (AUTH, API, UI, DB, REFACTOR, FIX, UPDATE, PERF, TEST, DOCS, INFRA, DEVOPS, SECURITY 等)
• ID 唯一性: 在 .moai/specs/ 中检查重复
• 目录结构: 必须创建目录,禁止平铺文件

复合域规则: 建议最多 2 个域(例: UPDATE-REFACTOR-001),最多允许 3 个

三个文件同时生成:

spec.md:

• YAML frontmatter(12 个必填字段: id, title, version, status, created, updated, author, priority, phase, module, lifecycle, tags)
• HISTORY 部分(紧跟在 frontmatter 之后)
• 完整的 GEARS/EARS 结构(5 种需求类型)
• 以 conversation_language 编写的内容

plan.md:

• 工作分解实现计划
• 技术栈规格与依赖
• 风险分析与缓解策略

acceptance.md:

• 至少 2 个 Given/When/Then 场景
• 边界情况测试场景
• 性能与质量门禁标准

质量约束条件:

• 需求模块: 每个 SPEC 最多 5 个
• 验收标准: 至少 2 个 Given/When/Then 场景
• 技术术语与函数名保持英文

plan-auditor 子智能体独立审计 manager-spec 编写的 SPEC 产出物。遵循制作的智能体不检查自己结果的 独立审计原则。

• 最多 3 轮迭代 (Retry Loop Contract)
• 每轮出现分数回退时给出 STOP 信号 + 缩小范围建议
• PASS / PASS-with-debt / FAIL 三种判定
• 审计报告保存到 .moai/reports/plan-audit/

若无 --no-issue 标志则创建 GitHub issue 并与 SPEC 建立双向引用。从 v3.0.0 起 issue 创建默认省略,可用 --issue 标志显式启用。

通过 BODP (Branch Origin Decision Protocol) 门禁 决定分支策略:

• –branch:创建传统的 feature 分支
• 保持当前分支:无标志时在当前 checkout 上继续

识别在实现阶段要添加的 @MX 代码注释目标:

• @MX:ANCHOR —— 不变契约(high fan_in 函数)
• @MX:WARN —— 危险区间(goroutine, 复杂度 ≥ 15)
• @MX:NOTE —— 上下文/意图记录

验证 GEARS/EARS 需求与验收标准(AC)之间的覆盖,并执行安全范围检查。

SPEC 生成完成后选择下一步。详情请参阅 Decision Point 3.5 部分。

SPEC 文档保存在 .moai/specs/ 目录中:

.moai/
└── specs/
    └── SPEC-AUTH-001/
        ├── spec.md          # GEARS 需求
        ├── plan.md          # 实现计划
        └── acceptance.md     # 验收标准

SPEC 文档的基本结构:

---
id: SPEC-AUTH-001
version: 1.0.0
status: ACTIVE
created: 2026-01-28
updated: 2026-01-28
author: 开发团队
priority: HIGH
---

SPEC 文档具有如下状态生命周期:

flowchart TD
    A["DRAFT
撰写中"] --> B["ACTIVE
批准完成"]
    B --> C["IN_PROGRESS
实现中"]
    C --> D["COMPLETED
完成"]
    B --> E["REJECTED
拒绝"]

在既有代码库(棕地)项目中对 SPEC 需求进行分类。

在 Plan phase 自动生成 SPEC 文档的摘要版 (spec-compact.md)。Run phase 加载摘要版而非完整 spec.md,可 节省约 30% 令牌 — 这是令牌经济学装置内嵌于 SPEC 生命周期之中的典型例子。

强制 Exclusions (“What NOT to Build”): 所有 SPEC 文档必须包含 Out of Scope / Exclusions 部分。预先防止范围偏移。

What/Why 约束: SPEC 需求只描述 What (什么) 和 Why (为什么)。How (如何) 在实现阶段决定,不在 SPEC 中过度规格化。

在 Plan 完成后、Run 开始前,自动检测执行环境并向用户推荐最优模式。

检测项目:

1. tmux 可用性 ($TMUX 环境变量)
2. 当前 LLM 模式 (llm.yaml 的 team_mode: cc/glm/cg)

tmux 可用时:

• Worktree + {当前模式} (Recommended)
• Team Mode (in-process)
• Sub-agent Mode (sequential)

tmux 不可用时:

• Sub-agent Mode (Recommended)
• Team Mode (in-process)

第 1 步: 执行命令

> /moai plan "基于 JWT 的用户认证系统: 注册、登录、令牌刷新"

第 2 步: manager-spec 提问 (必要时)

manager-spec 智能体可能会为确认细节而提问:

• “密码最小长度是多少位?”
• “令牌过期时间设置为多久?”
• “是否也包括社交登录?”

第 3 步: SPEC 文档生成结果

将生成如下结构的 SPEC 文档:

---
id: SPEC-AUTH-001
title: 基于 JWT 的用户认证系统
priority: HIGH
status: ACTIVE
---

# 需求 (EARS 格式)

## Ubiquitous

- 系统应当使用 bcrypt 对所有密码进行哈希后存储
- 系统应当记录所有认证请求

## Event-driven

- WHEN 使用有效凭证登录时,THEN 应当签发 JWT 访问令牌(1 小时)与刷新
  令牌(7 天)

## Unwanted

- 系统不得以明文存储密码
- 系统不得允许使用过期令牌访问 API

第 4 步: 用户批准后设置 Git 环境

# 使用 --branch 标志时
> /moai plan "JWT 认证" --branch

# 结果:
# 1. 生成 SPEC 文档 (.moai/specs/SPEC-AUTH-001/)
# 2. 提交 SPEC (feat(spec): Add SPEC-AUTH-001)
# 3. 创建并切换到 feature/SPEC-AUTH-001 分支

第 5 步: 执行 /clear 后进入实现阶段

# 清理令牌
> /clear

# 开始实现
> /moai run SPEC-AUTH-001

可以,您可以直接编辑 .moai/specs/SPEC-XXX/spec.md 文件。添加需求或修改验收标准后执行 /moai run,修改内容就会被反映。

也可以在 Claude Code 中直接编写代码,但没有 SPEC 的话,每次会话中断都会丢失上下文。功能越复杂,先创建 SPEC 越高效。

采用 SPEC-域-编号 格式(例: SPEC-AUTH-001)

• SPEC-AUTH-001: 认证相关的第一个 SPEC
• SPEC-PAYMENT-002: 支付相关的第二个 SPEC

域由 manager-spec 根据功能所属领域自动决定。

/moai plan 只负责 生成 SPEC 文档。/moai 则从 SPEC 生成到实现、文档化,自动执行 完整工作流。

plan 没有创建 worktree 的标志。请先用启动器进入(moai cc -w <名称>),再执行 plan。–branch 是另一个选项,只在当前仓库中创建新分支。若要同时开发多个功能,进入 worktree 更能避免互相冲突。

从 MoAI-ADK v3.0.0 起,引入 GEARS (Generalized Expression for AI-Ready Specs)作为撰写 SPEC 的推荐表示法。既有的 EARS 表示法在 6 个月 内保持向后兼容,期间可以逐步迁移到 GEARS。建议新 SPEC 从一开始就遵循 GEARS 模式。

GEARS 保留了 EARS 的 5 种核心模式,同时打磨了语义边界,使 AI 编程智能体能够更清晰地解读。核心变更是 废弃 IF/THEN 模式 (归一化为 WHEN)以及 重新定义 WHERE 的语义 (静态前提条件/配置/功能开关)。

参考资料: Σ*/SubLang, “GEARS: The Spec Syntax That Makes AI Coding Actually Work”, DEV Community 2026-01-23. https://dev.to/sublang/gears-the-spec-syntax-that-makes-ai-coding-actually-work-4f3f

迁移窗口自 v3.0.0 发布起 6 个月,或至 SPEC-V3R6-GEARS-SWEEP-001(provisional) 批量修正 SPEC 完成之时,以先到者为准。窗口期内的行为如下。

• 非 strict 模式(默认): 仅产生 LegacyEARSKeyword 代码的 warning,不导致 lint 失败
• --strict 模式(opt-in): warning 升级为 error,阻断 CI
• 既有 88 个 SPEC: 不在本 SPEC 范围内直接修改 (REQ-GM-007)。批量修正由后续 SWEEP SPEC 负责

internal/spec/lint.go 的 isLegacyEARSPattern() 助手在检测到 EARS legacy IF/THEN 模式时,输出如下消息。

REQ <REQ-ID>: GEARS migration: replace IF/THEN with WHEN/event normalization; see https://adk.mo.ai.kr/en/workflow-commands/moai-plan/#gears-notation

• 代码: LegacyEARSKeyword
• 严重度: warning (非 strict) / error (--strict)
• 来源: internal/spec/lint.go

在 downstream 工具(验证器、代码生成器、IDE 插件等)中匹配 SPEC 文本时,请按以下方式迁移。

• 将 IF .* THEN 匹配逐步转换为 WHEN .* shall 匹配
• 认知 6 个月的 deprecation 窗口,在窗口结束前实现为同时识别两种模式
• 将 LegacyEARSKeyword finding 代码用作 upgrade 信号

Before (EARS legacy):

IF input is null, THEN the system shall return an error.

After (GEARS canonical):

WHEN input is null is detected, the system shall return an error.

这种归一化通过将触发器明确表述为"事件"而非"条件",降低了 AI 智能体解读意图的模糊性,并使测试用例编写时的输入/验证时机更加清晰。

从 MoAI-ADK v0.1.0 起,AskUserQuestion 推荐 会根据用户的决策模式实现个性化。系统捕获选择,并基于观察到的统计多数(而非系统默认值)对未来的问题选项进行个性化。从循环积累观察、系统从观察中学习这一点来看,这是 v3 递归式自我学习 原则应用于提问·推荐领域的实例。

当 MoAI 通过 AskUserQuestion 提问时,适用指导推荐布局的 5 项原则:

1. Fisher 信息时机 — 在不确定性最高时(p≈0.5,Fisher 信息 I=p(1−p) 最大的决策边界)发起提问。当 p≈0 或 p≈1(几乎确定)时,系统自动处理并省略提问。

2. 问题排序 — 信息增益降序 — 需要多个问题时,按估算信息增益从高到低排序,让最重要的决策先被做出。

3. 统计多数的理性默认值 — 推荐选项(带 (推荐) 标记)反映决策记录中观察到的多数选择,而非系统策略默认值。数据不足时(cold-start)会公开 “基于默认设置,个性化需 N 次观察”。

4. 公开前提条件 — 每个推荐选项以 “Recommended when ” 格式明示成立的前提条件,便于立即评估权衡。

5. 基于熟练度的自适应强度 — 推荐强度按会话计数调节:

   • 专家 (20+ 会话): 弱强度 — 仅公开 inferred preference,不使用 (推荐) override(info-centric,尊重自主性)
   • 一般用户 (5-19 会话): 强强度 — (推荐) + 透明的依据说明
   • Cold-start (<5 会话): 中立强度 — 无 override,应用系统默认值

• 会话范围开关: 通过 moai preference toggle 按项目禁用个性化(不跨会话持久)
• 敏感域门禁: 安全相关主题(漏洞、渗透 test、泄露)采用中立推荐 + 公开日志
• 自动衰减: Transient 偏好 28 天后 soft-delete,stable 偏好(明确标记)保留
• Advisory 捕获: PostToolUse 捕获钩子绝不阻断 AskUserQuestion 执行(fail-open 设计)
• Recovery-Signal Carve-Out: 在 recovery 轮次(compact 恢复、prompt_too_long 等)中,advisory 钩子让位于恢复(遵循 recovery-signal carve-out,doctrine-honest)

信息

内部机制: 5 项原则在 .claude/rules/moai/core/askuser-protocol.md § Recommendation Placement Principles 中规格化,并渲染到 moai.md。捕获钩子实现于 internal/hook/user_decision_capture.go,支持 schema 宽容解析与域分类。衰减策略遵循 power-law 函数 (age+1)^(-0.5),α=0.5 固定(Standard tier)。完整架构与验收标准请参阅项目的 SPEC 文档。

• 基于 SPEC 的开发 - EARS 格式详解
• /moai run - 下一步: DDD 实现
• /moai sync - 最终步骤: 文档同步