What is MoAI-ADK?

MoAI-ADK is an Agentic Development Kit that wraps Claude Code around three core concerns — cost, self-improvement, and quality control. Same quality of code for fewer tokens (cost, Tokenomics); every turn the session runs, observations accumulate as rules so the harness gets better (self-improvement, Agentic Loop Engineering); and SPEC 3-phase + TRUST 5 gates keep rework out so ‘done’ is judged by evidence (quality control, Agentic Harness) — model selection, reasoning depth, and context usage are enforced from the outside by the system. 11 specialist AI agents and 31 skills work together, applying TDD (the default) to new projects and DDD to existing projects with low test coverage, automatically.

A single binary written in Go – runs immediately on every platform with zero dependencies.

Info

One-line summary: MoAI-ADK is an agentic development kit that “records your conversations with the AI as documents (SPECs), improves code safely (DDD/TDD), and verifies quality automatically (TRUST 5)” — while the system enforces all three from the outside: cost (Tokenomics), self-improvement (Agentic Loop Engineering), and quality control (Agentic Harness).

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

MoAI-ADK is a development kit that has agents collaborate on agentic coding inside Claude Code. Like an AI development team collaborating to finish a project, each agent takes on the work of its own specialty.

The value of v3.0 comes down to three core concerns.

Intelligent resource allocation that maximizes quality per cost. This core concern consists of the 3-tier model policy that declaratively assigns model and reasoning depth by work phase and SPEC size, CG mode that combines a Claude leader with GLM workers to cut implementation cost by 60-70%, the Token Circuit Breaker that stops gracefully before the budget is exceeded, and the context diet that shrinks always-loaded context.

The loop works on its own, and observations accumulate along the way. This core concern includes the goal engine that keeps the session working until a declared completion condition is met, the Ralph Engine (/moai loop) that iterates on fixes until the queue of issues found by diagnostic tools is drained, and Analyze-First routing that analyzes the intent of natural-language requests regardless of language. The accumulated observations become the raw material of harness learning, and guidance evolves along the 4-tier learning ladder (observation → heuristic → rule → auto-update) — auto-updates are always applied only under the user-approval gate.

Instead of writing code yourself, you design an environment where agents work well. This core concern is the 11-agent catalog, the SPEC-based 3-phase workflow (plan → run → sync), the TRUST 5 quality gates, and the Harness v4 Builder that creates project-specific harnesses from natural-language requests. For the full concept, see the Harness Engineering document.

Optimize cost alone and quality collapses, followed by rework and debugging loops — and rework is the most expensive token spend of all. Erect quality gates alone and the same mistakes repeat every session. Run autonomous loops without a cost ceiling and one runaway task eats the quota. The three core concerns hold each other up — cost stays economical because quality keeps rework out, quality is enforceable because the loop remembers the patterns it learned, and the loop stops at the right price because the cost gate halts it before the budget breaks.

Token unit prices keep falling, but agentic development’s token consumption grows faster. With multiple agents running, longer contexts, and deeper reasoning, what determines cost is not model pricing but how tokens are operated.

MoAI-ADK’s answer is threefold.

1. Assign the right model and reasoning depth per task — plan deeply, implement cheaply, verify independently.
2. Diet the context — minimize always-loaded guidance and measure prompt-cache hit rates.
3. Let the system keep the budget — track token usage and stop gracefully before crossing the threshold.

Declare a completion condition and the session works on its own until the condition is met (/moai goal); the routing decisions and gate evidence produced along the way accumulate as observations that feed harness learning. Observations are promoted into guidance along the 4-tier learning ladder (observation → heuristic → rule → auto-update), and auto-updates are always applied only under the user-approval gate.

Instead of writing code yourself, you design an environment where agents work well. The 11-agent catalog separates planning from auditing at design time so the author never scores its own work, and the SPEC 3-phase (plan → run → sync) plus TRUST 5 gates and worktree isolation judge completion by evidence, not by “it seems done”.

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

• 11 agents in the catalog (10 MoAI custom + 1 Anthropic built-in Explore)
• 31 skills (template-managed)
• 36 CLI commands · 16 /moai subcommands
• 16 programming languages supported
• A codebase developed with a SPEC-based workflow (plan → run → sync)

Vibe coding (Vibe Coding) means writing code through natural conversation with an AI. Say “build me this feature” and the AI generates code. It is intuitive and fast, but in practice serious problems arise.

flowchart TD
    A["Write code in conversation with the AI"] --> B["Good result produced"]
    B --> C["Session drops or\ncontext reset"]
    C --> D["Context lost"]
    D --> E["Explain from scratch again"]
    E --> A

Concrete problems in practice:

Prerequisites:

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

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

Recommended: using WSL with the Linux install command above provides the best experience.

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

Git for Windows must be installed first.

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

Prebuilt binaries can be downloaded from the Releases page.

moai init my-project

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

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

You can also make natural-language requests directly — /moai "fix the login bug" goes through Analyze-First intent analysis and is routed to the right workflow.

Warning

“The purpose of vibe coding is not fast productivity but code quality.”

MoAI-ADK is not a tool for churning out code quickly. The goal is to use AI to produce code of higher quality than a human would write directly. Speed is the side effect that follows naturally when quality is protected.

This philosophy is embodied in three principles:

1. SPEC-First: before writing code, define clearly in a document what will be built
2. Safe improvement (DDD/TDD): improve incrementally while preserving the behavior of existing code
3. Automatic quality verification (TRUST 5): verify all code automatically with the five quality principles

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

The default methodology for new projects and new feature development. Because you write the test first and then make it pass, the behavior you intend is settled before the code is. MoAI-ADK makes this the default so that “it’s done” is decided by test results rather than by anyone’s gut feeling. Each phase of the cycle, and the pre-RED analysis phase for brownfield projects, are covered in SPEC-Based Development.

The methodology for safely working on existing code that has almost no tests. Current behavior is pinned down with characterization tests before any improvement, which prevents the refactor from quietly breaking what already worked. That is why MoAI-ADK assigns this methodology to projects under 10% coverage. The step-by-step procedure is covered in DDD.

Info

The methodology is auto-selected at moai init (--mode <ddd|tdd>, default: tdd) and can be changed via development_mode in .moai/config/sections/quality.yaml.

Note: MoAI-ADK v2.5.0+ uses a binary methodology choice (TDD or DDD only). The hybrid mode was removed for clarity and consistency.

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

Info

“Human steers, agents execute.” — The engineer’s role shifts from writing code to designing the harness (SPECs, quality gates, feedback loops). The full concept is covered in the Harness Engineering document.

MoAI is the strategic orchestrator. It does not write code directly — it delegates work to the 11 retained agents (10 MoAI custom + 1 Anthropic built-in Explore). The core design principle is separating planning from auditing — the one who builds it does not inspect it.

Cost colors follow the default medium profile’s model×effort cells (inspect via moai model profile): 🔴 opus+high · 🟠 opus+medium · 🔵 opus+low · 🩵 sonnet+low · ⚪ session-model inherit (user-added agents). Assignments shift when switching profiles (high/low).

flowchart TD
    MoAI["MoAI orchestrator\nAnalyzes user requests and delegates"]

    subgraph Managers["Manager agents (5)"]
        M1["manager-spec\nPlan phase: SPEC creation"]
        M2["manager-develop\nRun phase: DDD/TDD implementation"]
        M3["manager-docs\nSync phase: documentation"]
        M4["manager-git\nPR creation, Git operations"]
        M5["manager-design\nDesign collaboration"]
    end

    subgraph Evaluators["Evaluator agents (2)"]
        E1["plan-auditor\nIndependent SPEC audits"]
        E2["sync-auditor\n4-dimension quality assessment"]
    end

    subgraph BuilderAdvisor["Builder · Advisor (2)"]
        B1["builder-harness\nDynamic harness generation"]
        B2["super-advisor\nHigh-reasoning consultation"]
    end

    subgraph Specialist["Specialist (1)"]
        S1["e2e-tester\nE2E test execution"]
    end

    subgraph Explore["Built-in (1)"]
        X1["Explore\nRead-only code analysis"]
    end

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

Managed token-efficiently through a 3-level Progressive Disclosure system. Only the skill descriptions (~100 tokens) are always listed; the body (~5K tokens) loads only when actually invoked — one of the core means of the context diet.

MoAI’s core workflow consists of 3 phases:

flowchart TD
    Start(["Development begins"]) --> Plan

    subgraph Plan["1. Plan phase"]
        P1["Codebase exploration"] --> P2["Requirements analysis"]
        P2 --> P3["SPEC document creation\nGEARS format"]
    end

    Plan --> Run

    subgraph Run["2. Run phase"]
        R1["SPEC analysis and\nexecution planning"] --> R2["DDD/TDD implementation"]
        R2 --> R3["TRUST 5\nquality verification"]
    end

    Run --> Sync

    subgraph Sync["3. Sync phase"]
        S1["Documentation generation"] --> S2["README/CHANGELOG updates"]
        S2 --> S3["Pull Request creation"]
    end

    Sync --> Done(["Development complete"])

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

The Plan-phase artifacts are independently audited by the plan-auditor, and right before entering the Run phase there is the Implementation Kickoff Approval (a human gate). When the Sync phase ends, the sync-auditor performs a 4-dimension quality assessment — completion is judged by evidence, not “it seems done”.

A real usage example:

# 1. Plan: define the requirements
> /moai plan "Implement JWT-based user authentication"

# 2. Run: implement with DDD/TDD
> /moai run SPEC-AUTH-001

# 3. Sync: generate docs and PR
> /moai sync SPEC-AUTH-001

At the transition from Plan to Run, MoAI automatically detects the current execution environment (cc/glm/cg) and shows a selection UI the user can confirm or change.

flowchart TD
    A["Plan complete"] --> B["Environment detection"]
    B --> C{"Mode selection UI"}
    C -->|"CC"| D["Claude-only execution"]
    C -->|"GLM"| E["GLM-only execution"]
    C -->|"CG"| F["Claude Leader + GLM Workers"]

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

All subcommands run inside Claude Code as /moai <subcommand>.

The MoAI orchestrator analyzes task complexity and selects the execution shape.

Info

Changed in v3.0: The old Agent Teams static-orchestration layer has been retired. Forcing --team falls back to sub-agent mode. However, Claude Code’s native teammate runtime — the tmux split panes of moai cg — is unaffected. The team-mode quality hooks (TeammateIdle’s LSP gate verification, TaskCompleted’s SPEC-reference checks) are also preserved along with the native teammate runtime.

The practical tool of the Tokenomics core concern. A hybrid mode where the Leader uses the Claude API and the Workers use the GLM API, implemented via tmux session-level environment-variable isolation. Claude handles strategy, planning, and audits; GLM handles bulk implementation — cutting costs 60-70% on implementation-heavy work.

┌─────────────────────────────────────────────────────────────┐
│  LEADER (current tmux pane, Claude API)                      │
│  - Orchestrates with /moai commands after activating moai cg │
│  - Handles the plan, quality, and sync phases                │
│  - No GLM env → uses the Claude API                          │
└──────────────────────┬──────────────────────────────────────┘
                       │ Agent Teams (new tmux panes)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  TEAMMATES (new tmux panes, GLM API)                         │
│  - Inherit the tmux session env → use the GLM API            │
│  - Execute implementation work in the run phase              │
│  - Communicate with the leader via SendMessage               │
└─────────────────────────────────────────────────────────────┘

# 1. Save the GLM API key (once)
moai glm setup sk-your-glm-api-key

# 2. Activate CG mode (run inside a tmux session — Claude Code starts automatically)
moai cg

# 3. Run the workflow
/moai "task description"

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

/moai fix       # Single pass: scan → classify → fix → verify
/moai loop      # Iterative fixing: repeat until the completion condition is met (up to 10 iterations by default)

How the Ralph Engine works:

1. Parallel scanning: run LSP diagnostics + AST-grep + linters simultaneously
2. Automatic classification: classify errors from level 1 (auto-fixable) to level 4 (user intervention)
3. Convergence detection: apply an alternative strategy when the same error repeats
4. Completion criteria: 0 errors, 0 type errors, 85%+ coverage

If you want to declare the completion condition yourself, use the goal engine:

/moai goal "go test ./... exits 0; all ACs recorded as PASS"
/moai goal status
/moai goal clear

/moai loop is a preset on top of the goal engine — it keeps fixing until the queue of issues found by the diagnostic tools is drained.

New feature development:

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

Bug fixing:

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

Refactoring:

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

Documentation updates:

/moai codemaps → /moai sync

Every code change is verified against five criteria: Tested, Readable, Unified, Secured, and Trackable. The point is to hold code to the same yardstick every time rather than to a reviewer’s taste, and each criterion comes with a check a machine can decide — coverage, lint, formatting, security scan, commit convention. The detailed checks behind each criterion are covered in TRUST 5.

MoAI-ADK uses the @MX code-level annotation system to convey 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 needs no tags, and that is by design.

# Scan the full codebase
/moai mx --all

# Preview (no file changes)
/moai mx --dry

# Scan by priority
/moai mx --priority P1

MoAI-ADK assigns the optimal model and reasoning depth to each agent. The goal is maximizing quality within the plan’s usage limits — the policy moves each agent along the Opus effort ladder rather than swapping in a weaker model class, because on long-horizon agentic work a weaker model spends more steps and costs more per task.

# During project initialization
moai init my-project          # Select the model policy in the interactive wizard

# Reconfigure an existing project
moai update                   # Interactive prompts for each setup step

Info

The default policy is medium. GLM settings are isolated in settings.local.json (never committed to Git). The config key is profile: high | medium | low (the profile matrix column) in llm.yaml, and the legacy performance_tier field is read as an alias when profile is absent (--high/--low are deprecated aliases of --model-policy high/low). You can set it directly with the --profile high|medium|low flag; the legacy max value is also accepted as input and normalized to high.

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 analysis, performance optimization, cost tracking

A PostToolUse hook logs metrics when the Task tool completes. Use this data to analyze agent efficiency and optimize token consumption — tokenomics starts with measurement.

Installing MoAI-ADK creates the following structure in your project.

my-project/
├── CLAUDE.md                  # MoAI's execution directive
├── .claude/
│   ├── agents/moai/           # 10 MoAI custom agent definitions (+ the Explore built-in)
│   ├── skills/moai-*/         # 31 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 repository
    │   └── SPEC-XXX/
    │       └── spec.md
    └── memory/                # Cross-session context persistence

Key files:

MoAI-ADK supports 4 languages. Ask in Korean and it answers in Korean; ask in English and it answers in English.

Info

Language settings: in .moai/config/sections/language.yaml you can set the conversation language, code comment language, and commit message language independently. For example, converse in Korean while writing code comments and commit messages in English.

Now that you understand the full picture of MoAI-ADK, it is time to explore each core concept in detail.

• Harness Engineering – Learn the paradigm of designing the environment agents work in
• SPEC-Based Development – Learn how requirements are defined as documents
• Domain-Driven Development – Learn how to improve existing code safely
• TRUST 5 Quality – Learn how code quality is verified automatically
• MoAI Memory – Learn how context is preserved across sessions