バッチ計画・実行

バッチ計画実行

このスキルは、要件ソースと現在の plans/ ディレクトリの状態に基づいて、モジュール計画とそこから派生する checklist.md を作成、修正、廃止、実行、または検査するタスクに使用します。

このスキルには現在、以下の明示的なモードがあります。

• plan: 実装可能な計画を生成または修正し、checklist.md を更新します。
• execute: すでにレビューされた計画を実装します。

このスキルは以下のことを実行できます。

• チャットからの要件テキスト、requirements.md などの要件ファイル、または既存の計画ファイルや plans/ ディレクトリを受け入れます。
• 最新の要件ソース、既存の計画ファイル、および隠し状態ファイルから現在の計画状態を再構築します。
• モジュールごとに、新規要件、変更要件、削除要件、レビューノートの混在した変更を検出します。
• 並列化可能な作業と直列的な作業を反映した、依存関係を認識するモジュールまたはワークストリーム計画を構築します。
• 最新の要件ソースと信頼できるレビューノートから、統合された checklist.md を生成します。
• ユーザーからの明示的な実行コマンドがあった場合にのみ、実装サブエージェントを使用して承認された計画を実行します。

入力処理

以下の優先順位で主入力を選択します。

1. ユーザーが言及した明示的な計画ファイルパスまたは plans/ ディレクトリパス。
2. ユーザーが言及した明示的な要件ファイルパス。
3. タスクコンテキストにすでに添付されているファイルまたはドキュメント。
4. チャットに直接書き込まれた要件テキスト。

以下のルールを使用します。

• 計画ファイルパスが指定された場合は、その計画系統を主要な開始点として扱い、同じ階層にある plans/ ディレクトリを検査します。
• plans/ ディレクトリパスが指定された場合は、そのディレクトリ内の計画ファイルと状態ファイルのみを検査します。
• 要件ファイルパスが指定された場合は、それを直接読み取り、最新の要件ソースとして扱います。
• 入力が生のチャットテキストの場合は、ユーザーテキスト全体を最新の要件ソースとして扱います。
• 要件ソースと plans/ ディレクトリの両方が利用可能な場合は、常に両方を使用します。

参照されたファイルまたはディレクトリが存在しないか、読み取り可能でない場合は、すぐに失敗します。

出力言語

以下のルールを使用します。

• ユーザーから見えるすべての出力言語を、最新の要件ソースの主要言語に一致させます。
• 要件ソースが存在しない場合は、ユーザーの今回のターンでの入力の主要言語に一致させます。
• ユーザーが翻訳や特定の出力言語を明示的に要求した場合は、代わりにそれに従います。

モード選択

デフォルトは plan モードです。

ユーザーが今回のターンで明示的に実行コマンドを発行した場合にのみ、execute モードに切り替えます。

execute モードに解決される例：

• 开始执行
• 按这个方案实现
• 去改代码
• 直接落地
• implement now
• apply the plan

デフォルトの plan 動作からモードを変更しない例：

• LGTM
• OK
• 继续
• 按这个方向
• review 过了
• 計画を確認するが、実装の開始を明示的に要求しない承認。

以下のルールを使用します。

• レビュー承認は実行承認ではありません。
• ユーザーの意図があいまいな場合は、plan モードを維持し、実行計画を洗練するか、より明確な実行コマンドを求めます。
• 勢い、楽観論、または反対意見の欠如から実行意図を推測してはいけません。

出力場所と命名規則

計画ファイルは plans/ ディレクトリに書き込みます。

• ソースが要件ファイルの場合は、そのファイルの隣に plans/ フォルダを使用します。
• ソースが計画ファイルまたは plans/ ディレクトリの場合は、同じ plans/ ディレクトリに書き込み続けます。
• ソースが生のチャットテキストの場合は、<cwd>/plans/ を使用します。

plans/ ディレクトリが存在しない場合は作成します。

基本計画ファイルは以下の形式を使用します。

• <module-slug>.md

改訂計画ファイルは以下の形式を使用します。

• <module-slug>.rev-<n>.md

派生チェックリストファイルは以下である必要があります。

• checklist.md

隠し状態ファイルは以下である必要があります。

• .state.json

以下の命名規則を使用します。

• new-plan は、モジュールに以前の系統がない場合、基本ファイルを作成する場合があります。
• revise-plan と obsolete-plan は、常に新しい rev ファイルを書き込む必要があります。
• no-op は新しい計画ファイルを書き込んではいけません。
• 既存のファイルを静かに上書きしてはいけません。
• 計画スラッグは、要件の見出しテキストではなく、実装の所有権に従う必要があります（両者が異なる場合）。
• 最新の要件ソースが読み取り可能なファイルである場合は、checklist.md を plans/ 内ではなく、その要件ファイルの隣に書き込みます。
• 読み取り可能な要件ファイルが存在しない場合は、アクティブな plans/ ディレクトリ内に checklist.md を書き込むようにフォールバックします。
• 安全に更新できる場合は、解決された checklist.md パスを常にその場で上書きします。
• checklist.md は派生スナップショットであり、計画系統の成果物でも実行ターゲットでもありません。

状態ファイル

計画のベースラインとして plans/.state.json を維持します。

状態ファイルには少なくとも以下を含める必要があります。

• requirement_source
• requirement_hash
• run_at
• modules

各モジュール状態オブジェクトには少なくとも以下を含める必要があります。

• slug
• title
• status
• source_excerpt_hash
• body_hash_without_heading
• latest_plan_file
• latest_rev
• last_action

ステータス値は明示的である必要があります。

• active
• obsolete

以下のルールを使用します。

• 状態ファイルは計画系統のみを記述します。
• 状態ファイルを実行の許可として扱ってはいけません。
• 状態ファイルがない場合は、失敗する代わりに、最新の要件ソースと既存の計画ファイルからブートストラップします。

プランモード

詳細な計画作成契約については、docs/plan.md を参照してください。

モジュール抽出

デフォルトでは、リポジトリのパッケージ構造や要件の見出しに機械的に従うのではなく、実装単位と依存関係の境界で分割します。

モジュールを抽出したり、要件ハッシュを計算したりする前に、コードフェンスの外側にある HTML コメントを削除して、最新の要件ソースを前処理します。

以下のルールを使用します。

• コメント化された要件コンテンツは存在しないものとして扱います。
• 最終的なモジュール境界としてではなく、抽出の補助としてのみ要件セクションから開始します。
• 背景、目標、範囲、非目標、前提条件、ロールアウト、受け入れ基準、非機能要件などのメタセクションは、独立したモジュールではなく、グローバルな制約として扱います。
• 同じ実装パス、共有コード面、または同じ所有者レベルの成果物に該当する要件スライスをマージします。
• セクションが、独立した成果物、または基盤作業の後の機能作業のような厳格な実装シーケンスを明確に記述している場合にのみ分割します。
• 機能的な所有権、共有インターフェースの所有権、移行境界、またはデプロイメント境界に一致するモジュール境界を優先します。
• 同じ共有変更を両方とも所有する、重複するモジュールを作成してはいけません。
• 実装を含むモジュールを抽出できない場合、または共有所有権を明確に割り当てられない場合は、大きな問題を報告して失敗します。

ソースが信頼できる見出しのないプレーンテキストの場合：

• 要件コンテンツから簡潔なモジュールリストを導出します。
• 機能境界、ワークフロー、成果物、前提条件関係をモジュール名として使用します。
• misc、other、supporting-work のような一般的なモジュール名は避けます。

依存関係と並列性のモデリング

候補モジュールを抽出した後、分類やサブエージェントの生成前に、明示的な依存関係グラフを導出します。

以下のルールを使用します。

• 各モジュールを foundation、feature、follow-on として分類します。
• depends_on、blocks、parallelizable_with、shared_change_owner を記録します。
• 同じ共有コードの所有権を同じフェーズで必要としない場合にのみ、並列モジュールを優先します。
• 1つのモジュールが、別のモジュールが利用するコントラクト、スキーマ、マイグレーション、または共有ユーティリティを変更する場合は、直列的な順序付けを優先します。
• 実装が A の後に B である場合は、両方を1つのピアリストに強制的に含めるのではなく、直接モデル化します。
• 偽の並列性を推測してはいけません。安全な順序が不明な場合は、控えめに順序付けします。

レビューの検出と系統

レビューの検出は plans/*.md 内でのみ意味があります。

以下のルールを使用します。

• コードフェンスの外側にある HTML コメントはレビューノートとして扱います。
• ユーザーコメント内のレビューコンテンツが元の要件ドキュメントと矛盾する場合は、レビューコンテンツを最新の信頼できる指示として扱います。
• 最終的な計画出力に HTML コメントを保持してはいけません。
• 最高の rev によって最新の系統成果物を解決し、それ以外の場合は最新の基本ファイルを解決します。
• 最初にスラッグの一致を優先します。
• body_hash_without_heading での安全な1対1の一致に対してのみ、名前変更の一致を許可します。
• 名前変更の一致があいまいな場合は、推測してはいけません。

チェックリストの生成

plan の実行が成功するたびに checklist.md を生成または更新します。

以下のルールを使用します。

• 最新の要件ソースと、最新の計画系統からの信頼できるレビューノートからチェックリストを構築します。
• チェックリスト項目を導出する前に、モジュール抽出に使用したのと同じ要件前処理を適用します。
• レビューコメントが元の要件ドキュメントと矛盾する場合は、それらを信頼できるものとして扱います。
• checklist.md に生の HTML コメントを決して保持してはいけません。解決された意図のみを保持します。
• チェックリストのセクションは、生の要件見出しの順序ではなく、依存関係レイヤーとモジュールの順序で整理します。
• Markdown 見出しと、- [ ] ... のようなアクション可能な未チェック項目を使用します。
• 物語的な要約ではなく、検証可能な実装または受け入れ結果を優先します。
• 最新の要件ソースが読み取り可能なファイルである場合は、checklist.md をその要件ファイルの隣に書き込みます。
• 読み取り可能な要件ファイルが存在しない場合は、アクティブな plans/ ディレクトリ内に checklist.md を書き込みます。
• ソースが計画ファイルまたは plans/ ディレクトリである場合は、チェックリストを更新する前に plans/.state.json から最新の読み取り可能な要件ソースを解決します。
• 要件ソースを安全に再構築できない場合は、レビュー主導の計画改訂の続行を許可しますが、checklist.md を更新できなかったことを報告します。

混合モード分類

実行全体に対して1回ではなく、モジュールごとにアクションを決定します。

各モジュールを正確に1つのアクションに分類します。

• new-plan
• revise-plan
• obsolete-plan
• no-op

以下のデフォルトを使用します。

• 要件の変更とレビューノートを1つの revise-plan にマージします。
• 削除されたモジュールを黙ってドロップする代わりに、obsolete-plan リビジョンを生成します。
• 要件ソースが利用できない場合は、レビュー主導のリビジョンのみを許可します。
• 要件ソースのコメントのみの編集は revise-plan をトリガーしてはいけません。

計画サブエージェント

モジュールリスト、依存関係グラフ、およびアクションをロックした後、影響を受けるモジュールごとに1つの計画サブエージェントを生成します。

以下のルールを使用します。

• 計画作業には、読み取り専用の分析サブエージェントを優先します。
• 専用の読み取り専用分析ロールが利用できず、サブエージェントが読み取り専用のままである場合にのみ、汎用サブエージェントを使用します。
• 計画サブエージェントはファイルを編集してはいけません。
• 同じ依存関係レイヤー内でのみ、計画サブエージェントを並列実行します。
• 各計画サブエージェントに、影響を受けるコード領域、インターフェース、依存関係、並列性に関する注意事項、リスク、テスト、および明示的な前提条件を返すように依頼します。

計画の統合

メインエージェントは、最終的な計画の品質、計画ファイルの出力、および状態ファイルの更新に責任を持ちます。

以下のルールを使用します。

• モジュール間の依存関係を解決して、用語と共有変更の一貫性を保ちます。
• 共有インターフェース、スキーマ、マイグレーション、またはインフラストラクチャの変更ごとに、1つの明確な所有者を確認します。
• 要件見出しの順序ではなく、依存関係レイヤーに従って最終的なモジュール出力を順序付けます。
• モジュールが別のモジュールによってブロックされている場合、または前提条件の後に並列実行できる場合に、明示的に記述します。
• モジュール計画が統合され、状態ファイルを更新する前に checklist.md を更新します。
• 影響を受けるすべてのモジュールが処理された後にのみ plans/.state.json を更新します。

実行モード

詳細な実行契約については、docs/execute.md を参照してください。

実行前提条件

以下のいずれかが当てはまる場合は、すぐに失敗します。

• ターゲットの計画ファイルまたは plans/ ディレクトリを解決できない。
• 最新のターゲット計画成果物に、未解決のレビューコメントがまだ含まれている。
• リポジトリを安全に書き込み所有権を割り当てるのに十分に接地できない。
• 共有変更の所有権があいまいである。
• 依存関係サイクルをマージされたモジュールとして正当化できない。

実行ルール

ゲートと前提条件が満たされた後：

• docs/execute.md を、ターゲット解決、接地、ワーカーディスパッチ、統合、検証、および完了に使用します。
• 選択された各モジュール系統の最新のレビュー済み成果物を実行します。
• プランモードで生成された依存関係グラフを尊重するか、ディスパッチ前に最新の計画セットからそれを再構築します。

失敗ルール

以下の場合は、弱い出力を生成する代わりに停止して問題を報告します。

• 要件ファイル、計画ファイル、または計画ディレクトリが見つからないか、読み取り不可である。
• 必要な要件ソースに対してモジュール抽出が失敗する。
• 計画がほとんど推測に基づいており、意味のあるコードベースとの関連性がない場合。
• 1つのモジュールに複数の最新系統候補が存在し、順序を安全に解決できない。
• 名前変更の一致があいまいで、安全な1対1のマッピングに絞り込めない。
• 共有変更または依存関係の所有権を1つの明確なモジュールまたはワークストリームに割り当てられない。
• 依存関係グラフに、単一のマージされたモジュールとして正当化できないサイクルが含まれている。
• 状態ファイルは存在するが、不正な形式であり、可視の成果物から安全に再構築できない。

タスクがモジュールごとの出力を必要とする場合に、空の計画ファイル、サマリーのみのファイル、または単一の集約計画を出力してはいけません。