directive-synthesis

Claude Code コマンドビルダー

目的

適切な構造、引数処理、ワークフロー設計を備えた効果的な Claude Code スラッシュコマンドの作成をユーザーに案内します。ユーザーがカスタムコマンドの作成や変更を希望すると、自動的に呼び出されます。

使用するタイミング

ユーザーが次のような内容に言及した場合、自動的に呼び出します。

• コマンドの作成 - 「コマンドを作成」「コマンドを作る」「新しいスラッシュコマンド」
• コマンドの構造 - 「コマンドのテンプレート」「コマンドの形式」「コマンドのフロントマター」
• 引数 - "$ARGUMENTS"、"$1"、"$2"、「コマンドのパラメーター」、「位置引数」
• ワークフロー - 「コマンドのワークフロー」「コマンドの手順」「コマンドのプロセス」
• Bash の実行 - "!command"、「コマンド内で Bash を実行」、「Bash を使うコマンド」

ナレッジベース

• 公式ドキュメント：.claude/skills/ai/claude-code/docs/code_claude_com/docs_en_slash-commands.md
• プロジェクトガイド：.claude/docs/creating-components.md
• リポジトリ内の例：.claude/commands/

プロセス

1. 要件を確認する

ユーザーに次の内容を尋ねます。

Let me help you create a Claude Code slash command! I need a few details:

1. **Command name** (lowercase-with-hyphens):
   Example: deploy, review-pr, commit, analyze-tokens
   This will be invoked as: /your-command-name

2. **What does this command do?**
   Describe the workflow in 1-2 sentences.

3. **Does it need arguments?**
   - None (simple prompt)
   - All arguments: $ARGUMENTS
   - Positional: $1, $2, $3, etc.

4. **Does it need bash execution?**
   Commands that run before the slash command (e.g., !`git status`)

5. **Scope:**
   - Personal (`~/.claude/commands/`) - just for you
   - Project (`.claude/commands/`) - shared with team

6. **Namespace/subdirectory?**
   Example: git/, deploy/, testing/
   Helps organize related commands

2. 入力を検証する

コマンド名を確認します。

• 有効なファイル名であること（スペースや、ハイフン以外の特殊文字を含まない）
• 説明的で覚えやすいこと
• 組み込みコマンドと競合しないこと
• アンダースコアではなくハイフンを使うこと

引数を検証します。

• 想定される引数を定義する
• 必要に応じてデフォルト値を指定する
• 引数の順序を記載する

3. コマンドの種類を決める

シンプルなプロンプト（フロントマターなし）：

Analyze this code for performance issues and suggest optimizations.

引数あり：

---
argument-hint: [file-path]
description: Analyze file for performance issues
---

Analyze the file at $1 for performance issues and suggest optimizations.

Bash 実行あり：

---
allowed-tools: Bash(git status:*), Bash(git diff:*)
description: Create a git commit
---

## Current State

- Git status: !`git status`
- Staged changes: !`git diff --staged`
- Recent commits: !`git log --oneline -5`

## Your Task

Based on the above changes, create a git commit with a clear, conventional commit message.

フル機能：

---
allowed-tools: Bash(npm run:*), Bash(git add:*), Bash(git commit:*)
argument-hint: [component-name]
description: Create a new React component with tests
model: sonnet
---

# Create React Component

Component name: $1

Execute the following workflow:

1. **Validate Input**
   !`test -n "$1" && echo "Creating component: $1" || echo "Error: Component name required"`

2. **Check Existing Files**
   !`ls src/components/$1.tsx 2>/dev/null || echo "Component does not exist"`

3. **Create Files**
   Create the following files:
   - `src/components/$1.tsx`
   - `src/components/$1.test.tsx`
   - `src/components/$1.module.css`

4. **Run Tests**
   After creation, run: !`npm run test -- $1`

4. コマンドファイルを生成する

複雑さに応じてコマンドの構造を作成します。

シンプルなコマンドのテンプレート：

Brief description of what the command does.

[Prompt instructions for Claude]

フロントマター付きコマンドのテンプレート：

---
argument-hint: [arg1] [arg2]
description: Brief description shown in /help
allowed-tools: Bash(command:*), Read, Write
model: sonnet
disable-model-invocation: false
---

# Command Name

Usage: /command-name [args]

[Detailed instructions]

5. コマンドのワークフローを構築する

明確な手順でワークフローを構成します。

Execute the following workflow:

1. **Step Name**
   ```bash
   # Bash command (if needed)
   command arg1 arg2

• この手順で行うこと
• 検証チェック
• エラー処理

2. 次の手順 [Claude への指示]

   • 確認する内容
   • 進め方
   • 出力する内容

3. 最後の手順

   • 結果の概要
   • ユーザーが次に行うこと
   • 成功条件

### 6. Add Argument Handling

**All Arguments ($ARGUMENTS):**
```markdown
Fix issue #$ARGUMENTS following our coding standards.

ユーザーが実行：/fix-issue 123 high-priority 次のようになります：「コーディング規約に従って、課題 #123（優先度：high-priority）を修正してください。」

位置引数（$1、$2、$3）：

Review PR #$1 with priority $2 and assign to $3.
Focus on: $4

ユーザーが実行：/review-pr 456 high alice security 個別に参照できるパラメーターになります。

デフォルト値を使う場合：

---
argument-hint: [environment] [branch]
---

Deploy to environment: ${1:-staging}
From branch: ${2:-main}

7. Bash 実行を追加する（必要な場合）

処理の前にコマンドを実行するには、! プレフィックスを使います。

---
allowed-tools: Bash(git:*)
---

## Context

- Current branch: !`git branch --show-current`
- Status: !`git status --short`
- Recent commits: !`git log --oneline -5`

## Your Task

[Instructions based on the above context]

重要：

• 特定の Bash 権限を指定した allowed-tools が必要です
• 出力はコマンドのコンテキストに含まれます
• コマンドは Claude がプロンプトを処理する前に実行されます

8. ファイル参照を追加する

ファイルを参照するには、@ プレフィックスを使います。

Review the implementation in @src/utils/helpers.js

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

Analyze all files in @src/components/

9. 思考モードを設定する（必要な場合）

複雑な問題では、拡張思考を開始します。

Carefully analyze the following code and think through...

Let's approach this step by step...

Consider all edge cases before implementing...

これらのキーワードによって、拡張思考モードを開始できます。

10. ファイルを作成する

正しい場所に保存します。

個人用コマンド：

~/.claude/commands/command-name.md
~/.claude/commands/category/command-name.md  # With namespace

プロジェクト用コマンド：

.claude/commands/command-name.md
.claude/commands/category/command-name.md  # With namespace

11. コマンドをテストする

テスト手順を提示します。

To test your command:
1. Restart Claude Code or start a new session
2. Type: /help
3. Find your command in the list
4. Try: /your-command-name [args]
5. Verify it behaves as expected

テストケース：

# No arguments
/your-command

# With arguments
/your-command arg1
/your-command arg1 arg2

# Edge cases
/your-command ""
/your-command "with spaces"

フロントマターのリファレンス

フィールド	用途	例
argument-hint	オートコンプリートに想定される引数を表示する	[pr-number] [priority]
description	/help メニューに表示する簡単な説明	Review pull request
allowed-tools	コマンドで使用できるツール	Bash(git:*), Read, Write
model	使用する特定のモデル	claude-sonnet-4-5-20250929
disable-model-invocation	SlashCommand ツールがこのコマンドを呼び出せないようにする	true

Bash ツールの権限

! プレフィックスを使う場合や、Bash の実行が必要な場合：

---
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git push:*)
---

権限のパターン：

• Bash(git:*) - すべての git コマンド
• Bash(npm run:*) - すべての npm run スクリプト
• Bash(git add:*), Bash(git commit:*) - 特定の git コマンド

引数のパターン

パターン 1：すべての引数

Run tests for: $ARGUMENTS

使用例：/test users api database 次のようになります：「users api database のテストを実行してください」

パターン 2：位置引数

Deploy $1 to $2 environment with tag $3

使用例：/deploy my-app staging v1.2.3 次のようになります：「my-app をタグ v1.2.3 で staging 環境にデプロイしてください」

パターン 3：混合

---
argument-hint: <file> [rest of args]
---

Analyze file $1 for: $ARGUMENTS

使用例：/analyze src/app.js performance security 次のようになります：「ファイル src/app.js を次の内容で分析します：src/app.js performance security」 注：$ARGUMENTS にはすべての引数が含まれるため、$1 は重複します

より良い方法：

Analyze file $1 for: ${2:+${@:2}}

これは $1 を個別に使用し、残りの引数を $2 から使用します

パターン 4：デフォルト値あり

Environment: ${1:-production}
Verbose: ${2:-false}

コマンドのサイズに関するガイドライン

• ✅ 良好： 100 行未満
• ⚠️ 警告： 100～150 行
• ❌ 大きすぎます： 250 行超（リファクタリングが必要です）

大きすぎる場合：

• 外部スクリプトに切り出す
• 複数のコマンドに分割する
• サブコマンドパターンを使用する

よくあるコマンドの種類

1. Git ワークフロー

---
allowed-tools: Bash(git:*)
description: Create conventional commit
---

## Context
- Status: !`git status --short`
- Diff: !`git diff HEAD`

Create a conventional commit message.

2. コードジェネレーター

---
argument-hint: [component-name]
description: Generate React component
---

Create a new React component named $1:
- Component file
- Test file
- Storybook story

3. 分析ツール

---
argument-hint: [file-path]
description: Analyze code complexity
---

Analyze @$1 for:
- Cyclomatic complexity
- Code smells
- Improvement suggestions

4. デプロイヘルパー

---
allowed-tools: Bash(npm:*), Bash(git:*)
argument-hint: [environment]
description: Deploy to environment
---

Deploy to ${1:-staging}:
1. Run tests: !`npm test`
2. Build: !`npm run build`
3. Deploy: !`npm run deploy:$1`

5. ドキュメントジェネレーター

---
argument-hint: [file-pattern]
description: Generate API documentation
---

Generate documentation for: $1
Include:
- Function signatures
- Parameters
- Return types
- Examples

TOON Formatter の例

シンプルなバージョン：

# Convert to TOON

Convert the specified JSON file to TOON v2.0 format with automatic optimization and show token savings.

Usage: /convert-to-toon <file>

bash を使った高度なバージョン：

---
allowed-tools: Bash(jq:*), Bash(.claude/utils/toon/zig-out/bin/toon:*)
argument-hint: <file> [--delimiter comma|tab|pipe]
description: Convert JSON to TOON format
---

# Convert to TOON

File: $1
Delimiter: ${2:-comma}

1. **Validate**: !`test -f "$1" && jq empty "$1" 2>&1`
2. **Analyze**: !`jq 'if type == "array" then length else 0 end' "$1"`
3. **Convert**: !`.claude/utils/toon/zig-out/bin/toon encode "$1"`
4. Show savings comparison

トラブルシューティング

コマンドが見つからない

確認事項：

# List all commands
ls ~/.claude/commands/*.md
ls .claude/commands/*.md

# Verify filename
ls .claude/commands/your-command.md

注意事項：

• ファイル名（.md を除く）がコマンド名になります
• ファイル名のハイフンはコマンドのハイフンになります
• Linux/Mac では大文字と小文字が区別されます

引数が機能しない

デバッグ：

Debug: $ARGUMENTS
Debug $1: "$1"
Debug $2: "$2"

コマンドを実行し、渡されている内容を確認するために出力を確認します。

Bash コマンドが実行されない

確認事項：

1. allowed-tools に正しい Bash 権限が含まれている
2. ! プレフィックスを使用している：!command``
3. バッククォートが正しい：`command` であり、'command' ではない
4. コマンドが権限によって許可されている

コマンドが /help に表示されない

考えられる理由：

• ファイルが正しい場所にない
• ファイルの拡張子が .md ではない
• フロントマターに構文エラーがある
• Claude Code の再起動が必要

ベストプラクティス

推奨事項：

✅ 引数のヒントを明確に示す ✅ 使用例を含める ✅ エラーを適切に処理する ✅ 長時間の処理では進捗を表示する ✅ 想定される動作を説明する ✅ さまざまな入力でテストする ✅ 説明的なコマンド名を使う

避けるべき事項：

❌ コマンドを複雑にしすぎる（250 行超） ❌ Bash の allowed-tools の指定を忘れる ❌ わかりにくい引数名を使う ❌ エラー処理を省略する ❌ 値をハードコードする（引数を使用する） ❌ エッジケースのテストを忘れる

比較：コマンドとスキル

コマンドを使う場合：

• 明示的な制御（手動での呼び出し）が必要な場合
• シンプルで繰り返し使うプロンプト
• 特定のワークフロー手順
• 頻繁に使うテンプレート

スキルを使う場合：

• Claude に必要性を自動検出させる場合
• 複雑な複数ファイルのワークフロー
• 包括的なドメイン知識
• チームで標準化された専門知識が必要な場合

両方を使用できます：

• コマンドからスキルを明示的に呼び出す
• スキルが自動的に有効になる
• コマンドで素早くアクセスする
• スキルで高度な機能を提供する

リソース

• 公式コマンドドキュメント： .claude/skills/ai/claude-code/docs/code_claude_com/docs_en_slash-commands.md
• プロジェクトコンポーネントガイド： .claude/docs/creating-components.md
• コマンドの例： .claude/commands/ ディレクトリ
• スキルとコマンド： slash-commands.md のセクション