moai-workflow-spec

SPEC ワークフロー管理

クイックリファレンス

GEARS 表記を使用した SPEC ワークフローのオーケストレーション（現行）— EARS のレガシー後方互換期間によって支えられ、体系的な要件定義と Plan-Run-Sync ワークフローの統合を実現します。

リントの動作は GEARS 移行ポリシーに従って標準化されています。

主な機能：

• GEARS 形式の仕様（現行）：統一された複合句 [Where ...][While ...][When ...] The <subject> shall <behavior> と一般化された <subject>（「the system」に限らず、任意の名詞）を使用する、5 つの要件パターン
• EARS レガシーリファレンス：リントエンジンの後方互換ポリシーに従って EARS の全パターンを維持し、GEARS が標準になる前に作成された v3 より前の SPEC を読み取れるようにします
• 要件の明確化：前提分析を含む体系的な 4 ステップのプロセス
• SPEC ドキュメントテンプレート：標準化された 3 ファイル構成（spec.md / plan.md / acceptance.md）
• Plan-Run-Sync の統合：シームレスなワークフロー接続
• 並行開発：Git Worktree ベースの SPEC 分離
• 品質ゲート：TRUST 5 フレームワークによる検証

GEARS の 5 つのパターン（現行の表記）：

パターン	GEARS 形式（現行）	EARS 形式（レガシー）	注記
常時	"The shall "	"The system shall "	<subject> は任意の名詞を使用できます。例：system、component、service、agent、function、artifact
イベント駆動	"When , the shall "	"WHEN , the system shall "	トリガーの意味は変更されていません
状態駆動	"While , the shall "	"WHILE , the system shall "	変更なし。第一級のパターンとして格上げされました
機能ゲート	"Where <capability / feature flag / static config>, the shall "	"WHERE , the system shall "	再定義されました。機能ゲート／フィーチャーフラグ／静的設定を表します（「Optional」ではなくなりました）
イベント検出（IF/THEN に代わるもの）	"When , the shall "	IF <condition> THEN <action> [DEPRECATED — use WHEN ]	IF/THEN の様式は廃止されました。同じ意図は、検出されたイベントとして記述します

統一された複合句：**Where** <precondition> **While** <state> **When** <event> the <subject> shall <behavior> — 3 つの修飾子は、任意の組み合わせで連結できます。

GEARS 表記リファレンスを参照してください。

IF/THEN の非推奨に関する説明：以前の作成ガイドでは、状態に応じた動作を記述するために IF <condition> THEN <action> を使用していました。GEARS では、その意図を When <condition-detected>（イベント検出形式）で表します。リントエンジンは、新しい SPEC に残っている IF/THEN に対して、警告（非厳格モードの場合は LegacyEARSKeyword）またはエラー（moai spec lint --strict）を出力します。レガシー SPEC に対する 6 か月の後方互換期間は引き続き有効です。

一般化された主語への置き換え：GEARS では、固定された主語「the system」を <subject> に置き換えます。<subject> には任意の名詞を使用できます。新しく SPEC を作成する場合、作成者は一般化された形式を使用してもかまいません。「the system」以外の有効な主語の例：

• "The skill shall present GEARS as the primary notation."（常時、<subject> = skill）
• "The agent shall return a blocker report instead of prompting the user."（常時、<subject> = agent）
• "When a SPEC author opens the file, the component shall display the deprecation banner."（イベント駆動、<subject> = component）

GEARS が標準になる前に作成された v3 より前の SPEC では、読みやすさのために既定の主語として「The system」を引き続き使用します。既存の読者が標準の表現を新たに覚え直す必要はありません。

EARS の 5 つのパターン（レガシー — 6 か月の後方互換期間）：

パターン	形式	用途
ユビキタス	"The system shall always X"	常に有効
イベント駆動	"WHEN event THEN action"	トリガーと応答
状態駆動	"WHILE state, the system shall ..."	条件付きの動作（従来の IF/THEN ではなく WHILE を使用）
禁止事項	"The system shall not X"	禁止
任意	"Where possible, provide X"	あれば望ましい

従来の IF/THEN モダリティは GEARS の When <event-detected> に置き換えられています。上記の囲み記事を参照してください。

使用する場面：

• 機能の計画と要件定義
• SPEC ドキュメントの作成と保守
• 機能の並行開発の調整
• 品質保証と検証の計画
• ユーザーストーリーの記述からの要件収集

クイックコマンド：

/moai:1-plan "user authentication system"                   # Create new SPEC
/moai:1-plan "login" "signup"                              # Parallel SPECs
/moai:1-plan "payment processing" --branch                  # New branch
/moai:1-plan SPEC-001 "add OAuth support"                   # Update existing

---

実装ガイド

コアコンセプト

SPEC ファースト開発の理念：

• EARS 形式により、曖昧さのない要件を実現します
• 要件を明確にすることで、スコープクリープを防ぎます
• テストシナリオを通じて体系的に検証します
• 実装には DDD ワークフローを統合します
• 品質ゲートにより完了基準を徹底します
• Constitution を参照し、プロジェクト全体の一貫性を確保します

Constitution リファレンス（SDD 2025 標準）

Constitution は、すべての SPEC が準拠すべきプロジェクトの DNA を定義します。SPEC を作成する前に、.moai/project/tech.md との整合性を確認してください。

Constitution の構成要素：技術スタック、命名規則、禁止ライブラリ、アーキテクチャパターン、セキュリティ標準、ロギング標準。

Constitution の検証：すべての SPEC の技術選択が Constitution のスタックバージョンに適合していること、禁止ライブラリが使用されていないこと、命名規則が守られていること、アーキテクチャ上の境界が維持されていることを確認します。

理由：Constitution によってアーキテクチャの逸脱を防ぎ、保守性を確保できます。

SPEC ワークフローの各ステージ

ステージ	アクティビティ
1	ユーザー入力の分析 — 自然言語による機能の説明を解析します
2	要件の明確化 — 4 ステップの体系的なプロセス
3	EARS パターンの適用 — 5 つのパターンを使用して要件を構成します
4	成功基準の定義 — 完了指標を設定します
5	テストシナリオの生成 — 検証用テストケースを作成します
6	SPEC ドキュメントの生成 — 標準化された Markdown を作成します

GEARS 形式（現行）

GEARS（Generalized EARS）は、v3.0.0 時点で標準の SPEC 表記法です。ユビキタス／When（イベント駆動）／While（状態駆動）を維持し、Where を機能ゲートとして再定義しています。従来の IF/THEN モダリティは When <event-detected> に置き換えられています。

GEARS 表記法の詳細については、docs-site の GEARS 表記法リファレンスおよび正規の GEARS 移行ポリシー記録を参照してください。

複合節の例（主語が「the system」ではない場合）：

Where the project is initialized While strict mode is active When a SPEC author runs moai spec lint, the lint engine shall emit a LegacyEARSKeyword finding for every residual IF/THEN modality.

この例では GEARS の 3 つの修飾子（Where、While、When）を連結し、<subject> に「the system」ではなく「lint engine」を使用しています。

EARS 形式（旧形式 — 6 か月の後方互換期間）

5 つのパターンですべての種類の要件を網羅します。各パターンには、固有のユースケースとテスト戦略があります。GEARS が標準になった以前に作成された v3 より前の SPEC は、引き続き EARS 表記法を使用し、lint エンジンの後方互換性ポリシーに基づいて有効なままです。

ユビキタス、イベント駆動、状態駆動、禁止事項、任意の要件について、ユースケース、例、テスト戦略を解説したパターン別 EARS 詳細ガイドを参照してください。

要件の明確化プロセス

5段階の体系的なプロセスです。

• Step 0：前提の分析（哲学フレームワーク） — 技術、ビジネス、チーム、統合に関する前提を明らかにします
• Step 0.5：根本原因分析（5 Whys） — 問題主導型 SPEC の問題から根本原因までを明らかにします
• Step 1：スコープの定義 — サポートするメソッド、検証ルール、障害への対応、セッション管理
• Step 2：制約の抽出 — パフォーマンス、セキュリティ、互換性、スケーラビリティ
• Step 3：成功基準 — カバレッジ目標、応答時間のパーセンタイル、機能の完了、品質ゲート
• Step 4：テストシナリオの作成 — 正常系、エラー、境界、セキュリティのケース

前提の文書化テンプレートと Five Whys の適用方法については、要件明確化の詳細なワークフローを参照してください。

[NEEDS CLARIFICATION] マーカーの規約

[NEEDS CLARIFICATION: ] マーカーは、plan.md と research.md にある未解決の質問を示します。これらは Implementation Kickoff Approval（plan→run HUMAN GATE）より前に必ず解決する必要があります。

配置：plan.md と research.md のみ（spec.md または acceptance.md には配置しないでください）。

形式：

• [NEEDS CLARIFICATION: <specific topic>] — 未解決の質問を示すインラインマーカー
• 各マーカーは、run フェーズに入る前にオーケストレーターの AskUserQuestion で必ず対応できる状態にしてください
• plan-auditor は未解決のマーカーを検出し、「clarification gate」の指摘として報告します

3 層の区別：

• [NEEDS CLARIFICATION: <topic>] — plan/research 成果物のブロッカー（ユーザーへの質問が必要）
• TODO — コードレベルの実装上の課題（ユーザーへの質問は不要）
• @MX:TODO — テストされていない、または未完成のコードに対するコードレベルの注釈

処理：

• plan-auditor は監査中に [NEEDS CLARIFICATION] マーカーをスキャンします
• マーカーが残っている場合、plan-auditor は Implementation Kickoff Approval の前に解決するよう推奨します
• オーケストレーターは AskUserQuestion のラウンドを実行し、各マーク付きトピックを解決します
• 必須の人的ゲートである Implementation Kickoff Approval は、すべての明確化が完了した後にのみ進められます

Plan-Run-Sync ワークフローとの統合

PLAN (/moai:1-plan)：manager-spec が入力を分析 → EARS 要件 → 明確化 → .moai/specs/ に SPEC を作成 → 任意で --branch を指定します。

RUN (/moai:2-run)：manager-develop が SPEC を読み込み → quality.yaml の constitution.development_mode に応じて ANALYZE-PRESERVE-IMPROVE（DDD）または RED-GREEN-REFACTOR（TDD）を実行 → moai-workflow-testing を参照 → スポーンごとに Agent(general-purpose) へドメイン別の委任 → 品質ゲートの検証（Stop hook / /moai gate）。

SYNC (/moai:3-sync)：manager-docs がドキュメントを同期 → SPEC から API ドキュメントを作成 → README とアーキテクチャを更新 → CHANGELOG → バージョン管理へのコミット。

Git Worktree による並行開発

Worktree は、ブランチを切り替えずに並行開発できるよう、SPEC ごとに分離された作業ディレクトリを提供します。メリット：並行開発、明確な責任範囲、依存関係の分離、リスクの軽減。

作成コマンドとチームでの共同作業例については、worktree ワークフローのパターンを参照してください。

---

リソース

SPEC ファイルの構成

標準の 3 ファイル形式：

• .moai/specs/SPEC-{ID}/spec.md — EARS 形式の仕様
• .moai/specs/SPEC-{ID}/plan.md — 実装計画、マイルストーン、技術的アプローチ
• .moai/specs/SPEC-{ID}/acceptance.md — 受け入れ基準、Given-When-Then シナリオ

[HARD] すべての SPEC ディレクトリには、3 ファイルすべてを必ず含めてください。ファイルが不足していると、要件が不完全になります。

状態ファイル：.moai/state/last-session-state.json。生成されるドキュメント：.moai/docs/api-documentation.md。

SPEC メタデータスキーマ

正規の必須 12 フィールド（SPEC frontmatter lint ルールによって強制されます）: id、title、version、status、created、updated、author、priority、phase、module、lifecycle、tags。

ステータス enum（8 値）: draft → in-progress → implemented → completed | superseded | archived | rejected。（planned はレガシー任意項目として enum に残されています — アクティブフローには含まれません。draft → planned の遷移を実行するエージェントは存在しません。.claude/rules/moai/development/spec-frontmatter-schema.md の § Status Enum を参照してください。）

任意フィールド: issue_number、depends_on、lint.skip、bc_id、tier（S/M/L LEAN tier）。

完全なスキーマは .claude/rules/moai/development/spec-frontmatter-schema.md（SSOT）にあります。

SPEC ライフサイクル管理

3 つのライフサイクルレベル:

レベル	説明	メンテナンス
spec-first	実装後に SPEC を破棄	なし
spec-anchored	実装と並行して SPEC を維持	四半期ごとのレビュー
spec-as-source	SPEC が唯一の信頼できる情報源であり、人間は SPEC のみを編集	変更が実装を再生成

遷移: 本番クリティカルになった時点で spec-first → spec-anchored、コンプライアンスまたは再生成ワークフローが必要になった時点で spec-anchored → spec-as-source。ダウングレードには明示的な正当化が必要です。

品質メトリクス

SPEC 品質指標: 要件の明確さ（すべての EARS パターンが使用されている）、テストカバレッジ（すべての要件にシナリオがある）、制約の完全性、成功基準の測定可能性。

検証チェックリスト: すべての EARS 要件がテスト可能、曖昧な表現（"should"、"might"、"usually"）がない、すべてのエラーケースが文書化されている、パフォーマンス目標が数値化されている、セキュリティ要件が OWASP 準拠である。

トークン管理

フェーズ	トークン予算
PLAN	約 30%
RUN	約 60%
SYNC	約 10%

コンテキスト最適化: SPEC ドキュメントは .moai/specs/ に保持されます。セッション状態は .moai/state/ にあります。SPEC ID 参照を通じた最小限のコンテキスト転送。エージェントへの委任によりトークンオーバーヘッドを削減します。

---

SPEC のスコープと分類

.moai/specs/ に属するもの

.moai/specs/ ディレクトリは、実装される機能を定義する SPEC ドキュメント専用です。

有効な SPEC コンテンツ: EARS 形式の機能要件、マイルストーンを含む実装計画、Given/When/Then シナリオを含む受け入れ基準、新機能の技術仕様、明確な成果物を含むユーザーストーリー。

SPEC の特性: 将来志向（何が構築されるか）、実行可能、テスト可能、構造化（EARS）。

.moai/specs/ に属さないもの

ドキュメント種別	SPEC でない理由	正しい場所
セキュリティ監査	既存のコードを分析する	.moai/reports/security-audit-{DATE}/
パフォーマンスレポート	現在のメトリクスを記録する	.moai/reports/performance-{DATE}/
依存関係分析	既存の依存関係をレビューする	.moai/reports/dependency-review-{DATE}/
アーキテクチャ概要	現在の状態を記録する	.moai/docs/architecture.md
API リファレンス	既存の API を記録する	.moai/docs/api-reference.md
議事録	行われた決定を記録する	.moai/reports/meeting-{DATE}/
レトロスペクティブ	過去の作業を分析する	.moai/reports/retro-{DATE}/

スコープ外の分類ルール

これらのルーティングルールは、SPEC ドキュメントにとって何がスコープ外であるか（および代わりにどこに属するか）を決定します。SPEC 自体の除外セクションを作成する際は、除外する各項目を ### Out of Scope — <topic> という H3 サブ見出しと - 箇条書きで表現して、そのセクションが OutOfScopeRule lint を満たすようにしてください。

[HARD] レポートは存在するものを分析します → .moai/reports/。SPEC は構築されるものを定義します → .moai/specs/。

[HARD] ドキュメントは使用方法を説明します → .moai/docs/。SPEC は構築するものを定義します → .moai/specs/。

---

相性の良いもの

• moai-foundation-core：SPEC ファーストの DDD 手法と TRUST 5 フレームワーク
• moai-workflow-testing：DDD の実装とテストの自動化
• moai-workflow-project：プロジェクトの初期化と設定
• moai-workflow-worktree：並行開発のための Git Worktree 管理
• manager-spec：SPEC の作成と要件分析を行うエージェント
• manager-develop：SPEC の要件に基づく DDD/TDD の実装
• /moai gate スキル（または sync-phase-quality-gate.sh Stop フック）：TRUST 5 の品質検証とゲートの適用（旧 manager-quality の役割）

移行シナリオと検証スクリプトについては、references/migration-guide.md を参照してください。

---

バージョン：1.3.1（スキル本文の圧縮） 最終更新日：2026-05-23 統合ステータス：完了 — SDD 2025 の機能を備えた Plan-Run-Sync ワークフロー

よくある正当化

正当化	実態
「SPEC は明白だから、EARS 形式は省略してもよい」	明白な要件ほど誤解されやすいため、EARS が存在します。この形式によって曖昧さが解消されます。
「受け入れ基準は要件と重複している」	要件は意図を記述します。受け入れ基準は観察可能な証拠を記述します。どちらも必要です。
「実装中に SPEC を洗練させればよい」	後からの洗練は実装の無駄につながります。考えを変えるなら、SPEC の段階が最も低コストです。
「調査はあればよいもので、必須ではない」	調査を省くと、既存コードと矛盾する SPEC が作られます。research.md によってやり直しを防げます。
「アノテーションサイクルはユーザーに手間をかけるだけだ」	アノテーションにより、コードを書く前に誤解を発見できます。これはパイプラインで最も低コストのフィードバックループです。
「この SPEC は小さいので、別ファイルは不要だ」	すべての SPEC は永続的な契約です。メッセージ内の SPEC は /moai run SPEC-XXX から参照できません。

危険信号

• 要件が EARS（WHEN X, SHALL Y）ではなく、命令形の文章で記述されている
• 受け入れ基準が主観的な判断（「速く感じる」「見た目がきれい」）で表現されている
• 既存コードを変更する場合に、SPEC ドキュメントと同じ場所に research.md がない
• アノテーションサイクルが省略されている、または「問題なさそう」という一度きりのやり取りに短縮されている
• 任意と必須の曖昧さがあるにもかかわらず、要件で「shall」の意味に「should」が使われている
• SPEC-ID が .moai/specs/ ディレクトリに登録されていない

検証

• 一意の ID を持つ SPEC ファイルが .moai/specs/SPEC-XXX/spec.md に存在する
• すべての要件で EARS キーワード（WHEN、WHILE、WHERE、IF、SHALL）が使われている
• すべての受け入れ基準が観察可能である（テスト出力、ファイルの存在、メトリクスのしきい値）
• SPEC が既存コードに関わる場合、research.md が存在する
• 明示的なユーザー承認マーカーを付けてアノテーションサイクルを完了している
• SPEC が、依存する、または置き換える既存の SPEC-ID を参照している
• スコープの拡大を防ぐために「Out of Scope」セクションがある — 少なくとも 1 つの ### Out of Scope — <topic> H3 サブ見出しと - 箇条書き項目がある（OutOfScopeRule lint を満たす）