Claude Code ハーネス — 4 層設計で成功率が変わる

「ハーネス」とは何か — モデル本体を除く周辺すべて(プロンプト・ツール・FB ループ)

ハーネスとは、Claude Code が長時間タスクを安定して回し続けるための周辺装置の総体 を指します。モデル本体(Claude)は同じでも、その外側をどう組むかで成果物の品質と完了率が大きく変わるという認識が、Anthropic 公式エンジニアリングブログをきっかけに 2025 年後半から急速に広がりました。具体的には次の 5 要素が「ハーネス」に含まれます。

• 指示(システムプロンプト・スラッシュコマンド・タスク文)
• コンテキスト(会話履歴・ファイル読み込み・参照ドキュメント)
• ツール(コード編集・シェル実行・Web 検索・MCP サーバー)
• フィードバックループ(テスト結果・Lint・型チェック・ユーザー修正)
• 永続化(メモリファイル・進捗ログ・Git コミット履歴)

これら 5 要素を どう組み合わせ、どの順番で回すか を体系的に設計することが「ハーネスエンジニアリング」です。馬具(harness)が荷馬車を制御するように、Claude Code に対しても外側の装置で「暴走させず、止めず、目的地まで運ぶ」設計が求められる、というのが命名の由来とされています。

モデル性能とハーネス性能は別物

同じ Claude Opus を使っていても、CLAUDE.md が空のリポジトリと、規約・テスト方針・避けるべきパターンが整理されたリポジトリでは、生成されるコードの一発合格率に大きな差が出ます。これは「モデルの実力」ではなく「ハーネスの実力」の差です。Anthropic 自身も「モデルを更新する以上に、ハーネス側の改善で品質が伸びることが多い」と説明しています。

なぜハーネスが重要か — フロンティアモデルでも単体プロンプトでは本番品質に届かない

モデル性能だけで判断すると、同じ Claude を使っても ハーネスの質 で成果が大きく変わります。Anthropic 公式エンジニアリングブログは、フロンティアモデルであっても「高レベルのプロンプト単体では本番品質のアプリ構築に不足する」と述べており、ハーネス設計が実用上の鍵になることを示しています。短い指示でデモを動かすことはできても、数時間〜数日にわたる開発タスクでは「途中で文脈を失う」「無関係なファイルを書き換える」「テストが落ちても走り続ける」といった問題が積み重なり、最終成果物が本番品質に届かなくなるためです。

同ブログはさらに「単一の汎用構成がすべての文脈で最良のパフォーマンスを発揮するのか、それとも複数の役割を分担する構成によってより高い性能が達成できるのかは、まだ明らかではない」と述べており、ハーネス設計が現在進行中の重要な研究領域であることが示されています。実務上の含意は明確で、「自社のドメイン・コードベース・運用フローに合わせてハーネスを継続的に磨き込む」ことが、汎用モデルを業務水準で使い倒す前提条件になっています。

「指示の質」より「装置の質」が効く理由

人間の開発でも、優秀なエンジニアを雇うだけで生産性が上がるわけではなく、CI / レビュー / Lint / テストの仕組みが整って初めて品質が安定します。Claude Code も同じで、モデル個体の知能を引き上げるより、検証手段(テスト・スクリーンショット差分)・参照ドキュメント(CLAUDE.md・Skills)・記録手段(コミット粒度・進捗ログ)を整備するほうが、結果として ROI が高くなる場面が多いと報告されています。

出典: Anthropic Engineering: Effective harnesses for long-running agents

ハーネス 4 層設計 — ガイド / センサー / ループ / 永続化

ハーネスは「事前にどう導くか(ガイド)」「事後にどう検知するか(センサー)」「どんな手順で回すか(ループ)」「セッションを越えて何を残すか(永続化)」の 4 層で考えると整理しやすくなります。Anthropic 公式の解説と、Claude Code のベストプラクティスドキュメントを突き合わせると、この 4 層がほぼ共通言語として浮かび上がります。以下、層ごとに「具体的に何を整備するか」を見ていきます。

層 1: ガイド(Guides / 事前制御)— CLAUDE.md・Skills・起動プロトコル

事前制御は「タスクを始める前に、Claude Code に渡しておく文脈」のことです。最重要は CLAUDE.md で、プロジェクトの背景・規約・地雷ポイント・避けるべきパターンを 1 ページに集約しておくと、毎回同じ前提を口頭で繰り返す必要がなくなります。Skills は再利用可能な業務手順を切り出した部品で、「画像生成」「記事公開」「DB マイグレーション」のような頻出フローを 1 ファイルにまとめておくと、必要なタイミングで自動的に読み込まれます。

• CLAUDE.md:プロジェクト固有の知識(規約・ドメイン用語・絶対ルール)
• Skills:再利用可能な業務手順(公開フロー・テスト方針・命名規則)
• 起動プロトコル:セッション開始時に必ず確認すべき差分・ロック・進行中タスク

層 2: センサー(Sensors / 事後制御)— テスト・Lint・スクショ比較・CI 結果

事後制御は「Claude Code が書いたものが正しいか」を機械的に判定する仕組みです。これがないと「動いているように見えるが本番で壊れる」コードが量産されます。最低限、ユニットテスト・型チェック・Lint の 3 点セットを通すこと、UI を触る場合はスクリーンショット差分を加えることが推奨されます。CI/CD のステータスを Claude Code 自身が読み取れるようにしておくと、失敗を検知して自動で修正に回す動きまで作れます。

• 自動テスト:ユニット・統合・E2E のいずれかで「壊れたら気づく」状態を作る
• Lint / 型チェック:tsc --noEmit や ruff 等を npm test 相当に組み込む
• スクリーンショット比較:Playwright 等で UI 差分を検知
• CI/CD の結果:gh run view で失敗ログを取り込み、自動再修正に回す

層 3: ループ(Loop / 反復)— Explore→Plan→Code→Commit、Writer/Reviewer 二段

実行フェーズは「いきなり書かせない」ことが鉄則です。Anthropic 公式が推奨する基本ループは Explore → Plan → Code → Commit の 4 ステップで、まずコードベースを読み(Explore)、変更計画を文章化し(Plan)、最小単位でコードを書き(Code)、論理的に閉じた段階でコミットする(Commit)という流れです。長いタスクではさらに、書き手と検証役を分ける二段構成や、計画役・実装役・評価役に分ける三段構成が有効とされ、後者は harness-design-long-running-apps 記事で詳しく扱われています。

• Explore → Plan → Code → Commit:基本の 4 ステップ。Plan 省略は事故の元
• 書き手と検証役の二段構え:同じセッション内で役割を切り替えて自己レビュー
• 計画役 / 実装役 / 評価役の三段構え:長時間タスクで「方向ずれ」を早期検知

層 4: 永続化(Persistence)— Git コミット・progress.txt でセッション間で記憶

セッションが切れても作業を続行できるようにする仕組みです。Claude Code の会話履歴は基本的に揮発するため、「いま何が終わっていて、次に何をすべきか」を外部ファイルに書き出しておくことが重要になります。Git コミットを細かく刻むこと自体が永続化であり、progress.txt や feature-list.json のような進捗ファイルを併用すると、再開時に状況把握のための時間を大幅に削れます。

• Git コミット:論理的に閉じた単位で頻繁にコミット(Plan 完了・テスト緑など)
• progress.txt:現在地・次やること・ブロッカーを 1 ファイルに
• feature-list.json:大規模機能を分割し、完了済みと残タスクを構造化

初心者がまずやる 3 ステップ — インストール → CLAUDE.md → 検証手段の明示

ハーネスエンジニアリングは奥が深い分野ですが、最初の 3 ステップは極めてシンプルです。難しい概念は後回しでよく、まず「自分の手元で Claude Code が動く」「プロジェクトの前提が 1 ページにまとまっている」「タスクごとに合否を機械的に判定できる」の 3 点が揃えば、ハーネスとして最低限の形になります。逆にこの 3 点が欠けたままモデルだけ最新版に乗せ換えても、品質は伸び悩みます。

Step 1: Claude Code を手元にインストール

まずはローカル環境で動かし、自分のリポジトリに対して数タスク投げてみます。「想像と違う動きをした場面」「指示が伝わらなかった場面」をメモしておくと、次の CLAUDE.md 整備に直結します。インストール手順や前提は公式ドキュメントの Best Practices に集約されています。

Step 2: CLAUDE.md を書く

プロジェクトの背景・コーディング規約・触ってはいけないファイル・絶対に守るべき制約を、1 ページ(目安 200〜500 行)で書き出します。完璧を目指さず、「同じ指摘を 2 回した時点で CLAUDE.md に書く」を運用ルールにすると、自然に育ちます。

Step 3: 検証手段を明示してから依頼する

「このタスクは npm test が緑になれば完了」「このページは Playwright スクリーンショットが既存と一致すれば完了」のように、合否判定を先に渡します。検証手段が無い指示は「動いたらラッキー」になりがちで、ハーネスの効果が出ません。テストがない領域でも、実行コマンドや手動確認手順を文章で渡すだけで安定度が上がります。

出典(一次情報)

本記事の作成に直接参照した一次情報源は以下の通りです。最新の正確な情報は各リンク先で必ずご確認ください。

• Anthropic Engineering: Effective harnesses for long-running agents — 長期実行エージェントの課題とハーネス設計手法(公開: 2025-11-26)
• Anthropic Engineering: Harness design for long-running application development — フロントエンド/フルスタック開発における generator-evaluator 構成(公開: 2026-03-24)
• Claude Code Best Practices(公式ドキュメント) — Anthropic 公式の Claude Code ベストプラクティスガイド