Claude Codeに「コードをレビューしてください」「テストが足りないところを探してください」と、そのたびに役割を説明するのは手間です。
最初から「レビュー担当」「テスト担当」として設定されたAIを用意しておけないか。そう考えて調べたのが、Claude Codeのカスタムエージェント(Custom Subagents)です。この記事では、役割を持たせた「AI社員」というイメージで、仕組みと作り方を整理します。
なお、私は今、広告の調査・制作・審査の担当をSkillとして作っていますが、カスタムエージェントはまだ作っていません。この記事は公式ドキュメントをもとにした学習の整理です。
この記事で分かること
- カスタムエージェントとは何か、Skillとの違い
- エージェントの作り方と、設定できる主な項目
- 最初の1人を作るときの進め方
カスタムエージェントとは
カスタムエージェントは、特定の仕事に合わせてあらかじめ設定しておく、専門の「サブエージェント」です。サブエージェントとは、メインのClaudeから仕事を分けて任せられる、別のAIのことです。
カスタムエージェントでは、その担当者について次のようなことを先に決めておけます。
- 何を専門にし、どんなときに呼ばれるか
- どのモデルを使うか
- どのツール(読む・書く・コマンドを動かすなど)を使ってよいか
- どんなルールで判断するか
単にAIを増やすのではなく、役職と仕事の内容を決めてから配置するイメージです。
ファイル1つで作れる
カスタムエージェントは、Markdownのファイル1つで作れます。プロジェクトの「.claude/agents/」フォルダに、例えば次のようなファイルを置きます。
---
name: code-reviewer
description: コード変更後に品質や問題点をレビューする
tools: Read, Glob, Grep
model: sonnet
---
あなたはコードレビュー担当です。
品質・安全性・保守性の観点から問題点を報告してください。
コードは変更せず、問題点と改善案だけを示してください。
上の「—」で囲んだ部分が設定で、下の文章がその担当者への指示書になります。必ず書く項目は、name(名前)とdescription(どんなときに使うかの説明)の2つだけです。
自分で書かなくても、Claudeに頼んで作ってもらうこともできます。公式ドキュメントでも、作りたいエージェントと保存場所をClaudeに伝える方法が案内されています。
コードレビュー専用のエージェントを作ってください。
・コードは変更しない
・読み取り系のツールだけ許可する
・Sonnetを使う
・このプロジェクト専用にする
できあがったファイルを人が読み、必要なら直せば十分です。
保存場所は2つあります。そのプロジェクトだけで使うなら「.claude/agents/」、自分のすべてのプロジェクトで使うなら「~/.claude/agents/」です。
AI社員ごとに設定できること
使える道具(tools)
レビュー担当に読む・探すツールだけを許可すれば、コードを勝手に書き換えることを防げます。実装担当には編集を、テスト担当にはコマンドの実行を許可する、という分け方ができます。会社で「経理担当には経理システムの権限だけ」と決めるのと同じ考え方です。
モデルと考える深さ(model・effort)
簡単な探し物は軽くて速いモデル、通常のレビューはSonnet、難しい設計の検討はOpus、と担当ごとにモデルを変えられます。すべての担当に最も高性能なモデルを使わせる必要はありません。
さらに、effort(どれだけ深く考えさせるか)も担当ごとに設定できます。段階はlow・medium・high・xhigh・maxで、使えるものはモデルによって異なります。
仕事の手順書(skills)
担当者に、起動したときにSkill(業務の手順書)を読み込ませることもできます。例えば「データ分析担当」に「週次分析Skill」を持たせる、という形です。
- カスタムエージェント=誰が仕事をするか
- Skill=その仕事をどうやるか
と分けて考えると分かりやすくなります。
記憶(memory)
会話をまたいで知識をためる記憶も持たせられます。範囲はuser・project・localから選べます。例えば、データベース担当が過去に起きた問題をためていく使い方です。
呼び出し方
Claude Codeは、頼まれた仕事と各エージェントのdescriptionを見比べて、合う担当に自動で仕事を回します。「code-reviewerを使って確認して」のように、こちらから名前を指定して呼ぶこともできます。
AI社員を増やしすぎない
担当を増やせば効率が上がるとは限りません。「Python担当」「Python API担当」「Python API認証担当」のように細かく分けると、どれを使えばよいか分かりにくくなります。
Claudeはdescriptionを見て任せる先を決めるため、説明は短く、はっきり書くことが大切です。公式ドキュメントでも、descriptionは短くし、詳しい指示は本文の指示書に書くよう案内されています。最初は「調査」「実装」「レビュー」くらいの大きな役割から始め、必要になってから増やす方が管理しやすいと考えています。
最初の1人の作り方
まずは「この仕事は何度もClaudeに頼んでいる」というものを1つ選びます。コードレビューなら、次の流れです。
- レビュー専用のエージェントを作る
- 読み取り専用にし、モデルを決める
- 必要ならレビュー用のSkillを持たせる
- 何度か実際に使う
- 足りないルールを指示書に足す
1人がうまく働いたら、次の担当を作ります。
まとめ
Claude Codeの機能を会社に例えると、CLAUDE.mdは就業規則、Skillは業務マニュアル、カスタムエージェントは役割を持ったAI社員、メインのClaudeは仕事を振り分けるマネージャーです。
Skillが「仕事のやり方」を残す仕組みなら、カスタムエージェントは「仕事をする役割」そのものを残す仕組みだと理解しています。大事なのはAI社員をたくさん作ることではなく、繰り返し出てくる役割を見つけ、その役割に必要な手順・道具・権限をはっきりさせることです。私も、今Skillで作っている広告の担当を、カスタムエージェントにすると何が変わるのかを確かめていきたいと考えています。
※機能や設定の項目は変わることがあります。記事作成時点の情報のため、最新の内容は公式ドキュメントをご確認ください。

