MoAI-ADK

Claude Code 的 Agent 开发套件 (Agentic Development Kit)

English · 한국어 · 日本語 · 中文

---

📚 官方文档

---

“Vibe coding 的目的不在于追求开发速度，而在于提升代码质量。”

MoAI-ADK 是一个专为 Claude Code 设计的高性能 AI 开发环境。它包含 24 个专业 AI Agent 和 52 种技能，协同工作以输出高质量代码。对于新项目和功能开发，它会自动应用 TDD（测试驱动开发）；对于测试覆盖率较低的现有项目，则应用 DDD（领域驱动设计）。该工具支持通过 Sub-Agent 和 Agent Teams 进行双重模式执行。

它是一个由 Go 语言编写的单一二进制文件，在任何平台上都能实现零依赖、即时运行。

---

为什么选择 MoAI-ADK？

我们使用 Go 语言完全重写了原有的 Python 版 MoAI-ADK（约 73,000 行代码）。

特性	Python 版本	Go 版本
分发方式	pip + venv + 依赖项	单一二进制文件，零依赖
启动时间	~800ms (解释器启动)	~5ms (原生执行)
并发处理	asyncio / threading	原生 goroutines
类型安全	运行时 (mypy 可选)	编译时强制执行
跨平台	需 Python 运行时	预构建二进制文件 (macOS, Linux, Windows)
Hook 执行	Shell wrapper + Python	编译后二进制文件，JSON 协议

关键数据

• 38,700+ 行 Go 代码，38 个包
• 85-100% 测试覆盖率
• 26 个专业 AI Agent + 47 种技能
• 18 种支持的编程语言
• 27 个 Claude Code hook 事件

---

Harness Engineering (工程化架构)

MoAI-ADK 实现了 Harness Engineering 范式——即为 AI Agent 设计环境，而不是直接编写代码。

组件	描述	命令
自我验证循环 (Self-Verify Loop)	Agent 自动执行：编写代码 → 测试 → 失败 → 修复 → 通过	/moai loop
上下文映射 (Context Map)	为 Agent 提供实时的代码库架构映射和文档	/moai codemaps
会话持久化 (Session Persistence)	通过 progress.md 跨会话追踪进度；中断后可自动恢复	/moai run SPEC-XXX
失败清单 (Failing Checklist)	运行开始时将所有验收标准注册为待办任务，实现后自动标记完成	/moai run SPEC-XXX
语言无关 (Language-Agnostic)	支持 16 种语言：自动检测语言并选择正确的 LSP/linter/测试/覆盖率工具	所有工作流
垃圾回收 (Garbage Collection)	定期扫描并移除无效代码、AI 冗余代码 (AI Slop) 和未使用的导入	/moai clean
脚手架优先 (Scaffolding First)	在实现之前创建空文件存根，以防止系统熵增	/moai run SPEC-XXX

“人类引导，Agent 执行。” —— 工程师的角色从直接编写代码转变为设计 Harness：即 SPEC、质量关卡和反馈循环。

---

系统要求

平台	支持的环境	备注
macOS	Terminal, iTerm2	完全支持
Linux	Bash, Zsh	完全支持
Windows	WSL (推荐), PowerShell 7.x+	不支持原生 cmd.exe

前提条件：

• 所有平台均需安装 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+)

推荐：使用 WSL 并通过上述 Linux 安装命令安装以获得最佳体验。

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. Windows 特有问题

用户名包含非 ASCII 字符路径错误

如果您的 Windows 用户名包含非 ASCII 字符（如中文、韩文等），由于 Windows 8.3 短文件名转换问题，可能会遇到 EINVAL 错误。

方案 1：设置备用临时目录：

# 命令提示符 (cmd)
set MOAI_TEMP_DIR=C:\temp
mkdir C:\temp 2>nul

# PowerShell
$env:MOAI_TEMP_DIR="C:\temp"
New-Item -ItemType Directory -Path "C:\temp" -Force

方案 2：禁用 8.3 文件名生成（需管理员权限）：

fsutil 8dot3name set 1

方案 3：创建一个仅包含 ASCII 字符的 Windows 用户账号。

3. 初始化项目

moai init my-project

交互式向导将自动检测您的编程语言和框架。