ハーネスエンジニアリング入門｜Claude CodeのCLAUDE.md・スキル・フックで最初のハーネスを作る

Claude Code で最初のハーネスを作るための入門です。CLAUDE.md・スキル・フック・エージェントの4つを、どの順番で、何を書けばよいかを手順で示します。ハーネスエンジニアリングという言葉の意味・経緯・具体例は ハーネスエンジニアリングとは？AIエージェントのハーネスの意味・具体例・始め方 に、Claude Code の設定全般は Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き にまとめています。

外部ハーネスフレームワーク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ループ（検証→修正→再検証の自律サイクル）が特徴。永続モードと組み合わせることで、長時間バックグラウンドで動き続けるエージェントを構築できる。

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つのセッションにすべての情報を詰め込む必要がない。コンテキスト汚染を防ぎつつ、大規模な並列処理が実現できる。

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

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')"

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

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：インストールから本番運用まで

2026-10-11 に実測で確かめ直した

本記事の対象リポジトリを 2026-10-11 に clone して、ライセンスの実体・更新状況・規模を測り直した。 紹介文やバッジではなく、リポジトリの中身を直接読んだ値だ。

# ① 浅く clone する
git clone --depth 1 https://github.com/walkinglabs/awesome-harness-engineering /tmp/awesome-harness-engineering

# ② 直近のコミット日を見る → 2026-08-19
git -C /tmp/awesome-harness-engineering log -1 --format=%ad --date=short

# ③ ライセンスの実体と規模を見る → Creative Commons / 7 ファイル
head -3 /tmp/awesome-harness-engineering/LICENSE* 2>/dev/null; git -C /tmp/awesome-harness-engineering ls-files | wc -l

③が肝心で、ライセンスは Creative Commonsだった。バッジや README の記述ではなく LICENSE ファイルの中身を読んでいる。

参照ソース

・walkinglabs/awesome-harness-engineering（GitHub） — 本記事が 2026-10-11 に測り直した対象
・LICENSE — ライセンスの実体（手順③で読んだファイル）
・Harnessing Claude’s Intelligence — Anthropic公式ブログ
・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）