Claude Codeでどこまでできる？

Claude Codeの使い方や連携を、実際に試してわかりやすく伝えるサイト

Claude Codeのサブエージェントを作って呼び出す方法—.claude/agents入門

,
CC-042

「Claude Codeにレビューだけ任せたい」「テストだけ専用にお願いしたい」——そう思ったことはありませんか？ 実は、プロジェクトフォルダの中にMarkdownファイルを1つ置くだけで、Claude Codeの”分身”に特定の役割を持たせることができます。.claude/agentsフォルダにファイルを作って、サブエージェントを呼び出せるようになるまでの最短ルートを案内します。

この記事でやること

ゴールは1つ——.claude/agentsフォルダにMarkdownファイルを1つ作って、サブエージェントを呼び出せるようにする。

対象は、Claude Codeの基本操作（チャットでの指示出し、ファイルの読み書き）ができる方を想定しています。「まだClaude Codeをインストールしていない」という方は、先にインストール手順の記事を済ませてから戻ってきてください。

なお、触れないものもあります。

まずは「1人のエージェントに1つの役割を任せる」に集中しましょう。

事前に必要なもの

手順に入る前に環境を確認しておきます。次の4つが揃っていれば大丈夫。

  • Windows 10 または 11 が動いていること
  • Claude Codeがインストール済みで、チャット画面が開けること
  • プロジェクトフォルダが1つあること（Git管理が推奨ですが、必須ではありません）
  • テキストエディタがあること（メモ帳でもVS Codeでも構いません）

プロジェクトフォルダがない場合は、適当な場所に新規フォルダを作ってください。C:\Projects\my-app のような空フォルダでも構いません。

サブエージェントって何？——30秒でイメージする

サブエージェントはClaude Codeの「分身」です。メインのチャット画面とは別に、特定の役割に特化したもう1人のClaudeを立ち上げる仕組み——と考えるとイメージしやすいでしょう。

例えば、こんな使い方ができます。

  • コードレビュー担当：書いたコードの問題点を指摘する専門家
  • テスト担当：テストコードを書いて実行する担当
  • ドキュメント担当：READMEや説明文を整える担当

各サブエージェントは自分だけの会話窓（コンテキストウィンドウ）を持ちます。メインのチャットが長くなりすぎるのを防げるため、本題に集中しやすくなるというメリットもあります。

なお、プロジェクトルートにAGENTS.mdを置く方法もありますが、本記事では.claude/agentsフォルダに個別ファイルを置く方式を紹介します。ファイルごとに役割が分かれているため、管理しやすく入門に向いています。

Step 1: .claude/agentsフォルダを作る

プロジェクトフォルダの中に、エージェント定義ファイルを置くためのフォルダを作ります。

1. プロジェクトフォルダを開く

エクスプローラーでプロジェクトフォルダ（例：C:\Projects\my-app）を開きます。

2. .claudeフォルダがあるか確認

Claude Codeをそのプロジェクトで一度でも使っていれば、.claudeフォルダが既にあるはずです。エクスプローラーで見えない場合は、次の手順で表示させてください。

  • エクスプローラーの上部にある「表示」タブを開く
  • 「表示」の中にある「隠しファイル」にチェックを入れる

これで「.」で始まるフォルダが見えるようになります。

3. .claudeフォルダの中にagentsフォルダを作る

.claudeフォルダを開き、その中にagentsという名前のフォルダを新規作成します。

コマンドプロンプトやPowerShellから作る場合は、プロジェクトフォルダをカレントディレクトリにして次のコマンドを実行します。

mkdir .claude\agents

最終的に次のような構造になっていればOKです。

C:\Projects\my-app\
└── .claude/
    └── agents/

.claudeフォルダ自体がまだない場合は、先に作ってからagentsを作ってください。

mkdir .claude
mkdir .claude\agents

Step 2: エージェント定義ファイルを書く

agentsフォルダの中に、Markdownファイルを作ります。ここでは「コードレビュー担当」のエージェントを例に進めます。

1. ファイルを作る

エクスプローラーで.claude/agentsフォルダを開き、code-reviewer.mdというファイルを新規作成してください。

ファイル名は自由ですが、役割が分かる名前にすると後で便利です。code-reviewer.md、test-writer.md、doc-helper.mdといった名前がよく使われます。

2. ファイルに内容を書く

メモ帳やVS Codeでcode-reviewer.mdを開き、次の内容を貼り付けて保存します。

---
name: code-reviewer
description: >
  Pythonコードのレビューに特化したエージェント。
  コードの品質、セキュリティ、可読性を中心に確認する。
  Pythonファイルの編集後にレビューを依頼されたらこのエージェントを使う。
---

あなたはPythonコードのレビュー専門家です。

次の観点でコードを確認し、改善点があれば具体的に指摘してください。

- バグや論理的な問題がないか
- セキュリティ上の懸念がないか
- 変数名や関数名が分かりやすいか
- 不要なコードがないか

指摘の際は、理由と修正案をセットで提示してください。

3. ファイルの構成

このファイルは2つの部分から成り立っています。

  • YAMLフロントマター（---で囲まれた部分）：エージェントの名前と説明を書きます。nameはファイル名と同じにするのが分かりやすいです。descriptionは、Claude Codeが「このタスクはどのエージェントに任せるべきか」を判断するためのヒント。詳しく書くほど、適切な場面で自動的に呼び出されやすくなります。
  • 本文（---より下）：エージェントへの指示（システムプロンプト）を書きます。ここに書いた内容が、そのエージェントの行動指針になります。

保存時の文字コードはUTF-8にしてください。メモ帳の場合、保存ダイアログの右下にある「文字コード」で「UTF-8」を選べます。

ファイルが正しく保存されたかどうかは、コマンドプロンプトで次のように確認できます。

type .claude\agents\code-reviewer.md

先ほど書いた内容がそのまま表示されれば保存できています。

Step 3: エージェントを呼び出してみる

定義したエージェントが認識されているか確認し、実際に呼び出してみます。

1. Claude Codeを起動する

プロジェクトフォルダ（C:\Projects\my-appなど）でClaude Codeを起動します。

2. エージェント一覧を確認する

Claude Codeのチャット画面で、次のコマンドを入力します。

/agents

エージェント一覧画面が開き、code-reviewerが表示されていれば、ファイルが正しく認識されています。

3. エージェントを呼び出す

チャット画面で、自然な言葉でエージェントを指定して指示を出します。

Use the code-reviewer subagent to review my recent changes

または、日本語でも大丈夫です。

code-reviewerエージェントに、直近の変更をレビューしてもらって

Claude Codeが指示内容を判断し、code-reviewerの定義を読み込んでレビューを実行します。確実に特定のエージェントを呼び出したい場合は、チャット入力欄で@を打ち、候補からcode-reviewer (agent)を選びます。手入力する場合も、候補に表示される形式に合わせて指定するのが安全です。迷ったら、手入力ではなく@候補から選んでください。

なお、.claude/agents/にファイルを追加した直後は、Claude Codeを再起動するか/agentsコマンドで一覧を表示して認識させる必要があります。

4. 期待される結果

エージェントが正常に動くと、メインのチャット画面にレビュー結果が表示されます。コードの問題点の指摘や改善案が含まれているはずです。

呼び出せない場合のチェック項目

  • ファイルの配置場所：.claude/agents/の直下にあるか確認
  • ファイル名：拡張子が.mdになっているか確認
  • YAMLフロントマター：---が3本線で正しく囲まれているか、インデントが揃っているか確認
  • 文字コード：UTF-8で保存されているか確認

YAMLの書き間違いは「コロンの後にスペースがない」「インデントがずれている」あたりが多いので、再度開いて確認してみてください。

代表的な役割分担パターン

エージェントの定義方法が分かったところで、いくつか実践的なパターンを紹介します。

コードレビュー担当

先ほど作ったcode-reviewerがこのパターンです。コードを書いた後にレビューを任せます。指摘の観点（品質、セキュリティ、可読性など）を指示に含めると、より的確なレビューが返ってきます。

テスト担当

テストコードの作成と実行を任せるエージェントです。ファイル名はtest-writer.mdなどにします。指示には「テストフレームワークを指定する」「境界値のテストも書く」などを含めると、より実用的なテストを出力してくれます。

ドキュメント担当

READMEやAPI説明文の作成・更新を任せるエージェントです。ファイル名はdoc-writer.mdなどにします。「対象読者を明示する」「コード例を含める」などの指示を書いておくと、読みやすいドキュメントが出力されます。

リサーチ担当

コードベースの中から特定の情報を探してまとめる役割です。読み取り専用のツールだけを許可しておけば、誤ってファイルを書き換える心配がありません。YAMLフロントマターにtoolsを指定する方法は後述します。

具体的には、フロントマターに次のように書きます。

---
name: researcher
description: >
  コードベース内の情報を検索・整理するエージェント。
  読み取り操作のみ許可。
tools:
  - Read
  - Grep
  - Glob
---

toolsに書かれたツールだけがそのエージェントで使えるようになり、それ以外のツール（EditやWriteなど）は使えなくなります。

どのパターンでも共通して言えるのは、descriptionを丁寧に書くこと。Claude Codeはこの説明文を見て「今のタスクはどのエージェントに振るべきか」を判断するため、「いつ使うか」が伝わる説明にしておくと自動委譲もスムーズに働きます。

うまくいかない時だけ見る——よくあるつまずきポイント

手順通りに進めたのにエージェントが動かない場合は、次のポイントを確認してみてください。大抵はここに挙げた原因のどれかです。

エージェントが一覧に表示されない

  • ファイルが.claude/agents/の直下にあるか（サブフォルダを作ってその中に入れていないか）
  • 拡張子が.mdになっているか（.txtになっていないか）
  • Claude Codeを起動したディレクトリが、.claude/agents/を含むプロジェクトフォルダか

YAMLフロントマターの書き間違い

YAMLはコロンの後にスペースが必要です。

# ダメな例
name:code-reviewer

# 正しい例
name: code-reviewer

複数行のdescriptionを書くときは、>-や|を使って正しくブロックを開始してください。先ほどの例にある>記号の後のインデントがずれていると、説明文が途中で切れてしまうことがあります。

Windows環境での注意点

  • 文字コードはUTF-8で保存する（メモ帳のデフォルトがUTF-8になっていない場合があります）
  • 改行コードはCRLFでもLFでも動きます。問題が出る場合はLF（Unix形式）に変換してみてください
  • ファイル名に日本語やスペースを使うと、環境によっては認識されないことがあります。英数字とハイフン（-）程度に留めるのが無難です

サブエージェントとエージェントチームの違い

Claude Codeには、サブエージェントの他に「Agent Teams」という機能もあります。ざっくり違いを整理しておきます。

サブエージェント（今回の記事でやったこと）

  • 1つのセッションの中で、特定の役割を持つClaudeの分身を呼び出す
  • 呼び出し元（メインのチャット）に結果を返して終了
  • 「レビューお願い」「テストお願い」のように、1つの役割に1つのタスクを任せる

Agent Teams

  • 複数のエージェントがそれぞれ独立したセッションで動き、互いにメッセージをやり取りしながら協調する
  • 並列で作業を進められるため、大規模なタスク向き
  • 複数のエージェント間で情報を共有しながら進めたい場合に使う

今のところは「1人のエージェントに1つの役割を任せる」を覚えておけば十分です。複数人で同時に作業させたくなったらAgent Teamsを調べてみてください。

最後に確認すること

ここまでの作業がうまくいっているか、3点で確認します。

  • .claude/agents/フォルダにMarkdownファイル（.md）が置いてある
  • /agentsコマンドでエージェントが一覧に表示される
  • チャットでエージェントを呼び出して、期待通りの応答が返ってくる

これらが全部通っていれば、サブエージェントの基本は完成です。

次にやることの導線をいくつか挙げておきます。

  • 別の役割を追加してみる：test-writer.mdやdoc-writer.mdを作って、役割を増やしてみる
  • ツールを制限してみる：YAMLフロントマターにtoolsフィールドを追加して、エージェントが使えるツールを限定する（例：読み取り専用にする）
  • Agent Teamsを試す：複数エージェントの協調作業に興味がある場合は、Agent Teamsのドキュメントを覗いてみる

サブエージェントは、プロジェクトごとに「レビュー担当」「テスト担当」「ドキュメント担当」のような役割を分けたいときに便利です。まずは1つ作って、/agentsで表示されるか確認するところから始めれば十分です。

まとめ

.claude/agentsフォルダにMarkdownファイルを置けば、Claude Codeに専用の役割を持つサブエージェントを追加できます。最初はcode-reviewer.mdのような小さな役割から試し、慣れてきたらテスト担当やドキュメント担当を増やしていくのが安全です。

Claude Code 関連記事