Claude Code Rules・Skills・Agents実践ガイド ==================================== Claude CodeのRules、Skills、Agentsは、それぞれ継続的な指示、再利用可能な手順、分離されたタスクの委任を担います。正確なファイル構造と呼び出し方法、セキュリティおよびコンテキスト管理の原則を実践例で解説します。 - プロジェクトルートに`.claude`ディレクトリを作成し、共有設定と個人設定の適用範囲を区別します。 - 常に守る基準は`.claude/rules`のMarkdownファイルに分け、必要に応じて適用パスを制限します。 - 反復手順は`.claude/skills/<이름>/SKILL.md`に記述し、自動または明示的な呼び出し方法を設定します。 - 独立したコンテキストと役割が必要なタスクは、`.claude/agents/<이름>.md`のサブエージェントに委任します。 - 小規模な検証タスクでロード、ツール権限、結果の品質を確認してから、チームのリポジトリに反映します。 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つの誤解 .claudeがClaude Codeのすべての指示に必須というわけではない。プロジェクトの指示は、ルートのCLAUDE.mdまたは.claude/CLAUDE.mdでも管理でき、ユーザー個人の設定はホームディレクトリの~/.claude配下に置くことができる。 ファイル名は、オペレーティングシステムによって大文字と小文字が区別される。Skillのエントリーファイルは、公式形式に合わせて大文字のSKILL.mdで作成するのが安全である。skill.mdとして保存すると認識されない場合がある。 プロジェクト設定と個人設定の選択基準 範囲 適した内容 例 プロジェクト共有 すべてのコントリビューターが同じように従うべきルールと自動化 テストコマンド、ディレクトリ構造、API規約 ユーザー個人 個人の好みやリポジトリで公開すべきでない設定 個人の作業方法、ローカルツールの選択 ローカル専用 特定のコンピューターでのみ有効なパスや実験的設定 ローカルデータのパス、一時的なデバッグ手順 チームで共用するファイルだけを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に入れられる。 要件と曖昧な部分を分ける。 既存の構造と再利用可能なモジュールを調査する。 データフロー、インターフェース、失敗条件を設計する。 docs/design/配下に設計文書を作成する。 ユーザーの承認または明示された承認条件を確認してから実装する。 テストとロールバック方法を提示する。 良い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の違い 基準 Rules Skills Agents 主な目的 継続的な指示の提供 反復手順の再利用 役割別の作業委任 適用タイミング 常時またはパス条件に応じて 自動選択または明示的な呼び出し Claudeによる委任またはユーザーの依頼 コンテキスト メイン作業に指示として含まれる 主に現在の作業フローで実行 別のコンテキストで実行後に結果を返す 代表例 コーディング標準 イシュー修正手順 コードレビュアー 保存場所 .claude/rules/*.md .claude/skills/<名前>/SKILL.md .claude/agents/*.md AgentsとAgent Teamsは異なる 通常のサブエージェントが別のコンテキストを使用するという事実は、エージェント同士が自由に会話するという意味ではない。一般的なサブエージェントは、割り当てられた作業を実行し、結果をメインエージェントに返す委任構造である。複数の独立したセッションが互いにメッセージをやり取りするAgent Teams機能は別の機能であり、サポート状況と有効化条件を公式ドキュメントで確認する必要がある。 エージェントが別のエージェントを連鎖的に作成し続けることを前提にワークフローを設計すると、バージョンや権限の制約により失敗する可能性がある。まずはメインエージェントが役割別のサブエージェントに作業を分け、結果を統合する単純な構造から始めるほうが安全である。 ステップ5：読み込み・権限・品質を検証する 設定ファイルを作成したからといって、意図どおりに動作すると想定してはならない。小さな作業を使って、各コンポーネントを個別に検証する。 推奨される検証順序 Rulesの確認： ルールが適用されるファイルと適用されないファイルをそれぞれ依頼し、パス条件を確認する。 Skillsの確認： 明示的にSkillを呼び出し、入力引数、成果物、中断条件が機能するか確認する。 Agentsの確認： 読み取り専用のレビューなど、リスクの低い作業を任せて結果形式を点検する。 権限の確認： Bash、Editなどの変更可能なツールが、本当に必要な構成にのみ付与されているか検討する。 自動検証： テスト、型チェック、リンター、セキュリティ検査で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によって決定的な検証を補完する。 FAQ Q. Claude Codeでは`.claude`フォルダが必ず必要ですか？ A. プロジェクト用のRules、Skills、Agentsを標準構造で管理する際に使用しますが、すべての指示に必ず必要なわけではありません。プロジェクトの指示はルートの`CLAUDE.md`または`.claude/CLAUDE.md`にも配置でき、個人設定は`~/.claude`以下で管理できます。 Q. Rulesと`CLAUDE.md`にはどのような違いがありますか？ A. `CLAUDE.md`は、プロジェクトの中核となる指示を1つの文書で提供するのに適しています。`.claude/rules`は、トピック別のファイル分割やパスごとの条件適用に適しているため、プロジェクトが大きくなるほどルールのモジュール化に役立ちます。 Q. Skillのファイル名は`skill.md`ですか、それとも`SKILL.md`ですか？ A. 公式のAgent Skills構造に準拠したエントリーファイル名は、大文字の`SKILL.md`です。プロジェクトのSkillは`.claude/skills//SKILL.md`に配置するのが安全であり、大文字と小文字を区別するオペレーティングシステムでは、`skill.md`は別のファイルとして扱われます。 Q. Claude CodeのSkillは、ユーザーが呼び出したときだけ実行されますか？ A. 必ずしもそうではありません。ClaudeがSkillの説明を確認し、適切なタスクで自動的に選択することがあり、ユーザーが`/`で呼び出すこともできます。自動呼び出しを防ぐ必要がある場合は、対応しているバージョンで`disable-model-invocation`設定を検討できます。 Q. SkillとAgentのどちらを使用すべきですか？ A. 現在のワークフローで反復的な手順を実行する場合は、Skillが適しています。大規模な調査、テスト分析、コードレビューのように、別の役割と分離されたコンテキストが必要な場合は、Agentが適しています。共通のコーディング基準のように継続的に適用する内容は、Ruleとして分離します。 Q. サブエージェント同士で直接会話したり、別のエージェントを呼び出したりできますか？ A. 一般的なClaude Codeのサブエージェントは、別のコンテキストで作業した後、結果をメインエージェントに返す仕組みです。複数の独立したセッションによる直接的な連携は、別のAgent Teams機能と区別する必要があり、使用中のバージョンの対応状況と制限を確認する必要があります。 Q. Rulesを作成すれば、Claudeは指示を常に完璧に守りますか？ A. いいえ。Rulesは継続的に提供される指示ですが、決定的な強制手段ではありません。指示の競合や曖昧さによって漏れる可能性があるため、リンター、型チェック、テスト、Hooks、コードレビューと併用する必要があります。 Q. 外部から入手したSkillやAgentをそのまま使用しても安全ですか？ A. すぐに実行しないことをお勧めします。ファイルに含まれる指示、シェルコマンド、許可されたツール、ネットワークおよびファイルへのアクセス範囲を先に確認し、最小権限で試す必要があります。秘密情報の送信や危険なファイル変更を誘導する内容がないかどうかも確認する必要があります。 Sources - Claude Code ドキュメント：Claudeのメモリを管理する: https://code.claude.com/docs/en/memory - Claude Code ドキュメント：スキルでClaudeを拡張する: https://code.claude.com/docs/en/skills - Claude Code ドキュメント：カスタムサブエージェントを作成する: https://code.claude.com/docs/en/sub-agents - Claude Code ドキュメント：Claude Codeの設定: https://code.claude.com/docs/en/settings Images - デスクでノートパソコンの開発ワークフローダッシュボードを見る人: https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTgyOSwicHVyIjoiYmxvYl9pZCJ9fQ==--8ba3d33d24232863ea1d744998bca1e2dbb088c6/ai-7c680af1.webp - フォルダー、フィルター、自動化工程、AI作業環境、セキュリティ、検証を結ぶワークフロー図: https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTgzNSwicHVyIjoiYmxvYl9pZCJ9fQ==--458d876e5a3cb0d4581f0909c6198e47789eda8b/ai-54d6eb4e.webp --- Category: チュートリアル Source: https://injoys.com/ja/articles/claude-code-rules-skills-agents-guide License: cc_by Translation-Status: reviewed