Claude Code のコマンド開発

参照: 公式仕様については command-spec.md を参照してください。

概要

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

主要な概念:

• コマンド用の Markdown ファイル形式
• 設定用の YAML frontmatter
• 動的な引数とファイル参照
• コンテキスト取得用の Bash 実行
• コマンドの整理とネームスペーシング

コマンドの基本

スラッシュコマンドとは

スラッシュコマンドは、ユーザーが呼び出したときに Claude が実行するプロンプトを含む Markdown ファイルです。コマンドは以下を提供します:

• 再利用性: 一度定義すれば、何度でも使用可能
• 一貫性: 一般的なワークフローを標準化
• 共有: チームやプロジェクト全体に配布可能
• 効率性: 複雑なプロンプトへの高速アクセス

重要: コマンドは Claude 用の指示です

コマンドはユーザー用ではなく、エージェント消費用に書かれています。

ユーザーが /command-name を呼び出すと、コマンドコンテンツが Claude の指示になります。コマンドは、「何をするか」を Claude に指示するディレクティブとして書き、ユーザーへのメッセージとして書かないでください。

正しいアプローチ (Claude 用の指示):

次のコードをセキュリティ脆弱性についてレビューしてください:
- SQL インジェクション
- XSS 攻撃
- 認証の問題

特定の行番号と深刻度レーティングを提供してください。

間違ったアプローチ (ユーザーへのメッセージ):

このコマンドはセキュリティの問題についてコードをレビューします。
脆弱性の詳細を含むレポートを受け取ります。

最初の例は Claude に何をするかを伝えます。2 番目の例はユーザーに何が起こるかを伝えていますが、Claude に指示していません。常に最初のアプローチを使用してください。

コマンドの場所

プロジェクトコマンド (チームと共有):

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

パーソナルコマンド (どこでも利用可能):

• 場所: ~/.claude/commands/
• スコープ: すべてのプロジェクトで利用可能
• ラベル: /help に "(user)" として表示
• 用途: パーソナルワークフロー、クロスプロジェクトユーティリティ

プラグインコマンド (プラグインにバンドル):

• 場所: plugin-name/commands/
• スコープ: プラグインインストール時に利用可能
• ラベル: /help に "(plugin-name)" として表示
• 用途: プラグイン固有機能

ファイル形式

基本構造

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

.claude/commands/
├── review.md           # /review コマンド
├── test.md             # /test コマンド
└── deploy.md           # /deploy コマンド

シンプルなコマンド:

次のコードをセキュリティ脆弱性についてレビューしてください:
- SQL インジェクション
- XSS 攻撃
- 認証バイパス
- 安全でないデータ処理

基本的なコマンドには frontmatter は不要です。

YAML Frontmatter 付き

YAML frontmatter を使用して設定を追加します:

---
description: セキュリティ問題についてコードをレビュー
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
---

次のコードをセキュリティ脆弱性についてレビューしてください...

YAML Frontmatter フィールド

description

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

---
description: プルリクエストをコード品質について確認
---

ベストプラクティス: 明確で実行可能な説明 (60 文字以下)

allowed-tools

目的: コマンドが使用できるツールを指定 型: カンマ区切り文字列 デフォルト: 会話から継承

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

注: 常にカンマ区切り形式を 1 行で使用してください。YAML 配列構文は使用しないでください。

パターン:

• 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: 番号別に問題を修正
argument-hint: [issue-number]
---

Issue #$ARGUMENTS をコーディング標準とベストプラクティスに従って修正します。

使用方法:

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

展開先:

Issue #123 をコーディング標準とベストプラクティスに従って修正します...
Issue #456 をコーディング標準とベストプラクティスに従って修正します...

位置指定引数の使用

$1、$2、$3 などで個別の引数をキャプチャ:

---
description: 優先度と担当者でプルリクエストをレビュー
argument-hint: [pr-number] [priority] [assignee]
---

プルリクエスト #$1 を優先度レベル $2 でレビューしてください。
レビュー後、$3 にフォローアップ用に割り当ててください。

使用方法:

> /review-pr 123 high alice

展開先:

プルリクエスト #123 を優先度レベル high でレビューしてください。
レビュー後、alice にフォローアップ用に割り当ててください。

引数の組み合わせ

位置指定引数と残りの引数を混在:

$1 を $2 環境にデプロイします。オプション: $3

使用方法:

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

展開先:

api を staging 環境にデプロイします。オプション: --force --skip-tests

ファイル参照

@ 構文の使用

コマンドにファイルコンテンツを含める:

---
description: 特定ファイルをレビュー
argument-hint: [file-path]
---

@$1 を以下についてレビューしてください:
- コード品質
- ベストプラクティス
- 潜在的なバグ

使用方法:

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

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

複数ファイル参照

複数ファイルを参照:

@src/old-version.js と @src/new-version.js を比較

以下を識別してください:
- 破壊的な変更
- 新機能
- バグ修正

静的ファイル参照

引数なしで既知のファイルを参照:

@package.json と @tsconfig.json の一貫性をレビュー

以下を確認してください:
- TypeScript バージョンが一致
- 依存関係が調整されている
- ビルド設定が正しい

コマンド内の Bash 実行

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

使用時:

• 動的コンテキストを含める (git ステータス、環境変数など)
• プロジェクト/リポジトリ状態を集約
• コンテキスト対応ワークフローを構築

実装の詳細: 完全な構文、例、ベストプラクティスについては、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,
  PR #$1 をレビューしてください,
  PR 番号を提供してください。使用方法: /review-pr [number]
)

ファイル参照

1. 明示的なパス: クリアなファイルパスを使用
2. 存在確認: 見つからないファイルを適切に処理
3. 相対パス: プロジェクト相対パスを使用
4. グロブサポート: パターンに Glob ツールの使用を検討

Bash コマンド

1. スコープを制限: Bash(*) ではなく Bash(git:*) を使用
2. 安全なコマンド: 破壊的な操作を回避
3. エラーを処理: コマンド失敗を検討
4. 高速を保つ: 長時間実行コマンドは呼び出しを遅くします

ドキュメント

1. コメントを追加: 複雑なロジックを説明
2. 例を提供: コメントに使用例を表示
3. 要件を記載: 依存関係を文書化
4. コマンドをバージョニング: 破壊的な変更を注記

---
description: アプリケーションを環境にデプロイ
argument-hint: [environment] [version]
---

<!--
使用方法: /deploy [staging|production] [version]
必須: AWS 認証情報が設定されている
例: /deploy staging v1.2.3
-->

アプリケーションを $1 環境にバージョン $2 を使用してデプロイします...

一般的なパターン

レビューパターン

---
description: コード変更をレビュー
allowed-tools: Read, Bash(git:*)
---

変更されたファイル: $ git diff --name-only

各ファイルを以下についてレビューしてください:
1. コード品質とスタイル
2. 潜在的なバグまたは問題
3. テストカバレッジ
4. ドキュメントの必要性

各ファイルの具体的なフィードバックを提供してください。

テストパターン

---
description: 特定ファイルのテストを実行
argument-hint: [test-file]
allowed-tools: Bash(npm:*)
---

テスト実行: $ npm test $1

結果を分析し、失敗に関する修正を提案してください。

ドキュメントパターン

---
description: ファイルのドキュメントを生成
argument-hint: [source-file]
---

@$1 の包括的なドキュメントを生成してください。以下を含めます:
- 関数/クラスの説明
- パラメータドキュメント
- 戻り値の説明
- 使用例
- エッジケースとエラー

ワークフローパターン

---
description: 完全な PR ワークフロー
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read
---

PR #$1 ワークフロー:

1. PR を取得: `gh pr view $1` を実行
2. 変更をレビュー
3. チェックを実行
4. 承認するか変更をリクエスト

トラブルシューティング

コマンドが表示されない:

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

引数が機能しない:

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

Bash 実行が失敗:

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

ファイル参照が機能しない:

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

プラグイン固有機能

CLAUDE_PLUGIN_ROOT 変数

プラグインコマンドは、プラグインの絶対パスに解決される環境変数 ${CLAUDE_PLUGIN_ROOT} にアクセスできます。

目的:

• プラグインファイルを可搬的に参照
• プラグインスクリプトを実行
• プラグイン設定を読み込み
• プラグインテンプレートにアクセス

基本的な使用方法:

---
description: プラグインスクリプトを使用して分析
allowed-tools: Bash(node:*)
---

分析を実行: $ node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1

結果をレビューして検査結果を報告してください。

一般的なパターン:

# プラグインスクリプトを実行
$ bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh

# プラグイン設定を読み込み
@${CLAUDE_PLUGIN_ROOT}/config/settings.json

# プラグインテンプレートを使用
@${CLAUDE_PLUGIN_ROOT}/templates/report.md

# プラグインリソースにアクセス
@${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: プラグイン設定を使用してデプロイ
argument-hint: [environment]
allowed-tools: Read, Bash(*)
---

設定を読み込み: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json

設定を使用して $1 にデプロイしてください。
デプロイを監視してステータスを報告します。

テンプレートベースパターン:

---
description: テンプレートからドキュメントを生成
argument-hint: [component]
---

テンプレート: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md

テンプレート構造に従って $1 のドキュメントを生成してください。

マルチスクリプトパターン:

---
description: 完全なビルドワークフロー
allowed-tools: Bash(*)
---

ビルド: $ bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh
テスト: $ bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh
パッケージ化: $ bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh

出力をレビューしてワークフロー状態を報告します。

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

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

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

エージェント統合

複雑なタスク用にプラグインエージェントを起動:

---
description: 深いコードレビュー
argument-hint: [file-path]
---

code-reviewer エージェントを使用して @$1 の包括的なレビューを開始します。

エージェントは以下を分析します:
- コード構造
- セキュリティ問題
- パフォーマンス
- ベストプラクティス

エージェントはプラグインリソースを使用します:
- ${CLAUDE_PLUGIN_ROOT}/config/rules.json
- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md

重要なポイント:

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

スキル統合

特化した知識用にプラグインスキルを活用:

---
description: 標準に従って API をドキュメント化
argument-hint: [api-file]
---

プラグイン標準に従って @$1 の API をドキュメント化してください。

api-docs-standards スキルを使用して以下を確保します:
- 完全なエンドポイントドキュメント
- 一貫したフォーマット
- 例の品質
- エラードキュメント

本番対応の API ドキュメントを生成してください。

重要なポイント:

• スキルは plugin/skills/ ディレクトリに存在する必要があります
• スキル名を提及して呼び出しをトリガー
• スキル目的を文書化
• スキルが提供するものを説明

フック調整

プラグインフックで機能するコマンドを設計:

• コマンドはフックが処理するための状態を準備できます
• フックはツールイベント上で自動的に実行されます
• コマンドは期待されるフック動作を文書化する必要があります
• Claude にフック出力の解釈をガイド

プラグインフックと調整するコマンドの例については references/plugin-features-reference.md を参照してください。

マルチコンポーネントワークフロー

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

---
description: 包括的なレビューワークフロー
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---

ターゲット: @$1

フェーズ 1 - 静的分析:
$ node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1

フェーズ 2 - 深いレビュー:
詳細分析用に code-reviewer エージェントを起動します。

フェーズ 3 - 標準確認:
coding-standards スキルを使用して検証します。

フェーズ 4 - レポート:
テンプレート: @${CLAUDE_PLUGIN_ROOT}/templates/review.md

テンプレートに従ってレポートに検査結果をコンパイルします。

使用時:

• 複雑なマルチステップワークフロー
• 複数のプラグイン機能を活用
• 特化した分析が必要
• 構造化された出力が必要

検証パターン

コマンドは処理前に入力とリソースを検証する必要があります。

引数検証

---
description: 検証でデプロイ
argument-hint: [environment]
---

環境を検証: $ echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"

$1 が有効な環境の場合:
  $1 にデプロイ
そうでない場合:
  有効な環境を説明: dev, staging, prod
  使用方法を表示: /deploy [environment]

ファイル存在確認

---
description: 設定を処理
argument-hint: [config-file]
---

ファイルが存在するか確認: $ test -f $1 && echo "EXISTS" || echo "MISSING"

ファイルが存在する場合:
  設定を処理: @$1
そうでない場合:
  設定ファイルの配置場所を説明
  期待される形式を表示
  設定例を提供

プラグインリソース検証

---
description: プラグインアナライザーを実行
allowed-tools: Bash(test:*)
---

プラグイン設定を検証:
- スクリプト: $ test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"
- 設定: $ test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"

すべてのチェックが成功した場合、分析を実行します。
そうでない場合、欠落しているコンポーネントを報告します。

エラー処理

---
description: エラー処理でビルド
allowed-tools: Bash(*)
---

ビルドを実行: $ bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"

ビルドが成功した場合:
  成功を報告して出力場所を表示
ビルドが失敗した場合:
  エラー出力を分析
  考えられる原因を提案
  トラブルシューティング手順を提供

ベストプラクティス:

• コマンド内で早期に検証