Claude Codeカスタムコマンド完全ガイド | Eraxel Blog

はじめに

Claude Codeの真の力は、カスタムコマンドを作成することで発揮されます。頻繁に使用するタスクをコマンド化することで、開発効率を劇的に向上させることができます。

本記事では、Claude Codeのカスタムコマンドの作成から実行まで、実践的な例を交えながら詳しく解説します。実際に使えるコマンドのコードも含めているので、すぐに活用できます。

カスタムコマンドとは？

カスタムコマンドは、特定のタスクや一連の処理をClaude Codeで自動化するための仕組みです。以下のようなメリットがあります：

繰り返し作業の自動化
チーム内での標準化されたワークフロー
複雑なタスクの簡略化
プロジェクト固有の処理の効率化

カスタムコマンドの基本構造

Claude Codeのカスタムコマンドは、YAML形式の設定ファイルで定義します。基本的な構造は以下の通りです：

commands:
  command_name:
    description: "コマンドの説明"
    template: |
      実行するプロンプトのテンプレート
    parameters:
      - name: param_name
        description: "パラメータの説明"
        required: true
        default: "デフォルト値"

ステップ1：設定ファイルの作成

まず、カスタムコマンドを定義する設定ファイルを作成します。

# Claude Code設定ディレクトリに移動
cd ~/.config/claude-code

# カスタムコマンド用のディレクトリを作成
mkdir -p commands

# メインの設定ファイルを作成
touch commands/custom_commands.yaml

ステップ2：基本的なカスタムコマンドの作成

例1：コードレビューコマンド

# ~/.config/claude-code/commands/custom_commands.yaml
commands:
  review:
    description: "指定されたファイルのコードレビューを実行"
    template: |
      以下のコードをレビューしてください：
      
      ファイル: {filename}
      言語: {language}
      
      レビューの観点：
      1. コードの品質と可読性
      2. パフォーマンスの改善点
      3. セキュリティの懸念事項
      4. ベストプラクティスとの整合性
      5. バグの可能性
      
      コード内容：
      ```{language}
      {file_content}
      ```
      
      具体的な改善提案と修正例を含めて、詳細なレビューを提供してください。
    parameters:
      - name: filename
        description: "レビュー対象のファイルパス"
        required: true
      - name: language
        description: "プログラミング言語"
        required: false
        default: "auto-detect"

例2：テスト生成コマンド

  generate-tests:
    description: "指定された関数やクラスのユニットテストを生成"
    template: |
      以下のコードに対する包括的なユニットテストを生成してください：
      
      ファイル: {filename}
      テストフレームワーク: {framework}
      カバレッジ目標: {coverage}%
      
      コード：
      ```{language}
      {code_content}
      ```
      
      要件：
      1. エッジケースを含む包括的なテストケース
      2. モックが必要な場合は適切に使用
      3. テストの説明とアサーションを明確に
      4. {framework}のベストプラクティスに従う
      
      生成するテストは実行可能で、保守しやすいものにしてください。
    parameters:
      - name: filename
        description: "テスト対象のファイル"
        required: true
      - name: framework
        description: "使用するテストフレームワーク"
        required: false
        default: "pytest"
      - name: coverage
        description: "目標カバレッジ率"
        required: false
        default: "90"
      - name: language
        description: "プログラミング言語"
        required: false
        default: "python"

例3：リファクタリングコマンド

  refactor:
    description: "コードのリファクタリングを提案・実行"
    template: |
      以下のコードをリファクタリングしてください：
      
      ファイル: {filename}
      リファクタリングの種類: {refactor_type}
      
      現在のコード：
      ```{language}
      {original_code}
      ```
      
      リファクタリング要件：
      - {refactor_type}の原則に従う
      - 機能は変更しない
      - テストが通ることを前提とする
      - コメントで変更理由を説明
      
      以下の形式で提供してください：
      1. リファクタリング前後の違いの説明
      2. 改善されたコード
      3. 必要に応じて追加のリファクタリング提案
    parameters:
      - name: filename
        description: "リファクタリング対象のファイル"
        required: true
      - name: refactor_type
        description: "リファクタリングの種類（DRY, SOLID, 可読性向上など）"
        required: false
        default: "一般的な改善"
      - name: language
        description: "プログラミング言語"
        required: false
        default: "auto-detect"

ステップ3：プロジェクト固有のカスタムコマンド

プロジェクトごとに異なるカスタムコマンドを作成することも可能です。

# プロジェクトルート/.claude-code/commands.yaml
commands:
  setup-component:
    description: "新しいReactコンポーネントのボイラープレートを生成"
    template: |
      以下の仕様で新しいReactコンポーネントを作成してください：
      
      コンポーネント名: {component_name}
      タイプ: {component_type}
      スタイリング: {styling_method}
      
      要件：
      1. TypeScriptを使用
      2. 適切なPropsインターフェースを定義
      3. {styling_method}でスタイリング
      4. 基本的なアクセシビリティを考慮
      5. Storybookストーリーファイルも生成
      
      以下のファイルを生成してください：
      - {component_name}.tsx
      - {component_name}.{style_extension}
      - {component_name}.stories.tsx
      - {component_name}.test.tsx
    parameters:
      - name: component_name
        description: "コンポーネント名（PascalCase）"
        required: true
      - name: component_type
        description: "functional/class"
        required: false
        default: "functional"
      - name: styling_method
        description: "CSS Modules/styled-components/Tailwind"
        required: false
        default: "CSS Modules"
      - name: style_extension
        description: "スタイルファイルの拡張子"
        required: false
        default: "module.css"

ステップ4：カスタムコマンドの実行

基本的な実行方法

# コマンドリストの確認
claude-code list-commands

# カスタムコマンドの実行
claude-code run review --filename src/utils/api.ts --language typescript

# パラメータを対話的に入力
claude-code run generate-tests -i

シェルエイリアスの設定

頻繁に使用するコマンドはエイリアスを設定すると便利です：

# ~/.bashrc or ~/.zshrc に追加
alias ccr="claude-code run review"
alias cct="claude-code run generate-tests"
alias ccrf="claude-code run refactor"

# 使用例
ccr --filename main.py

ステップ5：高度なカスタムコマンド

複数ファイル処理コマンド

commands:
  analyze-directory:
    description: "ディレクトリ全体のコード分析"
    template: |
      以下のディレクトリ構造を分析してください：
      
      ディレクトリ: {directory}
      除外パターン: {exclude_patterns}
      
      ファイルリスト：
      {file_list}
      
      分析項目：
      1. 全体的なアーキテクチャの評価
      2. コードの重複や改善可能な箇所
      3. 依存関係の健全性
      4. セキュリティの懸念事項
      5. パフォーマンスのボトルネック
      
      改善提案を優先度付きで提供してください。
    parameters:
      - name: directory
        description: "分析対象のディレクトリ"
        required: true
      - name: exclude_patterns
        description: "除外するファイルパターン"
        required: false
        default: "node_modules,*.pyc,__pycache__"
    pre_process: |
      import os
      import fnmatch
      
      def get_file_list(directory, exclude_patterns):
          files = []
          excludes = exclude_patterns.split(',')
          
          for root, dirs, filenames in os.walk(directory):
              # 除外ディレクトリをスキップ
              dirs[:] = [d for d in dirs if not any(fnmatch.fnmatch(d, pattern.strip()) for pattern in excludes)]
              
              for filename in filenames:
                  if not any(fnmatch.fnmatch(filename, pattern.strip()) for pattern in excludes):
                      filepath = os.path.join(root, filename)
                      files.append(filepath)
          
          return '\n'.join(files)
      
      file_list = get_file_list(directory, exclude_patterns)

ドキュメント生成コマンド

  generate-docs:
    description: "コードからドキュメントを自動生成"
    template: |
      以下のコードからAPI ドキュメントを生成してください：
      
      ファイル: {filename}
      ドキュメント形式: {doc_format}
      詳細度: {detail_level}
      
      コード：
      ```{language}
      {code_content}
      ```
      
      生成するドキュメントの要件：
      1. すべての公開API（関数、クラス、メソッド）を文書化
      2. パラメータの型と説明を含める
      3. 戻り値の説明
      4. 使用例を含める（{detail_level}が'detailed'の場合）
      5. {doc_format}形式で出力
      
      明確で開発者フレンドリーなドキュメントを作成してください。
    parameters:
      - name: filename
        description: "ドキュメント化するファイル"
        required: true
      - name: doc_format
        description: "Markdown/Sphinx/JSDoc"
        required: false
        default: "Markdown"
      - name: detail_level
        description: "basic/detailed"
        required: false
        default: "detailed"
      - name: language
        description: "プログラミング言語"
        required: false
        default: "auto-detect"

ステップ6：カスタムコマンドの管理

バージョン管理

# Git でカスタムコマンドを管理
cd ~/.config/claude-code
git init
git add commands/
git commit -m "Add custom Claude Code commands"

チーム共有

# team-commands.yaml - チーム共通のコマンド
include:
  - url: https://github.com/yourteam/claude-commands/main/commands.yaml
  - path: ./local-commands.yaml

commands:
  team-review:
    extends: review  # 既存コマンドを拡張
    template: |
      {super}  # 親コマンドのテンプレートを継承
      
      追加のチーム固有ルール：
      - 社内コーディング規約の遵守
      - セキュリティチェックリストの確認

トラブルシューティング

よくある問題と解決方法

問題1：コマンドが認識されない

# 設定ファイルの検証
claude-code validate-config

# 設定の再読み込み
claude-code reload-config

問題2：パラメータが正しく渡されない

# デバッグモードで実行
claude-code run review --debug --filename test.py

問題3：テンプレートエラー

# YAMLのインデントを確認
# template: | の後は必ず改行
template: |
  正しいインデント

ベストプラクティス

1. 命名規則

コマンド名は動詞-名詞形式（generate-tests, review-code）
わかりやすく簡潔に

2. パラメータ設計

必須パラメータは最小限に
適切なデフォルト値を設定

3. テンプレート作成

明確で具体的な指示
出力形式を明示

4. エラーハンドリング

想定されるエラーケースを考慮
ユーザーフレンドリーなメッセージ

まとめ

Claude Codeのカスタムコマンドは、開発ワークフローを大幅に効率化する強力な機能です。本記事で紹介したコマンドをベースに、プロジェクトやチームのニーズに合わせてカスタマイズしてください。

カスタムコマンドを活用することで、以下のようなメリットが得られます：

繰り返し作業の自動化による時間短縮
チーム全体での作業品質の標準化
複雑なタスクの簡略化
新規メンバーのオンボーディング効率化

ぜひ、今日からカスタムコマンドを作成して、より生産的な開発環境を構築してください！

注：Claude Codeは現在リサーチプレビュー版です。機能や仕様は変更される可能性があります。最新情報はAnthropicの公式ドキュメントをご確認ください。

Claude Codeカスタムコマンド完全ガイド：効率的な開発ワークフローの構築