MoAI-ADK是什么？

MoAI-ADK是为Claude Code打造的 高性能AI开发环境。28个专业AI Agent和52个技能协同工作，生产高质量代码。新项目和功能开发默认采用TDD，测试覆盖率低的现有项目自动采用DDD，同时支持Sub-Agent和Agent Teams双重执行模式。

使用Go语言编写的单一二进制文件 — 无依赖，在所有平台上即可运行。

MoAI-ADK简介

MoAI 意为”所有人的AI” (MoAI - Everybody’s AI)。ADK 是Agentic Development Kit的缩写，指AI Agent主导开发过程的工具集。

MoAI-ADK是一个 使Agent能够在Claude Code内通过交互进行Agent编码的Agentic Development Kit。就像AI开发团队协作完成项目一样，MoAI-ADK的AI Agent在各自的专业领域执行开发工作并相互协作。

为什么选择MoAI-ADK？

从Python到Go的完全重写

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

核心数据

• 34,220行 Go代码，32个 包
• 85-100% 测试覆盖率
• 28个 专业AI Agent + 52个 技能
• 18种 编程语言支持
• 16个 Claude Code Hook事件

Vibe Coding的问题

Vibe Coding 是一种与AI自然对话来编写代码的方式。你说”帮我做这个功能”，AI就生成代码。这种方式直观且快速，但在实际工作中会产生严重问题。

实际工作中遇到的具体问题:

MoAI-ADK的解决方案

系统要求

前提条件:

• 所有平台需要安装 Git
• Windows用户: 必须安装 Git for Windows  （包含Git Bash）
  • 推荐使用 WSL (Windows Subsystem for Linux) 获得最佳体验
  • PowerShell 7.x以上作为备选方案支持
  • 旧版Windows PowerShell 5.x和cmd.exe 不支持

快速开始

1. 安装

macOS / Linux / WSL

curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash

Windows (PowerShell 7.x+)

推荐: 使用上述Linux安装命令配合WSL可获得最佳体验。

irm https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.ps1 | iex

需要先安装 Git for Windows 。

从源码构建 (Go 1.26+)

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

预编译二进制文件可从 Releases  页面下载。

2. 项目初始化

moai init my-project

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

3. 在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创建

核心理念

这一理念体现为三个原则:

1. 规范优先 (SPEC-First): 在编写代码之前，先用文档明确定义要构建什么
2. 安全改进 (DDD/TDD): 在保留现有代码行为的同时逐步改进
3. 自动质量验证 (TRUST 5): 用5个质量原则自动验证所有代码

MoAI开发方法论

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

TDD方法论（默认）

新项目和功能开发的默认方法论。先编写测试，然后再实现。

对于棕地项目 (现有代码库)，TDD会增加一个 pre-RED分析阶段: 在编写测试前先阅读现有代码以理解当前行为。

DDD方法论（现有项目，覆盖率低于10%）

用于安全重构测试覆盖率低的现有项目的方法论。

ANALYZE   → 分析现有代码和依赖，识别领域边界
PRESERVE  → 编写特征化测试，捕获当前行为快照
IMPROVE   → 在测试保护下逐步改进。IMPROVE 完成后 /simplify 自动运行。

Harness Engineering 架构

MoAI-ADK 实现了 Harness Engineering 范式 — 不是直接编写代码，而是设计 AI 代理工作的环境。

自动质量和横向扩展层

MoAI-ADK v2.6.0+ 集成了两个 MoAI 自主调用的 Claude Code 原生技能 — 无需标志或手动命令。

/simplify — 自动质量检查

使用并行代理审查修改后的代码，检查复用机会、质量问题、效率和 CLAUDE.md 合规性，然后自动修复发现的问题。MoAI 在每个实现周期后直接调用。

/batch — 并行横向扩展

在隔离的 git worktree 中生成数十个代理进行大规模并行工作。每个代理运行测试并报告结果；MoAI 负责合并。按工作流自动触发：

AI Agent编排

MoAI是 战略编排器。它不直接编写代码，而是将任务委派给28个专业Agent。

Agent分类

52个技能 (Progressive Disclosure)

通过3级Progressive Disclosure系统实现token高效管理:

MoAI工作流

Plan → Run → Sync流水线

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

实际使用示例:

# 1. Plan: 定义需求
> /moai plan "实现基于JWT的用户认证功能"
 
# 2. Run: 以DDD/TDD方式实现
> /moai run SPEC-AUTH-001
 
# 3. Sync: 生成文档及PR
> /moai sync SPEC-AUTH-001

/moai子命令

所有子命令在Claude Code内以 /moai <子命令> 方式执行。

核心工作流

质量与测试

文档与代码库

默认工作流

执行模式标志

控制Agent在工作流执行中如何分配:

--team 支持3种执行环境:

执行模式选择门控

从 Plan 阶段过渡到 Run 阶段时，MoAI 自动检测当前执行环境 (cc/glm/cg) 并显示选择 UI，供用户在实现开始前确认或更改模式。

此门控确保无论环境状态如何，都使用正确的执行模式，防止实现过程中出现模式不匹配。

自律开发循环 (Ralph Engine)

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

/moai fix       # 单次: 扫描 → 分类 → 修复 → 验证
/moai loop      # 反复修复: 循环直到检测到完成标记（最多100次）

Ralph Engine工作方式:

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

推荐工作流链

新功能开发:

/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 coverage → /moai codemaps

文档更新:

/moai codemaps → /moai sync

TRUST 5质量框架

所有代码变更都通过5个质量标准进行验证:

@MX标签系统

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

@MX标签系统的设计目标是 只标记最危险和最重要的代码。大部分代码不需要标签，这是正常的设计。

# 扫描整个代码库
/moai mx --all
 
# 预览（不修改文件）
/moai mx --dry
 
# 按优先级扫描
/moai mx --priority P1

模型策略 (Token优化)

MoAI-ADK根据Claude Code订阅套餐为28个Agent分配最优AI模型。在套餐的使用限制内最大化质量。

配置方法

# 项目初始化时
moai init my-project          # 在交互式向导中选择模型策略
 
# 重新配置现有项目
moai update                   # 各设置步骤的交互式提示

双重执行模式

MoAI-ADK提供Claude Code支持的 Sub-Agent 和 Agent Teams 两种执行模式。

Agent Teams模式（默认）

MoAI-ADK自动分析项目复杂度来选择最优执行模式:

Agent Teams模式 使用并行团队协作开发:

• 多个Agent同时工作，通过共享任务列表协作
• 通过 TeamCreate、SendMessage、TaskList 进行实时协调
• 适用于大规模功能开发、多域任务

/moai plan "大规模功能"          # 自动: researcher + analyst + architect并行
/moai run SPEC-XXX                # 自动: backend-dev + frontend-dev + tester并行
/moai run SPEC-XXX --team         # 强制Agent Teams模式

CG模式 (Claude + GLM混合)

CG模式是Leader使用 Claude API、Workers使用 GLM API 的混合模式。通过tmux会话级环境变量隔离实现。

┌─────────────────────────────────────────────────────────────┐
│  LEADER（当前tmux窗格，Claude API）                           │
│  - /moai --team 执行时进行工作流编排                          │
│  - 处理plan、quality、sync阶段                               │
│  - 无GLM环境 → 使用Claude API                                │
└──────────────────────┬──────────────────────────────────────┘
                       │ Agent Teams（新tmux窗格）
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  TEAMMATES（新tmux窗格，GLM API）                             │
│  - 继承tmux会话环境 → 使用GLM API                             │
│  - 在run阶段执行实现任务                                      │
│  - 通过SendMessage与Leader通信                                │
└─────────────────────────────────────────────────────────────┘

# 1. 保存GLM API密钥（只需一次）
moai glm sk-your-glm-api-key
 
# 2. 激活CG模式
moai cg
 
# 3. 在同一窗格中启动Claude Code（重要！）
claude
 
# 4. 执行团队工作流
/moai --team "任务描述"

Sub-Agent模式 (--solo)

使用现有Claude Code的 Task() API进行顺序Agent委派。

• 将任务委派给一个专业Agent并接收结果
• 按Manager → Expert → Quality顺序逐步推进
• 适用于简单可预测的工作流

/moai run SPEC-AUTH-001 --solo    # 强制Sub-Agent模式

CLI命令

Task指标日志

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

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

Task工具完成时，PostToolUse Hook会记录指标。利用这些数据来分析Agent效率并优化Token消耗。

项目结构

安装MoAI-ADK后，项目中将生成以下结构。

my-project/
├── CLAUDE.md                  # MoAI的执行指令书
├── .claude/
│   ├── agents/moai/           # 28个AI Agent定义
│   ├── skills/moai-*/         # 52个技能模块
│   ├── hooks/moai/            # 自动化Hook脚本
│   └── rules/moai/            # 编码规则和标准
└── .moai/
    ├── config/                # MoAI配置文件
    │   └── sections/
    │       └── quality.yaml   # TRUST 5质量设置
    ├── specs/                 # SPEC文档存储
    │   └── SPEC-XXX/
    │       └── spec.md
    └── memory/                # 跨会话上下文保持

主要文件说明:

多语言支持

MoAI-ADK支持4种语言。用户用中文请求时用中文回复，用英文请求时用英文回复。

下一步

如果您已经了解了MoAI-ADK的全貌，现在可以深入了解各个核心概念了。

• 基于SPEC的开发 — 了解如何将需求定义为文档
• 领域驱动开发 — 了解如何安全改进现有代码
• TRUST 5质量 — 了解如何自动验证代码质量
• MoAI Memory — 了解跨会话上下文如何保留