Introduction

MoAI-ADK is an AI-based development environment, a comprehensive toolkit for efficiently generating high-quality code.

Notation Guide

In this documentation, command prefixes indicate the execution environment:

• Claude Code commands entered in the chat window

  > /moai plan "feature description"

• Terminal commands entered in the terminal

  moai init my-project

Core Concepts

MoAI-ADK is based on SPEC-based TDD/DDD methodology and ensures code quality through the TRUST 5 quality framework.

What is SPEC? (Easy Understanding)

SPEC (Specification) is “documenting conversations with AI.”

The biggest problem with Vibe Coding is context loss:

• 😰 Content discussed with AI for 1 hour disappears when the session ends
• 😰 To continue work the next day, you must explain from the beginning
• 😰 For complex features, results differ from intentions

SPEC solves this problem:

• ✅ Permanently preserve requirements by saving them to files
• ✅ Can continue work by reading just the SPEC even if session ends
• ✅ Define clearly without ambiguity using EARS format

What is TDD? (Easy Understanding)

TDD (Test-Driven Development) is “a method where you write tests before writing code.”

Using exam preparation as an analogy:

• 📝 Write the grading criteria (tests) first — naturally fails since the feature doesn’t exist yet
• 💡 Write minimal code to pass the criteria — exactly what’s needed, nothing more
• ✨ Refine to better code — improve while keeping tests passing

MoAI-ADK automates this process with the RED-GREEN-REFACTOR cycle:

What is DDD? (Easy Understanding)

DDD (Domain-Driven Development) is “a safe code improvement method.”

Using home remodeling as an analogy:

• 🏠 Without destroying the existing house, improve one room at a time
• 📸 Take photos of the current state before remodeling (= characterization tests)
• 🔧 Work on one room at a time, checking each time (= incremental improvement)

MoAI-ADK automates this process with the ANALYZE-PRESERVE-IMPROVE cycle:

Development Methodology Selection

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

TRUST 5 Quality Framework

TRUST 5 is based on 5 core principles:

Go Edition Features

MoAI-ADK 2.5 is a complete rewrite of the Python Edition in Go for maximum performance and efficiency.

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

System Requirements

Prerequisites:

• Git must be installed on all platforms
• Windows users: WSL (Windows Subsystem for Linux) is recommended for the best experience

Core Values

MoAI-ADK delivers the following core values:

• SPEC-based TDD/DDD: A structured methodology for documenting requirements and developing incrementally with TDD (default) or DDD for legacy code
• TRUST 5 Quality Framework: Five principles ensuring testing, readability, unification, security, and traceability
• 28 Specialized Agents: An AI agent team specialized for each stage of development
• 52 Skills: An extensible skill library supporting diverse development scenarios
• Multilingual Support: Support for 4 languages: Korean, English, Japanese, and Chinese
• Sequential Thinking MCP: Structured problem-solving through step-by-step reasoning
• Ralph-Style LSP Integration: LSP-based autonomous workflow with real-time quality feedback

Key Features

MoAI-ADK provides 28 specialized AI agents and 52 skills to automate and optimize the entire development workflow.

Agent Categories

Model Policy (Token Optimization)

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

Key Agent Model Assignment

Dual Execution Modes

Two execution modes are available: --solo (Sub-Agent mode) and --team (Agent Teams mode). Both modes autonomously determine whether to run sequentially or in parallel. Without a flag, MoAI-ADK analyzes task complexity and automatically selects the optimal mode.

/moai run SPEC-AUTH-001          # Auto selection
/moai run SPEC-AUTH-001 --team   # Force Agent Teams mode (parallel)
/moai run SPEC-AUTH-001 --solo   # Force Sub-Agent mode (sequential)

SPEC-First Workflow

MoAI-ADK follows a 3-phase development workflow. The methodology in the Run phase is automatically selected based on project state:

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

Multilingual Support

MoAI-ADK supports 4 languages:

• 🇰🇷 Korean (Korean)
• 🇺🇸 English (English)
• 🇯🇵 Japanese (Japanese)
• 🇨🇳 Chinese (Chinese)

You can select your preferred language in the installation wizard or change it directly in the configuration file.

LSP Integration

LSP (Language Server Protocol) is the standard communication protocol between code editors and language tools. It provides real-time detection of errors, type issues, and lint results, offering instant feedback to developers.

Ralph-Loop Style is an autonomous workflow that uses LSP diagnostic results as a feedback loop. When quality issues are detected, fix agents are automatically invoked and the cycle repeats until quality standards are met.

MoAI-ADK provides autonomous workflows through Ralph-Loop Style LSP integration:

• LSP-based completion marker auto-detection: Automatically detects when work is complete
• Real-time regression detection: Catches errors before they become problems
• Auto-completion trigger: Automatically completes when 0 errors, 0 type errors, 85% coverage achieved

💡 Save 50~70% Tokens with GLM

GLM is an AI model fully compatible with Claude Code. In CG Mode, combining a Claude Opus leader with GLM-5 teammates enables 50~70% token savings on implementation-heavy tasks.

CG Mode: Claude + GLM Agent Team

In CG Mode, Claude Opus orchestrates the entire workflow while GLM-5 teammates handle implementation tasks in parallel at a fraction of the cost.

Switching to GLM

# Switch to GLM backend
moai glm
 
# GLM Worker mode start (Opus leader + GLM-5 teammates)
moai glm --team
 
# CG Mode (Claude leader + GLM teammates, tmux required)
moai cg
 
# Return to Claude backend
moai cc

Getting Started

To start your MoAI-ADK journey:

1. Installation - Install MoAI-ADK on your system
2. Initial Setup - Run the interactive setup wizard
3. Quick Start - Create your first project
4. Core Concepts - Deepen your understanding of MoAI-ADK

Key Benefits

Additional Resources

• GitHub Repository 
• Documentation Site 
• Community Forum 

Next Steps

Learn about MoAI-ADK installation in the Installation Guide.