【初心者向け】ハーネスエンジニアリング入門｜Claude CodeのAIエージェントを確実に動かす設計技法

この記事ではClaude Codeに特化して解説します。Claude Code全般は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。

ハーネスエンジニアリングとは何か：一言で言うと

「モデルが賢いかどうか」より「環境が信頼できるかどうか」——これがハーネスエンジニアリングの核心だ。

ハーネスエンジニアリング（Harness Engineering）とは、AIエージェントが確実に動作するための「周囲の環境」を設計する実践技法だ。「ハーネス」は馬を制御する馬具が語源で、AIというパワーを制御・誘導する仕組みを指す。

「モデルはインテリジェンスを提供し、ハーネスはコントロールを提供する」——これがAnthropicの公式ドキュメントが示す核心的な考え方だ。どれだけ優秀なモデルでも、ハーネスが不十分なら長期タスクや複雑な推論で確実性を欠く。

プロンプトエンジニアリングとの違いを比較すると：

Claude Codeには、ハーネスを構成するすべての要素があらかじめ内蔵されている。そのため、特別なフレームワークを追加しなくても、設定ファイルを正しく書くだけでハーネスを構築できる。

なぜ今ハーネスエンジニアリングが注目されているのか

AIエージェントが単純なQ&Aを超えて「長期タスク・複雑な推論・ツール連携」を担うようになったことで、プロンプト最適化だけでは限界が顕在化した。

問題はモデルの能力ではなく、実行環境の設計にある。多くのプロダクションAI障害の原因は「モデルの回答が悪かった」より「コンテキスト管理の失敗」「ツール呼び出しの競合」「長期実行時の状態管理」などハーネス側の問題だ。

注目されている3つの背景：

1. AIエージェントの本番利用が加速した：Claude Codeのようなコーディングエージェントが、コードを書いてテストしてコミットするまでを一貫して担うようになった。「動けばいい」ではなく「確実に動く」設計が求められる
2. マルチエージェント化が進んだ：複数のサブエージェントが協調動作するシステムが増え、エージェント間のコントロール層がなければ全体が崩壊するリスクが高まった
3. walkinglabs/awesome-harness-engineeringが整備された：2026年に公開されたこのリポジトリが530件以上のリソースをカテゴリ別に整理し、ハーネスエンジニアリングを体系的な分野として広めた

外部ハーネスフレームワーク4選：選択基準と比較

Claude Code内蔵のハーネス要素を使って自作する方法のほかに、すでに設計が体系化された外部ハーネスフレームワークを採用する選択肢がある。2026年時点で実務採用が進んでいる主要4フレームワークと、選択判断の基準を整理する。

フレームワーク選択の4基準

複数フレームワークを実際に評価した実践者が共通して挙げる判断軸は以下の4点だ。

主要4フレームワーク比較

TAKTは4基準すべてで高水準を実現している。YAMLで定義されたステートマシンが状態遷移をコードで管理するため、遷移条件を満たさない限りエージェントは次フェーズへ進めない。「プロンプトで禁止する」のではなく「プログラムとして不可能にする」アプローチだ。プロバイダー抽象化レイヤーが成熟しており、Claude以外のLLMへの切り替えも設計上容易に実現できる。

Superpowersはサブエージェントの並列実行で強みを持ち、仕様確認→TDD→レビューの7ステップワークフローを自動注入する。Claude Code・Cursor・Codex等の複数ツールに対応しており、LLM非依存性も一定程度確保されている。

ECC（Everything Claude Code）はマニフェストファイルによる設定管理に特化した包括的なハーネスで、大規模チームの設定一元管理に強い。

OMC（oh-my-claudecode）はイベント駆動設計とUltraQAループ（検証→修正→再検証の自律サイクル）が特徴。永続モードと組み合わせることで、長時間バックグラウンドで動き続けるエージェントを構築できる。

TAKT：YAMLステートマシンとPieceEngine

TAKTの核心はPieceEngineだ。「Piece」と呼ばれる作業単位ごとにYAMLで状態遷移を定義し、各フェーズの完了条件が充足されてはじめて次フェーズへ遷移する。

# TAKTのPiece定義（概念例）
piece: code-review
phases:
  - name: analyze
    next: review
    complete_when:
      - file_exists: "analysis.md"
  - name: review
    next: fix
    complete_when:
      - test_pass: "npm test"
  - name: fix
    next: done
    on_failure: review   # 修正後に自動でreviewフェーズへ戻る

takt ejectコマンドを実行すると、内部で使われているPiece定義がすべてプロジェクトにコピーされ、自由にカスタマイズできる。フレームワークのデフォルト動作を理解した上で上書きする設計で、ブラックボックスにならない透明性が特徴だ。

また、カスタムPieceを自作することで独自の自動化を組み込める。例えば「デザインカンプのスクリーンショットと実装結果を反復比較して視覚的な乖離を自動検出するPiece」のように、標準的なテストでは検出しにくい検証もワークフローに組み込むことが可能だ。

Faceted Prompting：ポリシーとビヘイビアを分離する

TAKTが採用するFaceted Prompting（ファセッテッドプロンプティング）は、エージェントへの指示を「ペルソナ」「ポリシー」「ビヘイビア」の3ファセット（面）に明示的に分割する設計技法だ。

従来のプロンプトはこれらが混在しており、手順を変えようとすると意図せずポリシーが崩れるという問題があった。

# Faceted Promptingの構造（CLAUDE.md・スキル設計にも応用可）
persona: |
  シニアソフトウェアエンジニアとして振る舞う
  批判的思考を持ち、コードの品質を最優先する

policy: |
  テストのないコードはコミットしない
  セキュリティチェックは必ず実施する
  本番環境へのデプロイはCIパイプライン経由のみ

behavior: |
  コード変更後は必ずlintを実行する
  エラーが出たら3回まで自律修正を試みる
  修正不能な場合はユーザーに報告して停止する

3ファセットを分離することで「ポリシーを変えずにビヘイビアだけを変える」「ビヘイビアを変えずにペルソナだけを変える」という操作が可能になる。Claude CodeのCLAUDE.md（常時有効なポリシー）とスキル（タスク別のビヘイビア）という設計思想とも完全に共鳴する——この2要素の役割分担は、Faceted Promptingの思想を実装した形と捉えられる。

Claude Codeのハーネスを構成する4つの要素

Claude Codeには最初からハーネスに必要な仕組みが内蔵されている。4つの要素を理解することで、ゼロからハーネスを構築できる。

要素①：CLAUDE.md — 全セッションで読まれる「永続ルール」

CLAUDE.mdはすべてのセッションでClaudeが最初に読む「恒久的なコンテキスト」だ。プロジェクトルートに置いた CLAUDE.md は、Claude Codeが起動するたびに自動で読み込まれる。

# CLAUDE.md の基本構成例（実際のプロジェクトに合わせて書く）

## プロジェクト概要
このリポジトリはECサイトのバックエンドAPIです。Node.js + Expressを使用。

## 重要なルール
- コミット前に必ず `npm test` を実行すること
- TypeScriptファイル編集後は `npx tsc --noEmit` で型チェックを実行
- 外部APIへの直接リクエストは禁止。必ず src/lib/api-client.ts を経由すること

## よく使うコマンド
- テスト: `npm test`
- ビルド: `npm run build`
- ローカル起動: `npm run dev`

書くべき内容は「Claudeが推測できない情報だけ」だ。プロジェクト固有のコマンド、デフォルトと異なるコードスタイル、テスト手順などを書く。コードから読み取れる内容や標準的な慣習は書かなくていい。200行を超えたら @import で分割する。

要素②：スキル（Skills）— 再利用可能なワークフロー手順書

スキルは .claude/skills/<スキル名>/SKILL.md に置く「手順書」だ。/スキル名 で明示的に呼び出すか、エージェントに事前ロードして使う。

# .claude/skills/create-pr/SKILL.md の例
---
name: create-pr
description: 現在のブランチでPRを作成する（テスト・lint・PR作成を一括実行）
argument-hint: "[PRタイトルの補足（任意）]"
allowed-tools: Bash(npm test), Bash(git *), Bash(gh pr create *)
---
以下の手順でPRを作成する:

1. `git status` で変更内容を確認する
2. `npm test` でテストを実行する（失敗したら報告して停止）
3. `git add -p` で変更をステージングする
4. `git commit` でコミットする
5. `gh pr create --fill` でPRを作成する
6. 作成したPRのURLをチャットに報告する

/create-pr と打つだけで、テスト実行からPR作成まで一貫した手順が保証される。

要素③：フック（Hooks）— 決定論的な動作の「保証」

フックは .claude/settings.json に設定する「ライフサイクルスクリプト」だ。

CLAUDE.mdのルールは「アドバイス」だが、フックは「保証」だ。ファイル編集後に必ずlintを走らせたい、危険なコマンドをブロックしたいといった「絶対に守りたいルール」をフックで強制できる。

// .claude/settings.json の例
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'if [[ \"$CLAUDE_TOOL_OUTPUT_FILE\" == *.ts ]]; then npx eslint \"$CLAUDE_TOOL_OUTPUT_FILE\" --fix; fi'"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "python3 .claude/hooks/safety-check.py"
      }]
    }]
  }
}

主要なフックイベント：

要素④：エージェント（Agents）— 独立して動く専門担当者

エージェントは .claude/agents/<名前>.md に定義する「サブエージェント」だ。独立したコンテキストウィンドウで動作するため、メインセッションのコンテキストを汚染せず、専門タスクを切り出せる。

# .claude/agents/security-reviewer.md の例
---
name: security-reviewer
description: コード変更のセキュリティ脆弱性を検査する。auth/paymentコード編集時に自動起動。
tools: Read, Grep, Glob
model: opus
permissionMode: acceptEdits
maxTurns: 20
---
シニアセキュリティエンジニアとして以下を重点的にレビューする：
- SQLインジェクション・XSS・コマンドインジェクション
- 認証・認可の欠陥
- シークレット・クレデンシャルのコード内埋め込み
- 安全でないデータ処理パターン

具体的な行番号と修正案を提示する。

description に PROACTIVELY を含めると、Claude Codeが関連タスクを検出して自動起動する。

Anthropic公式が示す3つの実践パターン

2026年4月にAnthropicが公開した公式ブログ「Harnessing Claude’s Intelligence」では、ハーネス設計においてモデルの能力を最大限に引き出すための3つの実践パターンが示されている。4つの要素を理解した後、この3パターンを実装指針にすることで、より効率的なハーネスを構築できる。

パターン①：Claudeがよく理解するツールから始める

Anthropicが特に強調するのは bash と テキストエディタだ。この2つのツールだけで、Claude 3.5 SonnetはSWE-bench Verifiedで49%を達成している。複雑なカスタムツールを追加する前に「Claudeがすでに理解しているツール」の組み合わせで多くのタスクをカバーできる。スキル・プログラマティックなツール呼び出し・メモリツールはすべてこの基本ツールの延長線上にある。

パターン②：「やめられること」を問う

ハーネスに積み重なった不必要な仮定を取り除くパターンだ。

a) 行動調整をClaudeに委任する：大規模データを渡す前にClaudeにフィルタリングロジックを書かせる。コード実行ツールを提供することで、Claudeが「何を次のステップに渡すか」を自分で判断できる。ハーネス側のコードが減るほど、実行の信頼性は上がる。

b) コンテキスト管理を委任する：コンテキストウィンドウを効率的に使う手法を組み合わせる：

Anthropicの実績では、BrowseCompベンチマークでOpus 4.6がコンテキスト管理の改善により45.3%→61.6%に向上している。

c) 仮定を定期的に再テストする：Anthropicは「Claudeにできないと思っていた仮定は再テストが必要」と明言している。モデルのアップデートに伴い、ハーネス側の複雑な制御が不要になることも多い。

パターン③：ハーネスで境界を慎重に設定する

プロンプトキャッシュを活用する

キャッシュされたトークンのコストは通常の入力トークンの10%だ。以下の4原則でキャッシュヒット率を最大化できる：

キャッシュ最適化4原則
1. 静的コンテンツ（システムプロンプト等）を先頭に配置
2. 動的コンテンツ（ユーザー入力等）を末尾に配置
3. セッション中のモデル切り替えを避ける（キャッシュ無効化のため）
4. ツールの追加・削除を最小化する（ツール定義変更もキャッシュを破棄）

宣言的ツールで境界を明示する

セキュリティ境界・UX・監視可能性が必要なアクション（外部API呼び出し、ファイル編集など）には、汎用の Bash コマンドではなく専用の宣言的ツールを割り当てることが推奨されている。これにより「何が安全で何が危険か」をハーネス層で明確に定義できる。

ステップバイステップで始める：最初のハーネス構築

「完璧なハーネスを最初から作る必要はない。最初の10行のCLAUDE.mdから始めよ」——これがハーネスエンジニアリング実践者のコンセンサスだ。

Step 1: /init でCLAUDE.mdを自動生成する

# Claude Code内でコマンドを実行
/init

プロジェクトルートで /init を実行すると、Claude Codeがビルドシステム・テストフレームワーク・コードパターンを解析してCLAUDE.md の下書きを自動生成する。これを土台に育てる。

Step 2: ディレクトリ構造を確認・整える

.claude/
├── agents/          ← サブエージェント定義（.mdファイル）
├── skills/          ← スキル（/コマンド名 で呼び出し）
│   └── create-pr/
│       └── SKILL.md
├── hooks/           ← フックスクリプト
│   └── scripts/
└── settings.json    ← パーミッション・フック設定

CLAUDE.md            ← 最上位のルールファイル（必須）

Step 3: よく繰り返す作業を1つスキルにする

「毎回同じ手順で実行していること」を1つ選んでスキル化する。例：PR作成手順。

mkdir -p .claude/skills/create-pr

SKILL.mdを上記のフォーマットで作成し、/create-pr で呼び出せるか確認する。

Step 4: 最初のフックを設定する

ファイル編集後に自動でlintを実行する最小限の設定：

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'npx eslint \"$CLAUDE_TOOL_OUTPUT_FILE\" --fix 2>/dev/null || true'"
      }]
    }]
  }
}

Step 5: CLAUDE.mdを間違えるたびに育てる

Claudeが期待と異なる動作をしたとき：

（Claude Codeへの指示例）
「CLAUDE.mdを更新して、同じ間違いを繰り返さないようにして」

これを習慣にするだけで間違い率が目に見えて下がる。Claude Code作者のBoris Chernyが最重要プラクティスとして推奨している方法だ。

詳しいCLAUDE.mdの書き方はClaude Codeベストプラクティス完全ガイド2026年版で解説している。

実践例3選：ハーネスが威力を発揮するシーン

実践例①：コードレビューの自動化

課題: コードを書いた後のセキュリティチェックが抜けがちになる。

ハーネスによる解決:

1. .claude/agents/security-reviewer.md を設置（前掲のエージェント定義）
2. descriptionに「PROACTIVELY invoked when editing auth or payment code」を追加
3. auth/paymentディレクトリのコードを編集するたびに自動でセキュリティレビューが走る

効果: セキュリティチェックが漏れることがなくなる。エージェントが「書いた本人ではない」独立したコンテキストで評価するためバイアスがない。

実践例②：本番環境への誤デプロイ防止

課題: deploy production を誤って実行してしまうリスクがある。

ハーネスによる解決: PreToolUseフックでdeployコマンドをブロックする。

# .claude/hooks/safety-check.py
import sys, json, os

tool_input = json.loads(os.environ.get('CLAUDE_TOOL_INPUT', '{}'))
cmd = tool_input.get('command', '')

if 'production' in cmd or ' prod ' in cmd:
    print(json.dumps({
        "decision": "block",
        "reason": (
            "本番環境へのデプロイはClaude Codeから直接実行できません。"
            "PRをmainにマージしてCIパイプラインから実行してください。"
        )
    }))
    sys.exit(0)

// .claude/settings.json に追加
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "python3 .claude/hooks/safety-check.py"}]
    }]
  }
}

効果: deploy production がハーネス層でブロックされる。Claudeがどれだけ「実行すべき」と判断しても、ハーネスが上書きして阻止する。

実践例③：マルチエージェントリサーチシステム

課題: 大規模な調査タスクを1セッションで処理しようとするとコンテキストが汚染される。

ハーネスによる解決: 役割別エージェントが協調してレポートを作成する。

各エージェントが独立したコンテキストで動くため、1つのセッションにすべての情報を詰め込む必要がない。コンテキスト汚染を防ぎつつ、大規模な並列処理が実現できる。

Claude Codeの内部アーキテクチャ完全解剖では、このようなマルチエージェント設計の基盤となる4層フレームワークを詳しく解説している。

よくある疑問とつまずきポイント

Q: スキルとCLAUDE.mdの使い分けは？

→「常に意識すべきルール」はCLAUDE.mdへ。「特定の作業でだけ使う具体的な手順」はスキルへ。例えば「コミットメッセージはAngular形式を使う」はCLAUDE.mdに書くが、「PRを作成する具体的な手順」はスキルにする。

Q: スキルとエージェントはどう使い分けるか

Q: フックのスクリプトが動かない

→ 実行権限の確認が最初の一手だ。

chmod +x .claude/hooks/scripts/*.sh
# settings.jsonの構文確認
python3 -c "import json; json.load(open('.claude/settings.json')); print('OK')"

Q: ハーネス設定はどこから始めるべきか

→「今最もよく繰り返している作業」を1つスキルにすることが最初の一手だ。それだけでも体感が変わる。次にCLAUDE.mdを /init で生成し、間違えるたびに育てる。フックとエージェントはその後で足りないと感じた時に追加する。

次のステップ：学習リソースとコミュニティ

walkinglabs/awesome-harness-engineering

ハーネスエンジニアリングのリソースを体系化したキュレーションリポジトリ。530件以上のリソースが8カテゴリに整理されている。

初学者には「Foundations」と「Specs, Agent Files & Workflow Design」から入るのが最も効率的だ。

revfactory/harness プラグイン

Claude Codeのプラグインとして、ドメイン固有のエージェントチームの設計・スキル生成を自動化するメタスキル。Build a harness for this project と指示するだけで、6つのアーキテクチャパターン（パイプライン・ファンアウト/ファンイン・エキスパートプール・プロデューサー・レビュアー・スーパーバイザー・階層的委譲）から最適な構成を自動生成する。

Claude Code Auto Modeの設定方法と組み合わせることで、より自律的なエージェント環境を構築できる。

関連記事: Claude Code完全ガイド2026：インストールから本番運用まで

参照ソース

• Harnessing Claude’s Intelligence — Anthropic公式ブログ
• walkinglabs/awesome-harness-engineering — GitHub
• revfactory/harness — GitHub
• Harness Design for Long-Running Applications — Anthropic Engineering
• Claude Managed Agents Overview — Anthropic Docs
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• Extend Claude Code with Skills — code.claude.com
• TAKTを選んだ理由：ハーネスエンジニアリング4フレームワーク比較 — Zenn（purple_matsu1）