Command Development

Claude Code 向けコマンド開発

概要

スラッシュコマンドは、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 実行

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

使用する場面：

• 動的なコンテキスト（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/ ディレクトリを参照してください。