はじめに
直近、Claude Code を用いた開発を行っています。
ただし、様々な機能がリリースする中でそれぞれの役割が整理しきれなくなりました。
そこで、今回特に使い分けが混乱してきている下記 4 つの役割と使い方の違いをまとめました。
- CLAUDE.md
- サブエージェント
- スラッシュコマンド
- エージェントスキル
前提
こちらの記事は、あくまで個人的な考えです。
Boris Cherny さんが年始にポストしているように、Claude Code の設定に正解はないので、あくまで参考程度に見ていただけますと幸いです。
目次
1. 結論
それぞれの機能の役割と、私の使い分け基準は以下の通りです。
| 機能 | 実行タイミング | 役割・イメージ | 記載・設定する内容 | 具体的な利用シーン |
|---|---|---|---|---|
| CLAUDE.md | 常時 (自動) | 前提知識 | プロジェクト全体のルール、コーディング規約...etc | 開発中常に守らせたいプロジェクトルールを Claude に渡したい場合 |
| サブエージェント | 必要時 (自動) | メインとは別で動く Claude | 特定のタスク専用のプロンプト...etc | 特定のタスクを切り出して、メインの会話履歴を汚したくない場合 |
| スラッシュコマンド | 手動 (/) |
ショートカット | 頻繁に打つ指示、簡単かつ定型的なレビュープロンプト...etc | 「毎回同じ指示打つのが面倒な時」特定の単純なタスクを効率したいる場合 |
| エージェントスキル | 必要時 (自動) | 複雑な1つの機能 | 複数の手順を含む複雑な処理、特定の分析手順...etc | 複数のステップを挟むような複雑な機能を Claude に実行させたい場合 |
2. CLAUDE.md
参考記事
概要
CLAUDE.mdは、プロジェクト固有のコンテキスト、ルール、指示を Claude に提供するためのマークダウンファイルです。
つまり、Claude が作業する前に、必ず読み込んで頭に入れておくべき「前提知識」や「ルール」を記載します。
記述すべき情報
- コーディングガイドライン
- 標準ルール
- プロジェクト固有のコンテキスト
- 一般的なコマンドやワークフロー
- テスト要件や手順
- コアファイルとユーティリティ関数...etc
具体例
# プロジェクトガイドライン
## コードスタイル
- TypeScript strict modeを使用
- Reactでは関数コンポーネントを優先
- パブリックAPIには常にJSDocコメントを含める
## テスト
- コミット前に`npm test`を実行
- 80%以上のコードカバレッジを維持
- ユニットテストにはjest、E2Eにはplaywrightを使用
## コマンド
- ビルド：`npm run build`
- 開発サーバー：`npm run dev`
- 型チェック：`npm run typecheck`
補足
なお、CLAUDE.md に情報を詰め込みすぎると、巨大な md ファイルが出来上がります。
この場合、可読性やメンテナンス性も悪いので、.claude/rules/ を使用したモジュール化を行うことで、それぞれの役割に応じた md ファイルを作成することができます。
抜粋：Claude Code Docs - .claude/rules/を使用したモジュール化ルール
your-project/
├── .claude/
│ ├── CLAUDE.md # Main project instructions
│ └── rules/
│ ├── code-style.md # Code style guidelines
│ ├── testing.md # Testing conventions
│ └── security.md # Security requirements
3. サブエージェント
参考記事
概要
メインの会話から切り離された独立したコンテキストを持つ、専門のAIアシスタントです。
基本的には、Claude が自動的に呼び出して使用します。
例えば、下記のような場合に利用します。
-
メインのコンテキスト消費を節約したい場合
- サブエージェント内での試行錯誤や大量のログ出力はメインの会話履歴に残らないため、メインのコンテキスト消費を節約し、ノイズを排除できる
-
特定のタスク特化の専門性を持たせたい場合
- 特定のタスク専用のプロンプト、使用可能なツールの制限、権限設定を持たせることができる
- Agent に応じたモデルの選択もできる
- 並列処理を行いたい場合
- 「認証周りの調査」と「DB周りの調査」を同時に進めたい場合
- 複数のサブエージェントをバックグラウンドで並行稼働させることができる
- 「認証周りの調査」と「DB周りの調査」を同時に進めたい場合
記述すべき内容
基本的には、Claude が呼び出して実行するため、記載内容としては「何をしてほしいか」を記載します。
抜粋：Claude Code Docs - サブエージェントファイルを書く
※ わかりやすいように一部日本語にしています
---
name: code-reviewer
description: コードの品質とベストプラクティスをレビューする
tools: Read, Glob, Grep
model: sonnet
skills: pr-review, security-check
---
あなたはコードレビュアーです。
呼び出された際は、コードを分析し、品質、セキュリティ、およびベストプラクティスについて、具体的かつ実践的なフィードバックを提供してください。
補足
サブエージェントは、メインのコンテキストからエージェントスキルを自動的には継承しません。
その場合は、サブエージェントの skills フィールドを追加する必要があります。
こうすることで、サブエージェントが対象のスキル（手順やツール）を認識し、必要に応じてそのフローを利用できるようになります。
抜粋：Claude Code Docs - サブエージェントにスキル アクセスを与える
※ わかりやすいように一部日本語にしています
# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: コードの品質とベストプラクティスをレビューする
skills: pr-review, security-check
---
4. スラッシュコマンド
参考
概要
スラッシュコマンドは、繰り返し使用するワークフローやプロンプトを /command 形式のスラッシュコマンドとして定義し、再利用可能にする機能です。
つまり、Claude が特定のタスクを実行する際の手順を記載したものです。
例えば、よく使用される単純なプロンプを記載します。
記述すべき情報
下記のようなものを記載します。
- よく使用する単純なプロンプトスニペット
- クイックリマインダーまたはテンプレート
- 1つのファイルに収まる頻繁に使用される指示
抜粋：Claude Code Docs - スラッシュコマンド
※ わかりやすいように一部日本語にしています
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: Gitコミットを作成する
model: claude-3-5-haiku-20241022
---
$ARGUMENTS というメッセージで Git コミットを作成してください
5. エージェントスキル
参考
概要
エージェントスキルは、Claude が特定のタスクを実行する際の手順を記載したものです。
基本的には、Claude が自動的に呼び出します。
ここで、スラッシュコマンドと役割として似ていますが、違いとしては「より複雑な機能をコンテキストに基づいて Claude が自動的に呼び出す」になります。
具体的には、下記のページが特にわかりやすかったです。
Claude Code Docs - スキル対スラッシュコマンド
上記のページから抜粋すると
スラッシュコマンドを使用する場合
クイック、頻繁に使用されるプロンプト:
- よく使用する単純なプロンプトスニペット
- クイックリマインダーまたはテンプレート
- 1つのファイルに収まる頻繁に使用される指示
例:- /review → 「このコードをバグについてレビューし、改善を提案してください」
- /explain → 「このコードを簡潔に説明してください」
- /optimize → 「このコードをパフォーマンスについて分析し、最適化を提案してください」
スキルを使用する場合
複数のステップを持つ包括的な機能:
- 複数のステップを持つ複雑なワークフロー
- スクリプトまたはユーティリティが必要な機能
- 複数のファイルに整理された知識
- 標準化したいチームワークフロー
例:- フォーム入力スクリプトと検証を備えたPDF処理スキル
- さまざまなデータ型の参照ドキュメント付きデータ分析スキル
- スタイルガイドとテンプレート付きドキュメンテーションスキル
記述すべき情報
複数のファイルを参照したりするような複数のステップを持つタスクを記載します。
抜粋：Claude Code Decs - 最初のスキルを作成する
※ わかりやすいように一部日本語にしています
---
name: explaining-code
description: 視覚的な図解と例え話を用いてコードを説明します。コードの仕組みの説明やコードベースの教育、あるいはユーザーから「これはどう動くの？」と聞かれた際に使用してください。
---
コードを説明する際は、必ず以下を含めてください：
1. **例え話から始める**：コードを日常生活の何かに例えて比較してください
2. **図を描く**：ASCIIアートを使用して、フロー、構造、または関係性を示してください
3. **コードをウォークスルーする**：何が起きているかをステップバイステップで説明してください
4. **「落とし穴」を強調する**：よくある間違いや誤解されやすい点は何かを示してください
説明は会話調に保ってください。複雑な概念については、複数の例え話を使用してください。
6. まとめ
いかがだったでしょうか。
あくまで Claude Code の設定に正解はないので、少しでも Claude Code の設定の一助になれば幸いです。