AIエージェントに仕事を任せはじめると、遅かれ早かれ「やらかし」に出会う。頼んでいないファイルを量産する、確認せずに「できました」と言う、人の名前を記憶で書いて間違える。私たちの環境でも全部起きた。この記事は、そうした失敗とどう付き合うかの仕組み——エージェント・ハーネスと呼ばれている考え方——を、自社で実際に起きたことを材料に整理したものだ。

この記事の要点

  • ハーネスとは「AIという新人に仕事をさせるための職場環境ひとそろい」。部品は4つしかない
  • ルールは願望で書かない。実際の失敗が起きてから、その1件につき1行足す
  • 「できました」を信用しない。テスト・スクショなど機械的な検品をAI自身に回させる
  • 賢い新モデルが出たら、ルールは「足す」のではなく「剥がす」

ハーネスとは何か——部品は4つ

ハーネス（harness）は直訳すると馬具。AIエージェントの文脈では、モデルそのものではなく、モデルに仕事をさせるための周辺環境一式を指す。難しそうに聞こえるが、会社に新人が入ってきたときに用意するものと同じで、突き詰めると4つしかない。

ルールのメモ
「うちのやり方」を書いた紙。毎朝、新人が仕事の前に読む（CLAUDE.mdなどの指示ファイル）
立入禁止の線
見るのは自由。お金・削除・公開に関わる操作は許可制（権限設定）
検品のやり方
「できました」を信用せず、本人に確かめさせる（テスト実行・スクショ・別のAIによるチェック）
失敗ノート
やらかしたら1行書く。ルールはここから生まれる（incidents.md）

権限の線は、私たちは信号の3色で分けている。緑は読むだけの操作で自由。黄はあとで戻せる書き込みで、任せてよい。赤は戻せない操作——削除・送信・公開・本番データへの書き込み——で、人間の承認が必須。この分け方だけで、事故の大半は「起きても戻せる」側に寄せられる。

定義が簡単なのと、
やることが浅いのは、別の話だ。

失敗ノートには、こういうことが載る

抽象論より実物のほうが早い。以下はすべて、この1か月ほどで私たちの環境で実際に起きたことと、そこから生まれたルールだ。

起きたこと生まれたルール
LP作り直しの依頼で、渡していた参照資料を見ずに作りはじめ、全面やり直しになった参照物があればまず開く。なければ質問は1つだけ
長い音声書き起こしの依頼内容を取り違えたまま作業を進めた長い入力には、冒頭で「依頼の一行要約」を出してから着手
対外文書の人名を記憶で書いて誤記した人名・数字は原本と突合。できなければ【要確認】と明記
株主名簿のCSVを本番システムに投入しかけた（直前で停止）本番データへの書き込みは、たとえ消せるとしても承認必須の赤
UIの変更を「できました」と報告したが、実際は崩れていたUI変更の完了報告には、スクショを目視した結果を必ず添える
「なぜ4GBあるのか調べて」と頼んだだけなのに、削除まで進めようとした調査の依頼は掃除の許可ではない。頼まれたことだけやる

並べてみると、失敗はだいたい5つの型に収まる。捏造・誤記（名前や数字をでっち上げる）、不可逆操作（消す・送る・公開する）、完了の嘘（確認せずに「できました」）、スコープ超過（頼んでいないことまでやる）、環境汚染（ゴミファイルと設定の肥大化）。自分の環境で何か起きたら、どの型かを見るだけで対策の当たりがつく。

みんなの実践は、3つの層に収斂している

Anthropicの公式ドキュメントから個人の実践記まで読み比べると、うまく運用している人たちのやり方は驚くほど似ている。

  • 第1層失敗をルールにする。願望でルールを書かない。「同じミスが2回起きたらメモに追記」が公式の目安で、Mitchell Hashimoto氏はルールファイルの全行が実際の誤動作由来だと書いている
  • 第2層検品をAI自身に回させる。合格・不合格が機械的に出るチェック（テスト、ビルド、スクショ比較）を渡すと、AIは自分で「実行して、結果を読んで、直す」を回す。ただし実装した本人にはレビューさせず、まっさらな別のAIに裁かせる
  • 第3層お願いではなく強制にする。指示ファイルは助言にすぎず、ルールが多いほど・セッションが長いほど守られなくなることが実験でも確認されている。絶対に守らせたいことは、機械的にブロックする仕組み（フック）へ移す

第3層まで行くと大掛かりに聞こえるが、順番が大事だ。いきなり仕組みを作り込むのではなく、失敗が起きてから1段ずつ上げる。公式ドキュメント自身が「セットアップは前もって作り込むな」と言っている。

全自動の複雑なマシンは実在する。でも少数派

危険コマンドを実行前に自動ブロックし、全行動を記録し、AIの作業を別のAIが採点して、不合格なら手順書をAI自身に直させる——そういう自己改善ループを組んだ環境は実在する。設定ファイルごと公開している人もいる。それでも主流はシンプルな側に留まっている。理由は3つ。

  • モデルが数か月ごとに賢くなるので、仕掛けはすぐ腐る。仕掛けは全部「今のモデルはこれができない」という前提を固定化したものだから
  • 自動で増えるルールにはゴミが混ざる。人間の裁きを挟まないと肥大化して、逆に読まれなくなる
  • 連結が複雑なほど、壊れたときに原因が特定できない

では「自己改善する仕組み」の現実解は何かというと、全自動のベルトコンベアではなく、半自動のラチェット——一方向にしか回らないネジを、週に1回、人間がひと回しする形だ。失敗が起きたらノートに1行（これは即時）。週1回5分、人間が裁く。ルールにするか、強制の仕組みに上げるか、放置するか。同じ手順を3回手で繰り返していたら、そこだけ自動化に昇格させる。

前もって作り込む

想定される失敗を先回りしてルール200行。実際の失敗と噛み合わず、量が多すぎて守られない。

失敗してから1行足す

起きた失敗1件につき対策1行。全行に実話の裏付けがあり、短いまま保たれるので守られる。

新モデルが出たら「足す」でなく「剥がす」

見落とされがちなのが、賢い新モデルへの乗り換え時だ。旧モデル向けに書き込んだ細かい指示は、新モデルではかえって出力の質を下げることがある——これはAnthropic自身が公式ガイドに書いている。だから新モデルが出たときにやるべきは、ルールの追加ではなく削減になる。

ただし一気に剥がさない。1部品ずつ外して影響を実測する。そして薄くなる一方でもない。新しい世代には新しい世代の失敗の癖（途中で勝手に「もう終わった」と判断する、指示を字義どおりに取りすぎる）があり、そこには短い指示が新たに要る。ルールのメモは薄くなるのではなく、中身が入れ替わっていく。

追加は、実際の失敗を見てからのみ。
削除は、モデルが冗長さを証明したときのみ。

まとめ——最初の一歩は、ノート1冊

大掛かりな環境構築は要らない。今日から始めるなら、この順番だ。

  • 失敗ノートを1ファイル作る。AIがやらかしたら1行書く（まずこれだけでいい）
  • 操作を3色に分ける。読むのは自由、戻せる書き込みは任せる、戻せない操作は承認制
  • 「できました」には検品を付ける。テスト・スクショなど、合否が機械的に出る確認をAI自身にさせる
  • 週1回5分、ノートを見返して裁く。ルール化するか、強制の仕組みに上げるか、放置か
  • 新モデルが出たら、ルールを1つずつ外して様子を見る

ハーネスづくりの本体は、仕組みの構築ではなく「メモを短く保ち続ける」という地味な手入れだ。そしてその手入れの原資は、全部、実際に起きた失敗である。だから失敗は隠さず、1行書く。それがいちばん安い投資だと思う。

SOURCE

Anthropic — Claude Code Best Practices

code.claude.com/docs/en/best-practices

SOURCE

Mitchell Hashimoto — My AI Adoption Journey

mitchellh.com/writing/my-ai-adoption-journey

SOURCE

Anthropic Engineering — Harness Design for Long-Running Apps

anthropic.com/engineering/harness-design-long-running-apps