← ブログに戻る

AIエージェントのハーネスを構成する6要素 — 10分でCLAUDE.mdを棚卸しするチェックリスト

/ 5分で読めます / ai-agent · harness · claude-code · context-engineering

CLAUDE.md を書き始めて 3 ヶ月経ちました。ある日 hooks の発火ログを眺めていて気づいたのですが、私は 6 要素のうち 2 つを完全に無視していました。「実行駆動」と「トレーシング」です。プロンプトと権限だけをこねくり回して、他は放置していたわけです。

エージェントの挙動が読めない理由の 8 割は、6 要素のうちどれかが欠けているからだと最近は思っています。この記事は、その 6 要素を 10 分でチェックできる形にまとめたものです。

ハーネスは 6 要素で説明できる

Anthropic の Building Effective Agents (2024-12) は「エージェント = モデル + 環境」だと書いていて、LangChain のブログもほぼ同じ整理で「Agent = Model + Harness」と表現しています。この「ハーネス」の中身を分解すると、私の実装経験上、次の 6 つに落ちます。

ハーネスの6要素とClaude Code実装対応

  1. 情報管理: 何を知らせるか (CLAUDE.md / スキル / RAG / メモリ)
  2. 実行駆動: どう動かすか (タスク分割 / 並列 / リトライ / タイムアウト)
  3. 品質検証: 出力をどう検証するか (lint / 型 / テスト / LLM ジャッジ)
  4. トレーシング: 挙動をどう見るか (ログ / トークン / 実行時間)
  5. セキュリティ境界: どこまでやらせるか (permission / サンドボックス / 承認)
  6. ツール定義: 何を触らせるか (関数スキーマ / API / MCP)

「プロンプトエンジニアリング」で盛り上がっているのは主に①だけです。残りの 5 つが薄いと、①をいくら磨いてもエージェントは壊れ続けます。OpenAI が 2025 年に公開した Codex の 100 万行実験も、失敗の大半は「モデルではなくハーネス側」だったと結論付けていました。

Claude Code で各要素はどこに置かれるか

Claude Code を 3 ヶ月動かした私の設定を、6 要素に割り付けるとこんな配置になっています。

要素主な実装ファイル私の 3 ヶ月ログの数値
①情報管理~/.claude/CLAUDE.md / .claude/skills/skill 発火: 平均 6.2 回/セッション
②実行駆動Task / Workflow / Agent ツール並列 agent 起動: 週 47 回
③品質検証pre-commit hook / PostToolUse hookhook fire: 週 218 回 (fail 12)
④トレーシング~/.claude/logs/ / OTel exporter平均トークン/セッション: 82K
⑤セキュリティ境界settings.json permissions / Bash denypermission deny ヒット: 週 34 回
⑥ツール定義MCP サーバ (mcp.json) / built-in toolsMCP handshake: 起動時 27K token

「hooks は書けば動く」と思って書いた PostToolUse の週 12 回の fail が全部同じスキル起因だったり、MCP のハンドシェイクだけで 27K トークン食っていることが可視化されて初めて分かる、みたいなことが 6 要素それぞれで起きます。まず全部を数値化しないと、どこから直せばいいか分からない。

10 分棚卸しチェックリスト

以下を上から順に確認します。全部で 10 分を目標にします。時間を計ってやると、6 要素のうちどこに時間を溶かしているかで私のハーネスの弱点が分かります。

①情報管理 (2 分)

  • ~/.claude/CLAUDE.md は 200 行以内か (超えていると先頭しか読まれない可能性)
  • プロジェクト側の CLAUDE.md に「やってはいけないこと」節があるか
  • スキルは SKILL.md の description が 1 行で発火条件を明示しているか
  • 使っていないスキルが 3 ヶ月以上残っていないか (棚卸しでコンテキスト圧縮)

②実行駆動 (2 分)

  • 長時間タスクを Bash run_in_background で回しているか、それとも同期で待たせているか
  • 並列で回せる調査を Agent に投げているか (逐次で回しているなら要改善)
  • 各ツールのタイムアウトが設定されているか (未設定だと無限待ち)

③品質検証 (2 分)

  • pre-commit / PostToolUse hook が動いているか
  • fail 時のログが ~/.claude/logs/ などに残っているか
  • hook が「うるさすぎて無視される」状態になっていないか (週 100 回超は要調整)

④トレーシング (1 分)

  • トークン消費のログを 1 週間で 1 回でも見たか
  • 「一番トークンを食っているセッション」が特定できるか
  • エラーログが「何をしていたときのエラーか」まで残っているか

⑤セキュリティ境界 (2 分)

  • settings.json の permissions.deny に「削除系」「push 系」が入っているか
  • MCP サーバの権限が最小になっているか (フル権限のまま置いていないか)
  • 承認が必要な操作 (git push など) がスクリプト経由で bypass されていないか

⑥ツール定義 (1 分)

  • MCP サーバの description が「エージェントに読ませて分かる」書き方になっているか
  • 起動時のツール一覧が肥大化していないか (未使用は外す)
  • built-in tool と MCP tool の役割が重複していないか

6 要素の重み付けは用途で変わる

チェックリストは全部やらなくてもいいのですが、どこに重心を置くべきかは用途で違います。私は 3 ヶ月動かしてみて、こんな感触になりました。

ユースケース特に重い要素私の失敗パターン
コーディングエージェント③品質検証 + ⑤権限hook が緩くて壊れた PR が出た
コンテンツ生成①情報管理 + ③検証persona が薄くて機械的な文章が出た
業務自動化②実行駆動 + ④トレーシングリトライ未設定で夜中に止まっていた
データ分析⑥ツール定義 + ④トレーシングMCP 定義が曖昧で誤ったカラムを select

「エージェントが遅い」と感じるとき、大抵②が薄い。「エージェントが暴走した」ときは⑤が薄い。「何が起きたか分からない」ときは④が薄い。要素で切り分けるだけで、直すべき場所がだいたい特定できます。

昨日 (7/11) の話とつながるところ

昨日書いた 自己進化エージェントを 3 ヶ月動かしたら 2 回ロールバックした の話は、6 要素の話でいうと「①情報管理を自分で書き換える機構を足したら、⑤セキュリティ境界を踏み抜いた」に整理できます。要素をまたぐ変更をするときは、他の 5 要素に影響が飛ぶ前提でチェックリストを再走するのが安全でした。

まとめ

  • ハーネスは 6 要素 (情報 / 実行 / 検証 / トレース / 権限 / ツール)
  • 「プロンプトを頑張る」は①だけの話。他 5 つが薄いと壊れる
  • 10 分の棚卸しで、自分の CLAUDE.md がどこを無視しているか分かる
  • 私は「実行駆動」と「トレーシング」を無視していました。あなたはどこですか?

ハーネス 6 要素をもっと深く掘りたい方は ハーネス・エンジニアリング にまとめています。OpenAI / Anthropic / LangChain / Martin Fowler / アカデミアの 5 系統の解釈を 1 冊に統合した、AI エージェントを本番運用するための体系書です。

関連する記事

記事一覧を見る →