/moai plan

AI と交わした対話を永続的な要件ドキュメントに変えます。自然言語のリクエストが構造化された SPEC ドキュメントになり、このドキュメントが以降すべてのステップの基準になります。

情報

スラッシュコマンド: Claude Code で /moai:plan と入力すると、このコマンドをすぐに実行できます。/moai だけ入力すると、利用可能なすべてのサブコマンド一覧が表示されます。

/moai plan は MoAI-ADK ワークフローの Phase 1 (Plan) コマンドです。自然言語での機能リクエストを GEARS (Generalized Expression for AI-Ready Specs) 形式の構造化された SPEC ドキュメントに変換します。内部的に manager-spec エージェントが要件を分析し、曖昧さのない仕様書を生成します。

v3.0.0 から GEARS が正本の表記法であり、既存の EARS (Easy Approach to Requirements Syntax) は 6 か月間の後方互換として維持されます。2 つの表記法の違いとマイグレーションは GEARS 表記法セクション を参照してください。

計画ステップは v3 トークノミクス設計で最も深い推論が割り当てられるステップです — ここで要件が明確になるほど、後に続く実装ステップの手戻りとトークンの浪費が減ります。だから MoAI-ADK は「計画は深く、実装は安く」という配分原則に従い、生成された SPEC は plan-auditor が独立して監査します。作ったエージェントが自分で検査しません。

情報

SPEC がなぜ必要ですか?

バイブコーディング (Vibe Coding) の最大の問題は 文脈の喪失 です。

AI と対話中にセッションが切れると 以前の議論内容がすべて消えます。トークン上限を超過すると 古い対話から切られます。翌日作業を再開すると 昨日決めた事項を覚えていません。

SPEC ドキュメントがこの問題を解決します。

要件を ファイルに保存 して永久保存します。v3.0.0 から正式な表記法である GEARS 形式で 曖昧さなく 構造化します (既存の EARS 表記法は 6 か月間の後方互換を維持)。セッションが切れても SPEC を読めば 続けて作業 できます。

Claude Code の対話画面で次のように入力します:

> /moai plan "実装したい機能の説明"

使用例:

# 簡単な機能
> /moai plan "ユーザーログイン機能"

# 詳細な機能の説明
> /moai plan "JWT ベースのユーザー認証: ログイン、会員登録、トークン更新 API"

# リファクタリングのリクエスト
> /moai plan "レガシー認証システムを JWT ベースにリファクタリング"

ブランチ戦略のフラグが指定されると次の順序で適用されます:

1. –branch: 従来の feature ブランチの生成
2. フラグなし (デフォルト): SPEC のみ生成、BODP ゲートでユーザーがブランチ戦略を選択

--no-issue はブランチ戦略と独立したオプションで、GitHub Issue 生成ステップ (Phase 12) を省略します。

plan は作業スペースを生成しません。隔離された環境で計画するには、先にワークツリーへ入ってから plan を実行します:

moai cc -w payment          # その場でワークツリーに入る
> /moai plan "決済システムの実装"

現在のセッションを保ったまま新しい tmux ウィンドウで開くには --spawn を付けます:

moai cc -w payment --spawn

情報

複数の機能を同時に開発 するときは、機能ごとにワークツリーを分ければ互いに衝突 しません。入るのはランチャーの役目で、plan はその中でそのまま動きます。

SPEC ドキュメントは EARS (Easy Approach to Requirements Syntax) 形式で要件を定義します。5 つのパターンがあり、manager-spec エージェントが自然言語を自動的に適切なパターンに変換します。

v3.0.0 からは EARS の 5 つの核心パターンを維持しつつ、AI コーディングエージェントがより明確に解釈できるよう意味境界を整えた GEARS (Generalized Expression for AI-Ready Specs) が正式な表記法です。既存の EARS は 6 か月間の後方互換として維持され、新しい SPEC は GEARS パターンに従うよう推奨します。2 つの表記法の違いとマイグレーションは GEARS 表記法セクション を参照してください。

情報

EARS 形式を暗記する必要はありません。manager-spec エージェントが自然言語を 自動的に 変換 します。あなたは望む機能を自然に説明するだけで十分です。

/moai plan が内部的に行うプロセスです:

flowchart TD
    A["ユーザーリクエスト
/moai plan '機能の説明'"] --> B{明確か?}
    B -->|いいえ| C["Explore 下位エージェント
プロジェクト分析"]
    B -->|はい| D["manager-spec エージェントの呼び出し"]
    C --> D
    D --> E["要件分析
機能範囲、複雑度の評価"]
    E --> F{"明確化が必要?"}
    F -->|はい| G["ユーザーに質問
詳細の確認"]
    G --> E
    F -->|いいえ| H["EARS 形式へ変換
5 つのパターンを適用"]
    H --> I["受け入れ基準の定義
Given-When-Then"]
    I --> J["SPEC ドキュメント生成
spec.md, plan.md, acceptance.md"]
    J --> K{"ユーザー承認"}
    K -->|承認| L["Git 環境設定"]
    K -->|修正リクエスト| E
    K -->|キャンセル| M["終了"]
    L --> N{"フラグ確認"}
    N -->|--branch| P["ブランチ生成"]
    N -->|フラグなし| Q["ユーザー選択"]
    P --> R["完了"]
    Q --> R

核心ポイント:

• リクエストが不明確なら Explore 下位エージェント がプロジェクトを分析します
• manager-spec エージェントは要件が不明瞭なら ユーザーに追加質問 をします
• すべての要件に Given-When-Then 形式の受け入れ基準 を自動生成します
• 生成された SPEC ドキュメントはユーザーの 承認を受けた後 に確定されます

/moai plan は 15 個の Phase と 2 個の Decision Point で構成された構造化されたワークフローに従います。Phase 1-3 はコンテキスト発見、Phase 4-7 は深層インタビュー、Phase 8 以降が本格的な SPEC 組み立てです。

リクエストが曖昧かプロジェクトの状況を把握する必要があるとき Phase 1-3 が実行されます。明確なリクエストは Phase 3 でスキップできます。

明確度スコアが 4-10 の場合に実行されます:

manager-spec エージェントが次の作業を行います:

• プロジェクトドキュメントの分析 (product.md, structure.md, tech.md)
• 1-3 個の SPEC 候補の提案および命名
• 重複 SPEC の確認 (.moai/specs/)
• GEARS 構造の設計 (EARS レガシー形式も許容)
• 実装計画および技術制約条件の識別
• ライブラリバージョンの確認 (安定版のみ、beta/alpha 除外)

Phase 8 完了後、ユーザーが明示的に承認して次のステップに進みます。4 つの選択肢があります:

SPEC 生成前に一般的なエラーを防ぎます:

Step 1 - ドキュメントタイプの分類:

• SPEC, Report, Documentation キーワードの検出
• Report は .moai/reports/ にルーティング
• Documentation は .moai/docs/ にルーティング

Step 2 - SPEC ID 検証 (すべての検査の通過が必須):

• ID 形式: SPEC-ドメイン-番号 パターン (例: SPEC-AUTH-001)
• ドメイン名: 承認されたドメイン一覧 (AUTH, API, UI, DB, REFACTOR, FIX, UPDATE, PERF, TEST, DOCS, INFRA, DEVOPS, SECURITY など)
• ID の一意性: .moai/specs/ で重複を確認
• ディレクトリ構造: 必ずディレクトリを生成、フラットファイル禁止

複合ドメインルール: 最大 2 個のドメインを推奨 (例: UPDATE-REFACTOR-001)、最大 3 個まで許容

3 つのファイルが同時に生成されます:

spec.md:

• YAML フロントマター (12 個の必須フィールド: id, title, version, status, created, updated, author, priority, phase, module, lifecycle, tags)
• HISTORY セクション (フロントマターの直後)
• 完全な GEARS/EARS 構造 (5 種の要件タイプ)
• conversation_language で書かれたコンテンツ

plan.md:

• 作業分解の実装計画
• 技術スタック仕様および依存性
• リスク分析および緩和戦略

acceptance.md:

• 最小 2 個の Given/When/Then シナリオ
• エッジケーステストシナリオ
• 性能および品質ゲート基準

品質制約条件:

• 要件モジュール: SPEC あたり最大 5 個
• 受け入れ基準: 最小 2 個の Given/When/Then シナリオ
• 技術用語と関数名は英語を維持

plan-auditor サブエージェントが manager-spec が作成した SPEC 成果物を独立して監査します。作ったエージェントが自分の結果を検査しない 独立監査原則 に従います。

• 最大 3 回反復 (Retry Loop Contract)
• 各ラウンドでスコア回帰が発生時に STOP 信号 + 範囲縮小の提案
• PASS / PASS-with-debt / FAIL の 3 つの判定
• 監査報告書は .moai/reports/plan-audit/ に保存

--no-issue フラグがなければ GitHub Issue を生成し SPEC と双方向参照を連携します。v3.0.0 からは Issue 生成がデフォルトで省略され、--issue フラグで明示的に有効化できます。

BODP (Branch Origin Decision Protocol) ゲート を通じてブランチ戦略を決定します:

• –branch: 従来の feature ブランチの生成
• 現在のブランチを維持: フラグなしで現在のチェックアウトから継続

実装ステップで追加する @MX コード注釈のターゲットを識別します:

• @MX:ANCHOR — 不変契約 (high fan_in の関数)
• @MX:WARN — 危険区間 (goroutine、複雑度 ≥ 15)
• @MX:NOTE — コンテキスト/意図の記録

GEARS/EARS 要件と受け入れ基準 (AC) の間のカバレッジを検証し、セキュリティ範囲の点検を行います。

SPEC 生成完了後に次のステップを選択します。詳しい内容は Decision Point 3.5 セクション を参照してください。

SPEC ドキュメントは .moai/specs/ ディレクトリに保存されます:

.moai/
└── specs/
    └── SPEC-AUTH-001/
        ├── spec.md          # GEARS 要件
        ├── plan.md          # 実装計画
        └── acceptance.md     # 受け入れ基準

SPEC ドキュメントの基本構造:

---
id: SPEC-AUTH-001
version: 1.0.0
status: draft
created: 2026-01-28
updated: 2026-01-28
author: 開発チーム
priority: HIGH
---

SPEC ドキュメントは次のような状態ライフサイクルを持ちます:

flowchart TD
    A["draft
作成中"] --> B["in-progress
実装中"]
    B --> C["implemented
実装完了"]
    C --> D["completed
sync 完了"]
    A --> E["rejected
拒否"]

既存コードベース (ブラウンフィールド) プロジェクトで SPEC 要件を分類します。

Plan phase で SPEC ドキュメントの要約版 (spec-compact.md) を自動生成します。Run phase で spec.md 全体の代わりに要約版をロードして ~30% のトークンを節約 します — SPEC ライフサイクルの中にトークノミクスの仕組みが組み込まれている代表的な例です。

Exclusions の必須化 (“What NOT to Build”): すべての SPEC ドキュメントに Out of Scope / Exclusions セクションが必須です。範囲逸脱を事前に防ぎます。

What/Why 制約: SPEC 要件は What (何を) と Why (なぜ) のみを記述します。How (どうやって) は実装ステップで決定し、SPEC に過剰仕様化しません。

Plan 完了後 Run 開始前に、実行環境を自動検出しユーザーに最適モードを提案します。

検出項目:

1. tmux の可用性 ($TMUX 環境変数)
2. 現在の LLM モード (llm.yaml の team_mode: cc/glm/cg)

tmux 使用可能時:

• Worktree + 現在のモード (推奨)
• Sub-agent Mode (順次)

tmux 使用不可時:

• Sub-agent Mode (推奨)

情報

Agent Teams 静的オーケストレーション階層 (Module 3) は引退しました。--team フラグと Team Mode オプションはもう提供されず、強制時は MODE_TEAM_UNAVAILABLE フォールバックで Sub-agent Mode に切り替わります。CG モード (Claude+GLM) は moai cg コマンドで進入します。

ステップ 1: コマンド実行

> /moai plan "JWT ベースのユーザー認証システム: 会員登録、ログイン、トークン更新"

ステップ 2: manager-spec が質問 (必要時)

manager-spec エージェントが詳細を確認するために質問することがあります:

• 「パスワードの最小長は何文字ですか?」
• 「トークン有効期限はいくつに設定しますか?」
• 「ソーシャルログインも含めますか?」

ステップ 3: SPEC ドキュメント生成結果

次のような構造の SPEC ドキュメントが生成されます:

---
id: SPEC-AUTH-001
title: JWT ベースのユーザー認証システム
priority: HIGH
status: draft
---

# 要件 (GEARS/EARS 形式)

## Ubiquitous

- システムはすべてのパスワードを bcrypt でハッシュして保存しなければならない
- システムはすべての認証リクエストをロギングしなければならない

## Event-driven

- WHEN 有効な資格情報でログインしたら、THEN JWT アクセストークン (1 時間) とリフレッシュ
  トークン (7 日) を発行しなければならない

## Unwanted

- システムはパスワードを平文で保存してはならない
- システムは有効期限切れのトークンで API アクセスを許可してはならない

ステップ 4: ユーザー承認後の Git 環境設定

# --branch フラグ使用時
> /moai plan "JWT 認証" --branch

# 結果:
# 1. SPEC ドキュメント生成 (.moai/specs/SPEC-AUTH-001/)
# 2. SPEC コミット (feat(spec): Add SPEC-AUTH-001)
# 3. feature/SPEC-AUTH-001 ブランチの生成と切り替え

ステップ 5: /clear 実行後に実装ステップへ移動

# トークンの整理
> /clear

# 実装開始
> /moai run SPEC-AUTH-001

はい、.moai/specs/SPEC-XXX/spec.md ファイルを直接編集できます。要件を追加したり受け入れ基準を修正したりした後 /moai run を実行すると修正された内容が反映されます。

Claude Code で直接コードを書くこともできますが、SPEC なしで作業するとセッションが切れるたびに文脈を失います。複雑な機能ほど SPEC を先に作るのが効率的 です。

SPEC-ドメイン-番号 形式です (例: SPEC-AUTH-001)

• SPEC-AUTH-001: 認証関連の最初の SPEC
• SPEC-PAYMENT-002: 決済関連の 2 番目の SPEC

ドメインは機能の領域に応じて manager-spec が自動的に決定します。

/moai plan は SPEC ドキュメント生成のみ を担当します。/moai は SPEC 生成から実装、ドキュメント化まで ワークフロー全体 を自動的に行います。

plan にワークツリーを生成するフラグはありません。ランチャーで先に入ってから (moai cc -w <名前>)plan を実行します。–branch は現在のリポジトリに新しいブランチを作るだけの別オプションです。複数の機能を同時に開発するなら、ワークツリーに入るほうが互いに衝突しません。

MoAI-ADK v3.0.0 からは GEARS (Generalized Expression for AI-Ready Specs) を SPEC 作成の推奨表記法として導入します。既存の EARS 表記法は 6 か月 間の後方互換を維持し、その間に段階的に GEARS へマイグレーションできます。新しい SPEC は最初から GEARS パターンに従うよう推奨します。

GEARS は EARS の 5 つの核心パターンを維持しつつ、AI コーディングエージェントがより明確に解釈できるよう意味境界を整えた表記法です。核心的な変更は IF/THEN パターンの廃止 (WHEN に正規化) と WHERE の意味の再定義 (静的な前提条件/構成/機能フラグ) です。

参考資料: Σ*/SubLang、“GEARS: The Spec Syntax That Makes AI Coding Actually Work”、DEV Community 2026-01-23。https://dev.to/sublang/gears-the-spec-syntax-that-makes-ai-coding-actually-work-4f3f

マイグレーションウィンドウは v3.0.0 リリース時点から 6 か月 または SPEC-V3R6-GEARS-SWEEP-001 (provisional) の一括修正 SPEC 完了時点のうち先に到来する時点まで有効です。ウィンドウ中の動作は次のとおりです。

• 非-strict モード (デフォルト値): LegacyEARSKeyword コードの warning のみ発生、lint 失敗なし
• --strict モード (opt-in): warning が error に昇格され CI 遮断
• 既存の 88 個の SPEC: 本 SPEC の範囲では直接修正しない (REQ-GM-007)。一括修正は後続の SWEEP SPEC の責任

internal/spec/lint.go の isLegacyEARSPattern() ヘルパーが EARS legacy IF/THEN パターンを検出すると次のようなメッセージを出力します。

REQ <REQ-ID>: GEARS migration: replace IF/THEN with WHEN/event normalization; see https://adk.mo.ai.kr/en/workflow-commands/moai-plan/#gears-notation

• コード: LegacyEARSKeyword
• 深刻度: warning (非-strict) / error (--strict)
• 出所: internal/spec/lint.go

downstream ツール (検証器、コード生成器、IDE プラグインなど) で SPEC テキストをマッチングするときは次のようにマイグレーションしてください。

• IF .* THEN マッチングを今後 WHEN .* shall マッチングに転換
• 6 か月の deprecation ウィンドウを認識し、ウィンドウ終了時点まで両方のパターンを認識するよう実装
• LegacyEARSKeyword finding コードを upgrade 信号として活用

Before (EARS legacy):

IF input is null, THEN the system shall return an error.

After (GEARS canonical):

WHEN input is null is detected, the system shall return an error.

この正規化はトリガーを「条件」ではなく「事件」として明示することで AI エージェントの意図解釈の曖昧さを減らし、テストケース作成時に入力/検証時点をより明確にします。

MoAI-ADK v0.1.0 から AskUserQuestion の推奨 がユーザーの決定パターンに合わせてパーソナライズされます。システムは選択をキャプチャし、システムのデフォルト値ではなく観測された統計的多数に基づいて未来の質問オプションをパーソナライズします。ループが観察を蓄積しシステムがその観察から学ぶという点で、v3 の 再帰的な自己学習 原則が質問・推奨領域に適用された事例です。

MoAI が AskUserQuestion で質問するとき、推奨配置を案内する 5 つの原則が適用されます:

1. Fisher 情報タイミング — 不確実性が最も高いとき (p≈0.5、Fisher 情報 I=p(1−p) が最大の決定境界) に質問を提示します。p≈0 または p≈1 (ほぼ確定) のときはシステムが自動処理し質問を省略します。

2. 質問順序 — 情報利得の降順 — 複数の質問が必要なとき、推定情報利得が高い順にソートされ最も重要な決定を先に下します。

3. 統計的多数の合理的なデフォルト値 — 推奨オプション ((推奨) 表示) は決定記録の観測された多数選択を反映し、システムのポリシーデフォルト値ではありません。データが不足すると (cold-start) 「デフォルト設定ベース、パーソナライズに N 件の観察が必要」 を公開します。

4. 前提条件の公開 — 各推奨オプションは成立の前提条件を 「Recommended when 」 形式で明示し、即座にトレードオフを評価できるようにします。

5. 熟練度に基づく適応型の強度 — 推奨強度はセッションカウントに応じて調節されます:

   • 専門家 (20+ セッション): 弱い強度 — inferred preference を (推奨) override なしで公開のみ (info-centric、自律性尊重)
   • 一般ユーザー (5-19 セッション): 強い強度 — (推奨) + 透明な根拠の提示
   • Cold-start (<5 セッション): 中立強度 — override なし、システムのデフォルト値を適用

• セッション範囲トグル: moai preference toggle でプロジェクト別のパーソナライズを無効化 (セッション間で非永続)
• 機密ドメインゲート: セキュリティ関連のテーマ (脆弱性、侵入テスト、漏洩) は中立推奨 + 公開ログ
• 自動減衰: Transient な選好は 28 日後に soft-delete、stable な選好 (明示的な表示) は保存
• Advisory キャプチャ: PostToolUse キャプチャフックは AskUserQuestion 実行を決して遮断しない (fail-open 設計)
• Recovery-Signal Carve-Out: recovery ターン (compact 復旧、prompt_too_long など) で advisory フックは復旧に譲る (recovery-signal carve-out 準拠、doctrine-honest)

情報

内部動作: 5 つの原則は .claude/rules/moai/core/askuser-protocol.md § Recommendation Placement Principles に明細化されており、moai.md にレンダリングされます。キャプチャフックは internal/hook/user_decision_capture.go に実装されており schema 許容パースとドメイン分類をサポートします。減衰ポリシーは power-law 関数 (age+1)^(-0.5) に従い α=0.5 固定 (Standard tier)。全体のアーキテクチャと受け入れ基準はプロジェクトの SPEC ドキュメントを参照してください。

• SPEC ベース開発 - EARS 形式の詳細説明
• /moai run - 次のステップ: DDD 実装
• /moai sync - 最終ステップ: ドキュメント同期