クイックスタート

MoAI-ADK で最初のプロジェクトを作成し、開発ワークフローを体験してみましょう。このドキュメントに沿って進めると、SPEC 作成から実装、ドキュメント化まで1サイクルを完走できます。

始める前に、以下が完了している必要があります:

• MoAI-ADK のインストール (インストールガイド)
• 初期設定の完了 (初期設定)
• GLM API キーの取得 (任意 — CG モードでトークンコストを節約したい場合)

新しいプロジェクトを作成するには moai init コマンドを使います:

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

既存プロジェクトで MoAI-ADK を初期化するには、そのフォルダに移動してから実行します:

cd existing-project
moai init

プロジェクトの基礎文書を生成します。このステップは Claude Code がプロジェクトを理解するために必須です。毎セッションでプロジェクト構造を説明する代わりに、エージェントがこの文書を読みます。

> /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

情報

/moai project はプロジェクトの初期設定後、または構造が大きく変わった後に実行してください。プロジェクト文書と一緒に、プロジェクト専用のハーネスも自動的に構成されます。

最初の機能に対する SPEC 文書を生成します。EARS 形式を使って明確な要件を定義します。

情報

なぜ SPEC が必要なのか?

バイブコーディング (Vibe Coding) の最大の問題は コンテキストの喪失 です:

• AI と対話しながらコーディングしていると、「さっき何をしようとしてたんだっけ?」という瞬間が訪れます
• セッションが切れたりコンテキストが初期化されると、以前議論した要件が消えます
• 結局同じ説明を繰り返すか、意図と異なるコードが作られます

SPEC 文書がこの問題を解決します:

問題	SPEC の解決方法
コンテキストの喪失	要件を ファイルとして保存 し永久保存
曖昧な要件	EARS 形式 で明確に構造化
コミュニケーションエラー	受け入れ基準 で完了条件を明示
進捗の追跡不能	SPEC ID で作業単位を管理

一言要約: SPEC は「AI と交わした対話をドキュメントとして残すこと」です。セッションが切れても SPEC 文書を読むだけで作業を再開できます。同じ説明を繰り返さないのでトークンも節約できます。

> /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 ファイルに残っているので、対話履歴を維持する理由がありません。トークン節約の基本です。

SPEC 文書をもとに実装を進めます。

> /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

テストを先に書き、そのテストを通していく RED-GREEN-REFACTOR サイクルで実装します。各ステップが何を意味するかは SPEC ベース開発 で扱います。

既存の動作を特性テストで押さえたうえで少しずつ改善していく ANALYZE-PRESERVE-IMPROVE サイクルで進めます。詳しくは DDD で扱います。

情報

/moai run は自動的に 85% 以上のテストカバレッジを目標に開発します。開発方法論は .moai/config/sections/quality.yaml の development_mode で手動変更できます。

完了条件:

• テストカバレッジ >= 85%
• 0 errors, 0 type errors
• LSP ベースラインの達成

完了判定は感覚ではなく証拠で行われます。受け入れ基準の一つひとつがタスクとして登録され、テストが合格して初めてチェックされます。

開発が完了したら、品質検証とドキュメントを自動生成します。

> /clear
> /moai sync SPEC-001

このコマンドは次を実行します:

graph TD
    A["品質検証"] --> B["テスト実行"]
    A --> C["リンター検査"]
    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 "ユーザー認証機能の実装"

リクエストは 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 の自動実行"]

# 1. プロジェクト文書の生成 (初回のみ)
> /moai project

# 2. SPEC の生成
> /moai plan "ユーザー一覧取得 API エンドポイントの実装"
> /clear

# 3. 実装
> /moai run SPEC-001
> /clear

# 4. ドキュメント化と PR
> /moai sync SPEC-001

# プロジェクト文書がすでにあれば、自然言語で一括実行
> /moai "JWT 認証ミドルウェアの実装"

# 先にワークツリーへ入ってから計画します
$ moai cc -w payment
> /moai plan "決済システムの実装"

MoAI-ADK プロジェクトの標準構造:

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/
    └── [生成されたドキュメント]

開発中いつでも品質を確認できます:

moai doctor

このコマンドは次を確認します:

• LSP 診断 (エラー、警告)
• テストカバレッジ
• リンターの状態
• セキュリティ検証

graph TD
    A["moai doctor"] --> B["LSP 診断"]
    A --> C["テストカバレッジ"]
    A --> D["リンターの状態"]
    A --> E["セキュリティ検証"]

    B --> F["総合レポート"]
    C --> F
    D --> F
    E --> F

各ステップ後に /clear を実行してコンテキストを空にしましょう。決定事項は SPEC と progress.md にファイルとして残っているので、対話履歴なしでも次のステップを続けられます:

> /moai plan "複雑な機能の実装"
> /clear  # セッションの初期化
> /moai run SPEC-001
> /clear
> /moai sync SPEC-001

# 自動修正 (シングルパス)
> /moai fix "テストで発生する TypeError の修正"

# 反復修正 (完了するまで)
> /moai loop "すべてのリンター警告の修正"

# 完了条件宣言型ループ
> /moai goal "go test ./... exits 0; すべての lint 警告を解消"

コアコンセプト で MoAI-ADK の高度な機能を確認しましょう。