audit-choices

選択の監査

良い判断があれば、エージェントはそれを忠実に実装します。タスクの仕様が不十分な箇所では、エージェント自身が判断します。しかも、それは黙って行われるため、差分からは分かりません。変更された何千行ものコードをレビューするのは現実的ではなく、実行内容を調べても、おそらく問題はなかったでしょう。規模が大きくなっても可能な監査対象は選択です。実装者が独自に下した判断をすべて表面化させ、その一覧を評価し、判定を記録します。

これはバグよりもアーキテクチャに関するものです。実装が完璧に動作していても、ユーザーが決めていない選択に基づいていることがあります。データ構造、保存場所、依存関係、API コントラクト、メモリと速度のトレードオフなど、いずれも今後の作業を左右する重要な要素です。ユーザーがそれらを知る必要があるのは、選択が間違っているからではなく、ユーザー自身がその責任を負うことになったからです。

これは純粋な意思決定の監査です。コードの変更は行わず、いつでも呼び出せます。役割はさかのぼって追跡することです。このセッションで行われたすべての作業と、各サブエージェントが行ったすべての作業をたどり（実装中のエージェントは自身の作業を追跡し、それ以外の場合は報告、トランスクリプト、差分から再構成します）、元の仕様やプロンプトになかったにもかかわらず、ユーザーに代わって下された判断を一つ残らず明らかにします。これらの判断をまとめた台帳が、ユーザーにとってコードを読む代わりのレビュー対象になります。それがこの監査の目的です。判定に基づいて行動すること（問題のある選択をやり直す、暫定的な判断を適用するなど）は、呼び出し元が担当します。実行中の実装ワークフロー、またはレポートを読んだ後のユーザーです。

監査の入口は2通りありますが、監査内容は同じです。

• ワークフローから呼び出す場合（パス単位またはスライス単位）：そのパスを監査し、項目を台帳に追記してから返します。ワークフローは、結果を返す際に蓄積した台帳を提示します。
• ユーザーが直接呼び出す場合：目の前にある作業全体（セッション、ブランチ、または指定された変更）を監査し、すぐにレポートを提示します。推奨事項は示しますが、何も変更しません。

ワークフロー

1. 聞き出して、履歴をたどります。 実装者から完了の報告を受けたら、次のように尋ねます。「これに取り組む中で、自信がないまま決めたことは何ですか？ すべて挙げてください。」 — ただし、自己申告は出発点として扱い、調査範囲の限界とはしません。エージェントは申告しないことがあるためです。セッションの手順、サブエージェントの報告、差分、コミットを自分でたどり、元の仕様やプロンプトにはなかった、作業に含まれる判断をすべて集めます。疑わしい修正だけでなく、アーキテクチャ上の分類全体を確認します。データの形状と形式、保存方式と命名規則、API コントラクトとエラー時の動作、追加された依存関係、並行処理やパフォーマンス上のトレードオフ、スコープの解釈、後続のコードがお手本にするパターンなどです。自分のセッションを監査するときも、同じように自分の手順をたどります。計画で明示的に実装者へ委ねられた判断は、裁量であり、監査項目ではありません。

2. 根拠に基づき、判断ごとに振り分けます。 計画で必須だったのか、それとも独自に決めたのか。独自の判断は精査します。それは汎用的な解決策なのか、それとも目の前の失敗ケースだけに合わせた修正なのか。各判断に対して、妥当、不適切、またはユーザー判断が必要のいずれかを判定し、判定と併せて確信度も記します。確信度とは、ユーザーも同じ判断をしただろうと監査側がどの程度確信しているかです。報告での優先順位は確信度に基づいて決めます。「ユーザー判断が必要」とするのは、好み、製品の方向性、外部コストなど、本当にユーザーしか決められない場合に限ります。該当する項目には、監督なしでも待たずに進められるよう、取り消し可能な暫定案を必ず記録します。監査によって実行を止めることはありません。各項目は、実行やレビューのために引き継ぐ判断であり、処理を停止させる質問ではありません。

3. 修正パッチの案ではなく、正すべき判断を示します。 不適切な判断ごとに、その作業をやり直す際の起点となる判断、つまり一般に満たすべき性質を項目に記します。その判断の上にパッチを追加しても、判断自体はそのままです。台帳をレビューした後に、実際にやり直すかどうかは呼び出し元が決めます。

4. あらゆる判断を台帳（以下を参照）に記録し、 基盤となる妥当な判断は計画の引き継ぎ事項に含めます。後続の工程で再び判断するのではなく、前提として引き継げるようにします。

5. 判定ごとにまとめ、確信度順に並べて台帳を提示します。 監査の成果物は台帳です。次に作業する担当者へ引き継ぎます。実行中なら呼び出し元のワークフローに、実行終了時ならユーザーに渡します。判定グループごとに取るべき対応を示します。「ユーザー判断が必要」なら暫定案を踏まえて決める、「不適切」なら正すべき判断に基づいてやり直す、「妥当」ならユーザーが引き受けるアーキテクチャとして認識する、という対応です。各グループ内では、確信度の低いものから順に並べます。台帳が長い場合は、グループを問わず、全体で確信度が最も低い判断を2〜3件選び、「先に確認してください」という行で報告の冒頭に示します。妥当な判断も省略できません。些細な裁量（内部的な命名、見た目だけの判断）は、件数を示す1行にまとめられます。

   依頼されていなくても、各項目を必ずELI5で書きます。 読者はセッションを見ていません。各項目はeli5のスタイルで記述します。きっかけとなった出来事から最後まで、具体的な状況を順に説明してください（何がきっかけで、現在の作業では何をし、まだ実装されていない代替案ではどうなるか）。専門用語は初出時にすべて定義し、判断が制御フロー、順序、タイミングに関する場合は、そのレベルの擬似コードも示します。「条件に合う依頼は破棄され、保留にはならない」は見出しにすぎず、項目として不十分です。ユーザーに「これを説明してください」と尋ねさせるような簡潔すぎる項目は失敗です。差分、仕様、トランスクリプトがなくても単独で理解できる台帳にしてください。

選択事項の台帳

すべての作業パスを通じて残す専用ファイルです。プランの隣に置きます（仕様が作業を管理する場合は specs/<feature>/choices.md）。監査した選択事項ごとに1件記録します。

• 時期 — どのパスまたはコミットで決まったか。
• 選択内容 — 1行の見出しに続けて、ELI5形式のシナリオを記載します。きっかけとなった出来事、現在の実装が行うこと、未実装の代替案なら行うことを説明し、専門用語はその場で定義します。
• 不足事項 — それを決めざるを得なかった、プランで未指定だった内容。
• 影響範囲 — この決定によって制約または可能になる今後の作業、およびユーザーがその存在を知る必要がある理由。
• 評価 — 妥当／不適切／ユーザーへの確認が必要、のいずれかと、その理由を1行で記載します。不適切な場合は、やり直しの起点となる修正後の決定を記載します。ユーザーへの確認が必要な場合は、暫定的に推奨する判断と、それを覆す方法を記載します。
• 確信度 — 監査担当者が、ユーザーも同じ判断をしたはずだとどの程度確信しているか（低／中／高）。報告の優先順位を、低い順に示します。

台帳のルール：

• いったん記録された選択事項、またはプランに反映された選択事項は確定です。後続のパスでは前提として扱い、再記録も再判断もしません。
• 台帳はプランの品質を示す指標です。特定の作業範囲や領域に記録が集中している場合、その部分のプランが曖昧であることを意味します。同じ種類の選択事項を延々とトリアージするのではなく、作業を切り分け直すか、その部分を仕様策定に戻してください。
• ELI5形式は、どの書き換えでも維持します。 上記の記録形式、つまり見出しと、用語をその場で定義した具体的なシナリオは、見せ方を整えるためのものではなく、保存形式です。記録を統合するとき、まとめるとき、終了時に再監査するとき、最終台帳にコピーするときも、残す項目には完全なシナリオを残す（または復元する）必要があります。よくある失敗は、まさにこの圧縮です。終了時の書き換えで確定済みの項目を見出しだけに縮めると、読者が問いたださなければ内容を理解できない台帳になります。「チェックポイントはメールボックス順に行を読み込み、後の参照の createdAt がそれより前ならリストを拒否する」という記述だけでは決定事項として読めますが、具体的なシナリオ、つまり2つのセッション、それぞれのセッション内でのみ意味を持ち比較できない連番、そして共有の挿入タイムスタンプ用クロックを含めて初めて、読者はその選択を適切に評価できます。シナリオを削った統合は、すべての事実が残っていても失敗です。また、シナリオは残しても、「再試行エンベロープ」や「エビデンスの継ぎ目」など、ビルド時に作られたラベルを、使う場所で定義せずに頼っている場合も同様です。

ルール

• 「動く」は、その選択の妥当性を示す評価ではありません。 よくある危険な兆候は、偶然の修正です。バッファーのサイズ変更、タイムアウトの延長、あるいは失敗した入力をたまたまカバーする規模の特例によって、根本原因が潜在したままになるケースです。その修正が一般に有効であることを保証する性質は何かを問いかけてください。答えが「このケースは通る」であれば、コードが正常でも、その選択は不適切です。
• 成功を宣言した時点が最も危険です。実装者の自信が最も高まるのは、未検証の選択事項がまさにマージされようとしているときです。結果がきれいに見えるからといって、監査を省略してはいけません。
• 重要な作業でリストが空なら、合格ではなく危険信号です。作業で何が未指定だったかを調べてください。その不足を何かが補っています。
• 監査では、コード、テスト、ビルド状態を変更しません。不適切な選択を見つけることが成果であり、それを修正する許可ではありません。修正後の判断を記録し、監査時点のツリーをそのまま残してください。これにより、台帳とツリーの両方で、呼び出し元が何を判断しているかが一致します。証拠の収集は自由です。何でも読み、既存のテストを実行し、一時的な調査用コードを書くこともできます。ただし、引き渡す前に、調査用コードはすべて削除してください。

完了

この監査は、パスで行ったすべての創作的な判断に判定付きの台帳エントリーがあり、妥当でないエントリーにはやり直しの起点となる修正後の判断が記され、ユーザーの確認が必要なエントリーには取り消し可能な暫定判断が記され、台帳が次に作業する人へ提示され（判定別にまとめ、各グループ内では確信度の低いものから並べ、すべてのエントリーが追加の質問なしに ELI5 で理解できる形で）、ツリーに手を加えていない状態になったときに完了します。判断の代わりに差分を示す引き継ぎや、監査中に適用した「修正」は、完了とはみなしません。