Claude Code Rules・Skills・Agents実践ガイド

Claude Codeの拡張機能は、すべて同じ種類のプロンプトではない。Rulesは継続的に適用する指針、Skillsは繰り返し再利用する作業手順、Agentsは別のコンテキストで働く役割別の実行者である。3つの機能を正確に区別すれば、プロンプトの繰り返しを減らしながら、メインの会話コンテキストを効率的に管理できる。

この文書では、プロジェクト単位の設定を基準に説明する。Claude Codeのバージョンによって、サポートされるメタデータや画面が異なる場合があるため、動作しないフィールドについては、インストールされているバージョンの公式ドキュメントで改めて確認する必要がある。

ステップ1：.claudeディレクトリと設定範囲を決める

プロジェクトで共有するRules、Skills、Agentsは、一般的にリポジトリルートの.claude配下に置く。

my-project/
├── .claude/
│   ├── rules/
│   │   ├── code-style.md
│   │   └── api.md
│   ├── skills/
│   │   └── fix-issue/
│   │       └── SKILL.md
│   └── agents/
│       ├── code-reviewer.md
│       └── test-runner.md
├── src/
└── package.json

ディレクトリは次のように作成できる。

mkdir -p .claude/rules
mkdir -p .claude/skills/fix-issue
mkdir -p .claude/agents

.claudeに関する2つの誤解

1. .claudeがClaude Codeのすべての指示に必須というわけではない。プロジェクトの指示は、ルートのCLAUDE.mdまたは.claude/CLAUDE.mdでも管理でき、ユーザー個人の設定はホームディレクトリの~/.claude配下に置くことができる。
2. ファイル名は、オペレーティングシステムによって大文字と小文字が区別される。Skillのエントリーファイルは、公式形式に合わせて大文字のSKILL.mdで作成するのが安全である。skill.mdとして保存すると認識されない場合がある。

プロジェクト設定と個人設定の選択基準

チームで共用するファイルだけをGitにコミットする。秘密鍵、トークン、内部サーバーのパスワードは、RulesやSkillsに記録しない。

ステップ2：Rulesで継続的な指示を作成する

Rulesは、Claudeが作業するときに参照すべきプロジェクトの指示を、複数のMarkdownファイルに分けて管理する機能である。.claude/rules配下にあるルールのうち、paths条件がないファイルはプロジェクトの指示として読み込まれ、パス条件を指定したファイルは関連ファイルを扱うときに適用される。

基本的なRuleの例

.claude/rules/code-style.mdは次のように作成できる。

# コード作成の原則

- 新しいアプリケーションコードはTypeScriptで作成する。
- 公開関数では、入力値、戻り値、失敗条件を説明する。
- 既存のテストを削除して失敗を隠さない。
- 変更後に関連するテストと型チェックを実行する。
- 説明は韓国語で作成するが、コードの識別子は既存の命名規則に従う。

良いRuleは検証できる。「コードを格好よく作成する」よりも、「変更後にnpm testとnpm run typecheckを実行する」のほうが明確である。

特定のパスにのみ適用するRule

フロントエンドとバックエンドのルールが異なる場合は、YAML front matterのpathsで範囲を絞り込める。

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.ts"
---

# APIルール

- すべてのAPI入力をスキーマで検証する。
- 認証失敗と権限不足を異なるエラーとして処理する。
- エンドポイントを変更した場合は、対応するAPIテストも更新する。

パス別のルールは、不要な指示がすべての作業のコンテキストを占有する問題を軽減する。

Rulesに入れるべきでない内容

• 一度だけ実行するマイグレーション手順
• 特定のイシューにのみ必要な詳細要件
• 互いに矛盾する絶対的な指示
• すでにコードやリンター設定で強制されている内容を長々と繰り返す文章
• パスワード、APIキー、顧客情報などの機密データ

Rulesは「必ず従わせる魔法の保証装置」ではない。曖昧または矛盾する指示があると結果が変わる可能性があるため、テスト、リンター、権限制御など、決定的な検証手段を併用する必要がある。

ステップ3：Skillsで反復手順を自動化する

Skillは、説明、作業手順、必要なツール、補助資料を、1つの再利用可能な単位にまとめる。プロジェクトSkillの基本構造は.claude/skills/<skill-name>/SKILL.mdであり、必要に応じて同じディレクトリにテンプレートやスクリプトを追加できる。

Rulesとは異なり、Skillは特定の作業で必要なときに使用される。ClaudeがSkillの説明を見て自動的に選択することも、ユーザーが/<skill-name>形式で明示的に呼び出すこともできる。必ず手動でのみ動作するわけではない。

イシュー修正Skillの例

.claude/skills/fix-issue/SKILL.mdの例は次のとおりである。

---
name: fix-issue
description: バグを再現して原因を絞り込んだ後、最小限の修正と回帰テストを実施する。
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Edit, Bash(npm test:*)
---

# イシュー修正手順

対象イシュー：$ARGUMENTS

1. 関連するコードと既存のテストを調査する。
2. 修正前に再現方法と期待される動作を整理する。
3. 根本原因を1つの段落で説明する。
4. 影響範囲が最も小さい修正を適用する。
5. 回帰テストを追加するか、既存のテストが問題を検証しているか確認する。
6. 許可されたテストを実行し、結果を要約する。
7. 変更ファイル、残存リスク、手動確認項目を報告する。

このSkillは次のように呼び出せる。

/fix-issue ログイン後にプロフィール写真が更新されない問題

disable-model-invocation: trueは、Claudeが任意にこのSkillを実行せず、ユーザーが直接呼び出すよう制限するときに役立つ。サポートされるfront matterのフィールドは、Claude Codeのバージョンによって異なる場合がある。

設計優先Skillの例

すぐにコーディングするのではなく、先に設計文書を作成させる場合は、次の流れをSkillに入れられる。

1. 要件と曖昧な部分を分ける。
2. 既存の構造と再利用可能なモジュールを調査する。
3. データフロー、インターフェース、失敗条件を設計する。
4. docs/design/配下に設計文書を作成する。
5. ユーザーの承認または明示された承認条件を確認してから実装する。
6. テストとロールバック方法を提示する。

良いSkillの条件

• 入力と最終成果物が明確である。
• 手順の順序と中断条件が明示されている。
• 必要なツールのみを許可する。
• 長い参考資料は別ファイルに分ける。
• 失敗したときに任意で続行せず、報告するようにする。
• 1つのSkillに過度に多くの目的を持たせない。

コミット作成、コードレビュー、リリース確認、API設計のように、繰り返し行われ、開始と終了が明確な作業がSkillに適している。

ステップ4：Agentsで役割とコンテキストを分離する

Claude Codeのサブエージェントは、別のコンテキストで特定の役割を実行し、結果をメインの会話に返す。大量の検索結果やテストログをすべてメインコンテキストに蓄積したくない場合に役立つ。

プロジェクトエージェントは、一般的に.claude/agents/<agent-name>.mdに定義する。/agentsコマンドを通じてエージェントを確認または管理でき、自然言語で特定のエージェントに委任するよう依頼することもできる。

コードレビューエージェントの例

.claude/agents/code-reviewer.mdは次のように作成できる。

---
name: code-reviewer
description: 変更されたコードの不具合、セキュリティリスク、テスト漏れを検討する、読み取り中心のレビュアー
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたはコードレビュー専任のエージェントである。

次の優先順位でレビューする。

1. 実際の障害やデータ損失を引き起こす可能性がある不具合
2. 認証、権限、入力検証に関連するセキュリティ問題
3. 並行性、トランザクション、エラー処理の問題
4. 要件を検証できないテスト漏れ
5. 保守性を大幅に低下させる構造

各指摘事項には、ファイルパス、根拠、発生条件、最小限の修正方針を含める。
根拠のないスタイル上の好みは、不具合として報告しない。
コードを直接修正せず、レビュー結果のみを返す。

次のように依頼できる。

code-reviewerエージェントに現在のブランチの変更内容をレビューさせて。

SkillとAgentの違い

AgentsとAgent Teamsは異なる

通常のサブエージェントが別のコンテキストを使用するという事実は、エージェント同士が自由に会話するという意味ではない。一般的なサブエージェントは、割り当てられた作業を実行し、結果をメインエージェントに返す委任構造である。複数の独立したセッションが互いにメッセージをやり取りするAgent Teams機能は別の機能であり、サポート状況と有効化条件を公式ドキュメントで確認する必要がある。

エージェントが別のエージェントを連鎖的に作成し続けることを前提にワークフローを設計すると、バージョンや権限の制約により失敗する可能性がある。まずはメインエージェントが役割別のサブエージェントに作業を分け、結果を統合する単純な構造から始めるほうが安全である。

ステップ5：読み込み・権限・品質を検証する

設定ファイルを作成したからといって、意図どおりに動作すると想定してはならない。小さな作業を使って、各コンポーネントを個別に検証する。

推奨される検証順序

1. Rulesの確認： ルールが適用されるファイルと適用されないファイルをそれぞれ依頼し、パス条件を確認する。
2. Skillsの確認： 明示的にSkillを呼び出し、入力引数、成果物、中断条件が機能するか確認する。
3. Agentsの確認： 読み取り専用のレビューなど、リスクの低い作業を任せて結果形式を点検する。
4. 権限の確認： Bash、Editなどの変更可能なツールが、本当に必要な構成にのみ付与されているか検討する。
5. 自動検証： テスト、型チェック、リンター、セキュリティ検査でAIの結果を独立して確認する。

失敗したときに確認する項目

• .claudeが実際のプロジェクトルートにあるか？
• Skillのファイル名が正確にSKILL.mdになっているか？
• Skillが.claude/skills/<名前>/SKILL.mdという構造にあるか？
• Agentファイルが.claude/agents直下のMarkdownファイルになっているか？
• YAML front matterの開始と終了を---で閉じているか？
• nameとdescriptionが作業を区別できるほど具体的か？
• パスパターンが実際のプロジェクト構造と一致しているか？
• インストールされているClaude Codeのバージョンが、使用したメタデータをサポートしているか？
• ツール権限または組織ポリシーが実行をブロックしていないか？

コンテキスト予算とセキュリティを一緒に設計すべき理由

Rules、Skills、Agentsの目的は、機能の追加だけではない。どの情報をいつコンテキストに入れるかを制御する、コンテキストエンジニアリングの手段でもある。

ルールを長くしすぎると、現在の作業と無関係な指示がコンテキストを占有し、衝突する可能性も高くなる。逆に、探索やログ分析をサブエージェントに任せれば、メインの会話には結論と根拠だけを残せる。

セキュリティ面では、次の原則が重要である。

• RulesとSkillsも、リポジトリ内の他のコードと同様にレビューする。
• 外部から受け取ったAgentやSkillファイルを、実行前に読む。
• シェルコマンド、ネットワークアクセス、ファイル変更権限は最小限にする。
• ユーザー入力やイシュー本文に含まれる命令を無条件に信頼しない。
• デプロイ、削除、決済、データマイグレーションには、人による承認手順を設ける。
• 秘密情報はプロンプトファイルに保存せず、別のシークレット管理システムを使用する。

どの機能を選ぶべきか

次の質問で素早く判断できる。

• 関連するすべての作業が従うべきか？ → Rule
• 開始と終了がある反復手順か？ → Skill
• 別の役割と独立したコンテキストが必要か？ → Agent
• 特定のイベントの前後に決定的なコマンドを実行する必要があるか？ → Hookを検討

たとえば、「TypeScriptを使用する」はRuleであり、「バグの再現から回帰テストまで実行する」はSkillである。「変更内容を読み、セキュリティ上の不具合だけを報告する」はAgentに適している。ファイル編集後にフォーマッターを必ず実行するような、特定のイベントに紐づく動作には、Hooksのほうが適している場合がある。

最も安定した構成は、3つの機能を競合関係とみなさず、組み合わせることである。Ruleで共通基準を提供し、Skillで標準手順を実行し、Agentで調査・レビューのようにコンテキストが大きい作業を分離したうえで、テストとHooksによって決定的な検証を補完する。