「OpenAI の Codex「Plans.md (唯一の生きた文書) 戦略」 をVSCode GitHub Copilot で実行する方法」 - Qiita
👆️この記事は色々試行錯誤しつつ書いたまま整理整頓をしていないので非常に長く順番も前後して読みづらくなっていました。
なのでNotebookLMで内容を要約してもらいました。
動画紹介
提案する記事構成案：OpenAI の Codex「Plans.md (唯一の生きた文書) 戦略」 をVSCode GitHub Copilot で実行する方法 Notebookによる整理整頓版
I. はじめに：Plans.md戦略とは何か
-
概要と目的
- この記事が扱うテーマ：OpenAIのCodex「Plans.md (唯一の生きた文書) 戦略」をVSCodeとGitHub Copilotで実行する方法の解説。
- 戦略の核心：開発の指示書を1ファイル（
plans.md）だけで完結させる。 - 前提となる環境と費用：Windows 11、VSCode、GitHub Copilot Proプラン以上、使用モデルはGPT-5-Codex。
- この記事の対象者：ChatGPT月20ドル、GitHub Copilot月10ドルで安く済ませたい人向け。
-
plans.md戦略の哲学的基盤
-
plans.mdの役割：唯一の生きた文書として扱われる。 - ExecPlanの「読者」：GPT-5-Codex（AIエージェント）のこと。彼らは作業ツリーと
plans.mdのみを持つ完全な初心者として扱われる。 -
4つの指導原則（哲学）：
- 自己完結型：相手に期待せず、前提知識ゼロでも成功できるようにする。
- 自己充足型：進捗に応じて書き換えていくが、自己完結を維持する。
- 初心者誘導型：初心者に手取り足取り教えるように開発のレールを敷く。
- 成果重視型：見た目の綺麗さよりも、きちんと動作することを重視し、目に見える結果で判断する。
-
II. 実装前の準備：GitHub Copilotでの環境構築
-
指示書の初期化と設計
- 指示書を新規に作成、または既存の指示書を全て破棄する（
plans.mdファイルを唯一の指示書とするため）。 - シンプルな機能実装には
plans.mdは使わず、直接AIに指示する。複雑な機能や新しいプロジェクトでのみ使用する。 - AIによる設計書の作成：構想やメモを元に、AIに要件定義書と設計書を作成させる。
- ポイント：アプリ全体のコードを一気に作る設計書は避け、1機能ごとに絞って作り、できる限り範囲を狭くする。
- 指示書を新規に作成、または既存の指示書を全て破棄する（
-
必要な5つのファイルとその役割
-
plans.md：戦略本体であり、Codexエージェントの記憶となる「唯一の生きた文書」。 -
copilot-instructions.md：GitHub CopilotやVSCodeに対する指示（プロジェクト全体の指示書）。 -
AGENTS.md：plans.md戦略の実行を制御する指示書（ExecPlanの使用ルールなどを記述）。 -
plans.prompt.md：スラッシュコマンド/plansの起動トリガー。設計書を設定し、実装開始を指示する。 -
review.prompt.md：スラッシュコマンド/reviewの起動トリガー。実装後のレビューを依頼する。
-
-
プロンプトファイルの作成方法
- VSCodeでプロンプトファイルを構成する手順を解説。
- スラッシュコマンドの定義：
[ファイル名].prompt.mdを作成することで、GitHub Copilotチャット欄で/[ファイル名]として実行可能になる。
III. Plans.md戦略に基づく開発ワークフロー
-
計画（ExecPlan）の作成と承認
- ユーザーがAIに機能概要と計画作成を依頼する（「ExecPlan」などの特定の用語を使うことが推奨される）。
- AIが
plans.mdを作成。ユーザーはこれを設計ドキュメントとしてレビューし、問題がなければ実行を指示する。
-
実装の実行（
/plans）- GitHub Copilotチャット欄から
/plansスラッシュコマンドを実行。 - AIは
plans.mdのToDoリストに基づき、実装作業を継続する。 -
進捗と記録の永続化：AIは作業完了時や停止時に、実行内容、完了日時、課題、次のステップなどを
plans.mdに記録し、進捗を継続的に更新する。 - TDD（テスト駆動開発）の適用：TDDは明示的に指示された場合のみ実施され、既定ではない（指示書に「TDDを徹底します。」と加えることが推奨）。
- GitHub Copilotチャット欄から
-
レビューと軌道修正（
/review）- 実装完了後、
/reviewスラッシュコマンドを実行し、レビューを依頼。 - GPT-5-Codexのレビューの質：従来のスタイル指摘ではなく、セキュリティ、バグ、仕様逸脱といった**本当に重要な問題（P0、重大）**に焦点を当てる。
- 軌道修正：レビュー結果に基づき、AIは要件定義、設計書、
plans.md、コード自体の修正（修正計画の立案と実行）を行う。 -
/plansと/reviewを往復し、必要に応じて人の手で修復を行う。
- 実装完了後、
-
継続開発とプロジェクトの継続
- 複雑な2つ目の機能を実装する場合、新しい
plans.mdを用意せず、そのまま同じplans.mdを使用し続ける。 -
plans.mdはエグゼクティブサマリー機能を使って要約を記録していくため、長期にわたるタスクの記憶として機能する。
- 複雑な2つ目の機能を実装する場合、新しい
IV. ExecPlan（plans.md）の構造と作成ガイドライン
-
ExecPlanの厳格な構造
- ExecPlanは厳格な構造を持つ。読者（エージェント）を完全な初心者として扱い、何を編集するか、何を実行するか、何を観察するかを正確なステップで導く。
- フォーマット：三重バックティックで始まり終わる単一のフェンスされたコードブロック（
mdラベル付き）であるべきだが、.mdファイル単独の場合は省略する。平易な散文を優先する。
-
必須セクション
- タイトル：短く、行動志向の説明。
-
## Purpose / Big Picture(目的 / 全体像)：ユーザーがこの変更から何を得るか、動作を確認する方法を説明。 -
## Progress(進捗)：チェックボックス付きリストが必須。停止するたびに完了/残存タスクを記録し、タイムスタンプが推奨される。 -
## Surprises & Discoveries(驚きと発見)：実装中に発見された予期せぬ挙動、バグ、洞察を短い証拠スニペットとともに文書化。 -
## Decision Log(決定ログ)：重要な設計上の決定とその理由を記録。 -
## Outcomes & Retrospective(成果と振り返り)：主要なマイルストーンまたは完了時に、達成されたこと、課題、教訓を要約。
-
その他の主要セクション
-
## Context and Orientation(文脈とオリエンテーション)：読者が何も知らないと仮定して、現在の状態を説明。キーファイルをフルパスで指定。 -
## Plan of Work(作業計画)：編集と追加の順序を散文で具体的に記述。 -
## Concrete Steps(具体的なステップ)：実行する正確なコマンドと作業ディレクトリを明記し、予想される出力も示す。 -
## Validation and Acceptance(検証と受け入れ)：検証はオプションではない。システム起動方法、観察すべき動作を、人が検証できる行動として記述する。
-
V. まとめと高度な活用
-
戦略の利点と課題
- 良い点：指示書が少なくなる、要件定義書/設計書をAIに書いてもらえる。
- 悪い点/注意点：自分の能力以上のことをさせると破綻しやすい、複雑な箇所はバグの原因になりやすい。自分自身がアプリ全体のコードを把握できるようにし、AIをボタンを押すだけの人にならないようにする。
- 今後の開発者への影響：完璧なプロンプトよりも「完璧な計画」を立てることに重きを置くようになる。
-
開発のコツと自己回復
- 複雑なバグループに陥った場合：バックアップ用の
plans.mdを元に、現在のソースコードから新しいプランをAIに出力させ、問題の原因となりそうな複雑な指示箇所を修正する。 - 並列開発：
plans.mdを複製し、git worktreeで並列開発を行う。
- 複雑なバグループに陥った場合：バックアップ用の
この構成により、読者はまず戦略の目的と哲学を理解し、次に環境構築の具体的なファイル設定に進み、最後に日常的な開発手順（計画→実行→レビュー）を追い、ExecPlanの詳細構造を規範として参照できるようになります。これにより、情報の前後の飛びや重複が整理され、理解しやすくなるはずです。