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

ハーネスエンジニアリングのアンチパターン 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#