【魔法の記事】Claude Code ハーネスエンジニアリング 完全ガイド

この記事は「魔法の記事」です。 読者のみなさんのコメントが、AIの多段レビューを経て自動的に本文へ反映されます（不適切・無関係な内容は反映されません）。
更新はおおよそ 毎日 0:30 / 8:30 / 16:30 ごろ（JST） です。あなたのコメントが、この記事を育てます。

目次

• はじめに
• ハーネスエンジニアリングとは
• CLAUDE.md の設計
• ペルソナシステム
• サブエージェント委譲
• トークン・コスト管理
• Loop による定期・自走タスク
• Claude Design とフロントエンド設計、Claude Code 連携
• まとめ

はじめに

Claude Code を業務に組み込んで継続的に利用していくと、いくつかの実務的な課題が顕在化します。代表的なものは次の3つです。

• 出力のブレ: 同じ依頼でも、出力の粒度や形式が安定しない
• 長文会話での品質低下: 会話のターンが積み重なるにつれて、指示の遵守度や精度が下がる
• トークンコストの膨張: 文脈を都度与え直すことで、トークン消費がふくらむ

これらは個々のプロンプトを改善するだけでは解消しにくく、AI に作業をさせる「環境」そのものの設計に起因します。

この環境設計に対する体系的なアプローチが「ハーネスエンジニアリング」です。ハーネス（harness）は本来「馬具」を指す語であり、手綱や引き具によって馬の力を抑え込むのではなく、制御しながら目的の方向へと安全かつ効率的に引き出す道具を意味します。この語義が、AI の能力を扱う比喩としてそのまま当てはまります。

Claude Code におけるハーネスとは、AI の能力を安全・確実・低コストに引き出すための「環境設計」全体を指します。具体的には、プロジェクトの前提や規約を伝える CLAUDE.md、応答の役割や観点を定めるペルソナ、重い処理や専門的な処理を切り出すサブエージェントへの委譲ルール、再利用可能なスニペット、実行可能な操作を制限するパーミッションなどが含まれます。これらを個別の小技として散発的に使うのではなく、一貫した体系として設計する行為こそがハーネスエンジニアリングです。

各構成要素は独立して効くわけではなく、相互に補完し合います。たとえばペルソナで出力の方向性を定め、サブエージェント委譲でコンテキストの肥大を防ぎ、パーミッションで安全性を担保するといった具合に、組み合わせて初めて「ブレない・落ちない・かさまない」運用が成立します。本記事冒頭で挙げた3課題は、それぞれ「出力のブレ＝ペルソナと CLAUDE.md」「長文会話での品質低下＝コンパクション対策とサブエージェント分割」「トークンコストの膨張＝トークン管理」という形で、以降のセクションが対応します。

さらにハーネスエンジニアリングは、こうした課題への対処だけにとどまりません。環境を整えたうえでは、エージェントを定期実行・自走させたり（Loop）、デザインとコードのように離れた工程どうしをつないだり（Claude Design 連携）といった、能力を能動的に広げる設計にも踏み込めます。守りの安定化だけでなく、攻めの自動化までを同じ「環境設計」の枠組みで扱える点が、ハーネスエンジニアリングの射程の広さです。

本記事は、このハーネスというメンタルモデルを軸に、Claude Code の各構成要素がどのような役割を担い、どう設計すれば効果的かを整理するリファレンスです。基礎となる構成要素（CLAUDE.md・ペルソナ・サブエージェント委譲・トークン管理）から、エージェントを自走させる Loop、デザインとコードをつなぐ Claude Design 連携まで、以降のセクションで順に解説していきます。

ハーネスエンジニアリングとは

プロンプトエンジニアリングは、1回の発話を最適化する取り組みです。入力（プロンプト）に対してより良い出力を引き出すために、指示の言い回し・例示・制約条件を調整します。最適化の単位は個々の発話に閉じています。

ハーネスエンジニアリングは、その発話を包む環境全体を体系として設計する取り組みです。1回の指示を磨くのではなく、指示が実行される土台（コンテキスト・役割分担・実行権限・再利用部品）をあらかじめ整え、どの発話に対しても安定した品質が出る状態を作ります。最適化の単位が「発話」から「発話を取り巻くシステム」へ移ります。

ハーネスを構成する主な要素は次のとおりです。

要素	役割
CLAUDE.md	常駐ルール・トリガー表・ワークフロー定義
ペルソナライブラリ	役割分離によるバイアス排除と専門化
サブエージェント委譲ルール	どの工程を・どのモデルで・どう独立させるか
スニペット	再利用可能な定型文・引用書式
パーミッション設定	Claude が実行できる操作の明示的な許可範囲

これらは個別の発話ではなく、発話が置かれる「場」を規定します。だからこそ、発話ごとに同じ前提を書き直す必要がなくなります。

設計コストと回収

ハーネスの設計には初期コストがかかります。ルールの言語化、役割の整理、権限範囲の定義など、最初に一定の労力を要します。一方で、継続的に利用する場面では、このコストは回収できます。一度整えた土台は以降のすべての発話で再利用され、設計が積み上がるほど一回あたりの指示は軽くなります。

ハーネスが無い状態では、毎回その都度に頼み方を考え直すことになります。前提条件・役割・制約を発話のたびに記述する必要があり、記述の差異によって出力のブレも増えます。利用頻度が高いほど、ハーネスを設計しておく利点は大きくなります。

CLAUDE.md の設計

何を書くか

CLAUDE.md は起動ごとに読み込まれる常駐ルール集です。エージェントが毎回参照する前提情報を集約する場所であり、内容は「いつ読んでも正しい」ものに限定します。

入れるべき情報は次の4種類です。

• ディレクトリの地図: どこに何があるかの構造。記事・設定・スクリプトの配置を示します。
• トリガー表: 「〇〇と言われたら XXX する」という指示と動作の対応表。
• 常駐ルール: トーン・言語・コーディング規約など、常に適用される制約。
• ワークフロー定義: パイプラインや並列召喚など、定型作業の手順。

一方、入れるべきでない情報は一時的な状態です。PR 番号・今週のタスク・作業中のブランチ名などは、時間とともに陳腐化します。陳腐化した情報は単に古いだけでなく、エージェントを誤誘導する点で有害です。常駐ルールには「いつ読んでも正しい」情報のみを残します。

トリガー表の例

自然言語の指示とエージェントの動作を対応づけておくと、毎回説明せずに意図を解釈・実行できます。

## ユーザー指示 → やること（トリガー表）

| 言われたら | やること |
|-----------|---------|
| 「新しい記事を書いて」 | 記事制作パイプラインを起動 |
| 「レビューして」 | reviewers/experts を並列召喚 → synthesizer で統合 |
| 「投稿した、URLは〇〇」 | frontmatter の id と ARTICLES.md を更新 → コミット |
| 「ネタ思いついた」 | ARTICLES.md の企画バックログに追記 |

この表があれば、ユーザーは短い自然言語で指示するだけで、定義済みのワークフローを呼び出せます。

「リーン（lean）」に保つ規律

CLAUDE.md は肥大するほど価値が下がります。肥大化は読み込みコストの増加、ルール同士の矛盾、優先順位の喪失を招きます。

目安は「1スクロールで概要を把握できる」分量です。この範囲に収めるため、詳細は参照先のファイルへ逃がし、CLAUDE.md 自体は地図に徹します。個別の手順やルールの詳細を本文に書き込むのではなく、「どこを見ればよいか」を示すことに集中します。

ペルソナシステム

複数のサブエージェントに役割を割り当て、執筆・レビュー・企画・調査を分業させる仕組みです。各役割を独立したペルソナ定義ファイルとして管理し、用途に応じて呼び出します。

なぜ役割分離が必要か

生成と評価を同一モデル・同一コンテキストで実行すると、自分の出力に対する批判が甘くなります。同一モデルは直前に生成した内容を前提として保持したまま評価へ移るため、確証バイアスが働き、欠陥を欠陥として検出しにくくなります。

これを避けるには、執筆者と批評者を制度的に分離します。具体的には次の条件を満たすように構成します。

• 執筆担当と批評担当を別ペルソナとして定義する
• 互いの内部的な思考や中間出力を共有しない
• 批評担当には成果物のみを渡し、独立して評価させる

役割を分離することで、バイアスを個々のモデルの善し悪しに依存させず、ワークフローの構造として排除できます。

ライブラリの構成

ペルソナはディレクトリ単位で役割を分類し、ファイルとして管理します。

personas/
  INDEX.md           # 全ペルソナ一覧・推奨モデル・用途
  writers/           # 執筆担当
    tech-writer.md
    storyteller.md
  reviewers/         # レビュー担当
    logic-reviewer.md
    tone-reviewer.md
    rights-citation-reviewer.md
  planners/          # 企画担当
  researchers/       # 調査担当
  experts/           # ドメイン専門家
  meta/              # 統合担当
    review-synthesizer.md

各ペルソナファイルには、役割・制約・出力形式を記述します。このファイルがそのままサブエージェントへのインストラクションとして機能し、呼び出されたエージェントは定義に従って振る舞います。役割ごとにファイルを分けることで、責務の境界が明確になり、再利用と差し替えが容易になります。

INDEX.md パターン

ペルソナ数が増えると、どの役割にどのモデルを割り当てるかの選定がコストになります。INDEX.md に全ペルソナを一覧化し、推奨モデル列を持たせることで、この選定コストをゼロにします。

ペルソナ	用途	推奨モデル
tech-writer	技術記事の執筆	sonnet
logic-reviewer	論理・構成の批評	sonnet
review-synthesizer	複数レビューの統合	opus

用途の複雑さに応じてモデルを割り当てます。執筆や個別レビューには標準的なモデルを、複数レビューの統合のように高い判断力を要する役割には上位モデルを指定します。INDEX.md を参照するだけで適切なペルソナと推奨モデルが決まるため、ワークフロー構築時の判断負荷を抑えられます。

サブエージェント委譲

エージェントを使った執筆ワークフローでは、すべての処理をメイン会話のコンテキスト上で実行する必要はありません。タスクの性質に応じてインライン実行とサブエージェントへの委譲を使い分けることで、品質とコストの両方を最適化できます。

いつ委譲するか

インライン実行（メイン会話でそのまま処理する方式）が向くのは、次のような軽量なタスクです。

• 短い確認や状態の参照
• ファイルの一部を読み書きする単純な操作
• 直後の判断にすぐ使う情報の取得

一方、次のようなタスクはサブエージェントへの委譲が適しています。

• 長い生成タスク: 記事執筆やコード設計など、大量の出力を伴う処理
• 並列実行できる独立タスク: 複数ペルソナによるレビューなど、互いに依存しない処理
• メインコンテキストを汚染したくないタスク: 調査や実験的なコードの試行など、中間生成物が大量に出る処理

3点目のコンテキスト汚染は、委譲を判断する代表的な基準です。長い調査結果や大量のコードをメイン会話にそのまま展開すると、本来集中すべき判断材料の中に中間生成物が混ざり込み、注意が分散して出力品質が低下します。こうした処理をサブエージェントへ切り出すと、中間生成物はサブエージェント側のコンテキストに閉じ込められ、メイン会話には結論だけが返るため、メインを「判断」に集中させられます。

モデル選択の原則

委譲先のモデルは、タスクの難易度に応じて選び分けます。一律に高性能モデルを使うとコストが膨らみ、逆に難しいタスクに軽量モデルを使うと品質が落ちます。

探索・確認・単純なファイル操作  → haiku   （速い・安い）
執筆・設計・レビュー           → sonnet  （バランス）
難しい判断・最終統合           → opus    （最も正確）

調査タスクに opus を割り当てるのはやりすぎで、コストに見合いません。逆に、単純な探索にいつまでも sonnet を使い続けるのも無駄が生じます。タスクの難易度とモデルの性能を対応させることで、ワークフロー全体のコストが変わります。

プロンプト分離

サブエージェントは、メイン会話のコンテキストを共有しません。起動時のプロンプトに、メイン会話に依存した暗黙の前提を混ぜると、サブエージェントはその前提を解決できず、意図しない出力を返します。

悪い例は、メイン会話の文脈に依存した指示です。

先ほどの調査結果を踏まえ、過去の会話も考慮しつつ、
いい感じに記事を書いてください。

「先ほどの調査結果」も「過去の会話」も、サブエージェント側には存在しません。良い例は、トピック・対象読者・出力形式を明示し、そのタスクだけで完結させた指示です。

トピック: エージェント執筆ワークフローのコスト最適化
対象読者: Claude Code を使う中級エンジニア
出力形式: Qiita 向け Markdown、## と ### の見出しを使用
分量: 1500〜2000字、コードブロックを1つ以上含める

サブエージェントへの指示は、そのタスク単体で読んで成立する形にまとめます。

並列実行の活用

独立したタスク、とりわけ複数観点からのレビューは、並列実行がその本質に適しています。

[reviewers/logic-reviewer]      ─┐
[reviewers/tone-reviewer]       ─┤→ meta/review-synthesizer → 最優先1点
[experts/domain-expert]         ─┘

各レビュアーは互いの出力を参照せず、独立して評価します。その結果を review-synthesizer が統合し、最優先で対応すべき1点に絞り込みます。レビューをシリアル（直列）に実行すると、後段の評価者が前段の評価結果を目にして判断を引きずられ、観点の独立性が損なわれます。役割分離が「生成と評価」のバイアスを断つのに対し、並列実行は「評価者どうし」の相互影響を断つ点で、目的が異なります。

トークン・コスト管理

長い作業ほどトークン消費が積み上がり、コストとコンテキスト圧迫の両方に効いてきます。ここでは消費を抑えつつ出力品質を保つための実践を3点取り上げます。

思考は英語・出力は日本語

推論プロセスを英語で走らせると、トークン効率が上がる場合があります。日本語は1トークンあたりの情報密度が低くなる場合が多く、長い推論を日本語で展開すると余分なトークンを消費しがちです。一方で、最終的な出力は読み手に合わせて日本語にする必要があります。効果は環境やモデルに依存するため、実際の消費量を確認しながら調整するのが無難です。

この使い分けは CLAUDE.md に明記しておくと安定します。

# 思考言語
内部推論は英語で行う。最終的な回答・コード・コメントは日本語で出力する。

推論の実況をやめる

「今から〇〇を調べます」「次に△△を確認します」といった中間ステップの実況を出力させる最大の問題は、コンテキスト汚染です。有意義な情報ではない中間思考がメイン会話に混入し、後続のやり取りで参照できる有効なコンテキスト量を圧迫します。トークン消費の増加はその副次効果に過ぎません。委譲パターンで述べたコンテキスト汚染への対処と同じ考え方で、不要な実況はシステムプロンプトで明示的に抑制します。

# 出力スタイル
推論の中間ステップ（「〇〇を調べます」等）は出力しない。
結果と根拠のみを簡潔に返す。

長文会話でのコンパクション対策

会話が長くなると Claude Code はコンテキストを自動圧縮します。この際、プロジェクトの背景や判断の根拠が圧縮で失われることがあります。CLAUDE.md に意図の根拠を残しておくことで、圧縮後も重要な文脈が復元されやすくなります。

# プロジェクト背景
このリポジトリは〇〇を目的としている。△△の判断は□□の制約に基づく。

品質低下を感じたら /compact で手動圧縮を試みるか、新しいセッションを開始してください。

Loop による定期・自走タスク

Loop とは（前提）

/loop は Claude Code に同梱されているスキルで、開いているセッション内でプロンプトを自動的に再実行する仕組みです（Claude Code v2.1.72 以降）。指定したプロンプトやスラッシュコマンドを繰り返し走らせることで、状態確認や定期メンテナンスといったタスクを自走させられます。

タスクはセッションスコープで管理されます。新しい会話を始めると消えますが、--resume / --continue で未失効のセッションを再開すれば復元されます。

動作には2つのモードがあります。

モード	概要
（A）固定インターバル方式	指定した間隔ごとにプロンプトを再実行します。
（B）自走 / self-paced 方式	各反復のたびに Claude が次の実行間隔を自己決定します。

導入方法

呼び出し方によって挙動が変わります。主なパターンは次のとおりです。

入力例	挙動
/loop 5m デプロイが終わったか確認	固定インターバル。間隔を cron 式へ変換してスケジュールします（単位は s / m / h / d）。
/loop デプロイが終わったか確認	インターバルなし＝自走モード。各反復後に Claude が 1 分〜1 時間の範囲で次の間隔を自己決定し、選んだ間隔とその理由を表示します。
/loop	既定のメンテナンスプロンプト（または loop.md）を実行します。
/loop 20m /review-pr 1234	スラッシュコマンド連鎖。保存済みのコマンドを毎反復で再実行します。

※ 固定インターバルでは、秒は分に切り上げられます。7m や 90m のように cron のステップで表しにくい間隔は、最寄りの有効値へ丸められます。

なお、Bedrock / Vertex AI / Microsoft Foundry 上では、インターバルなしのプロンプトは自走モードにならず、固定10分間隔でスケジュールされます。

loop.md は次の順で探索されます。

1. .claude/loop.md（プロジェクト優先）
2. ~/.claude/loop.md（ユーザー）

応用テクニック

• Monitor ツール: 背景スクリプトを走らせ、出力行をストリームできます。固定インターバル・自走モードのいずれでもポーリングを回避でき、トークン効率が良くなります。
• 基盤の cron ツール: CronCreate / CronList / CronDelete がタスク管理の基盤です。各タスクには8文字の ID が割り当てられ、1 セッションあたり最大 50 タスクまで作成できます。
• ワンショットのリマインド: 「15時にリリースブランチを push するようリマインドして」のような自然言語による単発リマインドは /loop を必要とせず、実行後に自動削除されます。
• 他機能との使い分け: 条件達成まで作業を続ける /goal、CI イベントをセッションに push する Channels と用途に応じて使い分けられます。
• 永続化（7日越え）: セッションスコープを超えて永続化したい場合は、用途に応じて次の選択肢があります。

手段	特性
Routines	クラウド実行。最小間隔 1h。/schedule で管理。
Desktop の scheduled tasks	ローカル実行。最小間隔 1m。
GitHub Actions	リポジトリのワークフローとして実行。

• 停止方法: 待機中に Esc を押すと次回起動をクリアできます。自走モードはタスク完了を確認すると次回をスケジュールせず自動終了します。固定インターバル・自走モードのいずれも、明示的に停止しない限り、作成から7日で失効します。
• コスト注記: 各反復は1ターン分のモデル実行となりトークンを消費します。タイトな固定間隔よりも、Monitor や自走モードのほうが省トークンです。

参考: Run prompts on a schedule（Claude Code 公式ドキュメント）

Claude Design とフロントエンド設計、Claude Code 連携

Claude のデザイン関連の全体像

Claude のデザイン関連機能は、おもに2つのプラグインとして整理できます。いずれも Anthropic 公式で提供されています。

frontend-design プラグインは、UI コード生成時の意匠フレームワークです。2パス構成で動作します。

1. 第1パスで、色・書体・余白などを体系化した「デザイントークン」（UI 設計の最小単位）を設計します。色は4〜6色に絞り、書体を表示用・本文用・ユーティリティ用に分け、レイアウトと signature（その UI ならではの特徴的な意匠）を定義します。
2. 第2パスで、ブリーフに対して批評・改訂を行い、計画通りに構築します。

Inter・紫グラデーションといった、いわゆる「AIスロップの指紋」になりがちな汎用的デフォルトに陥らないための指針を備えます。あわせて、レスポンシブ対応・キーボードフォーカス・reduced-motion といったアクセシビリティ面の底上げを図ります。

design プラグインは、Anthropic 公式プラグインです。主に Claude Cowork 向けに提供されます。次の領域をカバーします。

• デザイン批評
• デザインシステム管理
• UX ライティング
• アクセシビリティ監査（WCAG 2.1 AA）
• 調査統合
• 開発ハンドオフ

Claude Design（製品）

Claude Design は、Anthropic Labs が提供するビジュアル制作ツールです。Claude Opus 4.7 を基盤とし、対話を通じてデザイン・プロトタイプ・スライド・マーケティング素材を作成できます。2026年4月17日の公式アナウンス「Introducing Claude Design by Anthropic Labs」でローンチが発表されました。

その後、2026年6月17日の公式ブログ「Claude Design now stays on brand for daily work」で、デザインシステムのインポートや Claude Code との連携を強化する大型更新が発表されています。現在は Claude Pro / Max / Team / Enterprise でベータ提供されています。

Claude Code との連携

design-sync によるデザイン↔コードの往復

2026年6月の更新で、Claude Design と Claude Code をつなぐ design-sync が公式に導入されました。ターミナルから離れずに、デザインとコードを行き来できます。公式ブログで案内されている主な挙動は次のとおりです。

• /design-sync で自分のデザインシステムを取り込み、Claude Design で作るものを既存コンポーネントから始められます。
• デザインシステムは、GitHub リポジトリ・デザインファイル・素のアップロードから取り込めます。
• /design で、ターミナルを離れずにデザインプロジェクトの作成・編集・同期ができます。
• デザインがソフトウェアになる段階では、Claude Code へ引き継げます。スクリーンショットからやり直すのではなく、既存の作業を引き継いで継続します。
• Claude は自分のコンポーネントで構築し、出力をデザインシステムと照合して、見せる前に補正します。

Figma 連携

Figma との連携は、Figma 公式ブログ（2026-02-17）で確認できます。

• 「Claude Code to Figma」により、稼働中の UI（本番 / staging / localhost）を編集可能な Figma フレームへ変換できます。
• Figma MCP サーバーを介して、Figma デザインからコードへの往復が可能です。プロンプトと Figma フレームのリンクを組み合わせて利用します。

出典

• Introducing Claude Design by Anthropic Labs（Anthropic 公式, 2026-04-17）
• Claude Design now stays on brand for daily work（Claude 公式ブログ, 2026-06-17）
• Claude Code to Figma（Figma 公式ブログ, 2026-02-17）
• frontend-design / design … Anthropic 公式プラグイン

Claude Skills でハーネスに「再利用可能な専門性」を組み込む

読者の方から「Claude Skills の情報がまとまっていない。ペルソナプロンプトとも関わる話では」というご指摘をいただきました。確かに Skills は、本記事で扱ってきたペルソナ・CLAUDE.md・サブエージェント委譲と地続きの「ハーネス構成要素」です。本節では公式仕様に基づき、Skills を体系的に整理します。

Skills とは何か（前提）

Claude Skills（Agent Skills）とは、SKILL.md を中心とした 1 つのフォルダとして定義される、再利用可能な専門能力のパッケージです。フォルダには SKILL.md 本体に加え、スクリプトや参照ドキュメントなどの補助ファイルを同梱できます。タスクの内容が Skill の説明文に合致したとき、Claude がそのフォルダを自動的に発見し、必要に応じて読み込みます。

ハーネス設計の観点では、Skills は「特定の作業手順や専門知識を、毎回プロンプトに書き直すことなく、必要なときだけ呼び出せる部品」として位置づけられます。つまりプロンプトの外部化と遅延読み込みを担う仕組みです。

SKILL.md の構造

SKILL.md は、YAML フロントマターと Markdown 本文の 2 部構成です。

---
name: pr-review
description: プルリクエストのレビュー手順を実行する。差分の確認、
  チェックリスト適用、コメント生成を行うときに使用する。
---

# PR レビュー手順

1. 変更差分を取得する
2. 以下のチェックリストを適用する
   ...

• name（必須）: Skill の識別子です。親フォルダ名と一致させる必要があります。
• description（必須）: いつこの Skill を使うかを記述します。後述する自動発見の精度を左右する最重要フィールドです。
• その他のフィールド（任意）: 実装によって allowed-tools（使用可能ツールの制限）、model、context などを指定できる場合があります。仕様は更新されうるため、利用時は最新の公式ドキュメントで確認してください。

自動発見とプログレッシブ・ディスクロージャー（導入）

Skills を理解するうえで核心となるのが、**段階的開示（progressive disclosure）**という設計思想です。

セッション開始時、Claude は各 Skill の name と description だけをシステムプロンプトに読み込みます。1 Skill あたりおよそ 100 トークン程度で、SKILL.md 本文や同梱ファイルがどれだけ大きくても、この時点では読み込まれません。そしてタスクの内容が description に合致したと判断されたときに初めて、本文以下の中身が展開されます。

これにより、多数の専門能力をハーネスに登録しておいても、コンテキストを圧迫しないという利点が得られます。常時すべてを抱え込むのではなく、「目次だけ常に持ち、必要な章だけ開く」という構造です。これは、長大な CLAUDE.md がコンテキストを恒常的に消費するのとは対照的な特性です。

設置場所と起動方法（手順）

Claude Code は次の 2 か所から Skills を自動的に発見します。

• ユーザーレベル: ~/.claude/skills/（全プロジェクト共通）
• プロジェクトレベル: <repo>/.claude/skills/（リポジトリ固有）

起動の経路は大きく 2 通りあります。

1. 自動発見による起動: タスク内容と description が合致したと Claude が判断したとき、自動的に読み込まれます。description の質がそのまま発火精度に直結するため、「何をするか＋いつ使うか（および、いつ使わないか）」を具体的に書くことが推奨されます。曖昧な説明は発火しません。
2. 明示的なトリガー起動: 本記事の環境がそうであるように、/<skill-name> のように明示的に呼び出す運用もできます。CLAUDE.md 側に「ユーザーが /graphify と入力したら Skill を起動する」と書いておけば、確実な起動を保証できます。

ペルソナ・CLAUDE.md・サブエージェントとの関係（応用）

読者の方のご指摘どおり、Skills はペルソナプロンプトと密接に関わります。両者の違いと使い分けを整理します。

構成要素	役割	読み込みタイミング	適する内容
ペルソナ／システムプロンプト	エージェントの「人格・基本姿勢」を定義	常時	全タスク共通の振る舞い・口調・原則
CLAUDE.md	プロジェクト／ユーザー全体の恒常ルール	常時	ほぼ毎回適用される規約・前提
Skills	特定タスクの「手順・専門知識」	該当時のみ（段階的開示）	たまにしか使わない反復作業
サブエージェント委譲	独立したコンテキストでの作業分離	委譲時	重い調査・並列処理

判断の目安はシンプルです。ほぼ毎回適用したいルールは CLAUDE.md（あるいはペルソナ）に、特定の場面でだけ必要になる手順は Skill に切り出します。

ペルソナとの関係でいえば、ペルソナが「誰として振る舞うか」を定義する常駐の土台であるのに対し、Skills は「その人格が特定状況で発揮する専門スキル」を必要時だけ装着する着脱式の能力です。たとえば「丁寧なレビュアー」というペルソナを常時保ちつつ、PR レビュー時にだけ詳細なチェックリスト Skill が展開される、という重ね方ができます。両者は競合せず、**常駐レイヤー（ペルソナ／CLAUDE.md）と遷移レイヤー（Skills）**として補完関係にあると捉えると、設計の見通しがよくなります。

また Skills は、allowed-tools の指定や同梱スクリプトを通じて、サブエージェントへ委譲する作業の「実行手順そのもの」をパッケージ化する用途にも向きます。サブエージェントが**実行の器（独立コンテキスト）を提供し、Skill が実行の中身（手順と知識）**を提供する、という分担が可能です。

設計上の注意点

• description に投資する: Skills の成否はほぼここで決まります。発火しすぎる場合は条件を絞り、発火しない場合は「いつ使うか」をより具体的に、やや強めの表現で記述します。
• 粒度を適切に保つ: 1 Skill = 1 つのまとまった専門能力が基本です。何でも詰め込むと発火条件が曖昧になり、自動発見の精度が落ちます。
• CLAUDE.md との重複を避ける: 恒常ルールを Skill に書くと「該当時しか読まれない」ため意図どおり効きません。逆に、たまにしか使わない手順を CLAUDE.md に書くと常時コンテキストを浪費します。配置先は「読み込みタイミング」で判断してください。
• 仕様の変化に追従する: フロントマターの任意フィールドや配布形態（プラグイン経由の配布など）は更新が続いている領域です。本節の必須要素（name／description／段階的開示）は安定していますが、詳細は公式ドキュメントで都度確認することをおすすめします。

Skills を使いこなすと、ハーネスは「巨大な単一プロンプト」から「必要な専門性を必要なときだけ呼び出す、モジュール化された能力群」へと進化します。ペルソナで土台を固め、CLAUDE.md で恒常ルールを敷き、Skills で専門手順を着脱する——この三層構造が、保守しやすいハーネス設計の現実的な型となります。

まとめ

各トピックの核心を整理します。

トピック	核心
CLAUDE.md 設計	常駐ルールは地図として機能させ、トリガー表で意図を明示し、リーンに保つ
ペルソナシステム	役割を分離し、バイアスを制度的に排除する
サブエージェント委譲	長い生成・並列評価・コンテキスト保護を切り出す
トークン管理	英語思考の活用、推論実況の抑制、CLAUDE.md に意図の根拠を残す
Loop	定期実行や自走でタスクを自動再実行し、Monitor と自走で省トークン化する
Claude Design 連携	デザインとコードの往復で UI 構築を効率化する

ハーネスはプロダクトです

最も重要な視点の転換は、ハーネスをプロダクトとして捉える点にあります。Claude Code が良い出力を出し続けるのは、良いプロンプトを書いているからではなく、良いハーネスを設計しているからです。CLAUDE.md の構造、ペルソナによる役割分離、サブエージェントへの委譲、トークンの配分、Loop による自走、デザインツールとの連携は、いずれも単発の指示ではなく、Claude が働く環境そのものを設計する営みです。

複数のペルソナやサブエージェントを並行して動かし、互いの出力を評価させ、長い処理を切り出して任せる構成が組めるようになると、仕事の焦点は「何を指示するか」から「その構成に何をさせるかを設計すること」へ移ります。プロンプトを磨く発想から、ハーネスを設計する発想へ。この転換が、Claude Code を継続的に良い成果へと導く鍵になります。

この記事が「生きている」理由

ハーネスエンジニアリングの知識は、消費期限が短い領域です。Claude Code は数ヶ月単位で更新され、ベストプラクティスとされていた手法も短期間で陳腐化します。昨日有効だった設定やプロンプトの組み方に対して、次のバージョンではより効率的な方法が登場する、という事態が日常的に起こります。本記事の Loop や Claude Design 連携のように、バージョンに依存する記述はとくに鮮度が問われます。

そのため、この記事は「書き上げて完成」という静的なドキュメントではなく、コメントによって育つ構造を採用しています。読者から寄せられたコメントは内容を審査したうえで、記事末尾のセクションに反映します。これにより、筆者一人の観測範囲には収まらない実践知が、記事そのものに蓄積されていきます。

更新の速い領域だからこそ、情報を一方向に発信して終わらせず、読者との相互作用で鮮度を保つ仕組みにしています。気づいた点や異なる運用知見があれば、コメントでお寄せください。

---

コミュニティからの補足・実践例

この記事はQiitaコメントと共に育ちます。
あなたのClaude Codeハーネスエンジニアリングの経験・補足・ツッコミが、
AIによる多段レビュー（セキュリティ・品質・矛盾・事実確認）を経て、以下に自動で追加されることがあります。

ご採用コメント一覧（記事に反映させていただいた提案です。ありがとうございます）

• @muryodecode 「推論の実況をやめる理由はコンテキストの汚染の予防が１番の理由なのでその記載が必要」（2026-06-21）
• @muryodecode 「Claude Skillsについての情報がない、まとめて新しい項目として追加してほしい ペルソナプロンプトともかかわる話だと思う」（2026-06-21）

参考・出典

• Anthropic Claude Code 公式ドキュメント (2026年6月参照)
• Run prompts on a schedule（Claude Code 公式ドキュメント・Loop） (2026年6月参照)
• Introducing Claude Design by Anthropic Labs（Anthropic 公式） (2026年4月17日)
• Claude Design now stays on brand for daily work（Claude 公式ブログ） (2026年6月17日)
• Claude Code to Figma（Figma 公式ブログ） (2026年2月17日)
• frontend-design / design … Anthropic 公式プラグイン

宣伝

普段はこんなものを作っています：

• コピペを題材にしたインクリメンタルゲーム
• なろう小説をマッチングアプリ式に探索できるアプリ
• 素数ガチャ（超大桁の素数をガチャで引いて、新発見かどうかを判定する謎アプリ）

リリースしたら、ぜひ遊んでください！
開発の進捗は X（@mryocode123）で発信しているので、よかったらフォローしてもらえると嬉しいです。

---

Qiitaもフォローお願いします

この Qiita では、今後も Claude Code やエージェント活用に関する情報を発信していく予定です。
ハーネスエンジニアリングを中心に、開発で役立つ知見を整理してシェアしていきます。
役に立ったら、フォローやこの記事へのいいねが次の記事の励みになります！