同じ間違いを、AIエージェントが何度も繰り返す。昨日直したはずの指摘が、今日また別のタスクで出てくる。モデルを最新版に上げても、なぜか改善している実感がない——。
AIコーディングエージェントを本格的に使い込むと、誰もが一度はこの壁にぶつかります。原因の多くは、モデルの性能ではなくエージェントを取り巻く環境の側にあります。
AIエージェント＝Model（賢さ）＋ Harness（環境）。これは、ある生成AI活用の勉強会で聞いた整理の仕方です。同じモデルを使っていても、周りの環境（設定・権限・フィードバック経路・運用の仕組み）の設計次第で、出てくる成果は大きく変わります。
この記事では、自分が個人開発・本業の両方で実際に使っている、AIエージェントのハーネス設計と、その上に載せている「Loop Engineering」（定型業務を人の承認ゲート付きで自動化する仕組み）を整理します。会社固有の内部事情には触れず、どこでも応用できる設計原則として書きます。
ハーネスは大きく4つの層に分けて設計しています。
| 層 | 役割 | 設計の要点 |
|---|---|---|
| コンテキスト | エージェントに何を知らせるか | 常時ロードする「前提知識」と、必要な時だけ読む「手順」を分離する |
| アクション | エージェントに何をさせてよいか | 安全な操作は自動許可、不可逆な操作は必ず確認を挟む |
| フィードバック | 間違いにどう気づかせるか | 過去の指摘パターンをカタログ化し、実装前・push前に機械的にチェックする |
| 運用 | 気づきをどう仕組みに戻すか | 繰り返し出た指摘・判断基準を、都度ドキュメントやルールに書き戻す |
この4層が噛み合って初めて、「賢いモデルに毎回同じ説明をする」状態から抜け出せます。1層でも欠けると、結局は人間が記憶と判断を肩代わりし続けることになります。
一番効果が大きかったのは、「エージェント設定ファイル」に前提知識だけを置き、手順は別の仕組み（実行時に必要なものだけ読み込ませる部品）に切り出したことです。
設定ファイルに手順まで書き込んでいくと、あっという間に肥大化します。肥大化した設定は、毎回のやり取りでコンテキストを圧迫し、かえって重要な情報が埋もれる原因になります。逆に、前提知識まで手順側に混ぜてしまうと、今度は同じ知識があちこちに重複し、更新のたびに矛盾が生まれます。
この役割分離を徹底するだけで、設定ファイルの見通しが劇的に良くなります。
エージェントの権限は、「基本は自由にやらせる」「不可逆・破壊的な操作の手前だけ機械的に止める」の二段構えにしています。
削除・強制上書き・本番への反映のような、後戻りしにくい操作の直前で、実行前チェックを機械的に挟む仕組みを用意しています。これにより、エージェントの判断ミスがそのまま取り返しのつかない結果に直結するのを防ぎます。逆に、それ以外の大半の操作（調査・ファイル編集・テスト実行など）は自由に任せることで、毎回の確認待ちで作業が詰まる事態を避けています。
人間によるレビュー指摘には、驚くほど再発するパターンがあります。過去に指摘された内容を、実装前にチェックリスト化しておき、機械的に検証してから提出する、という経路を作っています。
具体的には、実装前に「この領域でよく出る指摘」を確認し、コミット前にスクリプトでセルフチェックし、提出前に想定される指摘を先回りでレビューする、という3段階です。ここまでやると、レビュー往復の回数が目に見えて減ります。
同じ指摘を2度受けたら、それは「個人の記憶」ではなく「仕組みの穴」だと捉えます。都度、判断基準をドキュメントに追記していくことで、次に同じ状況に出会ったときはエージェントが自力で正しい判断にたどり着けるようになります。
このループを回し続けることが、結果的に「賢いモデルに頼らなくても、安定して同じ品質が出る」状態を作ります。
手順を切り出す部品（以下Skillと呼びます）の設計にも、いくつか実践パターンがあります。
Orchestrator型設計: 複数ステップにまたがる作業は、「親Skill（呼び出す順序だけを管理し、ロジックは持たない）」＋「子Skill（各ステップの実処理）」に分けます。各ステップは独立したエージェントに実行させ、そのつどコンテキストをリセットします。ステップ間の受け渡しは、直接会話の文脈を引き継がせるのではなく、ファイルシステム経由で成果物だけを渡します。こうすることで、前段の調査結果を丸ごと引きずってプロンプトが肥大化する事態を避けられます。
設定ファイル駆動の拡張: 新しいバリエーションを増やしたいとき、Skill本体のロジックは変更せず、設定ファイルを追加するだけで対応できるようにしています。本体を触らずに済むので、既存の動作を壊すリスクを増やさずに機能を広げられます。
二層管理: 個人的に試行錯誤する部品と、チームに展開する部品を分けています。個人側は変更のハードルを低くして自由に試し、汎用化できたものだけをチーム側に「使ってもいいStarter Kit」として置く、という順序です。義務にしないことで、展開そのもののハードルも下げています。
単純作業を1体のエージェントに任せるだけでなく、複数のエージェントをチームとして編成し、役割分担させる設計も使っています。
流れはシンプルです。
ここで効くのが、作業担当＋レビュー担当のペア構成です。1体のエージェントが実装し、別のエージェントが「正確性・網羅性・一貫性・公開して問題ないか・型に沿っているか・推測箇所が明示されているか」といった観点でチェックする。指摘があれば作業担当に差し戻し、これを上限回数まで繰り返します。上限に達しても解決しない場合は、人間にエスカレーションします。
1体でやらせるより明らかに時間はかかりますが、単独では見落としがちな観点を、別の視点から必ず一度チェックさせることで、品質のばらつきを抑えられます。
ここまでは「頼んだ作業をどう高品質にこなすか」でした。Loop Engineeringは一歩進んで、定型的な運用業務そのものを、周期的に自動で回す設計です。
パターンはどのループも共通で、次の5段階です。
実際に運用しているループの例を挙げると（固有名詞は伏せます）：
Loop Engineeringで一番大事にしているのは、実は自動化の範囲を最大化することではなく、信頼を損なわない範囲に自動化を抑えることです。
定型作業だからといって、間違った実行が積み重なると、それはやがて「このエージェントに任せて大丈夫か」という信頼の毀損につながります。特に、個人情報・認証認可・決済のように、間違えたときの被害が大きい領域に触れる変更は、フェーズや状況に関わらず必ず人間の目でレビューを挟む、というラインを譲らないようにしています。
また、ループの追加方法もSkill設計と同じ思想を踏襲していて、ループエンジン本体は変えずに、個々のループは設定ファイルの追加だけで増やせるようにしています。
うまくいっている部分だけでなく、正直に難しさも書いておきます。
このあたりは、今後も運用しながら調整していく部分だと思っています。定型業務が多い環境ほど、Loop Engineeringの効果は大きく出る一方で、承認ゲートの置き方の悩みも増える、というのが実感です。