Frontier Plan OpenCode Executor
核となる原則
フロンティアAIの計画は強い仮説であり、絶対的な真実ではありません。
計画の意図をステップごとに実行しますが、コードを編集する前に、すべての指示を実際のリポジトリに対して検証してください。フロンティアAIの計画は、存在しないファイル名、発明されたインポート、利用できないライブラリ、リポジトリに合わないパターン、欠落したテスト、理想化されたアーキテクチャ、内部APIの破壊などで頻繁に失敗します。
大規模な変更を一度に行わないでください。検証をスキップしないでください。不確実性を隠さないでください。明示的な承認なしに破壊的なアクションを実行しないでください。
使用すべき場面
- フロンティアAIが作成した、詳細な複数ステップの実装計画を受け取った場合
- 計画に、特定のファイルパスとコードパターンを含む3つ以上の明確なステップがある場合
- 実行規律の恩恵を受ける非フロンティアコーディングモデルを使用している場合
- 計画が実際のコードベースと競合するリスクがある場合
以下の場合は使用しないでください:
- 単一ファイルの変更や些細な修正
- 1〜2の簡単なステップのみの計画
- 同じセッション内で自分自身が作成した計画
- 安全性よりも速度を優先する迅速なイテレーション
コアワークフロー
0. PREFLIGHT: リポジトリのベースラインを確立
ファイルに触れる前に、リポジトリの状態を理解し、既存の障害を検出します。
1. git status --short # リポジトリはクリーンか?
2. package.json を検査 # 利用可能なスクリプト、依存関係
3. AGENTS.md、README.md を検査 # プロジェクトの規約、コマンド
4. package.jsonのスクリプトから利用可能な検証コマンドを検出
5. 可能であれば、最も安価なベースライン検証を実行(lintまたはtypecheck)
ベースラインがすでに失敗している場合:
- 失敗を明示的に記録: 正確なコマンド、終了ステータス、短いエラー概要
- 広範なクリーンアップや無関係な問題の修正を試みない
- 計画された変更が既存の障害から分離できる場合にのみ続行
- 既存の障害を自身の実装のせいにしない
危険な状態の検出:
git statusが計画に関係のない未コミットの変更を示している場合、ユーザーに警告- ロックファイルが変更されている場合、ユーザーに警告
- リポジトリがコンフリクト/リベース状態にある場合、停止して確認
チェックポイントの推奨:
- 開始前にリポジトリがクリーンな場合、実装前のチェックポイントコミットを作成することを推奨
- ユーザーから明示的に依頼されない限り、コミットを作成しない
自動コミットと自動プッシュ
ユーザーが明示的に無効にしない限り、自動コミットと自動プッシュはデフォルトで有効です。
エージェントは、検証済みの論理的な作業単位ごとにコミットし、アクティブなリモート作業ブランチにプッシュして、ユーザーが後で履歴を確認できるようにする必要があります。
実装前:
- 現在のブランチを特定する
main、master、production、release、またはその他の保護/メインブランチ上にいる場合、計画から推測した新しい作業ブランチを作成する- すでに作業ブランチ上にいる場合は、そのまま続行する
- 保護/メインブランチに直接プッシュしない
既存の未コミットの変更がある場合:
- それらをエージェントのコミットに自動的に含めない
- 現在の論理単位に関連するファイルのみをステージングする
- ユーザーの変更とエージェントの変更を安全に分離できない場合、停止してコンフリクトを報告する
以下の場合にのみコミットする:
- 論理単位が完了している
- 検証が成功している
- 差分が検査されている
- コミットに一貫した目的がある
Conventional Commits を使用:
type(scope): 簡潔な命令形のサマリー
例:
feat(auth): add session validation helper
fix(api): handle empty webhook payload
refactor(billing): extract invoice mapper
test(auth): cover expired session flow
1. PARSE: 計画を抽出し、現実性をチェック
計画全体を読みます。順序付けられたステップを抽出します。各ステップに対して、現実性チェックを実行します:
| チェック | 質問 |
|---|---|
| ファイル | 参照されたファイルはリポジトリに存在するか? |
| ライブラリ | 参照されたライブラリは package.json に存在するか? |
| パターン | リポジトリにはすでに同等のユーティリティ/コンポーネントがあるか? |
| コマンド | 計画の検証コマンドは利用可能か? |
| 依存関係 | このステップは前のステップに依存しているか? |
| リスク | 低 / 中 / 高 — 既存の動作を壊す可能性はどの程度か? |
ステップが存在しないファイル、存在しないライブラリ、古いパターン、利用できないコマンドを参照している場合: 計画の意図を保持したまま、実装前にステップを適応させてください。
2. TRACK: 進捗トラッカーを作成
可能であれば todowrite(OpenCodeのタスクリストツール)を使用します。
todowrite が利用できない場合(例: サブエージェントでデフォルトで無効になっている場合):
- レスポンス内にマークダウンチェックリストを作成
- 各ステップの後に手動で更新
- それを進捗の信頼できる情報源として使用
- ツールが使用されなかったのに使用されたふりをしない
各項目には以下を含める必要があります: 実装アクション、検証方法、触れる予定のファイル。
3. IMPLEMENT: 一度に1ステップ
現在のステップを in_progress としてマークします。そのステップのみを実装します。
- 編集前にターゲットファイルを読む
- 既存のコードベースの規約に従う(インポート、命名、パターン、アーキテクチャ)
- 既存のインフラに合わせて計画を適応させる(例: 計画が「トーストコンポーネントを作成」と言っているが、プロジェクトがSonnerを使用している場合、ゼロから構築する代わりにSonnerをラップする)
- 最小限の一貫した変更を行う
- 将来のステップは実装しないが、設計上の決定を行う際には下流の依存関係を念頭に置く
- 無関係なクリーンアップ、リファクタリング、フォーマットを行わない
- 明示的に承認されない限り、依存関係をインストールしない
4. VERIFY: 段階的検証
各ステップの後で、最も狭い意味のある検証を実行します。 毎回「すべてをlint」しないでください。
| 変更の種類 | 最小限の検証 | より強力な検証 |
|---|---|---|
| 新しいファイル/コンポーネント | lint または typecheck | 影響を受ける typecheck |
| 型/インターフェースの変更 | typecheck | 影響を受けるテスト |
| ロジック/関数の変更 | 対象を絞った単体テスト | 全テストスイート |
| API/サーバーの変更 | 対象を絞った統合テスト | ビルド + エンドポイントチェック |
| UIの変更 | typecheck + ビルド | ビジュアル/手動スモークチェック |
| 設定/ビルドの変更 | ビルド | 必要な場合はクリーンインストール/ビルド |
| データベース/スキーマの変更 | ドライラン/チェックコマンド | ユーザーの承認が必要 |
ステップに自動検証が存在しない場合: 手動レビューを実行し、何をチェックしたかを正確に述べてください。
検証が失敗した場合:
最初の失敗 — 修正して再検証:
- 現在のステップによって引き起こされたエラーのみを修正
- 既存または無関係なエラーは修正しない
- 直ちに再検証
繰り返しの失敗 — 盲目的にパッチを当て続けないでください。 以下の「繰り返し失敗処理」を参照。
重要: アサーションの弱体化、テストの削除、動作の削除、パブリックAPIの変更、エラーの抑制、失敗の隠蔽によって検証を通過させないでください。ただし、計画で明示的に要求され、ユーザーが承認した場合は除きます。アラームを止めることは問題を修正することと同じではありません。
5. DIFF: 変更を検査
検証が成功したら、実際に何が変わったかを検査します:
git diff --stat # どのファイルが変更されたか?
git diff # 差分がレビューできる程度に小さい場合
確認:
- 期待されたファイルのみが変更された
- 無関係なフォーマットが発生していない
- ロックファイルが変更されていない(明示的に意図した場合を除く)
- 生成されたファイルが誤って編集されていない
- シークレット、ローカルパス、デバッグログが導入されていない
- コードが誤って削除されていない
差分が期待されるスコープを超えている場合、続行する前に停止して修正してください。
6. CONFIRM: 完了をマーク
実装、検証、および差分検査がすべてクリーンになった場合のみ:
- ステップを
completedとしてマーク - 何が変わったかを一文で要約
- 次のステップを
in_progressとしてマーク
7. FINAL: 完全検証 + レポート
すべてのステップの後:
- 最も強力な妥当なチェックを実行: lint + typecheck + ビルド + テスト(プロジェクトコマンドを使用)
- 報告: 完了したステップ、変更されたファイル、検証結果、行われた適応、既存の失敗(ある場合)、ユーザーのレビューが必要なもの
繰り返し失敗処理
検証が同じ根本的な理由で繰り返し失敗する場合、小さな盲目的な修正を適用し続けないでください。 目標は、試行の間に新しいことを学習しているのか、それともランダムに手探りしているだけなのかを検出することです。
ステップが複数回失敗した場合:
- パッチ適用をやめてください。 小さな調整を加えて再実行するのをやめてください。
- エラー出力を注意深く読み直してください。 最初の行だけでなく、完全なスタックトレース。
- 差分と周囲のコードを検査してください。
git diff、関連する型、インターフェース、関数を読んでください。 - 元の前提を再評価してください。 現在の実装戦略は正しいですか?
- 失敗を分類してください:
- コードベースに関する誤った仮定?
- リポジトリの不一致(計画と現実)?
- 間違った抽象化の選択?
- インターフェースまたは型の非互換性?
- 依存関係の欠落?
- 古い生成アーティファクト?
- 変更とは無関係の既存の問題?
- 検証コマンド自体の設定ミス?
- 真に新しい仮説を立ててください。 新しい仮説がある場合にのみ再試行してください。
- スコープの縮小を検討してください。 ステップをより小さな部分に分割して、失敗を分離できますか?
重要なルール: 以下のいずれかから新しい情報が発見されない限り、同じ修正戦略を繰り返さないでください:
- ログ
- スタックトレース
- 差分
- テスト
- リポジトリの検査
- ドキュメント
複数回試行しても新しい戦略が現れない場合、停止してブロッカーを明確に報告してください:
ブロッカー:
- 検証コマンド: `npm run build`
- 失敗ファイル: `src/app/page.tsx`
- 根本原因の仮説: React Server Componentがクライアント専用フックをインポートしている
- 試行した戦略:
1. インポートをクライアントコンポーネントに移動
2. フックを別のファイルに分離
3. リポジトリ内の既存パターンを確認
- 停止理由:
境界を安全に解決するための一貫したパターンがリポジトリに見つからない
- 次のアクションの可能性:
ユーザーレビューまたはアーキテクチャの明確化
推測しながら「まだ失敗している」を繰り返すよりも、明確なブロッカーレポートの方が常に優れています。
計画を既存コードに適応させる
フロンティアAIの計画は、実際のコードベースと頻繁に競合します。その場合:
- 競合を特定 — 「計画では
import { X } from 'uninstalled-lib'とあるが、package.jsonにない」 - 無視せずに適応 — 計画の意図に合わせるために既存のインフラを使用
- 適応を説明 — 何を変更したか、その理由を一文で
- 計画のインターフェースを維持 — 計画が
useToast()をエクスポートしている場合、内部が異なっていても、適応版でもuseToast()をエクスポートする
重要なルール:
- リポジトリにすでに同等のプリミティブが存在する場合、新しい抽象化を作成しない
- 計画で明示的に要求され、ユーザーが承認しない限り、新しい依存関係をインストールしない
- 正当な理由なくアーキテクチャやパターンを変更しない
明示的なユーザー承認なしに禁止
以下のコマンドは、実行前にユーザーが「はい」と言う必要があります:
破壊的:
rm -rfgit reset --hardgit clean -fdgit push --force
インストール(ロックファイルを変更):
npm installpnpm installyarn installbun installnpm audit fix
データベース/インフラ:
prisma migrateprisma db pushsupabase db pushdocker compose down -v
設定:
.envファイルの変更- グローバルツール設定の変更
- デプロイ/非公開コマンドの実行
大規模変更:
- 広範なフォーマット(リポジトリ全体へのprettier/eslint --fix)
- レビューなしでの多数のファイルにわたる検索と置換
コマンドが安全かどうかわからない場合は、実行する前に確認してください。
よくある間違い
| 間違い | 現実 |
|---|---|
| 「フロンティアAIがそう言ったから正しいに違いない」 | フロンティアAIの計画は仮説です。実際のリポジトリに対して検証してください。 |
| 「最後に全部検証すればいい」 | エラーは複合します。各ステップを適切な粒度で検証してください。 |
| 「計画はもう読んだから、全部一度に実装できる」 | 一括実装 = 一括エラー + デバッグの困難化。 |
| 「ついでに既存のlintエラーも修正しておこう」 | 無関係なクリーンアップは、自分の変更が実際に何をしたかを隠します。やめてください。 |
| 「このステップは簡単だから、git diffを確認しなくても大丈夫」 | 単純な編集でも、誤ってコードを削除したり、意図しないファイルをフォーマットしたりする可能性があります。 |
| 「計画が参照している不足ライブラリをインストールしよう」 | 最初に確認してください。そのライブラリは意図的に存在しないか、承認されていない可能性があります。 |
| 「npm run buildだけが重要な検証だ」 | ビルドは遅くて広範です。中間ステップにはlint/typecheckを使用してください。 |
| 「失敗したら、ちょっと調整して再実行すればいい」 | 新しい情報なしでの盲目的なパッチ適用は手探りです。エラーを読み直してください。最初に新しい仮説を立ててください。 |
| 「同じエラーがまた出た。別の小さな変更を試してみよう」 | 同じエラー + 同じ戦略 = 同じ結果。戦略を変えてください。パッチを変えないでください。 |
レッドフラグ — 停止して再評価
- 「次のステップの後で検証しよう」 — 今すぐ検証してください。
- 「フロンティアAIの計画はリポジトリよりよく知っている」 — リポジトリが真実の情報源です。
- 「このライブラリはインストールされていないが、計画で必要とされている」 — ユーザーに確認してください。黙ってインストールしないでください。
- 「差分は予想より大きいが、おそらく問題ない」 — 続行する前に検査して説明してください。
- 「ステップ2と3は関連しているからまとめてやろう」 — 1ステップ = 1検証 + 差分サイクル。
- 「既存のlintエラーがあるから、先にそれを修正しよう」 — あなたの仕事ではありません。記録してください。集中を維持してください。
- 「編集中にこのファイルをフォーマットしよう」 — 別の変更 = 別のステップ。混在させないでください。
- 「まだ失敗している。もう一つクイックフィックスを試そう」 — パッチ適用をやめてください。エラーを読み直してください。最初に新しい仮説を立ててください。
- 「同じエラーが3回。もう一回調整すればうまくいくかも」 — 同じエラー + 同じ戦略 = 手探り。戦略を変えるか、ブロッカーを報告してください。
- 「全部書き換えて、それで直るか見てみよう」 — なぜ失敗したかを理解せずに作業を破棄しても何も学べません。最初に診断してください。
- 「ユーザーは急いでいるから、差分チェックはスキップしよう」 — 5秒の
git diff --statが何時間ものデバッグを防ぎます。
クイックリファレンス
| フェーズ | アクション | ツール |
|---|---|---|
| Preflight | git status、コマンド検出、ベースラインチェック | Bash |
| Parse + 現実性チェック | 計画を読み、各ステップをリポジトリに対して検証 | Read + Glob |
| Track | todowriteを作成... |