Quick Start

Create your first project with MoAI-ADK and experience the development workflow.

Prerequisites

Before starting, ensure the following are complete:

MoAI-ADK installed (Installation Guide)
Initial setup completed (Initial Setup)
GLM API key obtained

Creating Your First Project

Step 1: Project Initialization

Use the moai init command to create a new project:


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

To initialize MoAI-ADK in an existing project, navigate to that folder and run:


cd existing-project
moai init

Step 2: Generate Project Documentation

Generate basic project documentation. This step is essential for Claude Code to understand the project.


> /moai project

This command analyzes the project and automatically generates 3 files:

File	Content
product.md	Project name, description, target users, key features
structure.md	Directory tree, folder purposes, module composition
tech.md	Technologies used, frameworks, development environment, build/deploy config

Run /moai project after initial project setup or when structure changes significantly.

Step 3: Create SPEC Document

Create a SPEC document for your first feature. Use EARS format to define clear requirements.

Why do we need SPEC? 📝

The biggest problem with Vibe Coding is context loss:

While coding with AI, you reach moments like “Wait, what were we trying to do?”
When session ends or context initializes, previously discussed requirements disappear
Eventually, you repeat explanations or get code that differs from intentions

SPEC documents solve this problem:

Problem	SPEC Solution
Context loss	Permanently preserve requirements by saving to files
Ambiguous requirements	Structure clearly with EARS format
Communication errors	Specify completion conditions with acceptance criteria
Cannot track progress	Manage work units with SPEC ID

One-line summary: SPEC is “documenting conversations with AI.” Even if session ends, you can continue working by reading the SPEC document!


> /moai plan "Implement user authentication feature"

This command performs the following:

The generated SPEC document is saved at .moai/specs/SPEC-001/spec.md.

After SPEC creation, always run /clear to save tokens.

Step 4: TDD/DDD Development Execution

Execute implementation based on the SPEC document by selecting the appropriate development methodology.


> /clear
> /moai run SPEC-001

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

TDD Mode (New Projects / 10%+ Test Coverage)

What is TDD? 📝

TDD is “writing the exam questions before studying”:

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

Key point: Tests come before code!

RED-GREEN-REFACTOR Cycle:

Phase	Meaning	What it does
🔴 RED	Fail	Write a test for a feature that doesn’t exist yet
🟢 GREEN	Pass	Write minimal code to make the test pass
🔵 REFACTOR	Improve	Improve code quality while keeping tests passing

DDD Mode (Existing Projects / Under 10% Test Coverage)

What is DDD? 🏠

DDD is similar to “home remodeling”:

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

Key point: Safely improve while preserving existing behavior!

ANALYZE-PRESERVE-IMPROVE Cycle:

Phase	Analogy	Actual Work
ANALYZE (Analyze)	🔍 House inspection	Understand current code structure and problems
PRESERVE (Preserve)	📸 Take photos of current state	Record current behavior with characterization tests
IMPROVE (Improve)	🔧 Remodel one room at a time	Make incremental improvements while tests pass

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

Completion Criteria:

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

Step 5: Document Synchronization

When development is complete, automatically generate quality validation and documentation.


> /clear
> /moai sync SPEC-001

This command performs the following:

Complete Development Workflow

Integrated Automation: /moai

To automatically execute all phases at once:


> /moai "Implement user authentication feature"

MoAI automatically executes Plan → Run → Sync, providing 3-4x faster analysis with parallel exploration.

Workflow Selection Guide

Situation	Recommended Command	Reason
New Project	Run `/moai project` first	Basic documentation required
Simple Feature	`/moai plan` + `/moai run`	Quick execution
Complex Feature	`/moai`	Auto optimization
Parallel Development	Use `--worktree` flag	Independent environment guarantee

Practical Examples

Example 1: Simple API Endpoint


# 1. Generate project documentation (first time only)
> /moai project
 
# 2. Create SPEC
> /moai plan "Implement user list API endpoint"
> /clear
 
# 3. Implement
> /moai run SPEC-001
> /clear
 
# 4. Document & PR
> /moai sync SPEC-001

Example 2: Complex Feature (Using MoAI)


# If project documentation exists, execute all at once with MoAI
> /moai "Implement JWT authentication middleware"

Example 3: Parallel Development (Using Worktree)


# Parallel development in independent environments
> /moai plan "Implement payment system" --worktree

Understanding File Structure

Standard MoAI-ADK project structure:


my-first-project/
├── CLAUDE.md                        # Claude Code project guidelines
├── 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 information
│   │       ├── 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                  # Technology stack
│   ├── specs/
│   │   └── SPEC-001/
│   │       └── spec.md              # Requirements specification
│   └── memory/
│       └── checkpoints/             # Session checkpoints
├── src/
│   └── [project source code]
├── tests/
│   └── [test files]
└── docs/
    └── [generated documentation]

Quality Check

Check quality anytime during development:


moai doctor

This command verifies:

LSP diagnostics (errors, warnings)
Test coverage
Linter status
Security verification

Useful Tips

Token Management

For large projects, run /clear after each phase to save tokens:


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

Bug Fix & Automation


# Auto fix
> /moai fix "Fix TypeError in tests"
 
# Repeat fix until complete
> /moai loop "Fix all linter warnings"

Next Steps

Learn about MoAI-ADK’s advanced features in Core Concepts.