什么是 MoAI-ADK？

MoAI-ADK 是用 成本 · 自我改进 · 品质把控 三大核心把 Claude Code 包起来的 Agentic Development Kit。同等质量的代码用更少的 token 产出（成本，代币经济学），每轮会话跑过都会把观察沉淀成规则，让 harness 越用越好（自我改进，智能体循环工程），并用 SPEC 3-phase 与 TRUST 5 门禁挡住返工，用证据判定「完成」（品质把控，智能体 Harness）—— 模型选择、推理深度、上下文用量都由系统从外部强制。11 个专业 AI 智能体与 31 个技能协作，对新项目自动应用 TDD（默认），对测试覆盖率低的既有项目自动应用 DDD。

用 Go 编写的单一二进制 —— 无依赖即可在所有平台上即时运行。

信息

一句话概括: MoAI-ADK 是一个把"将与 AI 的对话作为文档(SPEC)留存、安全地改进代码(DDD/TDD)、自动验证质量(TRUST 5)“的工作 —— 由成本·自我改进·品质把控这三大核心从外部强制 —— 一并完成的智能体开发套件。

MoAI 意为"人人的 AI"(MoAI - Everybody’s AI)。ADK 是 Agentic Development Kit 的缩写,指 AI 智能体主导开发过程的工具集。

MoAI-ADK 是一个 让智能体在 Claude Code 内相互协作进行智能体式编码的开发套件。就像 AI 开发团队协作完成项目一样,每个智能体承担自己专业领域的工作。

v3.0 的价值可归纳为三大核心。

最大化性价比的智能资源分配。按作业阶段与 SPEC 大小声明式地分配模型与推理深度的 3 层模型策略,组合 Claude 领导与 GLM Worker 将实现成本降低 60-70% 的 CG 模式,在超预算前正常停止的 Token Circuit Breaker,以及缩减常驻加载上下文的 上下文瘦身 —— 这些构成了这一核心。

循环自行工作,过程中积累观察。声明完成条件后会话持续工作直到条件满足的 goal 引擎,反复修复直到清空诊断工具找到的问题的 Ralph Engine (/moai loop),把自然语言请求与语言无关地分析意图再路由的 Analyze-First 路由 都属于此。积累的观察成为 harness 学习的原料,沿 4 层学习阶梯(观察 → 启发式 → 规则 → 自动更新)使指令进化 —— 自动更新始终只在用户批准门禁之下应用。

不亲自写代码,而是设计智能体能好好工作的环境。11 个智能体目录、基于 SPEC 的 3-phase 工作流(plan → run → sync)、TRUST 5 质量门禁、用自然语言请求生成项目专用 harness 的 Harness v4 Builder 构成这一核心。详细概念请参阅harness 工程文档。

只优化成本,品质就会崩塌,随之而来的是返工与调试循环 —— 而返工恰恰是所有 token 支出里最贵的一项。只立品质门禁,每轮会话都会重复同样的失误。没有成本上限就让自主循环跑起来,一个任务失稳就会蚕食配额。三大核心互相支撑 —— 成本靠品质挡住返工才经济地维持,品质靠循环把通过的样本沉淀为可强制的规则,循环靠成本门禁在超预算前停下、停在合适的价位。

token 单价持续下降,但智能体式开发的 token 用量增长得更快。随着多个智能体运转、上下文变长、推理变深,决定成本的不是模型价格,而是 token 运用方式。

成本的实践方式有三:

1. 为每项作业分配合适的模型·推理深度 —— 计划要深,实现要便宜,验证要独立。
2. 给上下文瘦身 —— 最小化常驻加载的指令,并测量提示缓存命中率。
3. 由系统守住预算 —— 追踪 token 使用,在超过阈值前正常停止。

声明完成条件后,会话会自行工作直到条件满足（/moai goal），路由决策与门禁证据作为观察沉淀下来,成为 harness 学习的原料。观察沿 4 层学习阶梯（观察 → 启发式 → 规则 → 自动更新）晋升为指令,自动更新始终只在用户批准门禁之下应用。

不亲自写代码,而是设计智能体能好好工作的环境。11 个智能体目录从设计阶段起就把计划与审计分离,确保写的人不会给自己的工作打分;SPEC 3-phase（plan → run → sync）、TRUST 5 门禁与 worktree 隔离一起,用证据而非「好像完成了」来判定完成。

将基于 Python 的 MoAI-ADK(~73,000 行)完全用 Go 重写。

• 11 个 智能体目录(10 个 MoAI 自定义 + 1 个 Anthropic 内置 Explore)
• 31 个 技能(template-managed)
• 36 个 CLI 命令 · 16 种 /moai 子命令
• 16 种 编程语言支持
• 3 级 harness (minimal / standard / thorough)—— 依 SPEC 复杂度的自适应质量门禁
• 以 SPEC 驱动的工作流 (plan → run → sync)开发的代码库

氛围编程 (Vibe Coding)是与 AI 自然对话来编写代码的方式。说"帮我做这样的功能",AI 就生成代码。直观又快,但在实务中会出现严重问题。

flowchart TD
    A["与 AI 对话编写代码"] --> B["得出好的产出物"]
    B --> C["会话中断或\n上下文重置"]
    C --> D["上下文丢失"]
    D --> E["从头重新说明"]
    E --> A

实务中遇到的具体问题:

必要条件:

• 所有平台都需安装 Git
• Windows 用户:必须 安装 Git for Windows(含 Git Bash)
  • 为获得最佳体验,推荐使用 WSL (Windows Subsystem for Linux)
  • PowerShell 7.x 及以上作为替代方案受支持
  • 不支持 旧版 Windows PowerShell 5.x 与 cmd.exe

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

推荐:用上面的 Linux 安装命令搭配 WSL 可获得最佳体验。

irm https://adk.mo.ai.kr/install.ps1 | iex

需要先安装 Git for Windows。

git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk && make build

预构建的二进制可从 Releases 页面下载。

moai init my-project

交互式向导自动检测语言、框架、方法论后,生成 Claude Code 集成文件。

# 运行 Claude Code 后
/moai project                            # 生成项目文档 (product.md, structure.md, tech.md)
/moai plan "添加用户认证"                  # 生成 SPEC 文档
/moai run SPEC-AUTH-001                   # DDD/TDD 实现
/moai sync SPEC-AUTH-001                  # 文档同步与创建 PR

也可以直接用自然语言请求 —— /moai "帮我修登录 bug" 会经过 Analyze-First 意图分析后路由到合适的工作流。

注意

“氛围编程的目的不是快速生产,而是代码质量。”

MoAI-ADK 不是快速堆出代码的工具。它利用 AI,但目标是做出比人亲自编写 更高质量 的代码。快速是在守住质量的同时自然随之而来的附带效果。

这一哲学具体化为三条原则:

1. 规约优先 (SPEC-First):在写代码前用文档明确定义要做什么
2. 安全改进 (DDD/TDD):在保存既有代码行为的同时渐进式改进
3. 自动质量验证 (TRUST 5):用 5 项质量原则自动验证所有代码

MoAI-ADK 会依项目状态自动选择最优的开发方法论。

新项目与新功能开发的默认方法论。先写测试、再让测试通过,因此要实现的行为在代码之前就已确定。MoAI-ADK 把它设为默认,是为了让"完成了"由测试结果判定,而不是靠人的感觉。循环的各个阶段以及面向棕地项目的 pre-RED 分析阶段,请见 SPEC 驱动开发。

用于安全地改动几乎没有测试的既有代码。在着手改进之前,先用特性化测试把当前行为固定下来,从而避免重构悄悄弄坏既有功能。这正是 MoAI-ADK 为覆盖率不足 10% 的项目指派该方法论的原因。分阶段的具体流程请见 DDD。

信息

方法论在 moai init 时自动选择(--mode <ddd|tdd>,默认: tdd),可在 .moai/config/sections/quality.yaml 的 development_mode 中更改。

参考:MoAI-ADK v2.5.0+ 采用二元方法论选择(仅 TDD 或 DDD)。为明确性与一致性,hybrid 模式已被移除。

MoAI-ADK 实现 harness 工程 (Harness Engineering)范式 —— 不是亲自写代码,而是设计 AI 智能体工作环境的方法。

信息

“人把方向,智能体执行。” —— 工程师的角色从写代码转变为设计 harness(SPEC、质量门禁、反馈循环)。完整概念在harness 工程文档中讲解。

MoAI 是 战略编排器。它不亲自写代码,而是把工作委派给 11 个保留智能体(10 个 MoAI 自定义 + 1 个 Anthropic 内置 Explore)。核心设计原则是 计划与审计的分离 —— 制作者不检查。

成本颜色以默认 medium 配置文件的 model×effort 单元为准（用 moai model profile 查看）：🔴 opus+high · 🟠 opus+medium · 🔵 opus+low · 🩵 sonnet+low · ⚪ 继承会话模型（用户自行添加的智能体）。切换配置文件（high/low）时分配会变化。

flowchart TD
    MoAI["MoAI 编排器\n分析用户请求并委派"]

    subgraph Managers["Manager 智能体 (5 个)"]
        M1["manager-spec\nPlan 阶段: 生成 SPEC"]
        M2["manager-develop\nRun 阶段: DDD/TDD 实现"]
        M3["manager-docs\nSync 阶段: 文档化"]
        M4["manager-git\n创建 PR, Git 操作"]
        M5["manager-design\nDesign 协作"]
    end

    subgraph Evaluators["评估智能体 (2 个)"]
        E1["plan-auditor\n独立 SPEC 审计"]
        E2["sync-auditor\n4 维质量评估"]
    end

    subgraph BuilderAdvisor["Builder · Advisor (2 个)"]
        B1["builder-harness\n动态生成 harness"]
        B2["super-advisor\n高推理咨询"]
    end

    subgraph Specialist["Specialist (1 个)"]
        S1["e2e-tester\n执行 E2E 测试"]
    end

    subgraph Explore["内置 (1 个)"]
        X1["Explore\n只读代码分析"]
    end

    MoAI --> Managers
    MoAI --> Evaluators
    MoAI --> BuilderAdvisor
    MoAI --> Specialist
    MoAI --> Explore

用 3 级 Progressive Disclosure 系统进行 token 高效管理。只有技能说明(~100 token)常驻列表中,正文(~5K token)仅在实际调用时加载 —— 是上下文瘦身的核心手段之一。

MoAI 的核心工作流由 3 个阶段构成:

flowchart TD
    Start(["开始开发"]) --> Plan

    subgraph Plan["1. Plan 阶段"]
        P1["探索代码库"] --> P2["分析需求"]
        P2 --> P3["生成 SPEC 文档\nGEARS 格式"]
    end

    Plan --> Run

    subgraph Run["2. Run 阶段"]
        R1["分析 SPEC 并\n制定执行计划"] --> R2["DDD/TDD 实现"]
        R2 --> R3["TRUST 5\n质量验证"]
    end

    Run --> Sync

    subgraph Sync["3. Sync 阶段"]
        S1["生成文档"] --> S2["更新 README/CHANGELOG"]
        S2 --> S3["创建 Pull Request"]
    end

    Sync --> Done(["开发完成"])

    style Plan fill:#E3F2FD,stroke:#1565C0
    style Run fill:#E8F5E9,stroke:#2E7D32
    style Sync fill:#FFF3E0,stroke:#E65100

Plan 阶段产出物由 plan-auditor 独立审计,进入 Run 阶段前会经过 实施启动批准 (人工门禁)。Sync 阶段结束后 sync-auditor 执行 4 维质量评估 —— 不是"好像做完了",而是用证据判定完成。

实际使用示例:

# 1. Plan: 定义需求
> /moai plan "实现基于 JWT 的用户认证功能"

# 2. Run: 用 DDD/TDD 方式实现
> /moai run SPEC-AUTH-001

# 3. Sync: 生成文档与 PR
> /moai sync SPEC-AUTH-001

从 Plan 阶段转到 Run 阶段时,MoAI 会自动检测当前执行环境(cc/glm/cg)并显示用户可确认或更改的选择 UI。

flowchart TD
    A["Plan 完成"] --> B["环境检测"]
    B --> C{"模式选择 UI"}
    C -->|"CC"| D["Claude 专用执行"]
    C -->|"GLM"| E["GLM 专用执行"]
    C -->|"CG"| F["Claude Leader + GLM Workers"]

该门禁保证无论环境状态如何都使用正确的执行模式,防止实现过程中的模式不一致。

所有子命令都在 Claude Code 内用 /moai <子命令> 执行。

MoAI 编排器分析作业复杂度来选择执行形态。

信息

v3.0 变更:过去的 Agent Teams 静态编排层已退役。即使强制 --team 也会回退到子智能体模式。不过 Claude Code 的原生 teammate 运行时 —— moai cg 的 tmux 分割窗口 —— 原样保留。团队模式质量钩子(TeammateIdle 的 LSP 门禁验证、TaskCompleted 的 SPEC 参照确认)也与 native teammate 运行时一同保留。

代币经济学核心的实战工具。Leader 使用 Claude API、Workers 使用 GLM API 的混合模式,通过 tmux 会话级环境变量隔离实现。策略·计划·审计由 Claude 承担,大量实现由 GLM 承担,在实现为主的作业中节省 60-70% 成本。

┌─────────────────────────────────────────────────────────────┐
│  LEADER (当前 tmux pane, Claude API)                         │
│  - moai cg 激活后用 /moai 命令编排                            │
│  - 处理 plan, quality, sync 阶段                             │
│  - 无 GLM 环境 → 使用 Claude API                            │
└──────────────────────┬──────────────────────────────────────┘
                       │ Agent Teams (新 tmux pane)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  TEAMMATES (新 tmux pane, GLM API)                           │
│  - 继承 tmux 会话环境 → 使用 GLM API                        │
│  - 在 run 阶段执行实现作业                                    │
│  - 用 SendMessage 与领导通信                                  │
└─────────────────────────────────────────────────────────────┘

# 1. 保存 GLM API 密钥(仅一次)
moai glm setup sk-your-glm-api-key

# 2. 激活 CG 模式(在 tmux 会话内运行 —— Claude Code 自动启动)
moai cg

# 3. 运行工作流
/moai "作业说明"

结合 LSP 诊断与 AST-grep 的自主错误修复引擎:

/moai fix       # 单次 pass: 扫描 → 分类 → 修复 → 验证
/moai loop      # 反复修复: 直到完成条件满足(默认最多 10 次)

Ralph Engine 工作方式:

1. 并行扫描:同时运行 LSP 诊断 + AST-grep + linter
2. 自动分类:从级别 1(自动修复)到级别 4(用户介入)对错误分类
3. 收敛检测:同一错误反复出现时应用替代策略
4. 完成标准:0 错误、0 类型错误、85%+ 覆盖率

若想直接声明完成条件,可使用 goal 引擎:

/moai goal "go test ./... exits 0; 所有 AC 记录为 PASS"
/moai goal status
/moai goal clear

/moai loop 是 goal 引擎之上的预设 —— 反复修复直到清空诊断工具找到的问题队列。

新功能开发:

/moai plan → /moai run SPEC-XXX → /moai sync SPEC-XXX

Bug 修复:

/moai fix (或 /moai loop) → /moai review → /moai sync

重构:

/moai plan → /moai clean → /moai run SPEC-XXX → /moai review → /moai codemaps

文档更新:

/moai codemaps → /moai sync

所有代码变更都用 Tested · Readable · Unified · Secured · Trackable 这五项标准验证。目的是每次都对代码用同一把尺子,而不是取决于评审者的口味;每项标准都配有覆盖率、lint、格式化、安全扫描、提交规范这类可由机器判定的检查。各标准的具体验证项请见 TRUST 5。

MoAI-ADK 使用 @MX 代码级注释系统 在 AI 智能体间传递上下文、不变量、危险区域。

@MX 标签系统设计为 只标注最危险、最重要的代码。大多数代码不需要标签,这是正常的设计。

# 扫描整个代码库
/moai mx --all

# 预览(不修改文件)
/moai mx --dry

# 按优先级扫描
/moai mx --priority P1

MoAI-ADK 为每个智能体分配最优的模型与推理深度。目标是在套餐用量限制内最大化质量 —— 策略调整的是每个智能体在 Opus effort 阶梯上的位置,而不是换成更弱的模型级别,因为在长时程 agentic 作业中,更弱的模型会消耗更多步骤,每任务成本反而更高。

# 项目初始化时
moai init my-project          # 在交互式向导中选择模型策略

# 既有项目重新设置
moai update                   # 对各设置步骤给出交互式提示

信息

默认策略是 medium。GLM 设置隔离在 settings.local.json 中(不提交到 Git)。设置键是 llm.yaml 的 profile: high | medium | low(配置矩阵列)，legacy performance_tier 字段在 profile 缺失时作为别名读取(--high/--low 分别是 --model-policy high/low 的 deprecated 别名)。可用 --profile high|medium|low 标志直接指定，legacy 的 max 值也可作为输入并规范化为 high。

MoAI-ADK 在开发会话中自动捕获 Task 工具指标:

• 位置:.moai/logs/task-metrics.jsonl
• 捕获指标:token 用量、工具调用、耗时、智能体类型
• 目的:会话分析、性能优化、成本追踪

Task 工具完成时 PostToolUse 钩子记录指标。用这些数据分析智能体效率并优化 token 消耗 —— 代币经济学从测量开始。

安装 MoAI-ADK 后,项目中会生成如下结构。

my-project/
├── CLAUDE.md                  # MoAI 的执行指南
├── .claude/
│   ├── agents/moai/           # 10 个 MoAI 自定义智能体定义 (+ Explore 内置)
│   ├── skills/moai-*/         # 31 个技能模块
│   ├── hooks/moai/            # 自动化钩子脚本
│   └── rules/moai/            # 编码规则与标准
└── .moai/
    ├── config/                # MoAI 配置文件
    │   └── sections/
    │       └── quality.yaml   # TRUST 5 质量设置
    ├── specs/                 # SPEC 文档仓库
    │   └── SPEC-XXX/
    │       └── spec.md
    └── memory/                # 跨会话保持上下文

主要文件说明:

MoAI-ADK 支持 4 种语言。用户用韩语请求就用韩语回复,用英语请求就用英语回复。

信息

语言设置: 可在 .moai/config/sections/language.yaml 中分别设置对话语言、代码注释语言、提交信息语言。例如,可设置为对话用中文而代码注释与提交信息用英语。

理解了 MoAI-ADK 的全貌后,现在轮到详细了解各核心概念了。

• harness 工程 —— 学习设计智能体工作环境的范式
• 基于 SPEC 的开发 —— 学习如何把需求定义为文档
• 领域驱动开发 —— 学习安全改进既有代码的方法
• TRUST 5 质量 —— 学习自动验证代码质量的方法
• MoAI Memory —— 学习跨会话如何保存上下文