ハーネスエンジニアリングのプラクティス 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#

ハーネスエンジニアリングのアンチパターン AP10. 観測なきブラックボックス（The Unobservable Black Box） 🎯 ポイント 失敗の原因がモデルか、プロンプトか、ツールか、コンテキストか、環境か——誰にも切り分けられない。改善が迷信と勘で行われるハーネスは、改善不能です。 ❗ 発生する課題 失敗をサブシステムに帰属できないため、何を直すべきかが分かりません。改善が迷信と勘で行われ、ハーネスの振り返りループが回らなくなります。単一指標だけを追う「指標モノカルチャー」と結びつくと、測定されていない品質が静かに犠牲になります。 🔍 メカニズムと症状 可観測性は地味なインフラ作業であり、エージェントは「だいたい動く」ため、このアンチパターンは後回しにされがちです。しかし、サブシステムに失敗を帰属できなければ、振り返りループが回せず、ハーネスは改善不能になります。さらに、単一指標（例：成功率だけ）を追うと、測られていない美徳（レビュー時間・リグレッション率・コードの保守性）が静かに犠牲になる「指標モノカルチャー」が発生します。症状としては、「なぜ失敗したか分からない」が頻発する、改善施策が「プロンプトをいじる」一辺倒になる、モデルの問題かハーネスの問題か区別がつかない、成功率は上がっているのにレビュアーの不満が増える、といった現象が見られます。 📋 シナリオ ・エージェントがタスクに失敗するが、原因がモデルの推論ミスか、コンテキストの不足か、ツールのバグか、環境の問題か誰にも分からない。チームは「プロンプトをもう少し詳しくしよう」と対症療法を繰り返す。 ・成功率を唯一の指標として追跡。成功率は80%に向上したが、成功した案件のレビュー時間が3倍に膨れ上がっていることに気づかない。 ・モデルをアップグレードしたが性能が変わらない。原因がモデルの問題なのか、ハーネスの足場が制約しているのか（AP3）切り分けられず、投資判断が迷信になる。 🛡 回避方法 ・決定・ツール呼び出し・コンテキスト変遷をトレースし、7サブシステム（知覚・行為・フィードバック・制御・記憶・ガードレール・インターフェース）に帰属可能化します ・単一指標でなく束で測定します（成功率・介入率・手戻り率・リグレッション率・コスト・レビュー時間・確信度の較正） ・モデルを固定してハーネスの変更をA/Bテストし、改善をハーネスに帰属させます ・ハーネスの可観測性を「地味だが不可欠なインフラ」として投資し、改善ループの基盤を整えてください #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのアンチパターン AP9. 健忘症のハーネス（The Amnesiac Harness） 🎯 ポイント 毎セッション同じ地雷を踏み、同じ説明をされ、同じ訂正を受ける。複利が効くべきところで単利すら積まれていません——競争優位の最大の源泉を捨てています。 ❗ 発生する課題 ハーネスがセッション間で知識を蓄積しないため、同じ学習コストを無限に再支払いし続けます。エージェントは毎回同じ試行錯誤を繰り返し、組織のハーネスは時間とともに賢くなりません。 🔍 メカニズムと症状 このアンチパターンが見過ごされやすいのは、個々のセッションは「うまくいっている」ように見えるからです。「ビルドにはフラグXが要る」と学んだセッションは成功しますが、次のセッションで同じ発見を一からやり直します。知識固定という地道な作業は後回しにされがちで、「今回は動いたからOK」で終わります。しかし、学習コストの再支払いは1回なら些細でも数十回重なると膨大な浪費です。複利が効くべきところで単利すら積まれない——これは競争優位の最大の源泉を捨てているのと同じです。症状としては、「また同じエラーか」という既視感、毎回同じ環境設定でつまずく、チームが同じ情報をエージェントに何度も教える、といった現象が見られます。 📋 シナリオ ・エージェントが「このプロジェクトではDockerが必要」と3回のセッションで3回学び直す。毎回5分のビルドエラーとデバッグが発生し、合計15分を浪費。 ・レガシーコードの「このモジュールは廃止予定、代わりにYを使え」という知識を、5人の開発者がそれぞれのセッションでエージェントに教え直す。 ・インシデント対応で「このサービスのログはCloudWatchではなくDatadogにある」をエージェントが毎回発見し直し、初動の5分を無駄にする。 🛡 回避方法 ・エージェントが試行錯誤で学んだ知識を永続指示ファイル（AGENTS.md等）に即座に書き出すフックを実装します ・「一時的な情報」と「不変の知識」を区別し、後者だけを永続化するガイドラインを定めます ・指示ファイルの定期的な棚卸しサイクルを設け、古くなった知識を削除します ・知識が複利で積み上がるべき資産であることを認識し、「発見した瞬間の固定」を習慣化してください #HarnessEngineering# #KnowledgeManagement#

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

ハーネスエンジニアリングのプラクティス P15. 権限は「能力」ではなく「取り消し可能性」で設計する 🎯 ポイント 問うべきは「Xできるか」ではなく「Xを取り消せるか」です。可逆性こそ、自律性と安全性のトレードオフを切る正しい軸です。 📝 概要 可逆な行為（ブランチへのコミット、ファイル編集。gitが戻せます）は自由に許し、不可逆な行為（force-push、本番書き込み、外部メール送信、送金）だけをゲートします。可逆性が権限設計の基準です。 🔍 解説 多くの権限設計は「この操作は危険か？」という直感で行われますが、直感はしばしば間違います。ファイル編集は「危険」に見えますが、gitで即座に取り消せるため実際のリスクは低いです。一方、外部APIへのリクエストは「些細」に見えますが、送信後に取り消せないため実際のリスクは高いです。取り消し可能性を基準にすると、自律性と安全性の最適なバランスが自然に導かれます。可逆な操作にまで承認ダイアログを出すと「ゲート疲労」（AP8）が発生し、人間は反射で承認を押すようになり、本当に危険な操作も見逃してしまいます。 🛠 実践方法 ・エージェントが実行可能な全操作をリストアップし、各操作を「可逆」「不可逆」「条件付き可逆」に分類します ・可逆な操作（ブランチへのコミット、ファイル編集、サンドボックス内の実行等）は承認なしで許可します ・不可逆な操作（force-push、本番書き込み、外部API呼び出し、メール送信等）は承認ゲートを必須にします ・影響の連鎖を考慮します（コミット→CI→自動デプロイという間接的な不可逆性に注意） 💼 ユースケース ・issue-to-PRエージェントで、ブランチへのコミットは自由、でもforce-pushは禁止する場面 ・インシデント対応で、診断（読み取り）は自律、是正（本番書き込み）は人間承認必須の場面 ・プロトタイピングで、サンドボックス内の操作は自由、外部ネットワークアクセスだけをゲートする場面 ⚠ 落とし穴 「可逆」の判断は単純ではありません。ブランチへのコミットは可逆ですが、そのブランチが自動的にCIを起動し、CIがデプロイをトリガーするなら、間接的に不可逆な影響を持ちます。影響の連鎖全体を考慮して可逆性を判断する必要があります。また、「取り消せるから大丈夫」と安全を過信するのも危険で、取り消しコストの大小も考慮すべきです。 #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのアンチパターン AP1. コンテキストの溜め込み（The Context Hoarder） 🎯 ポイント 「念のため全部入れておこう」——その安心感が、エージェントの性能を静かに殺しています。情報は多いほど安全ではなく、しばしば害です。 ❗ 発生する課題 コンテキストウィンドウに無関連な情報が溢れ、エージェントの注意が希釈されます。重要な情報が中盤に埋もれ、本来必要なコードや仕様を載せるスペースが不足します。結果として、エージェントの判断精度が低下し、コストとレイテンシが線形以上に悪化します。 🔍 メカニズムと症状 このアンチパターンが魅力的に見えるのは、「情報は多いほど安全」という直感が強いからです。取得設計（何をいつ取りに行かせるか）は手間がかかるため、全部入れる方が楽に感じます。しかし、コンテキストウィンドウはCPUのL1キャッシュに相当する希少資源です。効用は単調増加しません。一定量を超えると無関連トークンが注意メカニズムを希釈し、重要情報の中盤埋没（lost in the middle）が発生します。症状としては、リポジトリ全体や長い会話履歴の丸ごと注入、全ツール定義の毎回ロード、「なぜか前に読んだはずの情報を無視する」といった現象が現れます。 📋 シナリオ ・issue-to-PRエージェントに、issueの内容だけでなくリポジトリ全体のREADME・設定ファイル・過去のPR履歴をすべて注入している。エージェントは肝心のissueの要点を見落とし、無関係なファイルを編集し始める。 ・マイグレーションエージェントに数千ファイルの情報を一度に渡し、コンテキストが溢れてエージェントが途中で一貫性を失う。 ・ペアプログラミングで、開いていないファイルや過去の長い会話履歴がコンテキストを圧迫し、レスポンスが遅くなる。 🛡 回避方法 ・コンテキストの使用量をカテゴリ別に計測し、メモリプロファイラのように配分を可視化します ・取得はpull既定（エージェント自身に必要な情報を取りに行かせる）とし、push（強制注入）は破ると致命的な不変条件だけに絞ります ・会話履歴は古いターンから要約・圧縮し、ツール定義は現在のタスクに必要なものだけを動的にロードします ・「全部入れれば安心」という思考に気づいたら、それがこのアンチパターンのサインだと認識してください #HarnessEngineering# #AIAgent#

ハーネスエンジニアリングのプラクティス P4. サブエージェントは「蒸留器」として契約する 🎯 ポイント サブエージェントが50ファイルの生ログを親に返したら、親のコンテキストは即死します。返すべきは「議事録」ではなく「結論」です。 📝 概要 探索用サブエージェントの契約を「結論を返す、議事録は返さない」と定義します。50ファイル探索して5行の所見を返す。これは礼儀ではなく、文脈階層のメモリ管理規律です。 🔍 解説 サブエージェントを使う主な目的は、親エージェントのコンテキストウィンドウを守ることです。しかし、サブエージェントが生の探索結果をそのまま返してしまうと、その目的は完全に失われます。サブエージェントは「蒸留器」として機能すべきです。大量の情報を読み込み、本質だけを凝縮して返す。この契約を明示的にプロンプトで定義し、返答のフォーマットも制約することで、文脈階層全体の効率が保たれます。安価なモデルで広く探索し、高価なモデルで深く判断する、というトークン経済の原則とも合致します。 🛠 実践方法 ・サブエージェントのプロンプトに「結論を返す、議事録は返さない」と明記し、返答フォーマット（行数上限・構造）を制約します ・探索タスクには安価なモデルを使い、親エージェントの判断には高価なモデルを使うトークン経済を設計します ・サブエージェントの返答サイズを監視し、閾値を超えた場合は再蒸留を要求するガードを設けます ・蒸留の粒度をタスクに応じて調整します（分類タスクなら3行、分析タスクなら10行など） 💼 ユースケース ・大規模コードベースの調査で、複数のサブエージェントにファイル群を分担探索させ、各々が要約のみ返す場面 ・マイグレーションで、各ユニットの状況を調査するサブエージェントが「移行可／要手動対応／不明」の3分類だけを返す場面 ・インシデント対応で、ログ・メトリクス・トレースを別々のサブエージェントが調査し、相関する異常の要約だけを返す場面 ⚠ 落とし穴 サブエージェントの蒸留品質が低いと、重要な情報が失われるリスクがあります。「結論だけ返せ」と指示しても、何が結論に値するかの判断はモデルの能力に依存します。また、蒸留の過程で文脈が失われすぎると、親エージェントが誤った判断をする可能性もあります。蒸留の粒度は、タスクの性質に応じて調整が必要です。 #HarnessEngineering# #AIAgent#