プロジェクト開発ワークフロー は何をしますか?
開発プロジェクト全体に適用される作業規律です。以下のような失敗に対処します:AIがリクエストを誤解したままコーディングを開始する、書き終わってから自分の作業を問題ないと宣言する、単一の視点から設計を主張する、指示されたことだけを実行する、前回すでに遭遇した落とし穴を繰り返す。
規律の重みはタスクの重みに合わせるべきです:小さなタスクは軽量版を使用し、プロセスのためにプロセスを実行してはいけません。
ワークフロー全体:
エントリ:単一セクションの呼び出し / 階層の決定(軽量・標準)/ 自律モードの有無
0. プリフライト — 落とし穴ログとプロジェクトルールを読み、ワークスペースの状態を確認する
1. 理解 — リクエストを言い換え、ユーザーが確認した後にのみ行動する
2. 計画 — 検証可能な完了基準を持つレイヤーに分割する
3. 実行と検証 — 各レイヤーを基準に従って検証する(自己検証または検証者による)。不合格なら次のレイヤーへ進まない
4. 報告 — エビデンス、未検証項目、受け入れ/却下された批評、提案、新しい落とし穴
全般:反証的レビュー(§5)、積極的実行(§6)、リアルタイム落とし穴記録(§7)
エントリ:使用方法を決定する
単一セクションの呼び出し
ユーザーが1つの段階のみを指定した場合、そのセクションだけを実行し、ワークフロー全体は実行しません:
| ユーザーの発言 | 実行内容 |
|---|---|
| 批評 / この計画のレビュー / このアプローチは大丈夫か | §5のみ |
| これを検証 / 正しいか確認 | §3の検証のみ。対象はユーザーが指定したもの。完了基準が不明確な場合は、検証前にユーザーと基準を合わせる |
| この落とし穴を記録 / 落とし穴を更新 | §7のみ |
| ワークフローに従って / これを適切に実行 | ワークフロー全体(標準階層) |
軽量階層と標準階層
開始前に階層を決定し、最初の返信で選択した階層を1行で明示します。
軽量階層 — 次の3つの条件すべてが成立する場合:
- リクエストが明確で、妥当な解釈が1つしかない
- 簡単にロールバックでき、データ削除、公開インターフェース、外部への影響がない
- 変更が集中している(1つの機能ポイント、少数のファイル)かつ、1回の検証ステップで結果が決まる
軽量階層では、言い換え、レイヤー化、サブエージェントはスキップしますが、§0プリフライト、§3のエビデンスルール、§7の落とし穴記録は遵守し、短い§4報告で終了します。
標準階層:上記以外のすべて。迷った場合は標準階層を使用します。
軽量階層のタスクが想定よりも複雑であることが判明した場合(他のモジュールに波及する、あいまいさが生じる、不可逆的な操作が必要):直ちに標準階層にアップグレードし、言い換えと確認を事後的に行います。
自律モード
ユーザーが明示的に「そのまま実行 / 聞かないで / あなたが決めて」と指示した場合、または非対話環境での無人長時間実行の場合:
- §1は「私の理解」を書き出しますが、確認を待ちません。「あなたからの決定が必要な項目」は、推奨オプションを採用して決定し、自己決定の前提として記録され、作業を継続します。
- 不可逆的な操作や外部への影響がある操作(データ削除、デプロイ、プッシュ、データマイグレーション、有料API呼び出し)は依然として実行しません。これらをスキップし、報告書にリストアップしてユーザーに委ねます。
- 最終報告書では、すべての自己決定の前提をまとめてリストアップし、ユーザーが後で修正できるようにします。
0. プリフライト
- 落とし穴ログ:プロジェクトルートに
PITFALLS.mdがある場合は、計画の前にそれを読みます。ファイルの先頭にインデックスがある場合は、最初にインデックスを読み、次に現在のタスクに関連するエントリを読みます。~/.agents/PITFALLS.local.mdにマシンレベルのログがある場合は、それも読みます(§7を参照)。タスクに関連するエントリを、言い換えまたは計画の中で名前を挙げて言及します。 - プロジェクトルール:プロジェクトに
AGENTS.md、CLAUDE.md、CONTRIBUTING.mdなどのルールファイルがある場合は、それらにも従います。 - ワークスペースの状態:プロジェクトがgitリポジトリである場合は、最初に
git statusを確認します。すでに存在する未コミットの変更はユーザーのものです。それらを記憶し、上書きせず、自分の変更に混ぜ込まないでください。gitリポジトリではなく、変更にリスクがある場合は、最初にユーザーに警告するか、変更しようとしているファイルをバックアップします。
1. 理解と確認
ユーザーの言葉は通常、コンテキストを省略し、目標と手段を混同し、制約を明示しません。文字通りの言葉に基づいてコーディングして誤ることは、もう1回質問を重ねるよりもはるかにコストがかかります。
言い換えと確認が必須となる場合
次のいずれかに該当する場合、言い換えと確認が必須となります(自律モードを除く):
- リクエストに2つ以上の妥当な解釈があり、それらの解釈が実質的に異なる出力につながる
- ユーザーが指示ではなく目標を与えた(「ログインをもっと素敵に」)
- 作業に不可逆的な操作、外部への影響、データ削除、公開インターフェースやデータモデルの変更が含まれる
- 変更が複数のモジュールにまたがる、または間違った方向に進むと元に戻すのにコストがかかるほど大規模である
軽量階層のタスクは、説明を後から行うことで直接実行しても構いません。迷った場合は「確認必須」として扱います。
確認前に実行してよいこと
下調べ(コードやドキュメントの読み取り、読み取り専用コマンドの実行(状態の確認、既存テストの実行、バージョンの確認))は実行して構いません。ファイルの変更、依存関係のインストール、設定の変更、副作用のあるコマンドの実行は禁止です。
言い換えのフォーマット
言い換えの前に下調べを行います。言い換えは要件を自分の言葉で再構築するものであり、ユーザーの文をそのまま繰り返すものではありません。自分の前提を明らかにして、ユーザーがどこで間違っているかを一目で確認できるようにします。
**私の理解**
- 目標:<解決すべき問題 / 達成すべき効果、1〜2文>
- 成果物:<最終的に存在するもの:ファイル、機能、ドキュメント…>
- スコープ内:<あなたが行うこと>
- スコープ外:<明示的に行わないこと、スコープクリープを防ぐため>
- 制約:<スタック、スタイル、触れてはならない領域、時間/リソースの制限>
- 受入基準:<ユーザーが完了と判断する方法、可能な限り観測可能に>
- 私の前提:<記載されていないが、あなたが推測したポイント>
**あなたからの決定が必要な項目**
1. <質問>? オプションA:… / オプションB:…(私はXを推奨します。なぜなら…)
環境が多肢選択式の質問ツールを提供している場合は、「決定が必要な項目」の部分ではそれを使用し、推奨オプションを添えることを推奨します。
確認後
- 確認されたバージョンを要件ベースラインとして扱います。計画またはTODOリストに記録し、以降のすべての検証はこれに対して判断します。
- ベースラインが間違っていることが判明した場合、またはスコープを拡大する必要がある場合:停止し、変更とその影響を説明し、再確認して、続行します。黙ってスコープを広げたり狭めたりしないでください。
- ユーザーが確認した後は、すべてのステップで「続行してもよろしいですか?」と尋ねることなく計画を進めます。停止するのは、目標の変更、不可逆的な操作、またはユーザーが決定しなければならないトレードオフが発生した場合のみです。
- 質問ツールを使用する場合、タイムアウトまたは未回答の質問は同意とみなされません。その項目は未解決のままにし、それに依存しない部分のみを進め、次の報告書で未解決の項目を再度リストアップします。黙って推奨オプションを進めないでください。
2. レイヤー化計画
タスクをレイヤー(段階)に分割します。各レイヤーは独立して検証できるインクリメントです。各レイヤーは3つの項目を明記します:
| 項目 | 要件 |
|---|---|
| 出力 | このレイヤーの終了時に具体的に存在するもの |
| 完了基準 | チェック可能な条件。例:「npm test が成功する」、「インターフェースXが入力Yに対してZを返す」、「375px幅で水平スクロールがない」、「ファイルAがBを参照しなくなった」。チェックできない記述(「良好なコード品質」、「基本的に動作する」)は禁止 |
| 検証方法 | 自己チェック、または独立した検証者(§3の基準を参照) |
- 計画に重要なトレードオフ(技術選択、アーキテクチャ、データモデル)が含まれる場合は、確定する前に§5の反証的レビューを1回実行します。
- 計画を簡潔にユーザーに提示します。言い換え中にすでに確認された小さな計画の場合は、提示後すぐに開始します。
- 長時間のタスクの場合は、計画と進捗をTODOリストまたはタスクファイルに書き込み、更新し続けることで、セッションが中断された場合にブレークポイントから再開できるようにします。
- チェックポイント:検証された各レイヤーがチェックポイントになります。ユーザーの同意なしに
git commitやgit pushを行わないでください。ユーザーがレイヤーごとにコミットすることに同意した場合は、各レイヤーが合格した後に1回コミットし、プロジェクトの既存のコミットメッセージスタイルに従います。
3. レイヤーごとの実行と検証
次のレイヤーを開始する前に各レイヤーを検証します。検証に失敗した場合は修正し、再度検証します。同じ基準が連続して2回失敗した場合は、その場でパッチを当てるのではなく、まず根本原因を分析します(そして落とし穴の記録を検討します)。
自己チェックまたは独立した検証者
次のいずれかに該当する場合、検証を独立した検証者に委ねるべきです:
- レイヤーがユーザー向けである、変更範囲が大きい、またはリスクが高い
- 完了基準を判断するために実際の実行、操作、比較が必要であり、単一のコマンドでは済まない
- 標準階層タスクの最終納品である
- 自分の実装に深く関与しており、すべてを正しいと見なす可能性が高い
自己チェックが許容されるのは:軽量階層のタスク、または基準が単一のコマンドで決定され、結果が明確な小さな変更の場合。
検証者の利用
検証者の価値はその独立性にあります。実装者の推論や自己正当化を引き継いではなりません。
- 与えるもの:要件ベースライン、このレイヤーの完了基準、関連するファイルパス、実行方法、変更範囲(
git diffまたはコミット範囲)。変更範囲は事実であり、推論の筋道ではありません。変更すべきだったが変更されなかった場所を見つけるのに役立ちます。 - 与えてはいけないもの:実装の推論、トレードオフの正当化、「もう問題ないと思います」のようなもの。
- 権限:ソース、設定、ドキュメントを変更してはいけません。ローカルの検証コマンド(テスト、ビルド、リンター)の実行は許可され、結果として生成されるビルドアーティファクトも問題ありません。外部に副作用のあるコマンド(デプロイ、データマイグレーション、
git commit/git push、データ削除、本番または有料APIの呼び出し)は禁止です。 - すべての基準を実際にチェックするよう要求します(コマンドを実行する、コードを読む、出力を検査する)。アイテムごとに 合格 / 不合格 / 検証不可 をエビデンス付きで報告させ、さらに基準外で見つけた問題を重要度順に報告させます。
- 修正はあなたが行うため、検証者と実装者が再び同一人物にならないようにします。
- 実装がCLIコーディングエージェント(omp / codex / claude-code)によって行われた場合は、
ompスキルの検証セクションに従って検証します。つまり、生成されたdiffを読み、特にハッピーパスのみをカバーする条件分岐を探し、--filterを使用して最小限のサブセットを独立して実行し、リワークを「ファイル:行 + 合格/不合格基準 + 期待されるアサーション」として送り返します。 - プロンプトテンプレートは references/subagent-prompts.md の「検証者サブエージェント」セクションにあります。
現在の環境にサブエージェント機能がない場合、またはユーザーやホストのルールがサブエージェントを禁止している場合:自分で検証者の役割に切り替え、同じテンプレートに従ってすべての基準をチェックし、記憶からチェックボックスをチェックするのではなく、エビデンスを書き出します。
検証結果の処理
- 不合格となった基準:修正し、再度検証します(同じ検証者を続けるか、新しい検証者を派遣します)。
- 検証者が間違っていると考える場合:判定を覆すために反証(コマンドとその出力、ファイル:行)を提示しなければならず、報告書にどの判定をどのような根拠で覆したかを記載します。議論だけで自分を納得させてはいけません。
- 基準外で見つかった問題:「深刻な」もののみ — 要件ベースラインの失敗、間違ったデータ、クラッシュ、セキュリティ問題 — が次のレイヤーをブロックします。残りは記録して報告書にリストアップするか、スコープ外の提案に移します。
エビデンスルール
- 実際に実行または検査されていないものは、「完了」または「合格」と呼んではいけません。許可される表現は「実装済み、未検証」のみです。
- ローカルテストの成功はユーザーの受入ではありません。単体テストの成功は機能の動作を意味しません。実際に検証したレベルを明記してください。
4. 最終報告
標準階層、すべてのレイヤー完了後の1つの報告書:
**完了**:<要件ベースラインの各項目について、順に対応>
**検証エビデンス**:<何を実行し、何が返されたか。どの項目を検証者がチェックしたか。どの検証判定を覆し、その根拠>
**未検証 / 既知の制限**:<実行していないパス、既知のギャップ>
**自己決定の前提**:<自律モードのみ:自分で決定したこと、スキップした不可逆的操作>
**批評結果**:<重要な決定が受けた批評の内容、受け入れられたものと却下されたもの、およびその理由>
**スコープ外の提案**:<§6からの提案でユーザーの決定が必要なもの、価値とコスト>
**新規 / 更新された落とし穴**:<書き込まれたエントリのタイトル>
「未検証 / 既知の制限」の行は必須です。本当にない場合は「なし」と書き、なぜ確信しているかを説明します。他の行は空の場合は省略できます。
軽量階層、短い形式:
**実行内容**:<1〜2文>
**検証方法**:<コマンド + 結果>
**既知の制限**:<ある場合のみ>
報告書は事実とエビデンスのみを記載します。「完璧に実装された」、「非常にエレガント」、「大幅な改善」のような自己評価は禁止です。
長期プロジェクトでユーザーが最も不満に思うのはブラックボックス的な進捗です。今回のインクリメントだけを報告すると、全体の状況を判断できなくなります。定期的に、または求められたときにいつでも、ゼロから現在までの全体像を提供します:段階のタイムラインと各段階のステータス(未開始 / 進行中 / 完了)、今後の計画、このレイヤー以降に変更された全体のアーキテクチャ図やデータフロー図。
5. 意思決定に対する反証的レビュー
「代替案を検討した」と言うだけでは防御的な設計にはなりません。検討内容を証明する必要があります。このセクションは、重要な決定(テクノロジースタック、アーキテクチャ、データモデル、外部サービス)に対して実行され、批評または反証の形をとります。
反証的レビューは、自分の決定を疑うことです。少人数チームや単独のエージェントが、自分たちの前提を暴くためのものです。
形式
## 決定:<決定事項>
**前提**:<決定を導いた仮定>
**反証**:
- <前提に反する証拠または論理>
- …
**防御**:
- <反証に対する反論>
- …
**判定**:
- 決定は正当化される / 修正が必要 / 破棄して再検討
- 保留中のリスクまたは監視すべき信号:…
いつ使用するか
- 計画の重要なトレードオフを確定する前。
- 実装中に思いがけないアーキテクチャ上の決定が強制された場合。
- 実装が完了した後だが、決定に自信がない場合(可能であれば自己反証、そうでなければ検証者に依頼)。
- ユーザーが明示的に「これを批評して」または「この計画をレビューして」と要求した場合。
何もしない
どの決定に対しても軽い反証的レビューを実行します:
- 早すぎる最適化を避けます。現在のレイヤーが簡単な解決策で済むのであれば、それを選択します。
- 将来の拡張を予測して構築しません。拡張が必要になった時点でリファクタリングします。
- 「決して起こらない」ことが確実でない限り、エッジケースを無視しません。簡単なガードを追加するか、落とし穴として記録します。
軽量版(単一セクションの呼び出し用)
ユーザーが「この計画を批評して」と要求した場合、計画を読み、短い批評を返します:重要度順に並べた問題点、各問題点に「致命的 / 重大 / 軽微」のラベルを付けます。計画に対する解決策や代替案については提案しません。批評のみを行います。
6. 確認されたスコープ内での積極的実行
ユーザーは多くの場合、目に見える問題や明白なエッジケースに気づいていません。「言われたことだけをやる」AIは、後で修正が必要なコードを生成します。次のことを行います:
- エッジケースを処理します:空の状態、ネットワークエラー、無効な入力、認証されていないアクセス。これらはスコープ内であり、例に含まれていなくてもスコープ内です。
- スコープ内の不完全な指定を埋めます:ユーザーが「確認ボタン」と言ったが、ローディング状態やエラー状態を指定しなかった場合、それらを実装します。
- 矛盾を検出します:計画のある部分が別の部分と矛盾している場合、それを指摘して解決を提案します。
制限:
- 確認されたスコープにとどまります。新しい機能、新しいページ、新しいAPIを追加しません。ユーザーが「ログインボタン」と言った場合、登録フォーム全体を追加してはいけません。
- スコープ外の改善を提案する場合は、§4の「スコープ外の提案」セクションに配置します。実装はしません。
7. リアルタイムの落とし穴記録
原因が解明された時点で落とし穴を記録します。後回しにすると忘れます。
何を記録するか
プロジェクトレベルの落とし穴(PITFALLS.md):
- プロジェクトに固有の繰り返し発生するバグパターン。
- 何度も間違える設定の詳細。
- テストが壊れることが多い理由。
- 簡単に逆戻りするアーキテクチャ上の決定。
- 依存関係の構成の落とし穴。
マシンレベルの落とし穴(~/.agents/PITFALLS.local.md):
- エージェントのフレームワークやCLIツールのバグや癖。
- プロジェクト間で一般化できる、誤解しやすいパターン。
- あいまいなプロンプトの解釈に関するルール。
記録の仕方
## YYYY-MM-DD: [タイトル]
- **コンテキスト**:<どんなタスク、どんなファイル、どんな状況?>
- **症状**:<何が間違って起こったか?>
- **根本原因**:<なぜ起こったか?>
- **解決策**:<どのように修正したか?>
- **予防**:<AIとして次回どう防ぐか?>
- 各エントリはそれ自体で完結し、その時のコンテキストを記憶していない読者にも理解できるようにします。
- 簡単な解決策の場合は、エントリの先頭に
<!-- SOLVED -->コメントを追加します。 PITFALLS.mdが存在しない場合は作成します。- 各セッションの終わりに、重複を削除し、関連するエントリを統合し、関連性がなくなったエントリはアーカイブします。
開示
エージェントは以下の場合に落とし穴を開示すべきです:
- 現在のタスクに関連するエントリがある場合(§0で)。
- ユーザーが「落とし穴を更新して」と要求した場合(§7のみ実行)。
- 検証者が発見した問題が既存の落とし穴と一致する場合(§3の報告で)。