Slash Command 応用編：サブエージェントとツールの連携

前2回では、slash command とは何か（Markdown ファイル1つ）と、! プレフィックスで shell 出力を context に注入する方法を扱った。今回はもっと重いテーマ——1つの command で Claude Code の最も強力な機能（ファイル参照、サブエージェント、MCP ツール）を編成し、かつ権限もきちんと管理する方法だ。

このレベルまで来ると、command はもう「プロンプトのショートカット」ではなく、再利用可能な小さなワークフローになる。

`@file` 参照：`!cat` より適した静的注入

!cat file.md でもファイルの中身を context に入れられるが、shell 経由なので欠点がある。毎回サブプロセスが起動する、パスにスペースや特殊文字があるとエスケープが必要、Claude Code はそれを「1つのファイル」ではなく単なるテキストとして扱う。

@ 参照はネイティブだ。

---
description: プロジェクト規約に沿って変更をレビュー
---

参照する規約：

@.claude/context/coding-standards.md
@.claude/context/security-checklist.md

下の git diff の変更をレビューし、規約違反の箇所をすべて指摘してください。

!`git diff HEAD`

@パス は Claude Code に「このファイルを添付として会話に入れろ」と指示する。違いはこうだ。

シーン	`!cat` を使う	`@` を使う
パスが引数（`$ARGUMENTS`）から来る	✅ `!cat` 必須	❌ `@` は変数展開しない
固定の規約・テンプレート	⚠️ 使えるが重い	✅ ネイティブ、shell 不要
動的コンテンツ（diff・ログ・テスト結果）	✅ `!` 必須	❌ 不可

原則：静的ファイルは @、動的出力は !、引数パスは !cat $ARGUMENTS。

`allowed-tools`：command に権限境界を設ける

デフォルトでは、command 実行中にモデルはセッション内の全ツールを使える。これが望ましくない場面がある——たとえば /review は読み取り専用のレビュータスクなのに、「ついでに」1行書き換えられては困る。

frontmatter に allowed-tools を追加すると、command が動いている間は列挙されたツールしか使えなくなる。

---
description: 読み取り専用コードレビュー
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
---

現在のブランチと master の差分をレビュー。読むだけで、変更はしない。

!`git diff master...HEAD`

ポイント：

Bash(git diff:*) は細粒度の認可——git diff で始まる bash 呼び出しだけ許可、git push はブロックされる
Read / Grep / Glob は読み取り専用ツールだけを明示的に与える
Edit / Write は列挙していないので、モデルが変更したくても呼び出せない

逆に /deploy のような高権限 command でも同じ仕組みが使える。

---
description: 現ブランチをデプロイ
allowed-tools: Bash(kamal deploy:*), Bash(git push:*), Read
---

「この command が何をできるか」を固定してしまう方が、実行のたびに手動で bash の承認を出すより信頼できる。

サブエージェントの呼び出し：context を食う作業を隔離する

メイン会話の context を一瞬で食い尽くすタスクがある——数十ファイルを巡回して関数の全呼び出し箇所を探す、コードベース全体の統計を取る、大量のログを分析する。これをメイン会話で直接やると、何千行もの出力が context に残り、以降の会話が遅く・鈍くなっていく。

正解は、その仕事を subagent に渡すこと。サブエージェントは独立した context で動き、終わったら結論だけをメイン会話に返す。command 側では明示的に指示するだけでいい。

---
description: あるシンボルの全使用箇所を深掘り調査
allowed-tools: Task
---

Explore サブエージェントで、以下のシンボルの全使用箇所を深掘り調査してください：$ARGUMENTS

サブエージェントは次を網羅すること：
- すべての呼び出し箇所（テストファイル含む）
- カバーされている業務シナリオ
- 同等の代替実装の有無

サブエージェントから戻ってきたら、300字以内のまとめだけを返してください。生のコード断片は貼らないこと。

/trace SomeClass#some_method を実行すると、Claude Code は Explore サブエージェントを起動してコードベースを並列スキャンし、メイン会話には抽出された結論だけが返る。grep の出力もファイル断片もなく、context はクリーンなまま。

さらに踏み込んだ使い方。

---
description: 3つの候補案を並列調査
allowed-tools: Task
---

3つのサブエージェントを並行で起動し、それぞれ以下の実装経路を調査してください：

1. 既存の ActiveJob + Sidekiq
2. Solid Queue
3. 自前の軽量キュー

各エージェントは：工数・リスク・既存コードへの侵入度を回答すること。3つの結論が揃ったら、比較はこちらで行う。

3つのサブエージェントが並列実行され、メイン会話は1回だけ待てばいい。これは command が提供する最大のレバレッジの1つ——「結論を得るのに大量のトークンが必要な調査タスク」を、ワンショットで起動できるワークフローにする。

MCP ツールの呼び出し：command を外部システムに接続する

セッションに MCP サーバ（Linear、GitHub、Sentry、自前 DB プロキシなど）が接続されているなら、command からモデルに直接これらのツールを使わせられる。

---
description: Linear issue から実装 todo を生成
allowed-tools: mcp__linear__*, Read, Grep
---

Linear issue $ARGUMENTS の完全な説明とコメントを読み取ってください。

コードベースの現状（Grep/Read で自分で関連ファイルを探す）と合わせて、実装 todo を作成：
- 変更が必要なファイル
- 各ステップは独立 commit か、まとめて commit か
- PM に先に確認すべき曖昧な点

コードは書き始めず、計画だけを出す。

mcp__linear__* で Linear MCP のすべてのツールを許可し、モデルは issue の詳細・コメント・ステータスを取得できる。command 全体が「チケットから実装計画へ」というワークフローの入口になる。

注意点：allowed-tools に MCP ツール名を書くときは完全なプレフィックス（mcp__<server>__<tool>）を使うこと。そうでないと認可が効かない。

command の組み合わせの落とし穴：slash は再帰展開されない

よくある誤解：/review のファイル内に /test と書けば test command が発火する、と思ってしまうこと。発火しない。 slash command はユーザー入力のトップレベルで1回だけ展開される。command 内部の /xxx は単なる文字列——モデルは読むが、Claude Code は実行しない。

複数の command を組み合わせたいなら、正しいアプローチは以下。

アプローチ A：共有ロジックを context ファイルに抽出し、各 command から @ か !cat で参照する

@.claude/context/review-checklist.md
@.claude/context/security-checklist.md

アプローチ B：「/review と同じ手順で」と書いて、重要な指示を繰り返す

優雅ではないが機能する。プロンプトが明確であれば、モデルは同じ手順に従う。

アプローチ C：1つの command が Task ツールでサブエージェントを起動し、サブエージェントのプロンプトで同じ context ファイルを再利用する

本格的なワークフロー編成は全部ここに行き着く。親 command が調整とまとめを担い、サブエージェントが実際のステップを実行する。

避けるべきアンチパターン：1つの command を何百行にも書いて、1回の指示で全部やろうとすること。粒度が崩れると保守コストが跳ね上がり、1回の実行でトークン予算も使い切ってしまう。

三種の神器の使い分け

@、!、サブエージェント、MCP ツールまで揃ったところで、Claude Code で command に「外部能力」を注入する仕組みは出揃った。選び方は次の通り。

要件	第一選択
固定の規約・テンプレート・コンテキスト文書	`@file` 参照
リアルタイム状態（diff・ログ・テスト結果・DB クエリ）	`!shell` 注入
引数化されたファイル内容	`!cat $ARGUMENTS`
context を食う調査・ファイル横断検索	Task 経由のサブエージェント
外部システム（issue tracker・監視・本番データ）	MCP ツール + `allowed-tools`
多段階の直列/並列ワークフロー	親 command がサブエージェントを調整

権限境界は allowed-tools で明示的に宣言する。特にチームで共有する command なら——何ができるかを固定する方が、毎回の手動承認に頼るより信頼できる。

本番に近い例

ここまでを組み合わせた例——「Linear ticket から実装経路を調査する」command だ。

---
description: Linear ticket から実装方針を生成
allowed-tools: mcp__linear__*, Task, Read, Grep, Glob, Bash(git log:*)
---

## コンテキスト

@.claude/context/architecture.md
@.claude/context/coding-standards.md

## 現在のリポジトリ状態

!`git log --oneline -10`

## タスク

Linear ticket $ARGUMENTS の説明、コメント、関連 ticket を取得してください。

次に2つのサブエージェントを並行起動：
1. 1つ目：コードベース内で関連する既存実装と再利用可能なモジュールを探す
2. 2つ目：リスク評価——この変更が触れるホットな経路、テストカバレッジの欠落

両方戻ってきたら、出力：
- 実装ステップ（依存順）
- リスク一覧
- 推奨 commit 粒度

コードは書き始めないこと。

/plan ENG-4213 を実行すれば、1つの command で全工程が走る：チケット取得 → コードベースの並列調査 → リスク評価 → 方針の統合。ユーザーは出力を見て開始するかどうかを決めるだけだ。

これで slash command シリーズ最初の3回分の弧が閉じる：再利用可能なプロンプトの定義（intro）→ 動的なコンテキストの注入（context）→ ツールとサブエージェントの編成（今回）。このレベルになると、.claude/commands/ はショートカットのディレクトリではなく、チームで共有する小さなワークフローライブラリになる。