What is MoAI-ADK?

MoAI-ADK is a high-performance AI development environment for Claude Code. 28 specialized AI agents and 52 skills collaborate to produce high-quality code. It automatically applies TDD (default) for new projects and feature development, and DDD for existing projects with low test coverage, while supporting both Sub-Agent and Agent Teams dual execution modes.

Written as a single Go binary — runs instantly on all platforms with zero dependencies.

MoAI-ADK Introduction

MoAI means “Everybody’s AI” (MoAI - Everybody’s AI). ADK stands for Agentic Development Kit, a toolkit where AI agents lead the development process.

MoAI-ADK is an Agentic Development Kit that enables agents to perform agentic coding through interaction within Claude Code. Just like an AI development team collaborating to complete a project, MoAI-ADK’s AI agents perform development work in their respective areas of expertise while collaborating with each other.

Why MoAI-ADK?

Complete Rewrite from Python to Go

The Python-based MoAI-ADK (~73,000 lines) was completely rewritten in Go.

Key Numbers

• 34,220 lines of Go code, 32 packages
• 85-100% test coverage
• 28 specialized AI agents + 52 skills
• 18 programming languages supported
• 16 Claude Code Hook events

Problems with Vibe Coding

Vibe Coding is a method of writing code while naturally conversing with AI. You say “create this feature” and AI generates code. It’s intuitive and fast, but causes serious problems in practice.

Specific problems encountered in practice:

MoAI-ADK Solutions

System Requirements

Prerequisites:

• Git must be installed on all platforms
• Windows users: Git for Windows  is required (includes Git Bash)
  • WSL (Windows Subsystem for Linux) is recommended for the best experience
  • PowerShell 7.x or later is supported as an alternative
  • Legacy Windows PowerShell 5.x and cmd.exe are not supported

Quick Start

1. Installation

macOS / Linux / WSL

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

Windows (PowerShell 7.x+)

Recommended: Use WSL with the Linux install command above for the best experience.

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

Git for Windows  must be installed first.

Build from Source (Go 1.26+)

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

Pre-built binaries can be downloaded from the Releases  page.

2. Project Initialization

moai init my-project

An interactive wizard auto-detects your language, framework, and methodology, then generates Claude Code integration files.

3. Start Development in Claude Code

# After launching Claude Code
/moai project                            # Generate project docs (product.md, structure.md, tech.md)
/moai plan "Add user authentication"     # Create SPEC document
/moai run SPEC-AUTH-001                  # DDD/TDD implementation
/moai sync SPEC-AUTH-001                 # Sync documentation and create PR

Core Philosophy

This philosophy is concretized in three principles:

1. SPEC-First: Before writing code, clearly define what to build in a document
2. Safe Improvement (DDD/TDD): Incrementally improve while preserving existing code behavior
3. Auto Quality Validation (TRUST 5): Automatically validate all code with 5 quality principles

MoAI Development Methodology

MoAI-ADK automatically selects the optimal development methodology based on the project state.

TDD Methodology (Default)

The default methodology for new projects and feature development. Write tests first, then implement.

For brownfield projects (existing codebases), TDD adds a pre-RED analysis phase: read existing code to understand current behavior before writing tests.

DDD Methodology (Existing Projects, < 10% Coverage)

A methodology for safely refactoring existing projects with low test coverage.

ANALYZE   → Analyze existing code and dependencies, identify domain boundaries
PRESERVE  → Write characterization tests, capture current behavior snapshots
IMPROVE   → Improve incrementally under test protection. /simplify runs automatically after IMPROVE completes.

Harness Engineering Architecture

MoAI-ADK implements the Harness Engineering paradigm — designing the environment for AI agents rather than writing code directly.

Auto Quality and Scale-Out Layer

MoAI-ADK v2.6.0+ integrates two Claude Code native skills that MoAI invokes autonomously — no flags or manual commands required.

/simplify — Automatic Quality Pass

Uses parallel agents to review changed code for reuse opportunities, quality issues, efficiency, and CLAUDE.md compliance, then auto-fixes findings. MoAI calls this directly after every implementation cycle — no configuration needed.

/batch — Parallel Scale-Out

Spawns dozens of agents in isolated git worktrees for large-scale parallel work. Each agent runs tests and reports results; MoAI merges them. Auto-triggered per workflow:

AI Agent Orchestration

MoAI is a strategic orchestrator. It does not write code directly, but delegates work to 28 specialized agents.

Agent Categories

52 Skills (Progressive Disclosure)

Managed token-efficiently with a 3-level Progressive Disclosure system:

MoAI Workflow

Plan → Run → Sync Pipeline

MoAI’s core workflow consists of 3 phases:

Actual usage example:

# 1. Plan: Define requirements
> /moai plan "Implement JWT-based user authentication"
 
# 2. Run: Implement with DDD/TDD
> /moai run SPEC-AUTH-001
 
# 3. Sync: Generate documentation and PR
> /moai sync SPEC-AUTH-001

Execution Mode Selection Gate

When transitioning from Plan to Run phase, MoAI automatically detects the current execution environment (cc/glm/cg) and presents a selection UI for the user to confirm or change the mode before implementation begins.

This gate ensures the correct execution mode is used regardless of the environment state, preventing mode mismatches during implementation.

/moai Subcommands

All subcommands are invoked within Claude Code as /moai <subcommand>.

Core Workflow

Quality and Testing

Documentation and Codebase

Default Workflow

Execution Mode Flags

Controls how agents are deployed during workflow execution:

--team supports 3 execution environments:

Autonomous Development Loop (Ralph Engine)

An autonomous error-fixing engine that combines LSP diagnostics with AST-grep:

/moai fix       # Single pass: scan → classify → fix → verify
/moai loop      # Iterative fix: repeat until completion marker detected (max 100)

How Ralph Engine works:

1. Parallel Scan: Run LSP diagnostics + AST-grep + linters simultaneously
2. Auto Classification: Classify errors from Level 1 (auto-fix) to Level 4 (user intervention)
3. Convergence Detection: Apply alternative strategies when the same errors repeat
4. Completion Criteria: 0 errors, 0 type errors, 85%+ coverage

Recommended Workflow Chains

New feature development:

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

Bug fix:

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

Refactoring:

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

Documentation update:

/moai codemaps → /moai sync

TRUST 5 Quality Framework

All code changes are validated against 5 quality criteria:

@MX Tag System

MoAI-ADK uses the @MX code-level annotation system to communicate context, invariants, and danger zones between AI agents.

The @MX tag system is designed to mark only the most dangerous and important code. Most code does not need tags, and this is by design.

# Scan entire codebase
/moai mx --all
 
# Preview only (no file modifications)
/moai mx --dry
 
# Scan by priority
/moai mx --priority P1

Model Policy (Token Optimization)

MoAI-ADK assigns optimal AI models to 28 agents based on your Claude Code subscription plan. It maximizes quality within your plan’s rate limits.

Configuration

# During project initialization
moai init my-project          # Select model policy in interactive wizard
 
# Reconfigure existing project
moai update                   # Interactive prompts for each configuration step

Dual Execution Modes

MoAI-ADK provides both Sub-Agent and Agent Teams execution modes supported by Claude Code.

Agent Teams Mode (Default)

MoAI-ADK automatically analyzes project complexity to select the optimal execution mode:

Agent Teams mode uses parallel team-based development:

• Multiple agents work simultaneously, collaborating via shared task list
• Real-time coordination through TeamCreate, SendMessage, and TaskList
• Ideal for large-scale feature development and multi-domain tasks

/moai plan "large-scale feature"    # Auto: researcher + analyst + architect in parallel
/moai run SPEC-XXX                  # Auto: backend-dev + frontend-dev + tester in parallel
/moai run SPEC-XXX --team           # Force Agent Teams mode

CG Mode (Claude + GLM Hybrid)

CG mode is a hybrid mode where the Leader uses the Claude API and Workers use the GLM API. It is implemented through tmux session-level environment variable isolation.

┌─────────────────────────────────────────────────────────────┐
│  LEADER (current tmux pane, Claude API)                      │
│  - Orchestrates workflow when /moai --team is executed        │
│  - Handles plan, quality, sync phases                        │
│  - No GLM env → uses Claude API                              │
└──────────────────────┬──────────────────────────────────────┘
                       │ Agent Teams (new tmux panes)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  TEAMMATES (new tmux panes, GLM API)                         │
│  - Inherits tmux session env → uses GLM API                  │
│  - Executes implementation tasks in run phase                │
│  - Communicates with leader via SendMessage                  │
└─────────────────────────────────────────────────────────────┘

# 1. Store GLM API key (one-time)
moai glm sk-your-glm-api-key
 
# 2. Activate CG mode
moai cg
 
# 3. Start Claude Code in the same pane (important!)
claude
 
# 4. Execute team workflow
/moai --team "task description"

Sub-Agent Mode (--solo)

A sequential agent delegation approach using the existing Claude Code Task() API.

• Delegates work to a single expert agent and receives results
• Proceeds step by step in Manager → Expert → Quality order
• Suitable for simple, predictable workflows

/moai run SPEC-AUTH-001 --solo    # Force Sub-Agent mode

CLI Commands

Task Metrics Logging

MoAI-ADK automatically captures Task tool metrics during development sessions:

• Location: .moai/logs/task-metrics.jsonl
• Captured Metrics: Token usage, tool calls, duration, agent type
• Purpose: Session analytics, performance optimization, cost tracking

The PostToolUse hook logs metrics when a Task tool completes. Use this data to analyze agent efficiency and optimize token consumption.

Project Structure

When you install MoAI-ADK, the following structure is created in your project.

my-project/
├── CLAUDE.md                  # MoAI execution guidelines
├── .claude/
│   ├── agents/moai/           # 28 AI agent definitions
│   ├── skills/moai-*/         # 52 skill modules
│   ├── hooks/moai/            # Automation hook scripts
│   └── rules/moai/            # Coding rules and standards
└── .moai/
    ├── config/                # MoAI configuration files
    │   └── sections/
    │       └── quality.yaml   # TRUST 5 quality settings
    ├── specs/                 # SPEC document storage
    │   └── SPEC-XXX/
    │       └── spec.md
    └── memory/                # Cross-session context persistence

Key file descriptions:

Multilingual Support

MoAI-ADK supports 4 languages. When users request in Korean, it responds in Korean; when requested in English, it responds in English.

Next Steps

Now that you understand the big picture of MoAI-ADK, it’s time to learn each core concept in detail.

• SPEC-Based Development — Learn how to define requirements as documents
• Domain-Driven Development — Learn how to safely improve existing code
• TRUST 5 Quality — Learn how to automatically validate code quality
• MoAI Memory — Learn how context is preserved across sessions