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