Quick Start

Create your first project with MoAI-ADK and experience the development workflow. Following this document takes you through a full cycle — from writing a SPEC to implementation and documentation.

Before starting, the following should be done:

• MoAI-ADK installed (Installation Guide)
• Initial setup completed (Initial Setup)
• GLM API key acquired (optional — if you want to cut token costs with CG mode)

To create a new project, use the moai init command:

moai init my-first-project
cd my-first-project

To initialize MoAI-ADK in an existing project, move into that folder and run:

cd existing-project
moai init

Generate the project’s foundational documents. This step is essential for Claude Code to understand your project — instead of explaining the project structure every session, the agents read these documents.

> /moai project

This command analyzes the project and automatically generates these 3 files:

flowchart TD
    A["Project analysis"] --> B["product.md
Project info"]
    A --> C["structure.md
Directory structure"]
    A --> D["tech.md
Tech stack"]

    B --> E[".moai/project/"]
    C --> E
    D --> E

Info

Run /moai project after initial project setup or after major structural changes. Along with the project documents, a project-specific harness is configured automatically.

Create a SPEC document for your first feature. It uses the EARS format to define clear requirements.

Info

Why do you need a SPEC?

The biggest problem with vibe coding (Vibe Coding) is context loss:

• While coding through conversation with the AI, there comes a moment of “wait, what was I trying to do?”
• When the session drops or the context is reset, the requirements you discussed earlier disappear
• You end up repeating the same explanation, or getting code that diverges from your intent

The SPEC document solves this:

Problem	How the SPEC solves it
Context loss	Requirements saved as files, preserved permanently
Ambiguous requirements	Clearly structured in the EARS format
Communication errors	Completion conditions stated as acceptance criteria
No progress tracking	Work units managed by SPEC ID

One-line summary: A SPEC is “recording your conversation with the AI as a document”. Even if the session drops, reading the SPEC lets you pick up where you left off — and since you don’t repeat the same explanation, you save tokens too.

> /moai plan "Implement user authentication"

This command does the following:

flowchart TD
    A["Requirements input"] --> B["EARS-format analysis"]
    B --> C["SPEC document generation"]
    C --> D["SPEC-AUTH-001 saved"]
    D --> E["Requirements verification"]

The generated SPEC document is saved at .moai/specs/SPEC-AUTH-001/spec.md (SPEC IDs follow the SPEC-<domain>-<number> format).

Warning

After creating the SPEC, clear the context with the /clear command. The decisions are already recorded in the SPEC file, so there is no reason to keep the conversation history — this is token-saving 101.

Implementation proceeds based on the SPEC document.

> /clear
> /moai run SPEC-AUTH-001

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

flowchart TD
    A["/moai run SPEC-AUTH-001"] --> B{"Project analysis"}
    B -->|"New project or
test coverage 10%+"| C["TDD
RED → GREEN → REFACTOR"]
    B -->|"Existing project
coverage under 10%"| D["DDD
ANALYZE → PRESERVE → IMPROVE"]
    C --> E["TRUST 5 quality gates"]
    D --> E
    style C fill:#4CAF50,color:#fff
    style D fill:#2196F3,color:#fff

Implementation follows the RED-GREEN-REFACTOR cycle: write the test first, then make it pass. What each phase of the cycle means is covered in SPEC-Based Development.

Work proceeds through the ANALYZE-PRESERVE-IMPROVE cycle: pin the existing behavior down with characterization tests, then improve it bit by bit. The details are covered in DDD.

Info

/moai run automatically develops toward 85%+ test coverage. The development methodology can be changed manually via development_mode in .moai/config/sections/quality.yaml.

Completion conditions:

• Test coverage >= 85%
• 0 errors, 0 type errors
• LSP baseline achieved

Completion is judged by evidence, not by feel — each acceptance criterion is registered as a task and checked off only when its tests pass.

Once development is complete, quality verification and documentation are generated automatically.

> /clear
> /moai sync SPEC-AUTH-001

This command does the following:

graph TD
    A["Quality verification"] --> B["Run tests"]
    A --> C["Lint checks"]
    A --> D["Type checks"]

    B --> E["Documentation generation"]
    C --> E
    D --> E

    E --> F["API docs"]
    E --> G["Architecture diagrams"]
    E --> H["README/CHANGELOG"]

    F --> I["Git commit and PR"]
    G --> I
    H --> I

sequenceDiagram
    participant Dev as Developer
    participant Project as "/moai project"
    participant Plan as "/moai plan"
    participant Run as "/moai run"
    participant Sync as "/moai sync"
    participant Git as "Git repository"

    Dev->>Project: Initialize project
    Project->>Project: Generate foundational docs
    Project-->>Dev: product/structure/tech.md

    Dev->>Plan: Enter feature requirements
    Plan->>Plan: Analyze in EARS format
    Plan-->>Dev: SPEC-AUTH-001 document

    Note over Dev: Run /clear

    Dev->>Run: Run SPEC-AUTH-001
    Run->>Run: Execute TDD/DDD cycle
    Run->>Run: Generate tests (85%+)
    Run-->>Dev: Implementation complete

    Note over Dev: Run /clear

    Dev->>Sync: Request documentation
    Sync->>Sync: Quality verification and doc generation
    Sync-->>Dev: Documentation complete

    Dev->>Git: Commit and create PR

To run every phase automatically at once, make a natural-language request:

> /moai "Implement user authentication"

The request goes through Analyze-First routing — whatever language you use, intent is analyzed first, missing context is filled in with questions, and then the Plan → Run → Sync pipeline runs automatically.

flowchart TD
    A["/moai 'natural-language request'"] --> B["Intent analysis
Analyze-First"]
    B --> C{"Enough context?"}
    C -->|"Insufficient"| D["Clarifying questions"]
    D --> B
    C -->|"Sufficient"| E["Compose execution plan
Skill and agent chain"]
    E --> F["Plan → Run → Sync automatic execution"]

# 1. Generate project docs (first time only)
> /moai project

# 2. Create a SPEC
> /moai plan "Implement a user list API endpoint"
> /clear

# 3. Implement
> /moai run SPEC-AUTH-001
> /clear

# 4. Document and open a PR
> /moai sync SPEC-AUTH-001

# If project docs already exist, run everything at once with natural language
> /moai "Implement JWT authentication middleware"

# Enter the worktree first, then plan inside it
$ moai cc -w payment
> /moai plan "Implement a payment system"

The standard structure of a MoAI-ADK project:

my-first-project/
├── CLAUDE.md                        # Claude Code project instructions
├── CLAUDE.local.md                  # Project-local settings (personal)
├── .mcp.json                        # MCP server configuration
├── .claude/
│   ├── agents/                      # Claude Code agent definitions
│   ├── commands/                    # Slash command definitions
│   ├── hooks/                       # Hook scripts
│   ├── skills/                      # Reusable skills
│   └── rules/                       # Project rules
├── .moai/
│   ├── config/
│   │   └── sections/
│   │       ├── user.yaml            # User info
│   │       ├── language.yaml        # Language settings
│   │       ├── quality.yaml         # Quality gate settings
│   │       └── git-strategy.yaml    # Git strategy settings
│   ├── project/
│   │   ├── product.md               # Project overview
│   │   ├── structure.md             # Directory structure
│   │   └── tech.md                  # Tech stack
│   ├── specs/
│   │   └── SPEC-AUTH-001/
│   │       └── spec.md              # Requirements specification
│   └── memory/
│       └── checkpoints/             # Session checkpoints
├── src/
│   └── [project source code]
├── tests/
│   └── [test files]
└── docs/
    └── [generated docs]

You can check quality at any time during development:

moai doctor

This command checks:

• Claude Code configuration
• Dependency verification (whether tools like git, go are installed)
• Environment diagnostics

Run detailed diagnostics with subcommands — moai doctor config (config), moai doctor hook (hook coverage), moai doctor permission (permissions), moai doctor sandbox (sandbox).

graph TD
    A["moai doctor"] --> B["Claude Code config"]
    A --> C["Dependency verification"]
    A --> D["Environment diagnostics"]

    B --> F["Consolidated report"]
    C --> F
    D --> F

Run /clear after each phase to empty the context. The decisions live on as files in the SPEC and progress.md, so you can continue to the next phase without conversation history:

> /moai plan "Implement a complex feature"
> /clear  # Reset the session
> /moai run SPEC-AUTH-001
> /clear
> /moai sync SPEC-AUTH-001

# Auto-fix (single pass)
> /moai fix "Fix the TypeError occurring in the tests"

# Iterative fixing (until done)
> /moai loop "Fix all linter warnings"

# Condition-declared loop
> /moai goal "go test ./... exits 0; all lint warnings resolved"

Explore MoAI-ADK’s advanced features in Core Concepts.