「プロンプトをどれだけ磨いても、AIの動きが安定しない」——そんな悩みを抱えながら、私はここ数ヶ月ずっとClaude Codeと格闘していました。
指示を丁寧に書けば書くほど、なぜかAIは迷走する。想定外のファイルを書き換える。確認してほしいのに勝手に進める。「自分の指示が悪いのか」と自己嫌悪に陥りながら、プロンプトを書き直す日々。
そんなときに出会ったのが「ハーネスエンジニアリング」という概念です。
2026年2月、OpenAIがCodexエージェントを使って100万行のコードを「人間の記述ゼロ」で生成したと発表しました。その成功の鍵として挙げたのが、AIに「働ける環境」を設計するという発想——ハーネスエンジニアリングです。
この記事では、ハーネスエンジニアリングとは何かを定義から丁寧に解説し、Claude Codeで実際に使える実践手順まで紹介します。AIコーディングツールを使い始めたものの「なんかうまくいかない」と感じている方に、特に読んでほしい内容です。
ハーネスエンジニアリングとは——定義と登場した背景
ハーネスエンジニアリングとは、AIエージェントが動作する「環境そのもの」を設計する技術領域です。AIに何を見せ、何をさせ、どう評価し、どこまで許可するかを設計して、能力を安全かつ再現性高く引き出すことを目的としています。
OpenAIが100万行を「人間記述ゼロ」で生成した衝撃
2026年2月にOpenAIが発表した内容は、業界に大きな衝撃を与えました。Codexエージェントを活用して100万行のコードを生成したのですが、そこで強調されたのがモデルの性能ではなく「エージェントが働く環境の設計」でした。
「Agent = Model + Harness」——この方程式が、ハーネスエンジニアリングの本質を一言で表しています。同じモデルでも、ハーネスの設計次第でパフォーマンスが劇的に変わる。LangChainがTerminal Bench 2.0でモデルを変えずハーネスだけを改善し、スコアを52.8%から66.5%に引き上げた事例も報告されています。13.7ポイントの差は、すべてアーキテクチャの改善によるものです。
「いいプロンプトを書けばAIは賢くなる」という時代は、すでに終わりつつあります。
ハーネスとは何か——エージェントを包む制御環境の正体
「ハーネス（harness）」は本来、馬具や安全帯を指す英語です。動物や人間の力を安全に制御しながら、目的に向けて活用するための道具——AIの文脈でも、この意味そのままです。
具体的には、AIモデルと外部の世界の間に挟まる「制御システム」がハーネスです。エージェントが取れる行動の範囲を定め、結果を監視し、問題があれば介入する。言ってしまえば「AIを飼いならすための檻と鎖と餌箱を全部まとめて設計する仕事」です（表現は悪いですが、意外とこの例えがしっくりきます）。
ハーネスはAIに「こう動け」と命令するのではなく、「この範囲でしか動けない」という環境を作ります。そこが、プロンプトやコンテキストとは根本的に異なる点です。
プロンプト・コンテキスト・ハーネスの3段進化
AIエンジニアリングには「プロンプト→コンテキスト→ハーネス」という3つの段階があります。それぞれの違いを整理しておくと、ハーネスエンジニアリングがなぜ必要なのかがよくわかります。
プロンプトエンジニアリング——「言葉」でAIを動かす時代
プロンプトエンジニアリングは、AIへの「指示文」を工夫することで出力を改善する手法です。「ステップバイステップで考えてください」「あなたは専門家です」のように、言葉の力でAIの思考を導きます。
単発の質問応答には非常に効果的ですが、複数ステップにわたる自律的なタスクになると限界が見えてきます。会話が長くなるにつれ指示を忘れる。毎回同じルールを書き直す必要がある。「これをやったらダメ」と言っても、やってしまう。プロンプトは「提案」であり、「強制」ではないからです。
コンテキストエンジニアリング——「情報」でAIを動かす時代
コンテキストエンジニアリングは、AIが判断するために必要な「情報」を整えることに焦点を当てた手法です。どのドキュメントを見せるか、どのコードを渡すか、どの過去履歴を含めるかを最適化します。
プロンプトよりも一歩進んでいて、RAG（検索拡張生成）やメモリ管理もここに含まれます。ただ、これも本質的には「AIに正しい情報を与えること」であり、AIの「行動範囲」や「承認フロー」を制御するものではありません。
ハーネスエンジニアリング——「環境」でAIを制御する時代
ハーネスエンジニアリングは、AIが動作する環境全体を設計します。プロンプトとコンテキストは「AIへの提案・情報提供」ですが、ハーネスは「強制と観測」です。
| 手法 | 何を最適化するか | 制御の強さ |
|---|---|---|
| プロンプトエンジニアリング | 指示文・言葉の工夫 | 弱い（提案） |
| コンテキストエンジニアリング | AIに渡す情報の質と量 | 中程度（誘導） |
| ハーネスエンジニアリング | AIが動ける環境・制約・観測 | 強い（強制・制御） |
3つは対立するものではなく、積み重なる層です。プロンプトとコンテキストを土台にしながら、ハーネスがその上に「守られた実行環境」を作る——そういうイメージです。
ハーネスの3つの構成要素を詳しく見る
ハーネスエンジニアリングを構成する要素は、大きく3つに整理できます。この3要素を押さえると、「何を設計すればいいか」が見えてきます。
ルールファイル——AIへの行動規範を明文化する
ルールファイルは、AIエージェントが守るべき規約を文書として明文化したものです。「本番環境のファイルは直接編集しない」「コミット前にテストを必ず実行する」「ユーザーへの確認なしに外部APIを呼び出さない」——こうした行動規範を言語化して、AIが参照できる場所に置きます。
プロンプトの中に埋め込むのと何が違うのかというと、永続性と構造化です。プロンプトは会話ごとに書き直す必要がありますが、ルールファイルはコードベースに存在し続けます。チームで使う場合、ルールファイルはGitで管理でき、更新履歴も残ります。
Claude Codeの場合は CLAUDE.md がこのルールファイルに相当します。私は自分のプロジェクトで実際に使っていますが、「ここに書けばAIが毎回読んでくれる」という安心感は想像以上に大きいです。
フィードバックループ——出力を自動で検証・修正する
フィードバックループは、AIの出力を自動で評価し、問題を検知する仕組みです。ビルドエラーが出たらAIに知らせる、テストが失敗したら原因と一緒にフィードバックする、コードのリントエラーを自動で返す——こういった仕組みを指します。
人間がAIの出力を目で見て評価して返答するのは、スケールしません。フィードバックループを自動化することで、AIは「失敗→修正→再試行」のサイクルを人間の介入なしに回せるようになります。CI/CDパイプラインをAIエージェントの自己修正ループとして機能させるイメージです。
これがないと、AIは「なんとなく完成した気がする出力」を返し続けます。フィードバックループこそが、エージェントを「一発勝負の助手」から「継続的に動く実行者」に変えるものです。
コンテキスト管理——AIが正しく判断できる情報を渡す
コンテキスト管理は、AIが適切に判断するために必要な情報を、タイミングよく・過不足なく提供する仕組みです。ハーネスの文脈でのコンテキスト管理は、「情報を渡す」だけでなく「いつ・どの情報を渡すか」の設計を含みます。
コンテキストウィンドウには限りがあります。全部詰め込めばいいわけじゃない。関連性の低い情報でトークンを使い切ると、AIはかえって判断を誤ります。必要な情報を必要なタイミングで渡す——これはエンジニアがしっかり設計しないといけない部分です。
セッションをまたいだ記憶管理も含まれます。前回の会話で決まったアーキテクチャ方針を今回のセッションに引き継ぐ仕組みは、コンテキスト管理の典型例です。
Claude Codeで実践するハーネス設計の4ステップ
ここからは、Claude Codeを使って実際にハーネスを設計する手順を紹介します。完璧な設計を最初から目指す必要はありません。小さく始めて、観測しながら育てていくのがポイントです。
ステップ1：CLAUDE.mdでルールを明文化する
まず、プロジェクトルートに CLAUDE.md を作成します。Claude Codeはセッション開始時にこのファイルを自動で読み込みます。ここに書いたルールは、毎回プロンプトに貼り付ける必要がなくなります。
最初に書くべき内容は3つです。
- プロジェクトの概要：何を作っているか、ディレクトリ構成の基本
- やってはいけないこと：本番環境への直接操作、特定ファイルの上書き禁止など
- コーディング規約：命名規則、コメントの言語、テストの書き方
さらに .claude/rules/ ディレクトリを使えば、トピック別にルールを分割管理できます。「Gitの操作ルール」「APIの呼び出し制限」「秘密情報の取り扱い」などを別ファイルに切り出すと、メンテナンスしやすくなります。私のプロジェクトでも、ファイルの種類ごとに自動ロードされるルールを分けています。
ステップ2：permissionsで実行範囲を絞る
Claude Codeの settings.json でpermissionsを設定すると、AIが実行できるコマンドの種類を制限・許可できます。
{
"permissions": {
"allow": [
"Bash(git status)",
"Bash(git diff*)",
"Bash(pytest*)"
],
"deny": [
"Bash(rm -rf*)",
"Bash(git push --force*)"
]
}
}
「許可リスト（allow）」と「拒否リスト（deny）」の2種類を使い分けることで、AIが意図しない操作をできない環境を作れます。特に破壊的なコマンド（rm -rf や git push --force）は明示的に禁じておくのが無難です。
permissionsは「言葉で禁じる」のではなく「物理的に実行できなくする」ものです。ここがルールファイルとの大きな違いです。
ステップ3：hooksでフィードバックを自動化する
hooksは、Claude Codeが特定のアクションを取ったときに自動でシェルコマンドを実行する仕組みです。たとえば「コードを書いたら自動でリントを走らせる」「ファイルを保存したらテストを実行する」といった自動フィードバックを実現できます。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "cd $PROJECT_ROOT && pre-commit run --files $TOOL_OUTPUT_FILE 2>&1"
}
]
}
]
}
}
このhookを設定すると、AIがファイルを編集するたびにpre-commitが走り、リントエラーがあればその結果がAIへのフィードバックとして返ります。「書く→チェック→修正→書く」のループが自動で回り始めます。
hooksを仕込んで初めて、AIが「自律的に品質を保ちながら動く」感覚を実感できます。ここまで来ると、ハーネスの価値がようやく体感できます。
ステップ4：観測して継続的に改善する
ハーネスは作って終わりではありません。AIがどんな判断をしたか、どこで詰まったか、どんなエラーが出たかを観測し、継続的に改善していく必要があります。
具体的には、以下の3つを定期的に見直します。
- CLAUDE.mdのルールが実態と乖離していないか
- permissionsで不必要に制限していることはないか（あるいは緩すぎる箇所はないか）
- hooksのフィードバックがAIに正しく届いているか
「AIが同じミスを繰り返す」と感じたとき、多くの場合は「ルールが曖昧」か「フィードバックが届いていない」かのどちらかです。プロンプトを直すより先に、ハーネスを見直すクセをつけるといいです。
ハーネス設計でやりがちな3つのミス
ハーネスエンジニアリングは「設計すればするほど良い」わけではありません。私自身も最初にいくつかの失敗をしたので、同じ轍を踏まないように共有します。
ルールを詰め込みすぎてAIが身動きできなくなる
「CLAUDE.mdにすべてを書けば完璧なはず」と思い、禁止事項を100行以上書き連ねた時期がありました。結果は逆効果でした。AIがルールの解釈に迷い、シンプルな作業でも必要以上に確認を求めてくる。自律性がまったくなくなりました。
ルールは「必要最小限」が基本です。「絶対にやってはいけないこと」だけを書き、「できればこうしてほしいこと」はプロンプトで伝えるほうがうまく機能します。ルールが多すぎると、AIはルールの整合性を保つために思考リソースを使い果たします。
フィードバックなしで放置して想定外の動きを招く
もう一つのよくある失敗は「ハーネスを作ったから大丈夫」と安心して放置することです。フィードバックループがない状態でAIに長時間の自律タスクを任せると、最初の判断ミスが雪だるま式に膨らみます。
AIは「失敗している」と気づかないまま進み続けます。人間でいう「現場の感覚」がないので、フィードバックがないと方向修正もできません。テストやリントといった自動検証を必ずフィードバックループに組み込み、AIが「自分の出力が正しいかどうか」を判断できる状態を作ることが重要です。
モデルを変える前にハーネスを見直すべき理由
「このモデルはダメだ、別のモデルに変えよう」と思ったとき、実はハーネスの問題だった——というケースが意外と多いです。前述のLangChainの事例が示すように、モデルを変えずにハーネスを改善するだけで13.7ポイントの性能向上が得られた実例があります。
モデルの変更はコストが高いです。API料金も変わるし、プロンプトの調整も必要になります。「うまくいかない」と感じたら、まずハーネス（CLAUDE.md・permissions・hooks）を見直すのが正しい順序です。環境を整えてからでないと、どのモデルを使っても同じ結果になります。
よくある質問（FAQ）
ハーネスエンジニアリングについてよく聞かれることをまとめました。
ハーネスエンジニアリングとプロンプトエンジニアリングの違いは？
プロンプトエンジニアリングはAIへの「言葉の入力」を最適化する手法で、制御は「提案」レベルです。ハーネスエンジニアリングはAIが動く「環境・制約・観測」を設計するもので、制御は「強制・物理制限」レベルです。プロンプトはAIに「こうしてほしい」と伝えますが、ハーネスはAIが「これしかできない」状態を作ります。
ハーネスエンジニアリングはどんな人に必要ですか？
AIコーディングツール（Claude Code・Cursor・Copilotなど）を日常的に使っているエンジニアは全員に関係します。特に、複数ステップにわたるタスクをAIに任せたい人、チームでAIエージェントを共有して使いたい人、AIの動きが安定しないと感じている人に効果的です。
ハーネスを一から作るのは難しいですか？
難しくありません。Claude Codeの場合は CLAUDE.md を1ファイル作ることがハーネスの第一歩です。最初は「やってはいけない3つのこと」を書くだけでも十分効果があります。完璧なハーネスを一度に作ろうとせず、使いながら少しずつ育てていくアプローチが現実的です。
Claude CodeのCLAUDE.mdとhooksは同じ概念ですか？
いいえ、役割が異なります。CLAUDE.md はルールファイルで、AIが参照する「行動規範」です。hooksはイベントトリガー型のフィードバックループで、AIのアクションに応じて自動でコマンドを実行します。CLAUDE.md が「憲法」なら、hooksは「自動警備システム」のようなイメージです。
OpenAIとAnthropicでハーネスの考え方に違いはありますか？
概念は共通ですが、実装の言語が異なります。OpenAIはCodex向けに汎用的なハーネス設計を提唱し、AnthropicはClaude Code向けに CLAUDE.md・permissions・hooks・MCPという具体的な実装レイヤーを提供しています。どちらも「Agent = Model + Harness」という基本方程式に基づいています。
まとめ——今日からできるハーネスエンジニアリングの第一歩
ハーネスエンジニアリングとは、AIエージェントが動作する「環境そのもの」を設計する技術です。プロンプトで言葉を磨くことよりも、AIが正しく動ける構造を作ることに注力する——この発想の転換が、AIコーディングの生産性を大きく変えます。
- ハーネスエンジニアリングは「AIの環境設計」であり、プロンプトより強い制御ができる
- 3要素はルールファイル・フィードバックループ・コンテキスト管理
- Claude Codeでは
CLAUDE.md・permissions・hooksが実装の核心 - 「うまくいかない」と感じたら、モデルより先にハーネスを見直す
- 最初のステップは
CLAUDE.mdに3つのルールを書くことだけでいい
「AIに任せたら大変なことになった」という経験をしたことがあるなら、それはたいていハーネス不足のサインです。完璧な設計は後から来る。まずは今日、 CLAUDE.md を1ファイル作ることから始めてみてください。
