command-development

Claude Code のコマンド開発

注記： .claude/commands/ ディレクトリはレガシー形式です。新しいスキルには、.claude/skills/<name>/SKILL.md ディレクトリ形式を使用してください。どちらも同じように読み込まれます。違いはファイルの配置だけです。推奨形式については、skill-development スキルを参照してください。

概要

スラッシュコマンドは、Claude が対話セッション中に実行する、Markdown ファイルで定義された頻繁に使われるプロンプトです。コマンドの構造、フロントマターのオプション、動的な機能を理解すると、強力で再利用可能なワークフローを作成できます。

主な概念：

• コマンド用の Markdown ファイル形式
• 設定用の YAML フロントマター
• 動的な引数とファイル参照
• コンテキストを得るための Bash 実行
• コマンドの整理と名前空間

コマンドの基本

スラッシュコマンドとは？

スラッシュコマンドは、Claude が呼び出されたときに実行するプロンプトを含む Markdown ファイルです。コマンドには次の利点があります。

• 再利用性：一度定義すれば、繰り返し使用できます
• 一貫性：一般的なワークフローを標準化できます
• 共有：チームやプロジェクト全体に配布できます
• 効率性：複雑なプロンプトにすばやくアクセスできます

重要：コマンドは Claude 向けの指示です

コマンドは人間が読むためではなく、エージェントが実行するために記述します。

ユーザーが /command-name を呼び出すと、コマンドの内容が Claude への指示になります。ユーザーへのメッセージではなく、Claude に何をすべきかを指示する形で記述してください。

適切な例（Claude への指示）：

Review this code for security vulnerabilities including:

- SQL injection
- XSS attacks
- Authentication issues

Provide specific line numbers and severity ratings.

不適切な例（ユーザーへのメッセージ）：

This command will review your code for security issues.
You'll receive a report with vulnerability details.

最初の例は Claude に何をすべきかを指示しています。2 つ目はユーザーに何が起こるかを伝えていますが、Claude への指示にはなっていません。必ず最初の形式を使用してください。

コマンドの保存場所

プロジェクトコマンド（チームと共有）：

• 場所：.claude/commands/
• 適用範囲：特定のプロジェクトで利用可能
• ラベル：/help に「(project)」として表示
• 用途：チームのワークフロー、プロジェクト固有のタスク

個人用コマンド（どこでも利用可能）：

• 場所：~/.claude/commands/
• 適用範囲：すべてのプロジェクトで利用可能
• ラベル：/help に「(user)」として表示
• 用途：個人用ワークフロー、プロジェクト横断のユーティリティ

プラグインコマンド（プラグインに同梱）：

• 場所：plugin-name/commands/
• 適用範囲：プラグインのインストール時に利用可能
• ラベル：/help に「(plugin-name)」として表示
• 用途：プラグイン固有の機能

ファイル形式

基本構造

コマンドは、拡張子 .md の Markdown ファイルです。

.claude/commands/
├── review.md           # /review command
├── test.md             # /test command
└── deploy.md           # /deploy command

シンプルなコマンド：

Review this code for security vulnerabilities including:

- SQL injection
- XSS attacks
- Authentication bypass
- Insecure data handling

基本的なコマンドにフロントマターは必要ありません。

YAML フロントマターを使用する

YAML フロントマターを使って設定を追加します。

---
description: Review code for security issues
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
---

Review this code for security vulnerabilities...

YAML フロントマターのフィールド

description

目的： /help に表示される簡潔な説明
型： 文字列
デフォルト： コマンドプロンプトの最初の行

---
description: Review pull request for code quality
---

ベストプラクティス： 明確で、実行内容がわかる説明にします（60 文字未満）。

allowed-tools

目的： コマンドで使用できるツールを指定します
型： 文字列または配列
デフォルト： 会話から継承

---
allowed-tools: Read, Write, Edit, Bash(git:*)
---

パターン：

• Read, Write, Edit - 特定のツール
• Bash(git:*) - git コマンドのみを使用する Bash
• * - すべてのツール（通常は不要）

使用する場面： コマンドに特定のツールへのアクセスが必要な場合

model

目的： コマンドの実行に使用するモデルを指定します
型： 文字列（sonnet、opus、haiku）
デフォルト： 会話から継承

---
model: haiku
---

使用例：

• haiku - 高速でシンプルなコマンド
• sonnet - 標準的なワークフロー
• opus - 複雑な分析

argument-hint

目的： オートコンプリート用に想定される引数を記載します
型： 文字列
デフォルト： なし

---
argument-hint: [pr-number] [priority] [assignee]
---

メリット：

• コマンドの引数をユーザーが理解しやすくなります
• コマンドを見つけやすくなります
• コマンドのインターフェースを文書化できます

disable-model-invocation

目的： SlashCommand ツールがプログラムからコマンドを呼び出すのを防ぎます
型： ブール値
デフォルト： false

---
disable-model-invocation: true
---

使用する場面： コマンドを手動でのみ呼び出す場合

動的な引数

$ARGUMENTS の使用

すべての引数を単一の文字列として取得します：

---
description: Fix issue by number
argument-hint: [issue-number]
---

Fix issue #$ARGUMENTS following our coding standards and best practices.

使用方法：

> /fix-issue 123
> /fix-issue 456

展開結果：

Fix issue #123 following our coding standards...
Fix issue #456 following our coding standards...

位置引数の使用

$1、$2、$3 などを使って個々の引数を取得します：

---
description: Review PR with priority and assignee
argument-hint: [pr-number] [priority] [assignee]
---

Review pull request #$1 with priority level $2.
After review, assign to $3 for follow-up.

使用方法：

> /review-pr 123 high alice

展開結果：

Review pull request #123 with priority level high.
After review, assign to alice for follow-up.

引数の組み合わせ

位置引数と残りの引数を組み合わせます：

Deploy $1 to $2 environment with options: $3

使用方法：

> /deploy api staging --force --skip-tests

展開結果：

Deploy api to staging environment with options: --force --skip-tests

ファイル参照

@ 構文の使用

コマンドにファイルの内容を含めます：

---
description: Review specific file
argument-hint: [file-path]
---

Review @$1 for:

- Code quality
- Best practices
- Potential bugs

使用方法：

> /review-file src/api/users.ts

効果： Claude はコマンドを処理する前に src/api/users.ts を読み込みます

複数ファイルの参照

複数のファイルを参照します：

Compare @src/old-version.js with @src/new-version.js

Identify:

- Breaking changes
- New features
- Bug fixes

静的ファイル参照

引数を使わずに既知のファイルを参照します：

Review @package.json and @tsconfig.json for consistency

Ensure:

- TypeScript version matches
- Dependencies are aligned
- Build configuration is correct

コマンドでの Bash 実行

コマンドでは、インラインで Bash コマンドを実行して、Claude がコマンドを処理する前にコンテキストを動的に収集できます。リポジトリの状態、環境情報、プロジェクト固有のコンテキストを含める場合に便利です。

使用する場面：

• 動的なコンテキスト（git status、環境変数など）を含める
• プロジェクトやリポジトリの状態を収集する
• コンテキストを考慮したワークフローを構築する

実装の詳細： 完全な構文、例、ベストプラクティスについては、references/plugin-features-reference.md の Bash 実行に関するセクションを参照してください。このリファレンスには、実行時の問題を避けるための正確な構文と複数の動作例が含まれています。

コマンドの整理

フラット構造

少数のコマンドセットに適したシンプルな構成です：

.claude/commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md

使用する場面： コマンドが5～15個で、明確なカテゴリ分けがない場合

名前空間構造

コマンドをサブディレクトリに整理します：

.claude/commands/
├── ci/
│   ├── build.md        # /build (project:ci)
│   ├── test.md         # /test (project:ci)
│   └── lint.md         # /lint (project:ci)
├── git/
│   ├── commit.md       # /commit (project:git)
│   └── pr.md           # /pr (project:git)
└── docs/
    ├── generate.md     # /generate (project:docs)
    └── publish.md      # /publish (project:docs)

メリット：

• カテゴリごとに論理的にグループ化できます
• 名前空間が /help に表示されます
• 関連するコマンドを見つけやすくなります

使用する場面： コマンドが15個以上あり、明確なカテゴリがある場合

ベストプラクティス

コマンドの設計

1. 単一責任： 1つのコマンドにつき1つのタスクにします
2. 明確な説明： /help で見ただけで内容がわかるようにします
3. 依存関係を明示： 必要に応じて allowed-tools を使用します
4. 引数を文書化： 必ず argument-hint を指定します
5. 一貫した命名： 動詞-名詞の形式を使用します（review-pr、fix-issue）

引数の処理

1. 引数を検証： プロンプト内で必須の引数を確認します
2. デフォルト値を指定： 引数がない場合に備えてデフォルト値を提案します
3. 形式を文書化： 想定される引数の形式を説明します
4. 例外的なケースに対応： 引数がない場合や無効な場合を考慮します

---
argument-hint: [pr-number]
---

$IF($1,
Review PR #$1,
Please provide a PR number. Usage: /review-pr [number]
)

ファイル参照

1. パスを明示： 明確なファイルパスを使用します
2. 存在を確認： ファイルがない場合も適切に処理します
3. 相対パス： プロジェクトを基準としたパスを使用します
4. Glob に対応： パターンには Glob ツールの使用を検討します

Bash コマンド

1. 範囲を限定： Bash(*) ではなく Bash(git:*) を使用します
2. 安全なコマンド： 破壊的な操作は避けます
3. エラーに対応： コマンドの失敗を考慮します
4. 高速に保つ： 実行時間の長いコマンドは呼び出しを遅くします

ドキュメント

1. コメントを追加： 複雑なロジックを説明します
2. 例を提示： コメント内で使用方法を示します
3. 要件を列挙： 依存関係を文書化します
4. コマンドのバージョンを記録： 互換性を損なう変更を記載します

---
description: Deploy application to environment
argument-hint: [environment] [version]
---



Deploy application to $1 environment using version $2...

一般的なパターン

レビューパターン

---
description: Review code changes
allowed-tools: Read, Bash(git:*)
---

Files changed: !`git diff --name-only`

Review each file for:

1. Code quality and style
2. Potential bugs or issues
3. Test coverage
4. Documentation needs

Provide specific feedback for each file.

テストパターン

---
description: Run tests for specific file
argument-hint: [test-file]
allowed-tools: Bash(npm:*)
---

Run tests: !`npm test $1`

Analyze results and suggest fixes for failures.

ドキュメントパターン

---
description: Generate documentation for file
argument-hint: [source-file]
---

Generate comprehensive documentation for @$1 including:

- Function/class descriptions
- Parameter documentation
- Return value descriptions
- Usage examples
- Edge cases and errors

ワークフローパターン

---
description: Complete PR workflow
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read
---

PR #$1 Workflow:

1. Fetch PR: !`gh pr view $1`
2. Review changes
3. Run checks
4. Approve or request changes

トラブルシューティング

コマンドが表示されない場合：

• ファイルが正しいディレクトリにあることを確認します
• .md 拡張子が付いていることを確認します
• 有効な Markdown 形式であることを確認します
• Claude Code を再起動します

引数が機能しない場合：

• $1、$2 の構文が正しいことを確認します
• argument-hint が使用方法と一致していることを確認します
• 余分なスペースがないことを確認します

Bash の実行に失敗する場合：

• allowed-tools に Bash が含まれていることを確認します
• バッククォート内のコマンド構文を確認します
• まずターミナルでコマンドをテストします
• 必要な権限があることを確認します

ファイル参照が機能しない場合：

• @ 構文が正しいことを確認します
• ファイルパスが有効であることを確認します
• Read ツールが許可されていることを確認します
• 絶対パスまたはプロジェクトを基準としたパスを使用します

プラグイン固有の機能

CLAUDE_PLUGIN_ROOT 変数

プラグインコマンドでは、プラグインの絶対パスを示す環境変数 ${CLAUDE_PLUGIN_ROOT} を利用できます。

目的：

• プラグインファイルを移植性の高い方法で参照する
• プラグインスクリプトを実行する
• プラグイン設定を読み込む
• プラグインテンプレートにアクセスする

基本的な使い方：

---
description: Analyze using plugin script
allowed-tools: Bash(node:*)
---

Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`

Review results and report findings.

一般的なパターン：

# Execute plugin script

!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`

# Load plugin configuration

@${CLAUDE_PLUGIN_ROOT}/config/settings.json

# Use plugin template

@${CLAUDE_PLUGIN_ROOT}/templates/report.md

# Access plugin resources

@${CLAUDE_PLUGIN_ROOT}/docs/reference.md

利用する理由：

• すべてのインストール環境で動作します
• システム間で移植できます
• パスをハードコードする必要がありません
• 複数ファイルのプラグインには不可欠です

プラグインコマンドの構成

プラグインコマンドは commands/ ディレクトリから自動的に検出されます。

plugin-name/
├── commands/
│   ├── foo.md              # /foo (plugin:plugin-name)
│   ├── bar.md              # /bar (plugin:plugin-name)
│   └── utils/
│       └── helper.md       # /helper (plugin:plugin-name:utils)
└── plugin.json

名前空間のメリット：

• コマンドを論理的にグループ化できます
• /help の出力に表示されます
• 名前の競合を避けられます
• 関連するコマンドを整理できます

命名規則：

• 動作を表す具体的な名前を使用します
• 汎用的な名前（test、run）は避けます
• プラグイン固有の接頭辞を検討します
• 複数の語からなる名前にはハイフンを使用します

プラグインコマンドのパターン

設定ベースのパターン：

---
description: Deploy using plugin configuration
argument-hint: [environment]
allowed-tools: Read, Bash(*)
---

Load configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json

Deploy to $1 using configuration settings.
Monitor deployment and report status.

テンプレートベースのパターン：

---
description: Generate docs from template
argument-hint: [component]
---

Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md

Generate documentation for $1 following template structure.

複数スクリプトのパターン：

---
description: Complete build workflow
allowed-tools: Bash(*)
---

Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`

Review outputs and report workflow status.

詳しいパターンについては、references/plugin-features-reference.md を参照してください。

プラグインコンポーネントとの統合

コマンドは他のプラグインコンポーネントと統合して、強力なワークフローを実現できます。

エージェントとの統合

複雑なタスクにはプラグインエージェントを起動します。

---
description: Deep code review
argument-hint: [file-path]
---

Initiate comprehensive review of @$1 using the code-reviewer agent.

The agent will analyze:

- Code structure
- Security issues
- Performance
- Best practices

Agent uses plugin resources:

- ${CLAUDE_PLUGIN_ROOT}/config/rules.json
- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md

重要なポイント：

• エージェントは plugin/agents/ ディレクトリに存在する必要があります
• Claude は Task ツールを使用してエージェントを起動します
• エージェントの機能を記載します
• エージェントが使用するプラグインリソースを参照します

スキルとの統合

専門知識を活用するためにプラグインスキルを利用します。

---
description: Document API with standards
argument-hint: [api-file]
---

Document API in @$1 following plugin standards.

Use the api-docs-standards skill to ensure:

- Complete endpoint documentation
- Consistent formatting
- Example quality
- Error documentation

Generate production-ready API docs.

重要なポイント：

• スキルは plugin/skills/ ディレクトリに存在する必要があります
• 呼び出しをトリガーするには、スキル名に言及します
• スキルの目的を記載します
• スキルが提供する内容を説明します

フックとの連携

プラグインフックと連携するコマンドを設計します。

• コマンドは、フックが処理する状態を準備できます
• フックはツールイベントに応じて自動的に実行されます
• コマンドでは、想定されるフックの動作を説明します
• フックの出力をどう解釈するかを Claude に示します

フックと連携するコマンドの例については、references/plugin-features-reference.md を参照してください。

複数コンポーネントのワークフロー

エージェント、スキル、スクリプトを組み合わせます。

---
description: Comprehensive review workflow
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---

Target: @$1

Phase 1 - Static Analysis:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Phase 2 - Deep Review:
Launch code-reviewer agent for detailed analysis.

Phase 3 - Standards Check:
Use coding-standards skill for validation.

Phase 4 - Report:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md

Compile findings into report following template.

使用する場面：

• 複雑な複数ステップのワークフロー
• 複数のプラグイン機能を活用する場合
• 専門的な分析が必要な場合
• 構造化された出力が必要な場合

検証パターン

コマンドでは、処理を開始する前に入力とリソースを検証してください。

引数の検証

---
description: Deploy with validation
argument-hint: [environment]
---

Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`

If $1 is valid environment:
Deploy to $1
Otherwise:
Explain valid environments: dev, staging, prod
Show usage: /deploy [environment]

ファイルの存在確認

---
description: Process configuration
argument-hint: [config-file]
---

Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"`

If file exists:
Process configuration: @$1
Otherwise:
Explain where to place config file
Show expected format
Provide example configuration

プラグインリソースの検証

---
description: Run plugin analyzer
allowed-tools: Bash(test:*)
---

Validate plugin setup:

- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"`
- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"`

If all checks pass, run analysis.
Otherwise, report missing components.

エラー処理

---
description: Build with error handling
allowed-tools: Bash(*)
---

Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"`

If build succeeded:
Report success and output location
If build failed:
Analyze error output
Suggest likely causes
Provide troubleshooting steps

ベストプラクティス：

• コマンドの早い段階で検証します
• 役立つエラーメッセージを提示します
• 修正方法を提案します
• エッジケースを適切に処理します

---

frontmatter フィールドの詳しい仕様については、references/frontmatter-reference.md を参照してください。
プラグイン固有の機能とパターンについては、references/plugin-features-reference.md を参照してください。
コマンドパターンの例については、examples/ ディレクトリを参照してください。