快速开始

更新 2026-08-13 6 分钟阅读在 GitHub 上编辑 ↗

用 MoAI-ADK 创建第一个项目，体验开发工作流。跟随本文，你将完整跑完从编写 SPEC 到实现、文档化的一个循环。

事前准备

开始之前需完成以下事项：

安装 MoAI-ADK（安装指南）
完成初始设置（初始设置）
获取 GLM API 密钥（可选 — 想用 CG 模式降低 token 成本时）

创建第一个项目

第 1 步：初始化项目

要创建新项目，请使用 moai init 命令：

bash

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

要在现有项目中初始化 MoAI-ADK，请进入该文件夹后执行：

bash

cd existing-project
moai init

第 2 步：生成项目文档

生成项目的基础文档。这一步对 Claude Code 理解项目至关重要 — 与其每个会话都解释项目结构，不如让智能体读这些文档。

bash

> /moai project

该命令会分析项目并自动生成以下 3 个文件：

flowchart TD
    A["项目分析"] --> B["product.md
项目信息"]
    A --> C["structure.md
目录结构"]
    A --> D["tech.md
技术栈"]

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

文件	内容
product.md	项目名、说明、目标用户、核心功能
structure.md	目录树、主要文件夹用途、模块构成
tech.md	使用的技术、框架、开发环境、构建/部署设置

信息
请在项目初始设置后或结构发生较大变更后执行 /moai project。在生成项目文档的同时，还会自动配置项目专属 harness。

第 3 步：生成 SPEC 文档

为第一个功能生成 SPEC 文档。使用 EARS 格式定义明确的需求。

信息
为什么需要 SPEC？
氛围编程 (Vibe Coding) 最大的问题是上下文丢失：
与 AI 边聊边写代码时，总有"刚才我要干什么来着？“的瞬间
会话中断或上下文被重置后，之前讨论的需求就消失了
结果就是重复同样的解释，或者做出与意图不符的代码
SPEC 文档解决了这个问题：
问题 SPEC 的解决方式
上下文丢失将需求保存为文件，永久留存
需求含糊用 EARS 格式明确结构化
沟通错误用验收标准明示完成条件
无法追踪进度用 SPEC ID 管理工作单元
一句话总结： SPEC 就是"把与 AI 的对话留成文档”。即使会话中断，只要读 SPEC 文档就能接着干 — 不重复同样的解释，token 也省了。

问题	SPEC 的解决方式
上下文丢失	将需求保存为文件，永久留存
需求含糊	用 EARS 格式明确结构化
沟通错误	用验收标准明示完成条件
无法追踪进度	用 SPEC ID 管理工作单元

bash

> /moai plan "实现用户认证功能"

该命令执行以下操作：

flowchart TD
    A["输入需求"] --> B["EARS 格式分析"]
    B --> C["生成 SPEC 文档"]
    C --> D["保存 SPEC-001"]
    D --> E["验证需求"]

生成的 SPEC 文档保存在 .moai/specs/SPEC-001/spec.md。

注意
生成 SPEC 后请用 /clear 命令清空上下文。决策事项已经留在 SPEC 文件里，没有理由保留对话记录 — 这是节省 token 的基本功。

第 4 步：执行 TDD/DDD 开发

基于 SPEC 文档推进实现。

bash

> /clear
> /moai run SPEC-001

MoAI-ADK 会根据项目状态自动选择最优开发方法论。

flowchart TD
    A["/moai run SPEC-001"] --> B{"项目分析"}
    B -->|"新项目或
测试覆盖率 10%+"| C["TDD
RED → GREEN → REFACTOR"]
    B -->|"现有项目
覆盖率低于 10%"| D["DDD
ANALYZE → PRESERVE → IMPROVE"]
    C --> E["TRUST 5 质量门禁"]
    D --> E
    style C fill:#4CAF50,color:#fff
    style D fill:#2196F3,color:#fff

TDD 模式（新项目 / 测试覆盖率 10%+）

先写测试、再让测试通过，按 RED-GREEN-REFACTOR 循环实现。各阶段分别代表什么，请见 SPEC 驱动开发。

DDD 模式（现有项目 / 测试覆盖率低于 10%）

先用特性测试把现有行为固定下来，再按 ANALYZE-PRESERVE-IMPROVE 循环逐步改进。详细内容请见 DDD。

信息
/moai run 会自动以 85% 以上的测试覆盖率为目标进行开发。开发方法论可在 .moai/config/sections/quality.yaml 的 development_mode 中手动更改。

完成条件：

测试覆盖率 >= 85%
0 errors、0 type errors
达到 LSP 基线

完成判定靠的是证据而非感觉 — 每一条验收标准都注册为任务，测试通过才会被勾选。

第 5 步：文档同步

开发完成后，自动进行质量验证并生成文档。

bash

> /clear
> /moai sync SPEC-001

该命令执行以下操作：

graph TD
    A["质量验证"] --> B["运行测试"]
    A --> C["lint 检查"]
    A --> D["类型检查"]

    B --> E["生成文档"]
    C --> E
    D --> E

    E --> F["API 文档"]
    E --> G["架构图"]
    E --> H["README/CHANGELOG"]

    F --> I["Git 提交与 PR"]
    G --> I
    H --> I

完整开发工作流

sequenceDiagram
    participant Dev as 开发者
    participant Project as "/moai project"
    participant Plan as "/moai plan"
    participant Run as "/moai run"
    participant Sync as "/moai sync"
    participant Git as "Git 仓库"

    Dev->>Project: 初始化项目
    Project->>Project: 生成基础文档
    Project-->>Dev: product/structure/tech.md

    Dev->>Plan: 输入功能需求
    Plan->>Plan: 以 EARS 格式分析
    Plan-->>Dev: SPEC-001 文档

    Note over Dev: 执行 /clear

    Dev->>Run: 执行 SPEC-001
    Run->>Run: 执行 TDD/DDD 循环
    Run->>Run: 生成测试 (85%+)
    Run-->>Dev: 实现完成

    Note over Dev: 执行 /clear

    Dev->>Sync: 请求文档化
    Sync->>Sync: 质量验证与文档生成
    Sync-->>Dev: 文档完成

    Dev->>Git: 提交并创建 PR

一体化自动化：/moai

要一次性自动执行所有步骤，用自然语言发出请求即可：

bash

> /moai "实现用户认证功能"

请求会经过 Analyze-First 路由 — 无论用哪种语言发出请求，都先分析意图，上下文不足时通过提问补全，然后自动执行 Plan → Run → Sync 流水线。

flowchart TD
    A["/moai '自然语言请求'"] --> B["意图分析
Analyze-First"]
    B --> C{"上下文充分？"}
    C -->|"不足"| D["澄清提问"]
    D --> B
    C -->|"充分"| E["构成执行计划
技能·智能体链"]
    E --> F["自动执行 Plan → Run → Sync"]

工作流选择指南

场景	推荐命令	理由
新项目	先执行 `/moai project`	基础文档必需
简单功能	`/moai plan` + `/moai run`	快速执行
复杂功能	`/moai`	自动优化
并行开发	用 `moai cc -w <名称>` 进入 worktree	保证独立环境

实战示例

示例 1：简单的 API 端点

bash

# 1. 生成项目文档（首次一次）
> /moai project

# 2. 生成 SPEC
> /moai plan "实现用户列表查询 API 端点"
> /clear

# 3. 实现
> /moai run SPEC-001
> /clear

# 4. 文档化与 PR
> /moai sync SPEC-001

示例 2：复杂功能（自然语言自动化）

bash

# 若项目文档已存在，可用自然语言一次性执行
> /moai "实现 JWT 认证中间件"

示例 3：并行开发（使用 Worktree）

bash

# 先进入 worktree，再在其中规划
$ moai cc -w payment
> /moai plan "实现支付系统"

理解文件结构

MoAI-ADK 项目的标准结构：

text

my-first-project/
├── CLAUDE.md                        # Claude Code 项目指南
├── CLAUDE.local.md                  # 项目本地设置（个人用）
├── .mcp.json                        # MCP 服务器设置
├── .claude/
│   ├── agents/                      # Claude Code 智能体定义
│   ├── commands/                    # 斜杠命令定义
│   ├── hooks/                       # 钩子脚本
│   ├── skills/                      # 可复用技能
│   └── rules/                       # 项目规则
├── .moai/
│   ├── config/
│   │   └── sections/
│   │       ├── user.yaml            # 用户信息
│   │       ├── language.yaml        # 语言设置
│   │       ├── quality.yaml         # 质量门禁设置
│   │       └── git-strategy.yaml    # Git 策略设置
│   ├── project/
│   │   ├── product.md               # 项目概述
│   │   ├── structure.md             # 目录结构
│   │   └── tech.md                  # 技术栈
│   ├── specs/
│   │   └── SPEC-001/
│   │       └── spec.md              # 需求规格说明书
│   └── memory/
│       └── checkpoints/             # 会话检查点
├── src/
│   └── [项目源代码]
├── tests/
│   └── [测试文件]
└── docs/
    └── [生成的文档]

质量检查

开发过程中随时可以检查质量：

bash

moai doctor

该命令检查以下内容：

LSP 诊断（错误、警告）
测试覆盖率
lint 状态
安全验证

graph TD
    A["moai doctor"] --> B["LSP 诊断"]
    A --> C["测试覆盖率"]
    A --> D["lint 状态"]
    A --> E["安全验证"]

    B --> F["综合报告"]
    C --> F
    D --> F
    E --> F

实用技巧

token 管理

每个步骤结束后执行 /clear 清空上下文。决策事项已以文件形式留在 SPEC 与 progress.md 中，即使没有对话记录也能继续下一步：

bash

> /moai plan "实现复杂功能"
> /clear  # 重置会话
> /moai run SPEC-001
> /clear
> /moai sync SPEC-001

Bug 修复与自动化

bash

# 自动修复（单次通过）
> /moai fix "修复测试中出现的 TypeError"

# 反复修复（直到完成）
> /moai loop "修复所有 linter 警告"

# 完成条件声明式循环
> /moai goal "go test ./... exits 0; 解决所有 lint 警告"

下一步

在核心概念中了解 MoAI-ADK 的深入功能。