本文書では、コーディングエージェントが機能実装やシステム変更を完了するために従うべき実行計画（「ExecPlan」）の要件を規定する。読者はこのリポジトリについて全くの初心者であると想定すること。彼らが利用できるのは現在の作業ディレクトリと、こちらが提供する単一のExecPlanファイルのみである。過去の計画に関する記憶や外部の文脈情報は一切存在しないものとする。
実行可能な仕様書（ExecPlan）を作成する際には、PLANS.mdの記載内容を厳密に遵守すること。もしその内容が現在の作業コンテキストに含まれていない場合は、PLANS.mdファイル全体を読み返して内容を再確認すること。仕様書の作成にあたっては、ソース資料を入念に読み込み（必要に応じて再読し）、正確な仕様書を作成すること。仕様書を作成する際は、まずスケルトンから始め、調査を進めるにつれて内容を肉付けしていく手法を採用すること。
実行可能な仕様書（ExecPlan）を実装する際には、ユーザーに次の手順を尋ねる必要はない。単に次のマイルストーンに進むだけでよい。すべてのセクションを最新の状態に保ち、各作業段階でリストの項目を追加または分割することで、達成した進捗と次のステップを明確に示すこと。曖昧さが生じた場合は自律的に解決し、頻繁にコミットを行うこと。
実行可能な仕様書（ExecPlan）について議論する際には、決定事項を仕様書内のログに記録し、後世に明確な理由が残るようにすること。ExecPlanは生きた文書であり、常にExecPlanのみから（他の作業を一切参照することなく）作業を再開できる状態を維持しなければならない。
要件が複雑で不確定要素が多い設計を検討する場合、概念実証や「簡易実装」などをマイルストーンとして実施し、ユーザーの提案が実現可能かどうかを検証すること。ライブラリのソースコードは、入手または調査によって徹底的に読み込み、深い理解を得た上で、完全な実装を導くためのプロトタイプを含めること。
交渉不可の要件：
- すべてのExecPlanは完全に自己完結している必要がある。自己完結とは、現在の形式において、初心者が成功するために必要なすべての知識と指示が含まれている状態を指す。
- すべてのExecPlanは生きた文書でなければならない。貢献者は、進捗の進展、新たな発見、設計上の決定が確定するたびに、仕様書を改訂する義務を負う。各改訂版も完全に自己完結している必要がある。
- すべてのExecPlanは、このリポジトリに関する事前知識がなくても、完全な初心者がエンドツーエンドで機能を実装できるようにしなければならない。
- すべてのExecPlanは、「定義を満たす」ための単なるコード変更ではなく、実際に動作する明確な挙動を生成しなければならない。
- すべてのExecPlanは、専門用語を平易な言葉で定義するか、使用を控えること。
目的と意図が最優先である。まず、この作業がユーザーにとってどのような意味を持つのかを、数文で説明することから始める：この変更によってユーザーが以前は不可能だったことが何であり、どのようにその動作を確認できるのかを説明する。その後、その成果を達成するための具体的な手順を読者に案内し、編集すべき箇所、実行すべきコマンド、観察すべき事項を明確に示すこと。
あなたの計画を実行するエージェントは、ファイル一覧の表示、ファイルの読み取り、検索、プロジェクトの実行、テストの実施が可能である。事前のコンテキストは一切把握しておらず、以前のマイルストーンからあなたが意図したことを推論することもできない。依存する前提条件はすべて明示的に記載すること。外部のブログやドキュメントを参照するのではなく、必要な知識がある場合は、独自の言葉で計画自体に組み込むこと。あるExecPlanが別のExecPlanを基盤として構築し、そのファイルがチェックインされている場合は、参照形式で組み込むこと。そうでない場合は、該当する計画から関連するすべてのコンテキストを含める必要がある。
フォーマットとエンベロープはシンプルで厳格である。各ExecPlanは、mdとラベル付けされた単一のフェンスドコードブロックで構成され、三重のバッククォートで開始および終了しなければならない。内部にさらに三重バッククォートのコードフェンスをネストしてはならない。コマンド、トランスクリプト、差分、コードなどを表示する必要がある場合は、単一のフェンスドコードブロック内のインデントされたブロックとして提示すること。ExecPlan内でコードフェンスをネストするのではなく、明確性のためにインデントを使用すること。これにより、ExecPlanのコードフェンスが早期に閉じられるのを防ぐことができる。各見出しの後には改行を2回挿入し、#や##などの適切な見出し記号を使用し、順序付きリストと順序なしリストの構文を正しく記述すること。
Markdownファイル（.md）にExecPlanを記述する場合、ファイルの内容が単一のExecPlanのみで構成されている場合は、三重バッククォートを省略してもよい。
平易な文章で記述すること。箇条書きよりも文章を優先すること。簡潔さのために意味が曖昧になる場合を除き、チェックリスト、表、長文の列挙は避けること。チェックリストはProgressセクションでのみ許可されており、このセクションでは必須となる。説明文セクションでは、常に文章を最優先とすること。
自己完結性と平易な表現が最も重要である。日常的な英語ではない用語（「デーモン」「ミドルウェア」「RPCゲートウェイ」「フィルタグラフ」など）を導入する場合は、その用語を直ちに定義し、このリポジトリ内でどのように実装されているかを明示すること（例えば、該当するファイルやコマンド名を記載する）。「前述の定義によると」や「アーキテクチャドキュメントによると」といった表現は使用せず、必要な説明はここで直接記載すること。たとえ重複する内容になったとしても、この原則を守ること。
一般的な失敗パターンを避けること。定義が不明確な専門用語に依存しないこと。「機能の文字面」だけを細かく記述した結果、コードはコンパイルされるが実質的に何も機能しない状態にならないよう注意すること。重要な判断を読者に委ねないこと。解釈の余地がある場合は、計画自体でその判断理由を明確に説明すること。ユーザーから見える影響については過剰に説明する傾向を持ち、付随的な実装の詳細については過小に仕様を定めること。
計画内容を観測可能な結果に基づいて記述すること。実装後にユーザーが実行できる操作、実行すべきコマンド、期待される出力結果を明確に記載すること。承認条件は、内部的な属性（「HealthCheck構造体を追加した」など）ではなく、人間が検証可能な動作（「サーバーを起動後、http://localhost:8080/healthにアクセスするとHTTP 200レスポンスとボディOKが返される」など）として表現すること。内部的な変更の場合、その影響をどのように実証できるかを説明すること（例えば、変更前は失敗するが変更後は成功するテストの実行方法や、新しい動作を利用するシナリオの提示など）。
リポジトリのコンテキストを明確に指定すること。ファイルはリポジトリ相対パスで完全に指定し、関数やモジュール名は正確に命名すること。新規ファイルの作成場所についても具体的に記述すること。複数の領域に手を加える場合は、初心者が自信を持って作業できるよう、各部分の関係性を説明する簡潔な導入文を記載すること。コマンドを実行する際は、作業ディレクトリと正確なコマンドラインを表示すること。結果が環境に依存する場合は、前提条件を明記し、合理的な場合には代替案を提供すること。
冪等性（同じ操作を繰り返しても結果が変わらない性質）と安全性を確保すること。複数回実行しても損傷や設定のずれが生じないよう、手順を記述すること。途中で失敗する可能性がある手順については、再試行方法や代替処理方法を明記すること。移行作業や破壊的操作が必要な場合は、バックアップ方法や安全なフォールバック手段を明確に記載すること。追加的でテスト可能な変更を優先し、作業を進めながら検証できるようにすること。
検証は必須事項である。テスト実行手順、該当する場合はシステムの起動方法、およびシステムが有用な処理を実行している様子を確認する方法を記載すること。新機能や追加機能については、包括的なテスト方法を詳細に記述すること。期待される出力結果とエラーメッセージを明記し、初心者が成功と失敗を区別できるようにすること。可能であれば、コンパイル結果を超えた有効性を証明する方法を示すこと（例えば、小規模なエンドツーエンドシナリオ、CLIコマンドの実行例、HTTPリクエスト/レスポンスのトランスクリプトなど）。プロジェクトのツールチェーンに適した正確なテストコマンドと、その結果の解釈方法についても明記すること。
証拠を記録すること。実行手順によってターミナル出力、差分ファイル（short diffs）、またはログが生成される場合、それらをインデントされた例示として単一のフェンスドブロック内に含めること。内容は簡潔にまとめ、成功を証明する要素に焦点を当てること。パッチを含める必要がある場合は、大規模なバイナリデータを貼り込むのではなく、ファイル単位の差分や読者が指示に従って再現可能な短い抜粋形式を優先すること。
マイルストーンは単なる形式的な手続きではなく、物語性を持つものである。作業をマイルストーン単位で分割する場合、各マイルストーンの冒頭に、その範囲、マイルストーン終了時に存在するようになるが開始前には存在しなかったもの、実行すべきコマンド、および期待する受け入れ基準について簡潔な段落で説明すること。物語として読みやすく構成すること：目標、作業内容、成果、証明。進捗とマイルストーンは明確に区別すること。マイルストーンは物語を伝えるものであり、進捗は詳細な作業工程を追跡するものである。どちらも必ず存在させる必要がある。単に簡潔さを求めるためにマイルストーンを省略したり、将来の実装において重要となる可能性のある詳細事項を記載し忘れることがあってはならない。
各マイルストーンは、独立して検証可能であり、実行計画の全体的な目標を段階的に達成するものでなければならない。
- ExecPlanは生きた文書である。重要な設計決定を行うたびに、その決定内容とその背景にある考え方を計画に反映させること。すべての決定事項は
決定ログセクションに記録すること。 - ExecPlanには、
進捗セクション、予期せぬ発見と気づきセクション、決定ログセクション、および成果と振り返りセクションを必ず含め、維持すること。これらはオプションではない。 - 最適化動作、パフォーマンストレードオフ、予期せぬバグ、またはアプローチに影響を与えた逆引き/非適用の意味論を発見した場合、それらを
予期せぬ発見と気づきセクションに短い証拠の断片（テスト出力が理想的）とともに記録すること。 - 実装途中で方針を変更する場合、その理由を
決定ログに文書化し、進捗セクションに反映させること。計画はあなた自身のチェックリストとしてだけでなく、次の担当者へのガイドとしても機能するものであること。 - 主要なタスクの完了時または計画全体の完了時には、達成事項、未完了事項、および得られた教訓を要約した
成果と振り返りエントリを作成すること。
大規模な変更に伴うリスクを軽減するため、明示的なプロトタイプ段階を設けることは許容される――むしろ推奨される――場合がある。具体例としては、実現可能性を検証するために依存関係に低レベル演算子を追加する場合や、最適化の影響を測定しながら2つの合成順序を検討する場合などが挙げられる。プロトタイプは追加可能でテスト可能なものにすること。明確に「プロトタイプ」の範囲をラベル付けし、実行方法と結果の確認方法を記述するとともに、プロトタイプを推進または破棄するための判断基準を明記すること。
テストが通過し続ける状態を維持しつつ、追加的なコード変更を行った後に不要な部分を削除する方法を優先する。並行実装（例：移行期間中に古いパスと並行してアダプタを保持する場合など）は、リスク低減や大規模な移行期間中にテストを継続可能にする場合であれば問題ない。両パスの検証方法と、テストを維持しながら安全に一方のパスを廃止する方法について明確に記述すること。複数の新規ライブラリや機能領域を扱う場合、これらの機能を相互に依存せずに個別に評価する「スパイク」（簡易実装）を作成し、外部ライブラリが期待通りに動作し、必要な機能を単独で実装できることを実証することを検討すべきである。
# <簡潔で行動指向型の説明>
本ExecPlanは生きた文書である。作業が進むにつれて、`進捗`、`予期せぬ発見`、`意思決定記録`、`成果と事後分析`の各セクションを常に最新の状態に保つこと。
リポジトリにPLANS.mdファイルがコミットされている場合、リポジトリルートから当該ファイルへのパスを参照し、この文書がPLANS.mdに準拠して維持されなければならない旨を明記すること。
## 目的／全体像
この変更によって得られるメリットと、ユーザーがその効果をどのように確認できるかを簡潔に説明すること。実現するユーザー可視の動作仕様を明確に記述すること。
## 進捗
チェックボックス付きのリスト形式を用いて、詳細な作業ステップを要約すること。作業が途中で中断された場合でも、必ずその時点までの状況を記録すること（例：「完了」と「未完了」に分割する）。本セクションは常に実際の作業の現状を正確に反映している必要がある。
- [x] (2025年10月1日 13:00 UTC) 完了した具体例
- [ ] 未完了の具体例
- [ ] 部分的に完了した具体例（完了部分：X、未完了部分：Y）
進捗率を測定するため、各作業項目にはタイムスタンプを付すこと。
## 予期せぬ発見と発見事項
実装過程で遭遇した予期しない動作、バグ、最適化ポイント、あるいは得られた知見を記録すること。簡潔な証拠資料を添付すること。
- 観察事項：…
証拠資料：…
## 意思決定記録
本計画の策定過程で下した全ての意思決定を、以下の形式で記録すること：
- 決定事項：…
判断根拠：…
決定日/作成者：…
## 成果と振り返り
主要なマイルストーン時点またはプロジェクト完了時に、得られた成果、未達成事項、および得られた教訓を要約すること。当初の目的と結果を比較検証すること。
## 背景と前提条件
読者がこのタスクに関する事前知識を全く持っていないと仮定し、現状を説明すること。重要なファイルやモジュールはフルパスで明記すること。自明でない専門用語については定義を記載すること。過去の計画については言及しないこと。
## 作業計画
編集作業と追加作業の順序を、文章形式で詳細に記述すること。各編集作業については、対象ファイルと変更箇所（関数名・モジュール名など）、および挿入または変更すべき内容を明示すること。具体的かつ最小限の記述に留めること。
## 具体的な作業手順
実行する正確なコマンドと、その実行場所（作業ディレクトリ）を明記すること。コマンド実行時に出力が生成される場合、読者が結果を比較できるよう、想定される出力の簡潔なサンプルを示すこと。このセクションは作業の進捗に合わせて随時更新すること。
## 検証と承認プロセス
システムの起動方法またはテスト実行方法、および確認すべき事項を具体的に記述すること。承認条件は動作仕様として表現し、具体的な入力値と期待される出力値を明記すること。テストを実施する場合は、「<プロジェクトのテスト実行コマンド>を実行し、<N>件のテストが合格することを期待すること。変更前の新規テスト<テスト名>は不合格となるが、変更後は合格すること」といった形式で記述すること。
## 冪等性と復旧手順
同じ手順を安全に繰り返し実行できる場合は、その旨を明記すること。リスクを伴う手順については、安全な再試行またはロールバックの方法を提供すること。作業完了後は環境をクリーンな状態に戻すこと。
## 成果物と補足情報
最も重要な実行結果のログ、差分比較結果、またはコードスニペットを、インデントを施した具体例として含めること。これらの内容は簡潔にまとめ、成功を実証するために必要な情報に限定すること。
## インターフェースと依存関係
具体的な指示を明記すること。使用するライブラリ、モジュール、サービスの名称とその理由を明確に記述すること。マイルストーン終了時に存在すべき型、トレイト/インターフェース、および関数のシグネチャを具体的に指定すること。可能な限り安定した名称とパスを使用することを推奨する（例：`crate::module::function` や `package.submodule.Interface`）。具体例：
crates/foo/planner.rs ファイルで以下のように定義する：
pub trait Planner {
fn plan(&self, observed: &Observed) -> Vec<Action>;
}上記のガイドラインに従っていれば、ステートレスな単一エージェント（あるいは経験の浅い人間）でも、ExecPlanを上から順に読み進めるだけで、実際に動作し観測可能な結果を生成できる。これが達成すべき基準である：自己完結型、自己充足型、初心者指導型、かつ成果物重視型であること。
計画を修正する場合は、変更内容がすべてのセクション（特に動的に更新される文書セクションを含む）に確実に反映されていることを確認し、計画の最下部に変更内容とその理由を簡潔に記述したメモを記載すること。ExecPlanでは、ほとんどのケースにおいて「何を」だけでなく「なぜそれを」行うのかについても明確に記述する必要がある。