2-1. もっとも単純な等式

ハーネスという言葉をめぐる過大評価・過小評価・混乱の多くは、この層構造を曖昧にしたまま語ることから生まれる。まずは最も単純な等式から始めよう。中心にあるのは LLM だ。これは突き詰めれば「テキストを生成する関数」にすぎない。入力された文字列に対して、確率的にもっともらしい続きの文字列を返す。それ以上でも以下でもない。素のLLMは、賢いが、自分でツールを呼ぶこともファイルを書き換えることもできない。ただ次の言葉を予測するだけの関数だ。このLLMを、より大きな構造で包む。その包みがハーネスだ。ハーネスとは「LLMをエージェントとして振る舞わせる制御の仕組み」のことを指す。LLMが返したテキストを解釈し、それがツール呼び出しなら実際にツールを実行し、その結果をまたLLMに戻す。この往復をループとして回し続ける仕組み——それがハーネスだ。そして、この二つが合わさったとき、初めて次が成立する。 > LLM(テキストを生成する関数)＋ハーネス(制御の仕組み)＝ AIエージェント例えば、ある素のLLMがあるとする。それ単体では、賢い文章生成器でしかない。だがこれを Claude Code のようなハーネスに乗せることで、ファイルを読み、コマンドを実行し、テストを走らせ、自律的にタスクを進める「エージェント」として振る舞い始める。エージェントとは、LLMという機関に、ハーネスという駆動系を取り付けたものだ。

2-2. 解像度を上げる — 「地盤」と「カスタマイズ領域」

「ハーネス＝制御の仕組み」という理解は正しいが、まだ解像度が粗い。ハーネスをもう少し分解して見ると、性質の異なる二つの領域に分かれることがわかる。この二層を混同することが、「ハーネス」という言葉の過大評価や過小評価、そして現場の混乱につながっている。一つめは、エージェントを動かす「地盤」にあたる領域だ。エージェントループそのもの、標準で備わっているツール群、コンテキストをどう構造化するか——こうした、エージェントが動くための土台となる部分。これらは多くの場合、ハーネス提供者(Claude Code を作っている側など)があらかじめ用意していて、ユーザーが自由に書き換えられるものではない。地盤は鍵がかかっている、と考えるとよい。二つめは、ユーザーによる「カスタマイズ領域」だ。モデル設定、CLAUDE.md のような指示ファイル、Hooks(フック)、ツールの使用権限、ネットワークアクセスの制御——こうした、ユーザーが自分の都合に合わせて調整できる部分。ここはツマミがついていて、ユーザーが回せる。 LLMという核を、まず「地盤」が包み、その外側を「カスタマイズ領域」が包む。この三重の入れ子全体が、エージェントを成立させている。 > 「地盤」と「カスタマイズ領域」を分けて理解する。これがハーネスの混乱を解く最初の一歩だ。

2-3. Claude Code はどういうハーネスか

この二層の視点で、Claude Code のような実在のハーネスを見ると、その性格がはっきりする。 Claude Code は、基本的なロジック(地盤)があらかじめ用意されていると同時に、挙動をユーザー側で制御する余地が一定ある、というハーネスだ。エージェントループや標準ツールは提供者側が固めている。一方で、モデル設定、CLAUDE.md、Hooks、ツール使用権限、ネットワークアクセスといった部分は、ユーザーが自分で調整できる。すると、ユーザー目線での「ハーネスエンジニアリング」とは何か、が定義できる。それは——そのコントロール可能な部分を、継続的に改善していく活動だ。地盤そのものは書き換えられない。だが、カスタマイズ領域というツマミ群を、自分の課題に合わせて回し続けることはできる。エージェントが失敗するたびに、どのツマミをどう回せばその失敗が二度と起きなくなるかを考え、設定に落とし込んでいく。それが、ハーネスエンジニアリングの日々の実践だ。

2-4. ベストプラクティスは「容易には出せない」

ここで一つ、注意すべき性質がある。Claude Code の中で取れる手段——どのツマミが存在するか——は、みんなが共有している。ドキュメントを読めば、誰でも同じ手段の一覧にアクセスできる。だが、解くべき課題と、その解法は、人によって違う。あなたのチームが抱える課題、コードベースの特性、組織の体制・文化・制度——これらはすべて固有だ。だから「これさえやれば正解」という万能のベストプラクティスは、容易には出せない。手段は共有できても、その手段をどう組み合わせて自分の課題に当てるかは、各自が試行錯誤するしかない。ハーネスエンジニアリングは、本質的にループの営みだ。手段を適用し、評価し、課題からのフィードバックを受け取り、また手段を調整する。このループを回し続ける。だから本稿が焦点を当てるのは「どうすべきか(あなたの正解)」ではなく、「何ができるか(手段の地図)」である。地図を渡すので、目的地は自分で決めてほしい。