Claude Codeのサブエージェントを使う｜/agentsで自分専用の小さなAIを作る

Claude Codeを毎日触っていると、「同じ依頼を何度も書いている自分」に気づきます。

「PR説明文をテンプレ通りに書いて」「コミットメッセージをこのフォーマットに整えて」「テストだけ実行して結果を要約して」 — こういう 繰り返しの依頼を専用エージェント化 できるのが、サブエージェント(subagents)です。

呼び出すのは /agents コマンド。Markdownファイル1枚で、 自分専用の小さなAI が手駒として並びます。今日はこの作り方を整理します。

Claude Code サブエージェント公式ドキュメント

code.claude.com

サブエージェントとは

ざっくり言うと、 特定のタスクに特化したAIを、Markdownファイル1枚で定義 できる仕組み。

.claude/agents/<name>.md または ~/.claude/agents/<name>.md に置く
frontmatterと本文(システムプロンプト)を書くだけ
メインのClaude Codeから「この子を呼んで」と頼むと、専用エージェントが動く

「専門家を雇う」イメージに近い。 PR説明文を書く担当・テスト実行する担当・依存関係を調査する担当、それぞれ別人格のAIが並んでいる感覚です。

/agents コマンドで作る

一番ラクな作り方。Claude Codeを起動して、

/agents

と打つと、対話形式でサブエージェント作成のメニューが開きます。

名前(例 — pr-writer)
説明(いつ呼ばれるか)
使えるツール(Read/Write/Bashなど)
システムプロンプト(本文)

を順に答えるだけで、 .claude/agents/pr-writer.md が生成されます。

手で書くより速いのと、 frontmatterの構造を間違えにくい のがメリット。

Claude Code Subagents実例(Qiita)

qiita.com

.claude/agents/*.md の中身

/agents で生成されるファイルは、こういう形をしています。

---
name: pr-writer
description: PR説明文をプロジェクトのテンプレに沿って書く。複雑な変更のPR本文作成時に使う。
tools: Read, Bash
model: sonnet
---

あなたはPR説明文を書く専門アシスタントです。

PRに含まれる変更を git diff から読み取り、以下の構造で本文を書いてください。

## Summary
- 変更の主要ポイントを2-3行

## 変更ファイル
- 主要な変更ファイルとその役割

## テスト方法
- 動作確認の手順

3つのfrontmatterが重要。

name — 呼び出し用の識別子(英数とハイフン)
description — 「いつ・何のために呼ぶか」を書く欄。 ここの精度がそのまま呼び出し精度 になる
tools — このエージェントが使えるツール。書かないと全ツール使える

ポイントは description。Claude Codeはこの説明文を読んで、「今のタスクに合うサブエージェントがあるか」を判断します。description が曖昧だと 誤って呼ばれる or 必要な時に呼ばれない。

私はここに「使うべき場面」「使ってはダメな場面」を両方書くようにしています。

呼び出す側の挙動

サブエージェントが揃ったら、メインのClaude Codeとの会話の中で、

「pr-writer エージェントを使って、今のブランチのPR本文を書いて」

のように指示できます。明示的に名前を呼ぶ方法と、 ClaudeがDescription を見て自動選択 する方法、両方あります。

私は最初は明示で呼んで、慣れたら自動選択に任せるようにしています。description の書き方を1〜2回調整すれば、だいたい狙ったサブエージェントが呼ばれるようになる。

Anthropic Cookbook — Subagents活用

github.com

実例3つ — 私の手駒

参考までに、私が普段使っているサブエージェント。

1つ目 — pr-writer(PR説明文専用)

git diff を読んで、 プロジェクト固有のテンプレート に沿ったPR本文を生成。Summary・変更ファイル・テスト方法の3節構成で固定。これだけで毎回のPR作成が30秒で終わります。

2つ目 — commit-tidy(コミットメッセージ整形)

「ふわっと書いたコミットメッセージ」を渡すと、 conventional commits 形式に直して返してくれる子。 feat: fix: docs: のプレフィックス選びが速くなる。

3つ目 — dep-investigator(依存関係の調査担当)

「このパッケージを上げたい時、何が壊れる可能性があるか」を package.jsonとロックファイルを読み取って予測 してくれる。これがあるおかげで、依存上げ作業が一段安全になりました。

3つとも実体は 20-40行のMarkdown。重い実装は何もしていません。

Agent Teamsとの違い

「サブエージェント」と「Agent Teams」は名前が似ていて混同しがち。違いを整理。

	サブエージェント	Agent Teams
提供	標準機能(全プラン)	環境変数で有効化
構成	1人の専門家を呼び出す	3-5人が同時並列で動く
関係性	メインClaudeが呼ぶ手駒	チームで議論・分業
用途	定型タスクの専門化	議論・敵対的検証

サブエージェントは 「呼ぶ手駒」、Agent Teamsは 「同時に動くチーム」。

私の使い分けは、 定型作業はサブエージェント、判断が分かれる調査はAgent Teams。

Claude Code Agent Teams解説(関連記事)

claude-code-lab.example.com

運用のコツ

1ヶ月使って見えてきたコツ。

1つ目 — 数を増やしすぎない

20個も並べると、Claude側がどれを呼んでいいか迷います。私は 3-4個 に絞って、それ以外は普通のClaudeに頼む運用。

2つ目 — descriptionに「使うべきでない場面」も書く

description: PR説明文をプロジェクトのテンプレに沿って書く。
        小さな変更や、PRを作らないコミットメッセージ用途では使わない。

「やること」だけだと誤呼び出しが起きやすい。 「やらないこと」も明記 すると精度が上がります。

3つ目 — toolsを最小限に絞る

「PR説明文を書くだけのエージェントに、Bash全権限はいらない」 — Read だけ、 Bash(git log:*) だけ、のように 必要最小限 にすると、暴走しにくく安全。

スキルとの違い

似た機能で「Skills」(.claude/skills/)もあります。違いは。

サブエージェント — 別人格として タスクを丸ごと委譲 する(役割分担)
スキル — メインのClaudeが 追加知識・手順 を読み込む(能力拡張)

「PR説明文を 代わりに書いてもらう 」がサブエージェント、「PR説明文の 書き方ルールをClaudeに教える 」がスキル、という違い。

両方併用もできます。

Claude Codeのスキル作り方(関連記事)