Commandsでワークフローを定義する

Commandsとは何か

Commandsは、よく使うワークフローをスラッシュコマンドとして定義する仕組みです。.claude/commands/<name>.mdにMarkdownファイルを作成すると、 Claude Code上で/nameと入力するだけでそのワークフローを実行できます。

Commandの最大の特徴は、ユーザーが明示的に起動するエントリーポイントであることです。 Claudeが自動的に呼び出すことはなく、常に/メニューに表示されます。 メインの会話コンテキストに知識をインラインで注入する形で動作します。

Skillsとの違い

CommandsとSkillsは似ていますが、明確な違いがあります。 この違いを理解しておくことで、適切な機構を選べるようになります。

• 起動方法: Commandはユーザーの明示起動のみ。 Skillsはユーザー起動に加え、Claudeによる自動呼び出しも可能
• コンテキスト: Commandは常にメイン会話とインラインで共有。 Skillsはcontext: forkで分離実行も可能
• メニュー表示: Commandは/メニューに常に表示される（非表示にできない）。 Skillsはuser-invocable: falseで非表示にできる

簡単に言えば、「自分で毎回起動するもの」はCommand、「Claudeに任せたいもの」はSkillです。

Command作成の基本

Commandファイルは.claude/commands/ディレクトリに.md形式で作成します。 SkillsとほぼYAMLフロントマターフィールドを共有しており、description、model、allowed-toolsなどを指定できます。

---
description: 技術的負債を検出してレポートを生成する
model: sonnet
allowed-tools: Read, Glob, Grep
---

# 技術的負債チェック

以下の手順で技術的負債を検出してください:

1. TODO/FIXME/HACKコメントを検索
2. 重複コードのパターンを特定
3. 未使用のインポートや変数を検出
4. 結果をMarkdownレポートとして出力

引数の受け取り

Commandでは$ARGUMENTS、$0、$1を使って引数を受け取れます。 ユーザーが/techdebt src/apiと入力した場合、$ARGUMENTSにsrc/apiが、$0にsrc/apiが入ります。

---
description: 指定ディレクトリの技術的負債をチェック
---

# 技術的負債チェック

対象ディレクトリ: $ARGUMENTS

上記ディレクトリ内のファイルを分析し、
技術的負債をレポートしてください。

動的コンテキスト

Commandの強力な機能の1つが、!`command`記法による動的コンテキスト注入です。 シェルコマンドの実行結果をプロンプトの一部として埋め込めます。

これにより、Commandの実行時に最新のプロジェクト状態を自動的に取り込めます。 毎回手動で情報を伝える必要がなくなるため、ワークフローの効率が大幅に向上します。

---
description: 現在の変更内容をレビューする
---

# コードレビュー

## 現在のブランチ
!`git branch --show-current`

## ステージされた変更
!`git diff --cached --stat`

## 変更の詳細
!`git diff --cached`

上記の変更内容をレビューし、
問題点や改善提案があれば指摘してください。

日常ワークフローをCommand化する

Commandの真価は、日常的に繰り返す作業を1コマンドに凝縮できることです。 Claude Codeのコミュニティで活躍するBoris氏は、「1日に2回以上やることはすべてCommand化すべき」と推奨しています。

私も実際にこのアプローチを試して、作業の立ち上がりが格段に速くなりました。 以下に実用的なCommandの例を紹介します。

/techdebt — 技術的負債の検出

---
description: プロジェクト内の技術的負債を検出・分類する
allowed-tools: Read, Glob, Grep
---

以下の観点でプロジェクトの技術的負債を検出してください:
- TODO/FIXME/HACKコメント
- 複雑度の高い関数
- テストカバレッジの低いモジュール

結果を優先度順にMarkdownで出力してください。

/context-dump — 現在の作業コンテキストの要約

---
description: 現在の作業状態を要約してセッション引き継ぎ用にまとめる
---

以下の情報を収集し、次のセッションで作業を再開できるよう
簡潔にまとめてください:

!`git branch --show-current`
!`git log --oneline -5`
!`git diff --stat`

## まとめるべき内容
1. 現在取り組んでいるタスクの概要
2. 完了した作業と未完了の作業
3. 次に取り組むべきステップ

/analytics — プロジェクトの統計分析

---
description: コードベースの統計情報を収集・分析する
model: haiku
allowed-tools: Bash, Glob, Grep
---

プロジェクトの統計情報を収集してください:
- ファイル数・行数（言語別）
- 最近1週間のコミット数・変更量
- 依存パッケージ数

結果を見やすいテーブル形式で出力してください。

Commandでオーケストレーションする

Commandは単なるプロンプトテンプレートにとどまりません。 Agent toolやSkill toolを呼び出すオーケストレーター（指揮者）として機能させることができます。

たとえば、Commandがまずユーザーに必要な情報を確認し、 次にAgentでデータを取得し、最後にSkillで成果物を生成する――という多段階のワークフローを構築できます。

---
description: データ取得から報告書生成までの一連の流れを実行
model: haiku
---

# 週次レポート生成

1. まずユーザーに対象期間を確認
2. Agent tool で data-collector エージェントを呼び出し、
   対象期間のデータを収集
3. Skill tool で report-generator スキルを呼び出し、
   収集データから週次レポートを生成

model: haikuを指定することで、オーケストレーション自体は軽量モデルで処理し、 重い処理は各Agent・Skillのモデル設定に任せるという効率的な設計が可能です。 この実行フローの設計パターンについては、次のページで詳しく解説します。

Commandの設計パターン

基本的なCommandの作り方がわかったところで、より実践的な設計パターンを紹介します。 これらのパターンを組み合わせることで、単なるプロンプトテンプレートではなく、 本格的な業務自動化ツールとしてCommandを活用できます。

$ARGUMENTSを活用した汎用Command

$ARGUMENTSはCommand起動時にユーザーが渡した引数全体を受け取ります。 さらに$0、$1、$2で個別の引数にアクセスできます。 これを使うと、1つのCommandで多様なユースケースに対応できます。

---
description: 指定コンポーネントのテストを生成する
argument-hint: [コンポーネントパス] [テスト種別]
allowed-tools: Read, Glob, Grep, Edit, Write
---

# テスト生成

対象: $0
テスト種別: $1（unit / integration / e2e）

## 手順
1. 対象コンポーネントのソースコードを読み取る
2. 既存のテストファイルがあれば確認する
3. 指定されたテスト種別に応じたテストを生成する
4. テストを実行して全件パスすることを確認する

/generate-test src/components/Header.tsx unitのように起動すると、$0にsrc/components/Header.tsx、$1にunitが入ります。argument-hintをフロントマターに記載しておくと、/メニューのオートコンプリートで引数のヒントが表示されるため、 チームメンバーにも使い方が伝わりやすくなります。

allowed-toolsで安全性を確保する

allowed-toolsを明示的に制限することは、Commandの安全性と予測可能性を高める重要なテクニックです。 たとえば、分析系のCommandにはRead, Glob, Grepのみを許可して、 ファイル編集やコマンド実行を防ぐことができます。

---
description: セキュリティ観点でコードをレビューする
allowed-tools: Read, Glob, Grep
---

# セキュリティレビュー（読み取り専用）

以下の観点でコードをレビューしてください:
- ハードコードされた認証情報やAPIキー
- SQLインジェクションの可能性
- XSS脆弱性
- 認証・認可の漏れ

※このCommandはコードの変更を行いません。
  問題を検出したら報告のみ行ってください。

読み取り専用のCommandではEditやBashを意図的に外しておきます。 逆に、ファイル生成を行うCommandではEdit, Writeを追加します。 ツールを制限することで「このCommandは何をするのか」が明確になり、 意図しない操作を防げます。

複数ステップのCommand設計

実務で使うCommandは、往々にして複数のステップで構成されます。 ステップを番号付きで明示することで、Claudeが手順を飛ばさず確実に実行してくれます。

---
description: PRを作成前にコード品質を総合チェックする
allowed-tools: Read, Glob, Grep, Bash
---

# PR前チェック

以下のステップを順番に実行してください。
各ステップの結果を報告し、問題があれば修正案を提示してください。

## Step 1: lint・型チェック
!`npm run lint 2>&1 | tail -20`
!`npx tsc --noEmit 2>&1 | tail -20`

## Step 2: テスト実行
!`npm test -- --silent 2>&1 | tail -30`

## Step 3: 変更差分の確認
!`git diff --stat`

## Step 4: 総合判定
上記の結果を総合して、PRを出せる状態かどうか判定してください。
問題がある場合は、優先度順に修正すべき点をリストアップしてください。

動的コンテキスト（!`command`）でステップの入力データを事前に収集し、 Claudeにはその結果を分析・判断させる設計です。 こうすることで、Claudeが自分でコマンドを実行する回数を減らし、 処理の予測可能性を高められます。

オーケストレーションとの連携

Commandの真の力は、Agent toolやSkill toolと組み合わせたときに発揮されます。 前のセクションで触れた基本パターンをさらに掘り下げ、 実際の業務フローにどう適用するかを解説します。

Command → Agent → Skill パターン

これはClaude Codeのオーケストレーションにおける最も基本的なパターンです。 Commandがエントリーポイントとして全体を指揮し、Agentがデータ取得や分析を担当し、 Skillが成果物を生成します。

---
description: プロジェクトのデプロイを実行する
model: haiku
---

# デプロイワークフロー

以下のステップを順番に実行してください。

## Step 1: ユーザーに確認
デプロイ先の環境（staging / production）を確認してください。

## Step 2: テスト実行（Agent）
Agent tool を使って test-runner エージェントを呼び出し、
全テストを実行してください。
- subagent_type: test-runner
- prompt: 全テストを実行し、結果を報告してください

テストが失敗した場合はデプロイを中止し、
失敗内容をユーザーに報告してください。

## Step 3: ビルド（Agent）
テストがすべてパスした場合のみ、
Agent tool を使って build-agent を呼び出してください。
- subagent_type: build-agent
- prompt: [環境名]向けにビルドを実行してください

## Step 4: デプロイ報告（Skill）
Skill tool を使って deploy-reporter スキルを呼び出し、
デプロイ結果のサマリーを生成してください。

このパターンのポイントは3つあります。 まず、Commandのmodel: haikuでオーケストレーション自体を軽量モデルで処理すること。 次に、各AgentやSkillは独自のモデル設定を持てるため、 重い処理だけ高性能モデルを使う効率的な構成が可能なこと。 そして、ステップ間の条件分岐（テスト失敗なら中止）を 自然言語で記述できることです。

並列Agent活用パターン

複数のAgentを並列で呼び出すことで、処理時間を大幅に短縮できます。 Claudeは独立したタスクを認識すると、自動的に並列実行します。

---
description: コードベースの総合分析レポートを生成する
model: haiku
---

# コードベース総合分析

以下の3つの分析を並列で実行してください。

## 分析1: セキュリティ
Agent tool で security-auditor エージェントを呼び出し、
セキュリティ上の問題を検出してください。

## 分析2: パフォーマンス
Agent tool で performance-analyzer エージェントを呼び出し、
パフォーマンスのボトルネックを特定してください。

## 分析3: コード品質
Agent tool で quality-checker エージェントを呼び出し、
コード品質メトリクスを収集してください。

## 統合レポート
3つの分析結果を統合し、優先度順に
改善アクションをまとめたレポートを生成してください。

各Agentが独立したコンテキストで動作するため、 メインの会話コンテキストを圧迫しません。 Boris氏も「サブエージェントを活用してメインエージェントのコンテキストウィンドウを クリーンに保つ」ことを推奨しています。

実務フロー例: 週次レポート自動生成

実際の業務で使えるオーケストレーションの例として、 週次レポートの自動生成フローを紹介します。

---
description: 週次レポートを自動生成する
model: haiku
---

# 週次レポート生成

## Step 1: データ収集
Agent tool で以下のデータを収集してください。
- subagent_type: data-collector
- prompt: |
    以下のデータを収集してください:
    - 今週のgitコミット統計（コミット数、変更行数、コントリビューター）
    - マージされたPR一覧
    - クローズされたissue一覧
    - 残っているオープンissue数

## Step 2: 分析
収集したデータをもとに、以下の観点で分析してください:
- 先週と比較した開発速度の変化
- 主要な成果物
- ブロッカーとなっている課題

## Step 3: レポート生成
Skill tool で report-writer スキルを呼び出し、
分析結果をMarkdownレポートとして出力してください。

Commandのデバッグと改善

Commandを作ったものの期待通りに動かない、というのはよくあることです。 ここでは、よくある問題パターンとその解決方法を紹介します。

期待通り動かないときの確認ポイント

• フロントマターの構文エラー: YAMLフロントマターの インデント、コロン後のスペース、文字列のクォートを確認する。 特にdescriptionに日本語を使う場合、 値をクォートで囲むと安全
• allowed-toolsの不足: Commandが途中で止まる場合、 必要なツールがallowed-toolsに含まれていないことが多い。 たとえばファイル検索にGlobとGrepの両方が必要な場合がある
• 動的コンテキストの失敗: !`command`のシェルコマンドが エラーを返している場合、そのエラー出力がプロンプトに混入する。2>&1でstderrをキャプチャし、| tail -Nで出力量を制限するのが安全
• $ARGUMENTSが空: ユーザーが引数を渡し忘れた場合に Commandが意図しない動作をすることがある。 プロンプト内に「引数が空の場合はユーザーに確認する」と記載しておく
• コンテキスト過多: 動的コンテキストで大量のデータを注入すると、 コンテキストウィンドウを圧迫する。| head -50や--statオプションで出力を要約する

プロンプト改善のイテレーション方法

Commandは一度作って終わりではなく、使いながら改善していくものです。 Boris氏のチームでは「1日に2回以上やることはCommand化し、 使うたびにCLAUDE.mdを更新する」という習慣を推奨しています。 Commandのプロンプトも同じように、使うたびに磨いていきます。

• まず最小限で動かす: 最初は2〜3行のシンプルなCommandから始める。 複雑なフロントマターや多段階ステップは後から追加する
• 失敗パターンを記録する: 期待と異なる出力が出たら、 その状況をCommandのプロンプトに「禁止事項」として追記する。 たとえば「ファイルを削除しないこと」「確認なしにpushしないこと」など
• 出力フォーマットを指定する: 「Markdownテーブルで出力」 「JSON形式で出力」のように、出力の形式を明示すると結果が安定する
• modelを使い分ける: 軽量な分析はmodel: haiku、 複雑な判断が必要なものはmodel: sonnetやmodel: opusを指定する。 コストと品質のバランスを実際に試して調整する
• チームでレビューする: Commandファイルは.claude/commands/に Markdownとして保存されるため、通常のコードと同様にPRレビューできる。 チームメンバーからのフィードバックがCommand品質の向上に直結する

デバッグ用Commandの例

Command自体をデバッグするためのCommandを用意しておくのも効果的です。

---
description: 指定したCommandファイルの内容を検証する
argument-hint: [command-name]
allowed-tools: Read, Glob
---

# Command検証

対象: .claude/commands/$ARGUMENTS.md

## チェック項目
1. ファイルが存在するか確認
2. YAMLフロントマターの構文が正しいか検証
3. 使用している変数（$ARGUMENTS, $0, $1等）が
   適切に参照されているか確認
4. allowed-toolsに指定されたツールが
   プロンプト内の指示と整合しているか確認
5. 問題があれば修正案を提示

まとめ

Commandsは、日常の繰り返し作業をスラッシュコマンド1つに凝縮する仕組みです。 動的コンテキストで実行時の最新情報を自動取得し、引数で柔軟にパラメータを変えられます。allowed-toolsで安全性を確保し、複数ステップの設計で複雑なワークフローにも対応できます。

さらに、Agent・Skillと組み合わせたオーケストレーションにより、 テスト→ビルド→デプロイのような多段階の業務フローも自動化できます。 まずは1日に何度も繰り返している作業を洗い出し、最小限のCommandから始めてください。 使いながらプロンプトを磨き、必要に応じてAgent・Skillを追加していくのが最も効果的なアプローチです。