Claude Codeのハーネスとは？CLAUDE.md・Skills・サブエージェント・hooksの4点セットを解説

なぜハーネスが必要か — LLMは確率論で動く

単発のタスクでうまくいっても、LLM（大規模言語モデル）は確率論で動くため、実務で使い続けると次のような問題が起きます。

• 入力が少し違うだけで出力が変わる
• 会話が長くなると要領を得なくなる
• 参照資料が増えると参照しなくなる
• 失敗時の再試行をしたりしなかったりする
• 権限や禁止事項を守らなくなる

そこで必要になるのが、コンテキストを適切に組み立て、流し込み、監視し、必要なら修正する枠組み＝ハーネスです。AIエージェントを馬にたとえるなら、ハーネスは馬の性能を最大限に引き出す「馬具」です。

コンテキストエンジニアリングが「AIに何をどう渡すかの設計」だとすると、ハーネスは「その設計を毎回安定して実行し、安全に運用する基盤」であり、両者は不可分の関係にあります。

Claude Codeにおける4つのハーネス

どの仕事をどの層に置くか — AIチームの4層編成

4つのハーネスは「道具の一覧」です。実務で先に決めるのは、その仕事をどの層に置くか。当社が社内の設計基準にしている4層編成モデルを先に共有します。

振り分けの原則はひとつです。判断が要らないものは下の層へ落とす。スクリプトで済む作業をAIにやらせない（遅い・高い・不安定）。逆に、判断が必要な仕事をスクリプトへ無理やり押し込まない。

同じ「レポートを作る」でも、数字を取ってくる部分はスクリプト、読み解いて示唆を書く部分は本体セッションと層が分かれます。ハーネスの整備とは、この線引きを1つずつ決めていく作業でもあります。

① CLAUDE.md — 毎回説明し直す内容を書き留める「憲法」

CLAUDE.mdは、セッション開始時にClaude Codeが必ず読む永続的な指示ファイルです。プロジェクトの目的、フォルダ構成と参照ルール、判断基準、禁止事項——毎回口頭で説明していた前提を書いておくことで、どのセッションでも同じ土台からスタートできます。

全プロジェクト共通のグローバル設定（~/.claude/CLAUDE.md）と、プロジェクト単位の設定（./CLAUDE.md）を使い分けます。書き方の詳細はCLAUDE.mdの書き方で解説しています。

② Skills — 繰り返し作業を定型化する「業務マニュアル」

Skillsは、特定タスクの手順書・チェックリスト・テンプレートをパッケージ化し、必要なときだけClaudeに読み込ませる仕組みです。「請求書作成」「レポート作成」「LP診断」のような繰り返し作業をスキル化しておくと、/skill-name と呼び出すだけで、毎回同じ品質で作業が実行されます。

CLAUDE.mdとの違いは読み込みタイミングです。CLAUDE.mdは毎回読む「憲法」、Skillsは必要時だけ読む「マニュアル」。この分担により、AIが一度に処理する情報量（コンテキストウィンドウ）を節約できます。

作り方はClaude Code Skillsの作り方をご覧ください。

③ サブエージェント — コンテキストを分離する「専門の同僚」

サブエージェントは、特定の役割を持つ専門エージェントをメインのClaude Codeとは別の文脈で動かし、調査・レビュー・分析などを代行させて結果だけを受け取る仕組みです。目的は「関心の分離」。メインの会話を汚さずに専門作業を任せられます。

もうひとつの目的がコンテキストの保護です。サブエージェントには、読み込んだファイルの全文ではなく結論だけを持ち帰らせます。調査で読んだ大量のテキストを本体の会話に流し込まないことが、サブエージェントを使う理由の半分を占めます。

当社が実際に運用しているサブエージェント9本

当社の3リポジトリで動いているサブエージェントは、合計9本です。すべてレビュー・検証の役割で、文章や資料を生成する仕事はいずれも本体セッション側に残しています。

並べると見えてくるのが、1エージェント＝1つの評価軸という原則です。事実が合っているかを見る役と、公開してよいかを見る役を別々のエージェントに割っています。

「なんでもレビューして」と1体に頼むと、どの観点も浅くなります。評価軸が増えたら体を増やすのが正解で、1体を賢くしようとしない。ファクトチェックも、社内資料と照合する版・Webで裏を取る版・官公庁の一次ソースに当たる版と、参照先ごとに分けています。

レビュー役は「観点」と「出力の型」を先に決める

「レビューして」とだけ頼むと、返ってくる指摘は毎回変わります。実際の定義ファイルでは、チェックする観点を番号付きで列挙し、返す形式まで固定しています。公開可否を見る役の観点は次の7つです。

• 個人が特定できる記述 — 実名、ハンドルネーム、職業と地域とエピソードの組み合わせ
• 公表していない事業数字 — 売上・成約率・受講者数など
• 認証情報・内部URL — APIキー、トークン、社内ツールのURL
• 第三者の権利・信頼 — 無断引用、根拠のない他社批判、内輪のやりとりの暴露
• 未公開の予定 — リリース前の講座・価格・キャンペーン
• 取引先との条件に関する情報
• 自社サービスの定義から外れた記述 — 提供していないものを在るかのように書いていないか

出力も「判定: 公開OK / 要修正」＋「深刻度つきの指摘リスト」と決めてあり、問題ゼロのときも観点ごとに1行で理由を書かせます。判定だけ返ってくると、本当に全部見たのか分からないからです。

定義ファイルには迷ったら「要修正」に倒すというルールも書いています。公開後に消しても検索キャッシュや魚拓には残るため、判定が割れたときの倒し方まで決めておく必要があります。

定義ファイルは .claude/agents/agent-name.md に置きます。レビュー・調査・ファクトチェック系のサブエージェントには、ファイルを書き換えられない読み取り専用のツール権限を与えるのが安全運用のコツです。

---
name: publish-safety-review
description: 外部公開ドラフトの公開可否レビュー。「公開してはいけない情報」（個人の特定につながる情報・内部数字・認証情報など）を洗い出す。ドラフト完成後、ユーザーレビューの前に必ず使う。
tools: Read, Grep, Glob
---

tools: に Read Grep Glob しか書いていないため、このエージェントは指摘しかできません。レビュー役に修正まで任せると、生成役と評価役の分離が崩れ、何が問題だったのかが記録に残らなくなります。

description にいつ呼ぶかまで書いているのもポイントです。「ドラフト完成後、ユーザーレビューの前に必ず使う」と条件を明示しておくと、本体セッションが委譲のタイミングで迷いません。さらに詳しい作り方はサブエージェントの作り方で解説しています。

④ hooks — 特定イベントで必ず発動する「自動処理」

hooksは、Claude Codeの特定イベント（ツール実行の前後、応答の終了時など）に反応して、決めた処理を必ず実行させる仕組みです。CLAUDE.mdへの記載が「お願い」であるのに対し、hooksは機械的に強制されるのが決定的な違いです。

• PreToolUse — ツール実行前に発動（危険な操作をブロックできる）
• PostToolUse — ツール実行後に発動（ファイル変更後の自動チェック等）
• Notification / Stop — 入力待ちや応答終了時に発動（通知音を鳴らす等）
• SessionStart — セッション開始時に発動（最新情報の自動読み込み等）

身近な例では「Claude Codeが入力待ちになったら通知音を鳴らす」、法人運用では「秘密情報ファイルへのアクセスを機械的にブロックする」といった使い方をします。セキュリティ用途については法人導入とセキュリティ対策も参照してください。

どこから整備すべきか — 推奨の順序

1. 1CLAUDE.md から始める — 毎回説明し直している前提・ルールを書き出すだけで、体感が大きく変わります
2. 2同じ作業を2回以上依頼したら Skills 化する — 「今やった手順をスキル化して」と伝えるだけで雛形が作れます
3. 3作業が複雑になってきたら サブエージェント で分業する
4. 4確実に守らせたいルールが明確になったら hooks で強制する

重要なのは、最初から完璧なハーネスを設計しようとしないことです。実際に業務で使いながら、「毎回言っていること」をCLAUDE.mdへ、「繰り返す手順」をSkillsへと、運用の中で育てていくのが正解です。

複数のサブエージェントをどう組むか — 門番は並列に置く

レビュー役が2体、3体と増えてきたら、次に決めるのは走らせる順番です。当社の制作フローでは、生成役が作った成果物を、独立した観点の門番へ同時に渡す形にしています。

生成役（本体セッション / Skill）
  → 並列レビュー: ①事実 ②公開可否 ③自社の原則
  → 全員通過で公開へ / 1人でも差し戻しなら理由付きで生成役へ

並列にする理由は速さだけではありません。直列にすると待ち時間が積み上がり、「今回は省略しよう」という誘惑が生まれます。門番は飛ばされた瞬間に意味を失うので、走らせるコストを下げておくことが仕組みの寿命を決めます。

もうひとつの原則は、判定の基準をエージェントの外に置くことです。定義ファイルには手順だけを書き、判断のよりどころになるガイドやチェックリストは別ファイルを正とします。基準を更新するときにエージェントを書き換えずに済みます。

ここまで来ると、ハーネスは「AIに指示を伝える仕組み」からAIチームの編成表に変わります。とはいえ最初の1本は、いま自分が毎回目視で確認していることを1つ切り出すだけで十分です。