カスタムエージェント

問題: デフォルトの Claude Code の動作が、チームの実際の作業スタイルと合っていません。社内スタイルを知っているレビュアーが欲しいかもしれません。あるいはインフラに組み込まれたデプロイスペシャリストが必要かもしれません。

すぐに使えるヒント: 最初のスラッシュコマンドは2分もかかりません。これから始めましょう。

mkdir -p .claude/commands

次に .claude/commands/code-review.md を作成します。

Review the recent code changes for quality and security:
 
1. Run git diff to see recent changes
2. Focus on modified files only
 
Review checklist:
 
- Code is readable and well-named
- No duplicated logic
- Proper error handling exists
- No exposed secrets or credentials
- Performance considerations addressed
 
Provide feedback by priority: Critical → Warnings → Suggestions

Claude Code 内から /project:code-review で呼び出せます。

カスタムコマンドがワークフローを変える理由

理解: カスタムスラッシュコマンドは保存された再利用可能なプロンプトです。呼び出すと Claude が中の指示を読み、スペシャリストが仕事を始めます。専門家のコンサルタント、キーひとつで呼び出せます。

「あのプロンプトなんだっけ」問題も解決します。毎セッションで長い指示を再入力する代わりに、ファイルに保存します。ファイルがチームの蓄積された専門知識を持ちます。

カスタムエージェントへの3つのルート:

1. スラッシュコマンド (.claude/commands/): /project:command-name で手動で起動
2. エージェント定義 (.claude/agents/): YAML定義のサブエージェントロール。スタンバイ状態を保ち、オーケストレーション中に自律的に生成される
3. CLAUDE.md の指示: 毎回ロードされ、会話のすべてのターンを形作る常時アクティブな動作

コマンドとエージェントの違い: 2つは異なるジョブを解決します。スラッシュコマンドは既知のワークフローに対してオンデマンドで起動する保存プロンプトです。.claude/agents/ のエントリーは Task ツールが自律的に呼び出せる永続的なサブエージェントを設定します。コマンドはワークベンチに置かれたツールのように感じます。エージェントファイルはすでに出勤しているチームメートのように感じます。

両方が同じスコーピングモデルを共有します。

プロジェクトパス以下のものは git にコミットされチーム全体で共有されます。ユーザーパスはあなたのマシンに留まり、リポジトリをまたいで付いてきます。

関心の分離: 小さなモジュールが大きなモジュールに勝る原則は、プロンプトにも当てはまります。1つのセキュリティチェックリストに絞ったコマンドは、汎用の「このコードをレビューして」よりも多くの問題を発見します。

効果的なカスタムコマンドの作り方

シンプルに始める: 自分の仕事に繰り返し現れる1つの問題を見つけてください。そのコマンドを書きましょう。

.claude/commands/security-audit.md を作成します。

You are a security expert. Scan this codebase for vulnerabilities.
 
Check for:
 
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication bypass issues
- Exposed API keys or secrets
- OWASP Top 10 violations
 
For each finding, provide:
 
1. Vulnerability description
2. Risk level (Critical/High/Medium/Low)
3. Specific fix recommendation
4. Code example of the fix
 
Start by searching for common vulnerability patterns in the codebase.

セキュリティスイープが必要な時はいつでも /project:security-audit を実行します。

動的引数: コマンドは $ARGUMENTS で引数を読めます。

.claude/commands/review-file.md を作成します。

Review this specific file for issues: $ARGUMENTS
 
Focus on: code quality, potential bugs, security concerns.

/project:review-file src/auth/login.ts で呼び出します。

CLAUDE.md: 常時アクティブなエージェント動作

すべてのセッションで有効にしたいルールは、プロジェクトの CLAUDE.md に追加します。

## Code Review Standards
 
When reviewing code, always check:
 
- All functions have error handling
- No console.log statements in production code
- API endpoints validate input parameters
- Database queries use parameterized statements
 
## Commit Message Format
 
Use conventional commits: type(scope): description
Types: feat, fix, docs, refactor, test, chore

何も呼び出す必要はありません。Claude はセッション開始時に CLAUDE.md を読み込み、その後のすべてのターンにルールを適用します。

プロジェクトとユーザーのコマンド:

• .claude/commands/ — git にコミットされチーム全体で共有
• ~/.claude/commands/ — あなたのマシンだけのプライベート

.claude/agents/ による永続的なサブエージェント定義

オーケストレーターが自律的に生成すべきサブエージェントは .claude/agents/ 以下に置きます。各ファイルは先頭に YAML ブロックを持つ Markdown です。アイデンティティ、機能、指示がすべてそのブロックに収まります。

スラッシュコマンドがキーストロークを待つのとは異なり、これらの定義はスタンバイ状態を保ちます。Task ツールはオーケストレーション中にそれらを認識します。Claude がタスクにスペシャリストが必要と判断した瞬間、コンテキストと制約が設定済みの状態で適切なエージェントを生成します。

YAML フロントマターの構文

.claude/agents/ 以下のすべてのファイルは Claude にエージェントの動作を伝える YAML ヘッダーで始まります。フィールドリファレンス:

---
# Required
name: "security-auditor" # Agent identity (used in Task invocations)
 
# Optional
model: "claude-sonnet-4-5" # Override the default model
allowedTools: # Restrict which tools this agent can use
  - Read
  - Grep
  - Bash
description: "Scans code for vulnerabilities and OWASP violations"
---

YAML ブロック以下はすべてプレーンな Markdown で、エージェントが実行するシステムプロンプトを持ちます。構造的にはスラッシュコマンドと同じです。本当の違いは、オーケストレーターがこのファイルを自律的に認識し、手動呼び出しなしにエージェントを生成できることです。

実践的な例

コミット前の品質ゲートに特化したエージェントの具体例です。ファイルは .claude/agents/quality-engineer に置きます。

---
name: "quality-engineer"
allowedTools: ["Read", "Grep", "Bash"]
description: "Validates code against project standards before commits"
---
 
You are a quality engineer. Your job is to validate, never to modify.
 
## Validation Protocol
 
1. Read the files that changed (use git diff --name-only)
2. For each file, check:
   - Imports resolve correctly (grep for the import targets)
   - No console.log/print statements left in production code
   - Functions under 50 lines
   - All exported functions have JSDoc or docstring
3. Run the test suite: `npm test -- --bail`
4. Report pass/fail with specific line numbers for failures
 
Never edit files. Never suggest fixes. Only report what you find.

オーケストレーターがバリデーションタスクを発見すると、この定義が自動的に選ばれます。allowedTools が Edit と Write を除外しているため、エージェントは物理的にコードベースに触ることができません。検査だけが唯一の選択肢です。この制限こそがパターンを成立させる理由です。

このフォルダ内のファイルも入力時に CLAUDE.md を読み込むため、プロジェクトの規約やコーディング標準が追加の配線なしに引き継がれます。

サブエージェントの動作の詳細、並列実行、Ctrl+B によるバックグラウンド化、呼び出し品質については、エージェントの基本ガイドで詳しく説明しています。

よく使うコマンドの例

データベースオプティマイザー (.claude/commands/db-optimize.md):

You are a database performance expert.
 
Analyze the database queries in this codebase:
 
1. Find slow or inefficient queries
2. Check for missing indexes
3. Review schema design
 
For each issue, provide:
 
- The problematic query or schema
- Why it's a problem
- Optimized version with explanation

ドキュメントライター (.claude/commands/write-docs.md):

Write documentation for: $ARGUMENTS
 
Include:
 
- Purpose and overview
- Setup instructions
- Usage examples
- Common troubleshooting
 
Target audience: developers new to this project.
Write in clear, concise language.

カスタムエージェント構築でよくある間違い

表面上、カスタムエージェントは何でもないように見えます。スコープを誤ると代償はトークンの無駄遣いと不安定な結果です。

間違い1: スコープが広すぎる。 「このコードベース全体の問題をスキャンして」と言われたエージェントは、全体にわたって薄い観察を返します。同じエージェントを SQL インジェクションに向け、データベース関連のファイルに制限すると、実際のバグを発見します。スコープを絞り込み、掘り下げを深める。

間違い2: 出力フォーマットが曖昧。 レポートの形を開放的にすると、実行ごとにブレます。あるパスでは箇条書き、次は散文。各発見について次の情報を提供せよ: ファイルパス、行番号、深刻度、1行での修正 のように明確に固定する。

間違い3: レビュアーへの書き込みアクセス。 エージェントの仕事が検査なら、allowedTools を Read、Grep、Bash に固定してください。レビュアーに Edit を与えた瞬間、コードを報告する代わりに修正するようになります。これはバリデーターを分離した理由を消し去ります。

間違い4: CLAUDE.md のルールをコマンド内で繰り返す。 コマンドが実行される時点で CLAUDE.md はすでにロードされています。コマンドファイル内でそれらのルールを再記述するのはコンテキストトークンを食うだけです。コマンドは動作を絞り込むものであり、共通のベースラインを再述するものではありません。「パラメータ化クエリを使用する」が CLAUDE.md にあるなら、データベースコマンドにその行は不要です。

どのアプローチをいつ使うか

スラッシュコマンド、エージェントファイル、スキル、CLAUDE.md の選択は2つのことに帰着します。動作のトリガーが何か、どれくらい持続すべきか。

実用的な境界はこうです。3回以上入力した詳細なプロンプトは、スラッシュコマンドとして保存すべきです。オーケストレーターが自律的に呼び出すべきスペシャリストは .claude/agents/ に置きます。それ以外はすべて CLAUDE.md に普遍的な動作として、またはドメイン知識を遅延ロードするスキルとして置きます。スキルガイドがその最後のルートを詳しく説明しています。

特定ロールへのプロンプティング

保存ファイルが常に必要なわけではありません。時に直接プロンプトで十分です。

Act as a senior security engineer. Review the authentication
flow in src/auth/ for vulnerabilities. Be thorough and paranoid.

1回限りには十分です。2回入力したと気づいた瞬間、保存コマンドに昇格させましょう。

次のアクション

最初のスペシャリストを構築する時です。今日最も大きな痛みを持つポイントを選んでください。

• コード品質: エージェントの基本ガイドを参考にして、社内ルールをレビュアーコマンドに変換する
• セキュリティフォーカス: サブエージェント設計のノートを基に脆弱性スキャナーを書く
• チームワークフロー: タスク配布プレイブックを使って協働パターンを設計する

保存コマンドは使えば使うほど価値が積み重なります。リポジトリにプッシュしてください。チームに共有してください。チームが実際にコードを出荷する方法を捉えたライブラリを育てていきましょう。