常见问题

以下是使用 MoAI-ADK 时经常被问到的问题与解答。

它们是完全不同的两样东西。这是最常见的混淆，先说清楚。

• 在终端运行 moai plan 不会生效 — /moai plan 只在 Claude Code 内有效。
• moai init 是用于设置项目的终端命令；在 Claude Code 中，用 /moai project 生成项目文档。

MoAI statusline 同时显示版本信息与更新提醒：

🗿 v3.1.2 -> 🗿 v3.1.3

• 🗿 v3.1.2：当前已安装的版本
• -> 🗿 v3.1.3：可更新的新版本（用 ASCII 箭头 -> 相连）

使用最新版本时只显示版本号：

🗿 v3.1.3

更新方法：执行 moai update 后更新提醒会消失。

信息

提示：这与 Claude Code 内置的版本显示（🔅 v2.1.38）不同。MoAI 显示追踪的是 MoAI-ADK 版本，Claude Code 会单独显示自己的版本。

statusline 按段落逐个开关。把各个段落分别打开或关闭，只留下你想看的信息。没有显示预设 —— 配置只有主题和段落两样。

可在 moai init 或 moai update -c 向导中设置，或直接编辑 .moai/config/sections/statusline.yaml：

statusline:
  segments:
    model: true
    context: true
    output_style: false
    directory: false
    git_status: true
    claude_version: false
    moai_version: false
    git_branch: true

没有 segments: 块时，默认启用全部段落。

信息

详细内容请参考 SPEC-STATUSLINE-001。

v3.2 起，逐智能体的模型策略已经没有可选项了。子代理沿用主会话的模型与推理深度 —— 生成子代理时不传 model 也不传 effort，MoAI 智能体定义对两者都不作声明。剩下的是会话层面的一个选择：moai profile setup 的会话模型策略，决定以此配置启动的 Claude 会话的默认推理强度（未单独选择推理强度时生效）。

注意

为什么重要？ 降低 effort 主要降低的是推理深度，而不是模型级别。在长时程 agentic 任务中，Opus 的 low effort 比任何 effort（包括 max）的 Sonnet 评分更高、每任务成本更低 —— 账单由模型完成任务所花的步数决定，而不是按 token 的单价。这份节省的落点现在是会话 effort，旧版本的逐智能体分配表已经退役。

到 v3.1 为止，MoAI-ADK 通过配置矩阵给 13 个目录智能体各自分配 {model, effort}，策略层级选出矩阵的一列。这套装置在 SPEC-AGENT-MODEL-INHERIT-001 中退役了 —— 实测显示带 model 参数的调用不足 1%，分配的位置因此移到了会话本身。旧的 --model-policy、--profile、--high、--medium-alias、--low 旗标以只打印警告、没有任何效果的弃用桩形式保留。

# 设置会话模型策略（会话模型策略问题）
moai profile setup

# 既有项目重新设置
moai update -c                # 重新运行设置向导

信息

默认 effort 回退为 medium。可在 moai profile setup 中修改，或用 /effort、ultrathink 随时调整会话 effort —— 之后的全部子代理生成都跟随该值。

打开项目时，Claude Code 可能针对外部文件 import 显示安全提示：

External imports:
  /Users/<user>/.moai/config/sections/quality.yaml
  /Users/<user>/.moai/config/sections/user.yaml
  /Users/<user>/.moai/config/sections/language.yaml

信息

推荐操作： 请选择 “No, disable external imports”。

原因：

• 项目的 .moai/config/sections/ 中已存在这些文件
• 项目级设置优先于全局设置
• 必需的设置已包含在 CLAUDE.md 文本中
• 禁用外部 import 更安全，且不影响功能

文件说明：

• quality.yaml：TRUST 5 框架及开发方法论设置
• language.yaml：语言设置（对话、注释、提交）
• user.yaml：用户名（可选，用于 Co-Authored-By 显示）

MoAI-ADK v2.5.0+ 在方法论上只能二选一（仅 TDD 或 DDD）。为了清晰与一致性，hybrid 模式已被移除。

TDD 是先写测试、再让测试通过的顺序，因此适合新开发；DDD 则是先用特性测试把现有行为固定下来、再逐步改动，因此适合几乎没有测试的代码。两个循环的分阶段流程请见 SPEC 驱动开发与 DDD。

# 项目初始化时自动检测
moai init my-project          # 可用 --mode <ddd|tdd> 标志指定

# 手动设置
# 编辑 .moai/config/sections/quality.yaml
development_mode: tdd         # 或 ddd

这是完全正常的。@MX 标签系统的设计目标，是只标记 AI 需要优先关注的最危险、最重要的代码。

用 @MX 标签扫描代码库：

/moai mx --all        # 全部扫描
/moai mx --dry        # 预览
/moai mx --priority P1  # 仅致命项

• GitHub Discussions — 提问、想法、反馈
• Issues — Bug 报告、功能请求
• Discord 社区 — 实时交流、分享技巧