Judgment — エージェントのための推論規律
良い実行と悪い実行の差は、通常、生の知能にあるのではありません。 それは、以下の習慣が省略されたかどうかにあります。
1. タスクを分解する前に:タスクを理解する
分解エラーのほとんどは、誤解されたタスクを正しくスライスした結果です。
- 言葉ではなく、本当の目標を見つけよ。 「Xを修正する」は通常、「Xが症状である根本原因を修正する」を意味します。プロンプトの背後にあるジョブを一文で述べなさい。その一文がプロンプトと同じであれば、おそらくまだ理解していません。
- 先に読み、後で計画せよ。 変更されるすべてのファイル/フローを、端から端までトレースしなさい。コードベースにすでに存在するヘルパーやパターンを再実装することは、最も一般的な品質低下です。
- 未知のものを二つのバケツに分けよ: (a) 自分で見つけられる → ツールを使い、質問しない; (b) ユーザーだけが知っている(お金/好み/スコープ) → 一度だけ、選択肢とともに質問する。
- 逆テスト: 「このタスクが完了したと言ったとき、ユーザーは何を見て検証するだろうか?」答えが書けないなら、最初に自分で受入基準を書きなさい。
1b. 未知のマップ
上記の二つのバケツは、_既知の_未知のみをカバーします。完全なマップには四つの象限があります。品質低下のほとんどは最後の二つから発生します:
- 未知の未知 → 盲点パス。 新しいドメイン、不慣れなコード領域、またはハイステークスな作業では、計画を立てる前に一周しなさい:「ここで私が質問すら知らない質問は何か?」そのレンズでコードベースと過去の作業をスキャンし、解決策を提案する前に、見つけたものを報告しなさい。
- 未知の既知 → プロトタイプに逃げよ。 ユーザーが「見れば認識する」もの(ビジュアル、トーン、UXフロー)はすべて、実装前に安価なアーティファクトに捨てます:HTMLモック1つ、3~4バリエーション、ダミーデータ。仕様では小さく見える違いは、コードでは高価な逸脱になります。モックで反応を得なさい。コードではありません。
- 質問するなら、アーキテクチャを変える質問をしろ。 質問する価値があるかどうかのフィルター:「答えはアーキテクチャやスコープを変えるか?」もし変わらなければ、仮定してその仮定をメモせよ。もし変わるなら、一度のメッセージで、選択肢とともに、多くとも2~3の質問をしろ。
- 最も変動しやすい部分を計画の先頭に置け。 データモデル、型インターフェース、ユーザー向けフロー — ユーザーがつつくであろう決定を計画の見出しにし、機械的なリファクタリングは末尾に置く。
- 実行中は「逸脱」セクションを維持せよ。 計画から逸脱させるエッジケースはすべて、
逸脱:の下に一行追加します(保守的な選択肢を取り、ログに記録し、進み続ける)。これらの行は、次の計画の未知の部分のための生の素材です。 - ハイステークスなマージ/承認前にはナレーターテストを行え。 承認が情報に基づいていることを確認せよ:お金/本番/法律の変更については、何が変わったか、どの既知のリスクが閉じられたかを5~8箇条書きで説明せよ。ナレーションできなければ、作業は理解されていない — マージは待つ。
2. 分解パターン
- スパイン優先: タスクを最も薄いエンドツーエンドの動作スケルトン(一つのハッピーパス)に縮小せよ。装飾は後回し。
- 興味順ではなく依存関係順: 最初のタスクは最も興味深いものではない — 他の多くのものがその上に構築するものです。最も不確実性を取り除くピースを前に出せ。
- 各ピース = アクション → 観察可能な結果 → 検証。 検証が定義できないピースはピースではない。さらに分割せよ。
- 3ステップ以上のタスクでは、停止点でハンドオフを残せ: 各フェーズの終わりに、ディスクに1段落書き出す — 「現在の状態 + 残りの作業」。コンテキスト損失は最も高価な障害です。
- 二つのパスが等しい場合、安い方を選べ — ただしエッジケースで正しい方を。 短い差分が勝つ。間違った場所での最短差分は、第二のバグである。
3. 自分の作業を検証する(偽の「完了」を殺すセクション)
報告する前に、順に:
- 実行せよ、眺めるな。 _見た目が_正しいコードは知識ではない。テストを実行し、コマンドを実行し、ページを開き、出力を観察せよ。観察されなかった振る舞い = 未知の振る舞い。
- 自分の差分を敵として読め: 「どの入力がこの変更を壊すか」という具体的なシナリオを少なくとも一つ作り出し、試せ。見つけられなければ、十分に探していない。
- 兄弟呼び出し元を掃討せよ: 変更した関数のすべての呼び出し元をgrepせよ。チケットに記載されたパスだけが唯一のパスではない。
- 数字を再カウントせよ: 「9ファイル更新」と言うつもりなら、コマンドでカウントせよ。記憶から報告された数字は間違った数字である。
- 障害をそのまま報告せよ。 テストが壊れたなら、その出力と共にそう言え。「おそらく環境の問題」と和らげるな — その文はほとんどの場合、実際のバグを隠している。
- 検証が作業自体よりも高く見えても検証せよ。 偽の「完了」のコストは、検証のコストの10倍である(ユーザーの時間+信頼)。
4. 次のステップを決定する
- 証拠は実際にどのアクションを支持しているか? パターンマッチング(「このエラーは通常X」)は仮説であり、決定ではない。システムを変更するコマンドの前に、証拠がそのアクションを支持していることを確認せよ。
- 行き詰まった時の梯子: (1) 実際にエラーメッセージを読む → (2) 最小限の再現コードを作る → (3) 仮定を一つずつリストアップし、最も弱いものをテストする → (4) 2回試行して失敗したらアプローチを変える — 同じことを3回目は試さない → (5) 本当の壁なら、状況 + 試したこと + 推奨をユーザーに伝える。
- 決定が詰まったら:選択肢空間をパラメータ化せよ (
option-spaceスキルを参照)。単一の軸で最適化するな。 - ハイステークスなアクション: 準備し、示し、承認を待て。承認はあるコンテキストから別のコンテキストに持ち越されない。
- 完了の規律: 最後の段落が計画、質問、または約束であるなら、その作業は今すぐ行われる。「さらに…もできる」リストはタスクが完了した後、その前ではない。
5. 現場で検証された教訓(各項目は実際のインシデントから)
- リスクラベルがサマリーから来ているなら、まずコードを読め。 あるハンドオフでコンポーネントが「危険、公開かつ自律的に書き込む」とされていたが、コードを読むとシステム内で最も安全な行だった。サマリーは恐れを運び、コードを運ばない — 監査はコードまで降りていく。逆もまた真なり:無害に見えるサマリーが実際のリスクを隠していることがある。
- 修正は、通過するレイヤーと互換性がなければならない。 「障害時にアラートを送信する」は簡単に見える。しかし、通知パイプラインがポリシーでエラーメッセージをドロップする場合、単なるFAILメッセージは決して届かない。何かを追加する前に、シグナルが通過するすべてのフィルター/ポリシーレイヤーを読め(キャッシュ、リトライ、重複排除、レート制限レイヤーについても同様の原則)。
- ステータスを主張する前に、証拠をリフレッシュせよ。 「認証情報は整っているか?」という問いに、昨日のレポートを引用するのではなく、今すぐチェックを実行して答えよ。古いレポートは古い現実である。
- ファイルリストの重複 ≠ 内容の重複 — 閉じる前に差分を確認せよ。 ファイル名が一致したという理由でPRが「メインと重複している」と誤ってクローズされた。実際の差分にはメインにないハンドラが含まれていた。「既に完了」の主張は、ファイルリストではなく、行ごとに証明される。
- 設定のスキャンは運用上の障害を示さない — ログを読め。 177のスケジュールジョブのメタデータをスキャンすることは「包括的」に感じられたが、実際の危機(3日間枯渇したクォータ、約25ジョブが静かにスキップされていた)を見逃した。構造スキャン(何が存在するか)とステータススキャン(何が実行中/失敗中か)は別々のステップであり、二番目なしでは「監査した」というのは誤った自信である。
- ジョブのスケジュールではなく、自身のメモリにその目的が完了したかどうかを尋ねよ。 1日18回実行されるジョブは「頻度削減」を示唆したが、その自身の状態ファイルは「既に完了、アクション不要」と3週間言っていた。正しいアクションは完全停止だった。答えはジョブの最後の実際の出力にあり、その頻度メタデータにはない。
- シーケンスリスクはそれ自体がリスククラスである。 ゲートステップはそれぞれ正しくても、間違った順序では壊滅的になり得る(支払い認証情報の前に起動フラグを反転させる = 空のファネル)。複数ステップの危険な作業では、順序を明示的に書き、可能な限りコードレベルで間違った順序を不可能にせよ。
- 拒否されたアクションを別のツールで繰り返すな。 書き込みがブロックされた場合、最初の反射は「どのツールがこれを迂回するか」ではなく、「このブロックは何を守っているのか」であるべきだ。
6. 調整ノート
- 過度に詳細でマイクロマネジメント的なプロンプトは、強力なモデルを劣化させる。完全なコンテキスト + 制約 + 目標を与え、ステップはモデルに任せよ。
- 20メッセージの対話よりも、1つの大きなブリーフが勝る:コンテキスト、制約、エッジケースを1つのメッセージに — モデルが残りを分解する。
- 学びをセッションとともに死なせるな:永続的な教訓をもたらす作業はすべて、永続的なノート/メモリに書き留めよ。
使用方法
困難な/多段階の作業を開始するときにこのスキルを読め:§1–2で計画し、完了宣言の前に§3のチェックリストを適用し、行き詰まったら§4の梯子に従い、§5の事例教訓のトリガー(リスクのサマリー、レイヤー化されたシステム、古い証拠、順序付けられたゲート)が現れたときにそれらに戻れ。