この記事の主張はタイトルに表れている。コーディングエージェントが指示を無視し、危険なコマンドを実行し、堂々巡りをするのを 1 年間見てきた著者らは、問題はモデルではなくその設定にあるという結論に何度も行き着いた。記事によれば、より賢いモデルはいくつかの失敗モードをなくすだろうが、今度はより大きな問題を与えられ、新しい予想外の形で失敗する。だから有益な問いは、今日のモデルから最大限を引き出すにはどうすればよいかである。記事はこれを「コーディングエージェント = AI モデル + ハーネス」とまとめている。ここでいうハーネスとは、スキル、MCP サーバー、サブエージェント、メモリ、AGENTS.md ファイルなど、エージェントの設定面のことである。
記事は、ハーネスエンジニアリング という用語は Viv が作ったものだとし、これらの設定ポイントを活用してコーディングエージェントの出力の品質と信頼性を高める実践だと説明する。そして、これを コンテキストエンジニアリング の一部 ── ハーネスの設定ポイントを使ってコーディングエージェントのコンテキストウィンドウを管理する部分 ── として位置づけている。記事の残りでは、各設定面を順に取り上げ、HumanLayer 自身の実践を紹介している。
要点
- 最初にカスタマイズすべきは CLAUDE.md / AGENTS.md ファイル（CLAUDE.md と AGENTS.md を参照）である。これはリポジトリの最上位に置く Markdown ファイルで、ハーネスがエージェントのシステムプロンプトに注入する。記事は、以前の 良い CLAUDE.md の書き方 で示した自らの助言 ── ファイルを自動生成しない、簡潔で普遍的に当てはまる内容に保つ、段階的開示を使う ── を改めて述べ、HumanLayer 自身の CLAUDE.md は 60 行未満だとしている。
- MCP サーバーはツールのためのものである。そのツール説明はシステムプロンプトに注入されるため、ツールが多すぎるとエージェントは「ダムゾーン」へと押しやられ、信頼できないサーバーはプロンプトインジェクションの経路になる。MCP サーバーが、学習データによく現れる CLI（GitHub、Docker、ほとんどのデータベース）と機能が重なる場合、著者らは、エージェントに CLI を使うよう促すほうがうまくいくことを見いだした。彼らは Linear の MCP サーバーを、CLAUDE.md に記述した小さくコンテキスト効率のよい CLI に置き換えた（Model Context Protocol を参照）。
- スキルは、段階的開示を通じて再利用可能な知識とツールを提供するためのものである。エージェントは、必要だと判断したときにだけ特定の指示やツールを受け取る（Agent Skills と 段階的開示（Progressive Disclosure） を参照）。記事は、スキルのレジストリが悪意あるスキルを配布していたことが発覚した例があると警告し、インストールする前にスキルの中身を読むよう勧めている。
- サブエージェントはロールプレイのためではなく、コンテキストを制御するためのものである。「フロントエンドエンジニア」や「バックエンドエンジニア」といったサブエージェントは著者らの場合うまくいかなかった。一方、サブエージェントを「コンテキストファイアウォール」として使う ── 親は自分が書いたプロンプトと要約された結果だけを見る ── と、多数のコンテキストウィンドウにわたって親スレッドの一貫性が保たれる。著者らはこれを、コンテキストが長くなるほどモデルの性能が落ちることと結びつけている（コンテキストロット を参照）。また、コストを抑えるため、サブエージェントには親セッションより安価なモデルを使っている。
- フックは制御フローのためのものである。エージェントのライフサイクルの特定の時点で実行されるユーザー定義のスクリプトで、通知、ツール呼び出しの自動承認・拒否、外部連携、検証に使われる。記事の例のフックは、Claude が停止したときにフォーマッタと型チェックを実行し、成功時には何も出力せず、失敗時には終了コード 2 を返して、ハーネスがエージェントにエラーを修正させるようにする（エージェントフック を参照）。
- バックプレッシャー：記事は、コーディングエージェントで問題を解決できる可能性は、エージェントが自分の作業を検証できる能力と強く相関すると述べ、テストと検証の仕組みをチームがこれまでに作ったものの中で最もレバレッジの高いものの 1 つと呼び、それらをコンテキスト効率のよいものにすることを強く求めている（バックプレッシャー と コーディングエージェントのためのコンテキスト効率の良いバックプレッシャー を参照）。
- ポストトレーニングについては、モデルはポストトレーニングで使われたハーネスの中でより良い性能を発揮しうることを認めつつ、モデルがそのハーネスに過剰適合しうる以上これは両刃の剣であり、ハーネスをカスタマイズせずにおく理由にはならないと論じている。
背景
これらの推奨事項は、「数十のプロジェクトと数百のエージェントセッション」にわたる HumanLayer 自身の経験から来ており、記事はチーム自身による、うまくいったこと・いかなかったことの一覧で締めくくられている。最初から理想的なハーネスを設計したり、「念のため」に多くのスキルや MCP サーバーをインストールしたりするのではなく、シンプルに始め、エージェントが実際に失敗したときにだけ設定を追加せよ、というものである。記事は自らを、ハーネスに関する Viv 自身の著作の姉妹編と位置づけ、Viv があまり強調していないとする 2 つのレバー ── 決定的な制御フローのためのフックと、知識の段階的開示のためのスキル ── を付け加えている。関連ページとして エージェントハーネス と コーディングエージェントのための高度なコンテキストエンジニアリング がある。