ハーネスエンジニアリングのプラクティス P17. ドライラン既定とブラスト半径プレビュー 🎯 ポイント 「40ポッドを再起動します」は事後に発見するのではなく、事前に提示するものです。副作用は実行前にプレビューしましょう。 📝 概要 副作用を伴う行為は、まず効果のプレビュー（どのファイル・どの行・どのポッド）を出し、ゲートまたは人間確認を経てから実行します。既定はドライラン（実行しないで結果を表示）とし、明示的な承認があってから実行します。 🔍 解説 エージェントが「何をするか」を事前に知ることは、安全性の基本です。コードの差分プレビュー、影響を受けるサービスのリスト、再起動されるポッドの数、送信されるメッセージの内容。これらを実行前に提示することで、人間は情報に基づいた判断ができます。特にインシデント対応では、是正案のブラスト半径（影響範囲）とロールバック計画をセットで提示し、承認後に実行・監視するパターンが有効です。ドライランを既定にすることで、「うっかり実行」のリスクを構造的に排除します。 🛠 実践方法 ・副作用を伴う全操作に「プレビューモード」を実装し、実行前に影響範囲を表示します ・ドライランの出力に「影響ファイル数」「影響ポッド数」「変更行数」等の定量情報を含めます ・不可逆な操作にはドライランを必須にし、可逆な操作ではオプションにして効率を保ちます ・ドライラン結果と実行結果の乖離を記録し、ドライランの精度を継続的に改善します 💼 ユースケース ・インシデント対応で、是正アクションのブラスト半径とロールバック計画を事前提示する場面 ・ペアプログラミングで、エージェントの編集を適用前に差分プレビューとして表示する場面 ・マイグレーションで、各ユニットの変更内容をカナリアとして一部先行適用し、問題がないか確認する場面 ⚠ 落とし穴 ドライランが常に正確とは限りません。ドライランでは問題なくても、実行時に環境の違いで失敗することがあります。また、ドライランが形骸化して「常にスキップ」になると意味がなくなります。P15（取り消し可能性）と組み合わせて、可逆な操作はドライランなしで即実行、不可逆な操作のみドライランを必須とする設計が効率的です。 #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのプラクティス P16. 信頼の獲得制（capability ramping） 🎯 ポイント 新入社員にいきなり本番デプロイ権限を渡す会社はありません。エージェントにも「信頼を実績で獲得させる」仕組みが必要です。 📝 概要 新しいハーネスは厳しいゲートから始め、あるタスク種別で実績（高成功率・ゼロのリグレッション）を積めば、その種別に限って自律性を自動拡張します。信頼はタスク種別ごとに測定に基づいて獲得され、いつでも剥奪可能です。 🔍 解説 最初から全てのタスクに高い自律性を与えるのは危険ですが、永遠に厳しいゲートを維持するのも非効率です。解決策は段階的な信頼の獲得です。たとえば、lint修正タスクで10件連続成功・リグレッションゼロなら、lint修正に限って自動マージを許可する。しかしセキュリティパッチの自動マージは別のトラックで実績を積むまで許可しない。重要なのは、信頼がタスク種別ごとに独立していることと、測定に基づいていること、そしていつでも引き下げ可能であることです。リグレッションが発生したら、その種別の信頼レベルを即座に引き下げます。 🛠 実践方法 ・タスク種別ごとに信頼レベル（例：L0=全て承認必須、L1=軽い自律、L2=自動マージ可）を定義します ・昇格条件を数値で定義します（例：直近20件で成功率95%以上かつリグレッションゼロ） ・降格条件も定義します（リグレッション発生時は即座にL0に引き下げ） ・信頼レベルの変化と根拠をログに記録し、意思決定の透明性を確保します 💼 ユースケース ・CI自動メンテナンスで、低リスク種別（lintパッチ）のみ自動マージを段階的に許可する場面 ・issue-to-PRエージェントで、バグ修正の成功実績に応じて人間レビューの粒度を調整する場面 ・レガシーコード改修で、特性評価テスト作成は自律、コード変更はカナリアデプロイ付きで慎重に進める場面 ⚠ 落とし穴 信頼の獲得基準が不明確だと、いつまでも厳しいゲートのままか、いつの間にか緩みきるかのどちらかになります。基準を数値で定義し（成功率X%以上・直近N件でリグレッションゼロ）、自動的に判定する仕組みが必要です。また、「成功率が高い」と「安全である」は同義ではありません。簡単なタスクばかりで成功率を稼いでいないか、タスクの難易度も考慮すべきです。 #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのプラクティス P14. 独立した自己批評パス（生成器と批評器の文脈を分ける） 🎯 ポイント 自分が書いたコードを自分でレビューして「良さそう」と言うエージェント、信頼できますか？レビューは作者と切り離して初めて機能します。 📝 概要 実装後、別の文脈（できれば別の役割プロンプト）で差分を仕様に照らして批評させます。「自分が今書いたから正しいはず」というバイアスを避けるには、生成器と批評器が文脈を共有しないことが鍵です。 🔍 解説 人間のコードレビューが作者以外の人間によって行われるのと同じ理由で、エージェントの自己批評も文脈を分離する必要があります。同じ文脈で生成と批評を行うと、生成過程で持った「なぜこう書いたか」のバイアスがそのまま批評に持ち込まれ、問題を見逃しやすくなります。別の文脈（理想的には別のプロンプト、別のモデルインスタンス）で、変更差分と仕様だけを見せて批評させると、フレッシュな視点でのレビューが可能になります。これは計算コストが追加されますが、流出欠陥を防ぐ効果は大きいです。 🛠 実践方法 ・実装完了後に別の文脈（新しい会話セッション）を起動し、差分と仕様だけを渡してレビューさせます ・批評器には焦点を絞った役割を与えます（「仕様との乖離」「セキュリティリスク」「リグレッション可能性」等） ・可能であれば生成と批評に異なるモデルやプロンプトを使用し、視点の多様性を確保します ・批評結果を構造化フォーマットで出力させ、ハーネスが自動的に対応（修正指示の送付・人間への報告）を判断します 💼 ユースケース ・issue-to-PRエージェントが完了前に、別のプロンプトで自己レビューを行う場面 ・自律バグ修正で、修正の妥当性を別の文脈で検証する場面 ・コード生成で、セキュリティ観点のレビューを別のエージェントとして実行する場面 ⚠ 落とし穴 批評器が「何でも指摘する」設計だと、瑣末な指摘が大量に出て実装→修正→批評→修正の無限ループに陥ります。批評器には「仕様との乖離」「セキュリティリスク」「リグレッション可能性」など、焦点を絞った役割を与えることが重要です。また、批評器の品質が低いと、正しい実装を不必要に修正させるリスクもあります。 #HarnessEngineering# #CodeReview#

ハーネスエンジニアリングのプラクティス P12. 意味的サーキットブレーカーと「文脈ごと捨てる」リスタート 🎯 ポイント 同じエラーを3回繰り返すエージェント、見たことがありますか？「押し通す」より「教訓つき仕切り直し」の方が圧倒的に速いです。 📝 概要 単なる最大反復数ではなく、「同じエラーが二度」「二つの編集を振動」「正味の進捗なし」を意味的に検出して停止します。行き詰まったら、汚染された文脈でこね続けず、最後の正常チェックポイントへロールバックし、失敗の経緯を文脈から捨て、一行の教訓だけ携えて別アプローチで再起動します。 🔍 解説 エージェントが行き詰まったとき、最も非効率な対応は「同じ文脈でもう少し頑張る」ことです。失敗の経緯がコンテキストに蓄積すると、エージェントはそれに引きずられて同じ轍を踏みやすくなります。意味的サーキットブレーカーは、単なる反復回数制限ではなく、「進捗があるか」を実質的に判定します。振動（AをBに変えてまたAに戻す）や同一エラーの反復を検出したら、gitで最後の正常状態にロールバックし、新しい文脈で「前回はXで失敗した。別のアプローチを試す」という一行の教訓だけを持って再起動します。gitはエージェントのUndoです。 🛠 実践方法 ・エラーメッセージやテスト結果を比較し、「同じエラーが2回」「編集のAB振動」を検出するロジックをハーネスに実装します ・停止時にgit checkoutで最後のクリーンなコミットにロールバックし、汚染された文脈を破棄します ・リスタート時に「前回はXで失敗した」という一行の教訓だけを新しい文脈に持ち込みます ・サーキットブレーカーの閾値をタスクの難易度に応じて調整します（簡単なタスクは厳しく、難しいタスクは余裕を持たせる） 💼 ユースケース ・issue-to-PRエージェントが同じテスト失敗を修正できずループする場面 ・コンパイルエラーの修正で、修正→別のエラー→戻す→の繰り返しを検出する場面 ・レガシーコード改修で、アプローチの根本的な変更が必要だと判断する場面 ⚠ 落とし穴 サーキットブレーカーが敏感すぎると、あと一歩で解決するところで打ち切ってしまいます。逆に鈍感すぎると、コストを浪費するだけの無限ループになります。「進捗」の定義をタスクに合わせて調整することが重要です。また、リスタート時に教訓を正確に蒸留することも難しく、間違った教訓を持って再起動すると、別の失敗パターンに陥ることがあります。 #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのプラクティス P10. 二相設計 —— 読み取り専用の探索 → 実装 🎯 ポイント 「まず理解してから書く」は人間の美徳です。エージェントにも同じ規律を、願望ではなく権限で強制しましょう。 📝 概要 まず書き込み禁止の探索フェーズを強制し、計画を出させてから実装フェーズに入ります。早すぎる編集を構造的に防ぐことで、計画の質が上がります。フェーズ境界は願望ではなくハーネスが権限で強制します。 🔍 解説 エージェントは「とりあえず書いてみる」傾向があります。コードの全体像を把握する前にファイルを編集し始め、後から「そもそもアプローチが間違っていた」と気づいて大幅な手戻りが発生する、というパターンは非常に多いです。二相設計では、最初のフェーズでファイル読み・検索・シンボル解決のみを許可し、編集ツールを無効化します。エージェントはコードベースを探索し、理解し、計画を立てることだけに集中します。計画が承認されて初めて編集権限が解放されます。これにより「思いつきで書いて壊す」リスクを構造的に排除できます。 🛠 実践方法 ・フェーズ1では編集ツールを無効化し、ファイル読み・検索・シンボル解決のみを許可するツールセットを設定します ・フェーズ1の出力として計画ファイル（plan.md）を要求し、計画の承認をフェーズ2への移行条件にします ・フェーズ境界はプロンプトのお願いではなく、ツールの権限レベルで強制します ・探索フェーズの時間・ステップ数に上限を設け、コンテキスト枯渇を防ぎます 💼 ユースケース ・issue-to-PRエージェントで、issueの分析と計画策定を読み取り専用で行い、計画承認後に実装に入る場面 ・レガシーコード改修で、まずモジュール地図化と理解を行い、その後に変更を加える場面 ・インシデント対応で、診断（読み取り・安全・自律）と是正（書き込み・ゲート付き）を分離する場面 ⚠ 落とし穴 探索フェーズが長すぎると、エージェントがコンテキストウィンドウを使い切ってしまいます。また、探索フェーズで得た知識が実装フェーズまでに陳腐化するリスクもあります（P3のTTLと組み合わせる）。フェーズ境界を「プロンプトでお願いする」だけでは不十分で、ツールの権限レベルで強制することが重要です。 #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのアンチパターン AP8. ゲート疲労と空承認（Gate Fatigue / Rubber-Stamping） 🎯 ポイント 可逆な操作にまで承認ダイアログが出て、一日に何十回も反射で「承認」を押す。過剰なゲートはゲートそのものを無力化します。 ❗ 発生する課題 承認要求が多すぎるため、人間がゲートを反射的にスキップするようになります。アラート疲労と同じメカニズムで、本当に危険な不可逆行為の承認も反射で通過してしまい、ゲートの存在意義が完全に失われます。 🔍 メカニズムと症状 「すべてに人間承認を」は安全に見え、監査担当を安心させるため、このアンチパターンは組織的に採用されやすいです。しかし、意味のない承認の反復は承認を反射にします。これはアラート疲労と完全に同じ機序です。一日に50回「ファイルを編集してよいですか？」と聞かれれば、51回目の「本番DBを削除してよいですか？」も反射で承認してしまいます。症状としては、承認にかかる時間が1秒未満（読んでいない証拠）、全承認のログが記録上は「確認済み」だが実際は未確認、重要な操作の承認が他の瑣末な承認に埋もれる、チームが「承認がうざい」と不満を漏らす、といった現象が見られます。 📋 シナリオ ・エージェントがファイルを読むたびに承認を要求。開発者は無意識に「全て許可」を選択する習慣がつき、後日エージェントがforce-pushを実行した際も反射で承認。 ・セキュリティチームが「全操作に承認必須」のポリシーを導入。開発者は1日に200回の承認を処理するため、全てを一括承認するスクリプトを作成。ゲートが完全に形骸化。 ・ペアプログラミングで、エージェントの全編集に差分プレビューと承認を要求。開発者は差分を見ずにEnterを連打し、結果として意図しない変更が混入。 🛡 回避方法 ・権限設計を「能力」ではなく「取り消し可能性」で行い、可逆な操作は自由に許可します ・不可逆な操作だけを「重い儀式」のゲートに集約し、ゲートの希少性を保ちます ・承認の反応時間を測定し、1秒未満が続く場合はゲートが形骸化しているサインとして対処します ・ゲートの数を意識的に最小化し、「本当に人間の判断が必要な瞬間」だけに限定してください #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのプラクティス P7. 負の検証 —— リグレッションとブラスト半径のゲート 🎯 ポイント エージェントは「自分の変更が動く」を最適化し、「他を壊していない」を過小評価します。正の検証だけでは流出欠陥は止まりません。 📝 概要 完了ゲートに、既存テストスイート全体の実行に加えて「触れたシンボルを誰がimportしているか」というブラスト半径チェックを組み込みます。自分のコードが動くかだけでなく、他の箇所を壊していないかを検証するのが負の検証です。 🔍 解説 エージェントは自然と「自分の変更に関連するテストが通る」ことに集中します。しかし、変更の影響は変更した箇所だけに留まりません。関数のシグネチャを変えれば呼び出し元が壊れ、共有モジュールの挙動を変えれば依存先すべてに影響します。負の検証とは「壊したものがないこと」を明示的に検証する仕組みです。変更したシンボルのimport元を特定し、それらのテストも実行する。影響範囲の可視化とそのテスト実行を完了ゲートに組み込むことで、流出欠陥を構造的に防ぎます。 🛠 実践方法 ・変更したシンボルのimport元を静的解析（import解析・コールグラフ）で自動特定するツールを完了ゲートに組み込みます ・特定された依存先のテストを自動的に実行対象に追加し、既存テストスイートと併せて実行します ・変更のブラスト半径（影響ファイル数・影響モジュール数）を差分と一緒に可視化し、レビュアーにも提示します ・カバレッジ情報と静的解析を組み合わせ、テストが不足している影響範囲を特定してフラグを立てます 💼 ユースケース ・issue-to-PRエージェントで、共有ユーティリティの変更時に全依存先のテストを自動実行する場面 ・マイグレーションエージェントで、APIシグネチャ変更の影響範囲を全て検証する場面 ・レガシーコード改修で、変更の波及先を特性評価テストでカバーする場面 ⚠ 落とし穴 ブラスト半径チェックを網羅的にやりすぎると、モノレポ全体のテスト実行になり非現実的です。影響範囲の特定には静的解析（import解析・コールグラフ）と動的解析（カバレッジ情報）の組み合わせが効果的です。また、負の検証が存在するからといって正の検証を軽視してよいわけではありません。両方が必要です。 #HarnessEngineering# #QualityAssurance#

ハーネスエンジニアリングのアンチパターン AP7. 決定性の取り違え（The Misplaced Determinism Boundary） 🎯 ポイント テスト実行をLLMの善意に委ね、端ケースの判断を硬いルールに押し込む。境界を取り違えると、信頼性と適応性を同時に失います。 ❗ 発生する課題 確率的な要素を決定的であるべき場所に置くと信頼性が漏れ、決定的なルールを判断が要る場所に置くと適応性を失います。結果として、簡単なタスクで不安定になるか、複雑なタスクで硬直するか、あるいはその両方が同時に起きます。 🔍 メカニズムと症状 この取り違えには二つの形態があります。形態Aは「LLMの判断が要る長いテールを硬いルールに押し込む」パターンで、ルールは予測可能なため魅力的に見えますが、端ケースに遭遇すると脆く壊れます。形態Bは「決定的であるべき処理（テスト実行、ゲート判定、リトライ）をLLMの善意に委ねる」パターンで、モデルに任せれば実装が楽に見えますが、100回に1回はテストを忘れるという不安定さを生みます。症状としては、形態Aでは「想定外のケースでルールが破綻」「新しいパターンのたびにルール追加が必要」、形態Bでは「テストの実行忘れ」「ゲートのスキップ」「時々なぜか動かない」が見られます。 📋 シナリオ ・形態A：「import文の変更は必ずファイル先頭に」という硬いルールを設定。circular importの解消が必要なケースでルールが邪魔をし、エージェントが行き詰まる。 ・形態B：「テストを必ず実行すること」をプロンプトに記載するだけで、ハーネスが強制しない。エージェントは95%の確率でテストを実行するが、残り5%でテスト未実行のまま完了を宣言する。 ・両方同時：コードモッドの大部分はASTベースの決定的変換で処理できるのに、全てをLLMに任せている（形態B）。一方、LLMの判断が必要な端ケースには「この場合はスキップ」という硬いルールを適用（形態A）。両方が間違っている。 🛡 回避方法 ・ハーネスの全処理を「判断が要る」と「判断不要で決定的に実行可能」に分類し、境界を明示します ・テスト実行・lint・ビルド・ゲート判定は決定的コードで強制し、「お願い」しません ・LLMは本当に判断が必要な部分（原因分析・方針決定・コード生成）に限定して使います ・モデルの進化に合わせて境界を定期的に見直し、適切に移動させてください #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのプラクティス P20. 可読性とキャリブレートされた不確実性をSLOにする 🎯 ポイント 生成が安価になった今、真のボトルネックは「人間のレビュー時間」です。差分は正しさだけでなく、レビューしやすさに対しても最適化すべきです。 📝 概要 差分は正しさだけでなくレビュー時間に対しても最適化します。小さく焦点の合ったPR、「なぜ」を語る説明、危険箇所の明示。さらにエージェントには「自信のない箇所」を明示出力させ、ハーネスがそこを追加検証や人間レビューへ振り分けます。偽の自信より較正された不確実性の方が価値が高いです。 🔍 解説 エージェントの生成速度が上がるほど、ボトルネックは「コードを書く」から「コードをレビューする」に移ります。巨大なPR、説明のない変更、自信満々だが実は不確かな実装。これらはレビュアーの時間を爆発的に消費します。可読性をSLO（サービスレベル目標）として扱い、PRサイズ・説明の有無・変更理由の明記を測定・最適化することで、全体のスループットが向上します。また、エージェントに「ここは自信がない」「この部分は人間に確認してほしい」と明示させることで、レビュアーは重要な箇所に集中できます。これは自律エージェントの信頼性を高める最も見落とされがちな施策です。 🛠 実践方法 ・PRテンプレートに「変更理由」「確信度（高/中/低）」「レビュー重点箇所」の欄を設け、エージェントに必ず記入させます ・PRサイズの上限を設定し、超過した場合は分割を強制します ・エージェントの出力に「自信のない箇所」のマーカーを要求し、ハーネスがそこを追加検証へ振り分けます ・レビュー時間をPR単位で計測し、レビュー時間が長い原因（巨大差分・説明不足等）を特定して改善します 💼 ユースケース ・issue-to-PRエージェントが、PRに変更理由と確信度マーカーを含める場面 ・コードレビューエージェントが、低確信の瑣末指摘を抑制し、人間が見落とす種別に集中する場面 ・マイグレーションで、各ユニットのPRを小さく焦点を絞り、レビュアーの負荷を分散する場面 ⚠ 落とし穴 可読性を追求しすぎると、エージェントの出力が過度に保守的になります。また、「不確実性の表明」がノイズになるリスクもあります。「すべてに自信がない」と表明するエージェントは役に立ちません。較正が重要で、本当に不確かな箇所だけを正確にマークできることが価値です。レビュー時間の測定も忘れずに。PRスパムや巨大差分がレビュー帯域を圧迫していないかを定量的に把握することが改善の出発点です。 #HarnessEngineering# #CodeReview#

ハーネスエンジニアリングのプラクティス P19. 失敗をデータ資産化する（ハーネス自身のレトロループ） 🎯 ポイント 同じ失敗を何度も繰り返すハーネスは、改善不能なブラックボックスです。失敗をログ化し、ハーネス改善にフィードバックする仕組みを持ちましょう。 📝 概要 あらゆる人間の介入・ロールバック・流出欠陥を原因とともにログ化し、ハーネス改善（新ゲート・新指示・新ツール）にフィードバックします。ハーネスは自分自身に対するCIを持つべきです。これが成熟度L3（測定する）とL4（改善し続ける）を分けます。 🔍 解説 エージェントが失敗したとき、多くの組織は「モデルが悪い」で終わらせます。しかし本当の問いは「なぜハーネスはこの失敗を防げなかったか」です。人間が介入したということは、ハーネスにガードレールか検証が足りなかったということです。ロールバックが必要だったということは、サーキットブレーカーが機能しなかったということです。流出欠陥があったということは、検証器が不十分だったということです。これらの事象を原因分析とともに記録し、ハーネスの改善アクション（新しいゲートの追加、指示ファイルの更新、ツールの改善）に変換するループが、ハーネスを製品として成熟させます。 🛠 実践方法 ・人間の介入・ロールバック・流出欠陥の全事象を、原因分類とともに構造化ログに記録します ・定期的（週次や隔週）にレトロスペクティブを実施し、頻出する失敗パターンを特定します ・各失敗パターンに対して最も効果的な改善アクション（新ゲート・指示追加・ツール改善）を選定し、実施します ・改善アクションの効果を測定し、効果が低いものは撤回して別のアプローチを試します 💼 ユースケース ・issue-to-PRエージェントの失敗事例を週次で分析し、ハーネスの改善点を特定する場面 ・CI自動メンテナンスで、偽陽性の原因を追跡し、トリアージロジックを改善する場面 ・インシデント対応で、エージェントの推奨が不正確だった事例から、可観測性アクセスの改善点を導く場面 ⚠ 落とし穴 失敗のたびにルールを追加するだけでは「足場のラチェット」（AP3）に陥ります。失敗をデータ資産化するとは、単にルールを増やすことではなく、根本原因を分析して最も効果的な改善を選ぶことです。また、ログ化だけして分析しなければ、データは蓄積するだけで価値を生みません。定期的なレトロスペクティブの仕組みが不可欠です。 #HarnessEngineering# #ContinuousImprovement#