Claude Codeハーネス完全ガイド｜仕組み・構成要素・設定手順を解説

AIコーディングツールを比較するとき、多くの方は「どのAIモデルを使っているか」に注目します。しかし実際に開発現場で成果を分けるのは、モデルそのものと同じくらい「ハーネス」の出来です。同じモデルを使っていても、ハーネスの設計と設定次第でAIエージェントの働きぶりは大きく変わります。

本記事では、Anthropic社のAIコーディングエージェント「Claude Code」を題材に、ハーネスとは何か、どんな構成要素があるのか、そして自社の開発環境でハーネスを整備していく手順を、順を追って解説します。

Claude Codeのハーネスとは何か

モデルとハーネスの関係

ハーネス（harness）とは、AIモデルの周囲に組まれた「実行の枠組み」全体を指す言葉です。車にたとえるなら、AIモデルがエンジンで、ハーネスは車体・ハンドル・ブレーキにあたります。エンジンがどれだけ強力でも、車体がなければ荷物は運べません。

Claude Codeの場合、モデル（Claude）が「次に何をすべきか」を考え、ハーネスがその判断を実際の作業に変換します。ファイルを読む、コードを書き換える、コマンドを実行する、テストを走らせる。こうした一つひとつの操作を安全に実行し、結果をモデルに返す往復（エージェントループ）を管理しているのがハーネスです。

ハーネスが担う4つの役割

Claude Codeのハーネスの役割は、大きく次の4つに整理できます。

• ツール実行：ファイルの読み書き、検索、シェルコマンド実行などの「手足」を提供する
• 権限管理：どの操作を自動で許可し、どの操作で人間の確認を求めるかを制御する
• コンテキスト管理：長い作業でも文脈を失わないよう、会話履歴の圧縮や記憶の仕組みを提供する
• 拡張機構：スキル・フック・MCP・サブエージェントなどで、チーム独自の使い方に育てられる

Claude CodeはCLI（ターミナル）だけでなく、デスクトップアプリ、Web版、VS CodeやJetBrainsの拡張機能としても提供されていますが、どの形態でもこのハーネスの考え方は共通です。

ハーネスを構成する主要コンポーネント

ツール群と権限モード

Claude Codeには、ファイル読み取り・編集・検索・Bash実行といった標準ツールが組み込まれています。重要なのは、これらが「権限モード」の管理下にある点です。既定では、ファイルの書き換えやコマンド実行の前にユーザーの承認を求めます。頻繁に使う安全なコマンドは、プロジェクトの.claude/settings.jsonに許可ルールを書いておくことで確認を省略でき、逆に触ってほしくないファイルやコマンドは拒否ルールで防げます。

また、実装前に計画だけを立てさせる「プランモード」もあり、大きな変更ほど「まず計画を確認してから実行させる」という運用がしやすくなっています。

CLAUDE.mdによるプロジェクト知識の共有

ハーネスの中でも費用対効果が高いのが、プロジェクト直下に置くCLAUDE.mdです。コーディング規約、ディレクトリ構成、ビルドやテストのコマンド、やってはいけない操作などを書いておくと、Claude Codeは毎回それを前提として動きます。新しいメンバーに渡すオンボーディング資料をAIにも渡す、というイメージです。書き方のコツはCLAUDE.mdの書き方ガイドで詳しく解説しています。

スキル（カスタムコマンド）で定型作業を仕組み化する

繰り返し発生する作業は、スキルとして.claude/skills/に手順書（SKILL.md）を置いておくと、スラッシュコマンド一つで呼び出せるようになります。たとえば「リリースノートの作成」「定型的なコードレビュー」「ブログ記事の下書き生成」など、社内の定型業務をコマンド化しておけば、担当者が変わっても同じ品質で実行できます。

フック（hooks）による自動化と統制

フックは、ツール実行の前後など特定のタイミングで任意のコマンドを自動実行する仕組みです。「ファイル編集のたびにフォーマッタを走らせる」「特定のコマンド実行をブロックする」といった統制を、AIの気分に任せず確実に効かせられます。設定方法はClaude Codeのhooks解説記事をご覧ください。

MCPとサブエージェントで能力を広げる

MCP（Model Context Protocol）は、外部サービスをツールとして接続するための標準規格です。データベース、社内API、SaaSなどをMCPサーバー経由でつなげば、Claude Codeの「手の届く範囲」を自社の業務システムまで広げられます。詳細はMCPサーバー活用ガイドにまとめています。

さらに、調査や並列作業を別のエージェントに任せるサブエージェント機能を使うと、メインの作業文脈を汚さずに大規模なコードベースの探索や複数タスクの同時進行が可能になります。

ハーネスを整備する実践ステップ

ゼロから完璧を目指す必要はありません。次の順番で少しずつ育てるのが現実的です。

1. CLAUDE.mdを書く：まずはビルド・テストのコマンドと守ってほしいルールを箇条書きで10行程度から。使いながら追記していきます
2. 権限設定を調整する：数日使ってみて、毎回承認している安全な操作を.claude/settings.jsonの許可リストに移します
3. 定型作業をスキル化する：同じ指示を3回書いたら、それはスキルにする合図です
4. フックとMCPで統制・接続を強化する：チーム利用が本格化したら、フォーマッタの強制実行や社内システムとの接続を検討します

中小企業がハーネス整備で得られる効果と注意点

ハーネスの整備は「AIを使える個人」を「AIを使える組織」に変える投資です。CLAUDE.mdやスキルはGitでバージョン管理できるため、ベテランの暗黙知やレビュー観点がファイルとしてチームの資産になります。担当者の退職や異動で運用が止まる、という中小企業にありがちなリスクの軽減にもつながります。

一方で注意点もあります。権限を緩めすぎると、意図しないファイル変更やコマンド実行のリスクが高まります。本番環境に影響する操作は必ず確認を挟む設定を残す、APIキーなどの秘密情報はAIが読めるファイルに置かない、といった基本は押さえておきましょう。導入初期は小さなプロジェクトで試し、権限とルールを固めてから本番のリポジトリに広げる進め方が安全です。

まとめ

Claude Codeのハーネスは、ツール実行・権限管理・コンテキスト管理・拡張機構という4つの役割で、AIモデルの判断を安全な実作業に変換する仕組みです。CLAUDE.md、権限設定、スキル、フック、MCP、サブエージェントといった構成要素を少しずつ整備していくことで、同じモデルでも成果は着実に変わっていきます。

「自社の開発や業務にAIエージェントを組み込みたいが、どこから手を付ければいいかわからない」という場合は、ハーモニックソサエティのIT顧問サービスで導入設計から運用ルールづくりまで伴走支援しています。まずはお気軽にご相談ください。