一人で AI に任せているうちは、困らない。ずれても自分で気づき、その場で方向を直せる。頼み方が毎回少し違っても、直すのは自分だからである。
困り始めるのはチームで使ったときである。人によって頼み方が違い、渡す情報も違う。だから成果物も違う。レビューで気づいて直し、次の案件でまた同じことが起きる。
社内の技術共有会でこの整理をやったので、外向けに書き直して残しておく。実際に入れてみて、まだ塞げていない穴も含めて書く。
■ ハーネスとは、AI の「周りの仕組み」
ハーネスとは、AI モデルそのものではなく、その周りに置くもの全部を指す。Böckeler は "everything in an AI agent except the model itself" と定義している。
中身は 4 つに分かれる。
・伝える。 判断に必要な情報。仕様・規約・既存のやり方
・道具。 実行する手段。ファイル編集、コマンド実行
・確かめる。 結果の検査。テスト、型チェック、lint
・返す。 検査結果を受け取り、直してもう一度走らせる仕組み
モデルは考える。だが何を読めるか・何を実行できるか・結果をどう確かめるかは、周りが決める。そして「一度でも起きたら困ること」は、この循環の中ではなく外側に柵として立てる。
■ 伝える — AI は、渡されたものしか知らない
頼み方が人で違うからこそ、判断の材料は頼み方に含めない。頼む人の口ではなく、置いてある場所から渡す。誰が頼んでも、AI は同じ材料を読んでから判断する。
用意するものは 3 種類に分かれる。
・今回の仕様。 この依頼だけの条件。決まっていないことは、人が決めてから渡す
・社内の規約。 どの案件でも同じもの。命名、レビュー、禁止事項
・既存のやり方。 このプロジェクトで決まっているもの。どこを読むかが要る
書く場所は読まれるタイミングで分ける。毎回読まれる案内は短く保ち、依頼ごとの仕様書は依頼の単位で書き、必要なときだけ読まれる手順書は長くてよい。
ここで一度失敗した。書けば書くほど良いと思って、毎回読まれる案内が 289 行に太った(自分たちで数えた行数である)。冒頭に「地図であって百科事典ではない」と自分で書いてあるのに、である。
同じ説明が 4 箇所に重複し、文書どうしが矛盾する失敗が実際に起きた。常時読まれる案内には地図とルールとコマンドだけを残し、詳細は手順書へ移した。
■ 確かめる — エディタの赤線は、AI には見えない
材料を渡しても、出力は毎回ぶれる。だから出てきたものを、人ではなく機械で確かめる。見るのは「書きました」という報告ではなく、成果物そのものである。
要点は 1 つだけある。エディタが引く赤線は人間用で、AI には見えない。AI が自分で実行して結果を読めるコマンドだけが、「確かめる」になる。
■ 返す — 「テストが失敗した」では、直せない
確かめて落ちたら、その中身を返す。事実だけ返しても直す材料にならない。
「テストが失敗した」では、落ちたという事実しか分からない。どの入力で、何を期待して、実際に何が返ったのかが無い。入力・期待・実際の 3 点が揃って、初めてどこがずれたのかが特定できる。
直ったかどうかも、同じ 3 点で判定できる。返す先は AI だけではない。途中で交代する次の担当者にも、同じ 3 点が要る。
■ 強制する — 指示は守られる確率、強制は機械が止める
「本番データを変更しない」という同じ 1 行を、2 通りのやり方で置いてみる。
指示として書くと、守るのは AI である。読んだうえで守るかどうかを選ぶので、破られたらそのまま実行され、あとから気づく。向いているのは判断を伴うこと、書き方や進め方の方針である。
できないようにすると、守るのは機械である。読む・書く前に判定して止めるので、そもそも実行されず、理由が返る。向いているのは、一度でも起きたら困ることである。
Claude Code なら、前者は毎回読まれる案内に 1 文を書くことで、後者は permissions のdeny と Hook の組み合わせで実現する。どちらが良いではなく、使いどころが違う。
そして「破れない」は言い過ぎである。柵にも穴がある。編集操作にしか検査が掛かっていなければ、シェル経由の書き込みは通る。自分で作った仕組みほど完璧だと思いたくなるので、穴は先に文書化しておく。
■ 教科書に無かった、入れてから足したもの
ここからは、外部の資料に書いていなかったが、運用して必要になったものである。
□ ルールは 4 種類。いつ消えるかが違う
書いていくと性質の違うルールが混ざり、消していいものが分からなくなった。そこで強制のされ方と、いつ消えるかで 4 つに分けた。
・機械が拒否するもの。 破れない。消さない
・モデル向けの指示。 守るのは AI。モデルが賢くなれば消える
・組織の知識。 必要なときだけ読む。会社が変われば消える
・踏んだ落とし穴。 作業の直前に読む。消さない。増える
混ぜると、消していいものを怖くて消せなくなる。指示だけが増えて、全体が薄まる。
□ 「絶対ルール」と書いたのに、機械で守れていない
案内に「絶対ルール」として 5 本書いたが、そのうち 2 本は機械で止められていなかった。指示でしか守られていないので、破っても誰も気づけない。
消す代わりに、その 2 本の下に「まだ機械で止めていない」と明記した。これは次に何を機械側へ移すかの候補リストになる。
□ 「グリーンでした」は、報告ではない
検証を AI にやらせる仕組みで一番危ないのは、実行したかどうかを本人が申告することである。「全部通りました」を信じるのをやめて、記録を 1 ファイル残すことにした。
記録に並べる列は 4 つだけである。実行したコマンド。その結果。受け入れ条件との照合。そして未確認のもの。最後の欄が本体である。
□ 足した指示には「消せる条件」を付ける
一度足したルールは、半年後に「なぜあるのか」が分からなくなって消せない。だから台帳に追加日・根拠・消せる条件の 3 列を書くことにした。
消し方も決めてある。候補を 1 つ外した状態で検証ケースを複数回まわし、失敗率で判定する。1 回通ったからでは消せない。出力は確率的だからである。
■ 失敗は「仕組みの欠陥」として直す
ある要件書のレビューで、レビュー用の AI が 42 件を指摘した。それでも人間が 3 件の抜けを見つけ、その 3 件について AI の指摘は 0 件だった。
このとき直したのは要件書ではなく、仕組みの 3 箇所である。あわせて、同じ失敗を検出する検証ケースを 1 本足した。ところが、同じ型がまたすり抜けた。検査が「語」頼みだったからである。
そこで語ではなく構造で探すように変え、全要件へ横展開した。「次から気をつける」は、次のセッションに引き継がれない。
ただし何でも仕組みのせいにすると、仕組みのほうが太る。だから失敗の型ごとに直す場所を決めた。
・文書を見つけられない → 案内の地図と、探し方の手順
・要件が曖昧 → 要件を書く手順書と、レビュアーの観点
・バグを検知できず → テスト、E2E、静的解析
・自律反復せず聞き返した → 実装ループの定義と停止条件
・やってはいけないことをした → 柵。1 回目で直す
・人間の判断ミス → 仕組みは変えない。記録だけ
■ 効果は、まだ数字で言えない
効果を数字で言いたくなるが、まだ 1 行も無い。計測ファイルはヘッダー行だけで、データ行が無い。
先に Baseline を取り、判断は中央値で、5 件たまるまで判断しない、と決めてある。見るのは補足説明の回数、上流への差し戻し回数、レビューでの検出数である。
整合性レビューの検出数だけは向きが逆で、多いほど柵が効いている。
■ 何から始めるか。1 つだけ選ぶ
全部は要らない。順番だけ守れば、どこからでも始められる。
1. 素の状態で一度走らせ、逸脱を記録する
2. ルールを書く。薄く。AI に草案を書かせ、人が削る
3. 検査を 1 コマンドに束ねる
4. 失敗を返して直させる
5. 繰り返しが見えてから、手順書とサブエージェントを足す
6. 足すだけでなく、棚卸す
今週やるなら 1 だけでいい。よく行う作業を 1 つ選び、素のまま走らせて逸脱をメモする。いま「気をつける」で守らせているルールを 1 つ選び、機械が止める側へ移せるかを見る。移せないなら、せめて破られたことに気づける仕組みを置く。
■ 参考
・Birgitta Böckeler「Harness engineering for coding agent users」(https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)
・Anthropic「Effective harnesses for long-running agents」(https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
・Anthropic「Effective context engineering for AI agents」(https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
・Claude Code「Hooks reference」(https://code.claude.com/docs/en/hooks)
・Claude Code「Configure permissions」(https://code.claude.com/docs/en/permissions)
・Claude Code「How Claude remembers your project」(https://code.claude.com/docs/en/memory)
■ この記事を書いている会社について
株式会社MIRAILABS では、こうした検証を社内で持ち寄りながら、業務への組み込み方を詰めています。システム開発や AI を使った開発の進め方について、相談したいことがあればお問い合わせください。
MIRAILABS では一緒に働く仲間を募集しています。手を動かして確かめる進め方に心当たりのある方は、採用ページをご覧ください。
・採用情報(https://mirailabs.co.jp/recruit/)