msd-core/docs/ja-JP/explanation/the-phase-loop.md

フェーズループ

MSD Core が作業を整理する方法の核心的なメンタルモデル。

---

ループとは何か

MSD Core はすべての開発作業を繰り返すサイクルとして構造化します：

Discuss → (UI デザイン) → Plan → Execute → Verify → Ship

フェーズ と呼ばれる作業の各単位は、順番にこれらのステップを経ていきます。ループは形式的なものではありません。各ステップは、前のステップだけでは防ぎきれない特定のクラスの失敗を防ぐために存在します。

このドキュメントは、ループがなぜこの形をしているかを説明します。各ステップの実行方法については、下部にリンクされた how-to ガイドを参照してください。

---

各ステップが存在する理由

Discuss（議論）

計画は、何を作るかだけでなく、どのように作るかを知るまでは始められません。ROADMAP.md のフェーズ目標は成果を記述します。Discuss ステップは、その成果への道を形作る実装上の決定を記録します：どのライブラリを使うか、どのエラーハンドリング戦略か、機能がルートごとかグローバルか、エッジケースはどう振る舞うべきか。

Discuss ステップなしでは、プランナーがこれらの決定を自分で行わなければなりません。うまく推測することもありますが、もっともらしいが誤った推測をすることも多く——一貫性はあっても実際の好みとずれた計画を生み出します。実行が終わってエラーに気づく頃には、かなりの作業を巻き戻すことになります。

Discuss ステップは意図的に軽量です。それは仕様書を書く演習ではなく、会話です。出力はフェーズディレクトリ内の CONTEXT.md です：プランナー、エグゼキューター、検証者がすべて読める決定の構造化された記録です。会話には数分かかります。それが何時間もの手直しを節約できます。

UI デザイン（任意）

視覚的なコンポーネントを持つフェーズの場合、Discuss と Plan の間にオプションの /msd-ui-phase ステップがあります。これは UI-SPEC.md を生成します——コードが書かれる前にレイアウト、インタラクション、視覚的な振る舞いを説明するデザインコントラクトです。デザインの曖昧さが異なる実装上の選択を生む可能性があるほど UI が複雑な場合に、このステップを実行する価値があります。明確なデザインコントラクトは、再実装するよりずっと安く書けます。

Plan（計画）

Plan ステップは、実行に必要な調査、分解、構造的な思考を行います。フレッシュコンテキストサブエージェントのシーケンスとして実行されます：エコシステムを調査して RESEARCH.md に発見を記録する調査エージェント、調査と CONTEXT.md の両方を読んで PLAN.md ファイルを生成するプランナー、そして計画が完全で一貫していてスコープ内にあることを検証するプランチェッカー。

計画には何が含まれるのか？各 PLAN.md は作業の境界が明確な単位を記述します：変更するファイル、行う特定の変更、完了を定義する受け入れ基準。計画は依存関係のウェーブ順に並べられ、並行実行が安全になります——同じウェーブ内のエグゼキューターは重複しない懸念事項を担当します。

Plan ステップは曖昧さが最もコストが高い瞬間です。曖昧な計画は仮定を立てるエグゼキューターを生み出します。同じ懸念について異なる仮定を立てる複数の並行エグゼキューターは競合を生み出します。プランチェッカーの仕事は、実行が始まった後ではなく、その前にこれらをキャッチすることです。

Execute（実行）

実行は計画を実施します。各エグゼキューターは、必要なものだけを正確にロードしたフレッシュな 200k トークンのコンテキストウィンドウを受け取ります：プロジェクトサマリー、フェーズコンテキスト、調査結果、そして自分のタスクのための特定の PLAN.md。それ以上でも以下でもありません。

エグゼキューターはコードを書いてアトミックにコミットします。各コミットは計画内の完了したタスクに対応します。並行エグゼキューターのウェーブが完了すると、オーケストレーターはその状態をマージして次のウェーブを開始します。

エグゼキューターのフレッシュコンテキストは便宜のためではありません——コンテキスト腐敗を防ぐメカニズムです。180k トークンの蓄積されたセッション履歴で実行するエグゼキューターは劣化しています。クリーンな状態で開始し、計画が必要とするものだけを読み取るエグゼキューターは、最大能力で動作しています。

Verify（検証）

すべてのエグゼキューターが完了した後、検証エージェントはフェーズ目標、CONTEXT.md の決定、計画、実行サマリーを読み取り、構築されたものが意図されたものと一致するかを確認します。VERIFICATION.md を生成し、不一致があれば対象を絞った修正計画を生成します。

検証はテストだけではありません。要件カバレッジ（すべての REQ-ID が対処されたか？）、決定カバレッジ（CONTEXT.md に記録された決定が実際に実装されたか？）、そして全体的なフェーズ目標との整合性を確認します。実行がエラーなく終了したからフェーズが完了なのではありません。構築されたものが計画されたものであり、計画されたものが決定されたものである場合に完了です。

Ship（出荷）

Ship ステップはプルリクエストを作成し、フェーズアーティファクトをアーカイブします。STATE.md はフェーズ完了としてマークするために更新されます。その後ループは次のフェーズのために再び始まります。

---

マイルストーンとフェーズ

マイルストーン はバージョンサイクルです——プロジェクトの意味のあるリリース可能な増分。名前、バージョン番号、そして何を提供しなければならないかを定義する要件のセットを持ちます。すべてのフェーズが出荷され、要件がカバーされるとマイルストーンは完了です。

フェーズ はマイルストーン内の一つの作業単位です。フェーズには目標、それが対処する要件のセット、それを実装する計画のセットがあります。

この関係は重要です。なぜならマイルストーンとフェーズは異なるスコープの懸念事項を持っているからです。マイルストーンは「このバージョンの製品は何をするのか、しないのか？」と問います。フェーズは「調査、計画、実行、検証ができる次の境界が明確なものは何か？」と問います。

マイルストーンの境界は自然な製品境界——デプロイ可能な API、動作する UI フロー、完全なデータモデル——に引かれます。フェーズの境界は、ループが手に負えなくなることなく一度のループで安全に実行できることの限界に引かれます。

---

良いフェーズスコープとは

これはループで最もよく見られる摩擦の原因なので、詳しく考える価値があります。

大きすぎるフェーズはそれ自体が調査プロジェクトになります。プランナーは独立した計画に分解するのに苦労します。後のウェーブのエグゼキューターは前のウェーブを待ちながらブロックされます。検証は対象を絞ったレビューではなく全体監査になります。フィードバックサイクルが時間から日に延びて、多くのコードが書かれた後に根本的な設計ミスを発見するリスクが急激に高まります。

小さすぎるフェーズは自然に属する作業を断片化します。数行の計画ファイル、数分で完了するフェーズ、実行コストを矮小化する計画オーバーヘッドが生じます。ループは役に立つというよりお役所的に感じられます。

良いフェーズスコープとは：

• 目標が明らかに些細でも疑わしいほど広くもない単一の文で述べられる。
• 計画するために必要な調査が境界を持つ——エコシステムの問題に、他のフェーズが先に完了することに依存しない答えがある。
• 実行が少数の非重複する計画に並行化できる（数十ではなく）。
• 検証者がコードベース全体を読まずに確認できる、明確でテスト可能な完了の定義がある。

具体的には：「HMAC-SHA256 署名検証ミドルウェアを追加する」は良いフェーズスコープです。「認証システムを構築する」は通常そうではありません——ほぼ常に、別々のフェーズの方が良い複数の独立した懸念事項が含まれています。「README のタイポを修正する」はループが価値を加えるしきい値を下回っています；代わりに /msd-quick を使ってください。

迷ったら、分割してください。小さいフェーズは速く完了し、より自信を持って検証でき、設計上の決定が誤りとわかった場合に方向修正しやすくなります。

---

.planning/ はどのようにループをまたいで状態を維持するか

ループは単一のセッションではありません。調査、計画立案、実行は複数のセッションにわたって行われ、その間にコンテキストリセットが発生することもあります。.planning/ ディレクトリがこれを可能にするものです。

ループの各ステップは以前のステップが生み出したアーティファクトを読み取り、後のステップのためのアーティファクトを書き出します。Discuss ステップが生成する CONTEXT.md は、プランナーが実行するときに——たとえそれが数時間後の別のセッションであっても——まだ利用可能です。プランナーが生成する PLAN.md ファイルは、エグゼキューターが実行するときに——再起動をまたいでも——まだ利用可能です。検証者が書く VERIFICATION.md は、フェーズをレビューするときにまだ利用可能です。

STATE.md はこれすべての上のナビゲーション層です。ループ内でプロジェクトが現在どこにいるかを正確に記録します：どのマイルストーンがアクティブか、どのフェーズが進行中か、どの計画が完了していてどれが保留中か。自分の方向を確認する必要があるエージェントやワークフローは、まず STATE.md を読み取ります。

これらのファイルの正確な構造については、計画アーティファクト と STATE.md スキーマ を参照してください。

---

ループはリズムであり、制約ではない

ループを官僚主義として見たくなる誘惑があります——コードを書く許可を得る前に実行しなければならない必須ステップのセット。そのフレーミングは誤りです。

ループは、各ステップが後で修正するのが本当にコストが高い失敗を防ぐために存在します。Discuss は誤った仮定の上での計画立案を防ぎます。Plan は根本的に壊れた設計の実行を防ぎます。Verify は仕様を外れた作業の出荷を防ぎます。これらは作り上げられた問題ではありません。実際の機能規模での AI 支援開発の実際の失敗モードです。

ループがうまく機能すれば、リズムのように感じます：各ステップが前のステップが仕事をしたために明確である、集中した境界を持つ作業のカデンス。オーバーヘッドは現実ですが、前払いです——何時間もの手直しではなく数分の計画として支払われます。

ループが正当化されるしきい値を下回る作業には、MSD Core はより軽量なプリミティブを提供します。フェーズループは一つのツールであり、唯一のツールではありません。

---

Related

• コンテキストエンジニアリング — フレッシュコンテキストサブエージェントがなぜループを必要にする品質低下を防ぐのか
• フェーズの議論
• フェーズの計画
• フェーズの実行
• 検証と出荷
• 計画アーティファクト
• STATE.md スキーマ
• ドキュメント索引