kinoko dev

前回GPT5でがんばるぞいって言った夜にSonnet4.5が出て、すっかりClaudeCode一択になってます。

ClaudeCodeにはサブエージェントという、本編チャットとは独立したコンテクストを持つチャットを持つことができます。サブエージェントにはそれぞれに役割を付加する事でかなり生成効率を上げる事ができます。

基本的な導入方法とカスタムエージェントのアイディアを共有していきます。

サブエージェントの役割

機能リリースから2ヶ月以上経っていて何番煎じだよって感じですが、一応説明しときます。

例えばセキュリティの専門家、フロント制作の専門家、ビジネスドメインの専門家（金融知識とか）など、チームメンバーを補充してそれぞれに推論してコーディングすることもできる機能です。 用例はAnthlopicの公式ブログに100個くらい書いてありました。多すぎて見きれない。

「〇〇のエージェントを使って」と明示して使うこともできるし、メインのチャットコンテクストで必要と判断したらClaudeが自動で呼び出してくれる時もあります。

これだけ聞くと「それでなんかいいことあるの？」って思いますよね、私も最初そういう反応でした。まぁこれが、AIならではのいろいろなメリットがあるんですよね。

コンテキストを効率的に使用できる

AIコーディングではコンテキストの良し悪しでコーディングの品質が大きく変わります。少ないと希望のモノは生成してくれませんが、多すぎてもダメ。チャットの履歴もコンテキストに含まれますので、無駄なチャットの履歴は減らしたいところです。

冒頭に書いた

本編チャットとは独立したコンテクストを持つ

これがキモです。ちょっと重めのプロンプトを投げたとしましょう。

ワイ「こういうAPI作って」
　↓
Claude「こういうプランでいきます」
→じゃぁこういうHTTPのシステムが要るな
→どのライブラリを使うか調べないと
→セキュリティにこういう機能が必要だな
→JSONのパーサも必要だな
→POST入力のバリデーション処理も必要だな
→システム本体のデータ形式どうなってたっけ？
→データ結合する処理も必要だな
→ここにデータ不整合バグがあるな。この修正は緊急だな
→バグが治っているか調査が必要だな
→（compact）
→まだエラーが出ているな
→エラーの修正完了
　↓
Claude「バグの修正が無事に完了しました！APIを実装する準備が整いました！」

過去編をやってるうちに打ち切りになるマンガを彷彿します。

Claudeに限らずですけどコンテクストが長くなりすぎると自動的にcompact処理をされます。チャット内容のうちで重要じゃなさそうな内容をカットしちゃうので、細かい内容が漏れてしまう時もあるんですよね。

これが、エージェントを使うとこうなります。

ワイ「こういうAPI作って」
　↓
Claude「こういうプランでいきます」
　HTTP処理実装よろしく → バックエンドの専門エージェント
　データ処理実装たのんます → ドメイン専門エージェント
　入出力処理の実装よしなに → バリデータ専門のエージェント
Claude「それぞれのエージェントのレスポンスをまとめよう」
　↓
Claude「データ不整合バグがあったので直して実装完了しました！」

文字数で比べても一目瞭然ですけど、サブエージェントは呼び出し元のチャットにはほとんど文字出力をしませんので、つまりコンテクストを増加させません。コンテクストの量を抑えることで、呼び出し元のスレッドではプロンプトの内容を一貫性を持って考えることに集中できるようになります。

言うなれば、

• プロンプト=PM
• 各エージェント=プロジェクトメンバー

みたいに、ClaudeCode内部にプロジェクトチームを作れるようなイメージですね。

ちなみにサブエージェントでは別スレッドでAIを動かしているだけですので、トークンの使用量の節約とかの意味合いはありません（直截的には）。

並列動作するけど編集は逐次

Claudeの公式ブログを見てると「10個まで同時起動して並列に作業できる」って書いてあるんですが、差分を把握してのコード編集は逐次作業になるようです。エージェントが編集許可を親プロンプトにとってから編集、みたいな感じっぽいです。まぁ一気にやられても編集競合とかで大変なことになりそうなのでそこはいいんですけどね。

上の例のような場合は各エージェントがそれぞれの分野を編集していますが、きちんと責任分離出来ているプロジェクトだとそれほど問題にはならないんじゃないかと思います。

編集が無いときは並列処理

調査・デバッグ・設計の段階では速度も上がり精度もあがる仕組みです。バンバン使いましょう。ただし使用量もバンバン上がります。エージェントごとに推論の使用モデルを選択できますが、今は全部Sonnetでいいんじゃないでしょうかね。

サブエージェントは分身出来る

「並列処理でやって」と指示を出すと、同じエージェントが複数起動して作業することがあります。まさしく分身の術。分身したエージェントもそれぞれのコンテクストで稼働しているようで、重複メソッドを書くことがありますのでそれをチェックするエージェントも作ったほうが良さげです。

並列処理で行っている作業は、どれか1個が「このコマンドを実行してもいいですか？」のプロンプトが出ている間もガリガリ進んでいきますので、監視してる側も結構忙しくなります。。

コーディング中に臨時のエージェントを作成する事もできる

一旦コーディングを止めさえすれば、いつでもエージェントは追加・編集可能です。

上の例でも途中で緊急めのバグフィックスがあった場合とか、新規フィーチャーの実装中に関連ドメインの致命的なバグを見つけちゃうこと、よくありますよね。今のチャット内で修正することも可能ですが、その後のチャットコンテクストがフィックス内容の事も考えながら新規フィーチャーを実装するという状態になります。

これは コンテクスト汚染とかコンテクストコンタミネーションと呼ばれていて、AIコーディングする際には結構深刻なトラブルです。それだけトークンも無駄になりますし、フィックスとフィーチャーが混ざった謎の新規モジュールをつくっちゃうこともありました。要するにトラブルのもとなんです。

それを回避するためにコーディングを一旦停止して、関連ドメインのスペシャリストのエージェントを新規作成、「〇〇のバグをエージェントに修正させて」とやるともとのコンテクストは”関連ドメインのフィックスが完了した”という情報だけを受け取って、フィーチャーの実装を安定して続ける事ができるんです。

サブエージェントのデメリット

と、便利なサブエージェントなんでバンバン使ったほうがいいですけど、一応デメリットも上げておきます。

CoTが見えない

CoT(Chain of Thought)はAIがどういう作業をしているか・どういう考えで推論を進めているかをテキストで表示してくれる機能です。

トップレベルのチャットで動かしているAIはCoTを逐一表示しますが、サブエージェントはCoTは画面出力しません。ctrl+Oを押すと履歴は見れますがリアルタイム表示ではないので、ペアプロ感覚での緊急停止して修正指示とかはちょっと難しいです。

ブラックボックス化しやすいかも

CoTがリアルタイムで見えないせいもあり、「どこで間違ったか」を後から追跡するのが結構大変だったりします。”ビルドもテストも通るけど、値が間違っている”系のバグとかは結構しんどい。

トークン消費量が多くなりがち

メンバーが多い組織あるあると同じで、仕様書やコードをそれぞれのエージェントが読んだりそれぞれの進捗待ちがあったりと、全体で見るとトークン消費が増えるパターンはあります。コード品質チェックのサブエージェントとかは結構トークン食います。

でもSonnet4.5になってからはトークンの消費量自体が減ってるので、前よりは気軽に使えるようになった気がします。

サブエージェント同士は何をやってるか理解していない

フロント専門のサブエージェントとバックエンド専門のサブエージェントがいたとします。「こういうJSONが来ます。値を処理してJSONで返すAPIをサブエージェントを使って実装して」と指示した場合とかですね。

修正が競合することはないんですけど、フロントとバックとでバリデーションの二重実装とかはよくあります。日常茶飯事で発生します。この辺はプランモードで機能ごとの担当サブエージェントまで指定してやると解消できますので、設計の時間は増えます。こういうところもチーム開発と一緒ですね。

それとサブエージェントがサブエージェントを呼ぶことも出来ないみたいなので、専門性をあんまり小分けにすると個別指定がめんどくさくなったりします。

2025-10-05訂正：サブエージェントからサブエージェントの呼び出しも可能でした。サブエージェントの権限設定で Tools: * になっていれば呼び出せます。

❌️「〇〇のライブラリのエキスパートです」
⭕️「APIのセキュリティのエキスパートです」

くらいの粒度の方が自動で呼ばれやすいです。

サブエージェントの登録

実のところClaude Codeにはデフォルトで multi-purpose (汎用）というエージェントが入ってます。カスタムエージェントを登録していない状態でも、「並行処理でやってください」と指示されると、このmulti-purposeが複数呼び出されて実行されます。

汎用ですので、CLAUDE.mdだけ読み込んだプレーンな状態で、細かい設定もできません。

また、専用の設定ファイルがないのでエージェントごとの”知見”を蓄えることが出来ません。ある程度の規模で長時間取り組む必要がありそうなプロジェクトでは、カスタムエージェントがあとあと効いてきます。

このサイトに自力でたどり着いてる人には耳タコだと思うんですけど、一応説明しておきます。

カスタムエージェントの作成

MCPサーバは外部アプリがAIに対応していないとどうにもならないんですけど、サブエージェントに関してはプロンプト一発で作成可能です。

エージェントの設定ファイルは実態としてはMarkdown形式のテキストファイルです。フォルダの場所は

~/.claude/agents // for user global
// or
${projectRoot}/.claude/agents // project level

ユーザフォルダに置いたものは全プロンプトで使用でき、プロジェクトルートに置いたものはそのディレクトリでclaudeコマンドを実行した時のみ使用できます。

それぞれ、サブディレクトリの中のMarkdownファイルもエージェントとして認識されます。

コマンドで生成する際にUserに保存するかプロジェクトに保存するか聞かれますが、そこはケースバイケースですね。プロジェクト固有の単位のWatchdogとかだとグローバルに置く意味もないので、プロジェクトに配置してしまっていいんじゃないでしょうか。実例はページ最下部に書いてますので見てみてください。

サブエージェントをプロンプトで生成するメリット

Markdownなので直接書くこともできますが、claudeを起動して /agents のコマンドで生成してもらうほうが間違いないですし、英語で生成されるメリットがあります。

Claudeは英語でのプロンプティングのほうがトークンも抑えられて精度も高いので、ほんとは全部英語でプロンプト打ったほうが良いんですけど、英語苦手な人こそサブエージェントをゴリゴリ使ったほうがいい、ということになります。

エージェントのMarkdownファイル自体を配布してるGitHubレポジトリもありますけど、すでにある程度実装があるプロジェクトなら自前で生成したほうが、現行システムを踏襲した内容で作ってくれます。それでも既存のものをコピペして使う場合は、「〇〇のエージェントをこのプロジェクトに最適化してください」みたいにプロンプトを打つと、よしなにしてくれると思われます。

設定とか運用あれこれ

雑多に気づいたことを追加していきます。

自動で使ってほしいエージェントの設定

エージェントの設定にMUST BE USED とか use PROACTIVELY とか書くと使ってくれやすいです。

DTO層専門のサブエージェントだとこんな感じ。

description: MUST BE USED when editing files in /src/dto/ or when serialization/validation errors occur. Use PROACTIVELY for all DTO-related changes.

ユーザーグローバルのエージェント設定を他の端末でも使いたい

職場デスクトップPCと、ノートや自宅PCなどで同じ環境でコーディングしたい時、あると思います。プロジェクトに保存したエージェントならプロジェクトのgitで同期出来ますが、~/.claude/agentsの方はそうもいかず。

Dropboxに置いてWindowsのショートカットではNGでした。lnでハードリンクを貼ればいけるかもしれませんけど、そこまで環境を汚したくないというか。。

上でも書きましたけど.claude/agentsフォルダのサブフォルダにあるMarkdownファイルもエージェント設定として認識してくれます(v2.0.5現在)。共有したいエージェントはサブフォルダに移動して、gitで手動で同期するのが一番クリーンかなと思います。

ClaudeCodeから/agentsで生成したエージェントファイルも、ClaudeCodeを起動していなければフツーにD&Dで移動して大丈夫です。

権限のRead-OnlyとWritableは分けたほうが良さそう

2025-10-05追記：

同じ内容で2つ作るという意味ではなくて、エージェントのタイプごとに分けたほうがいいよ、というお話です。

たとえばlint-enforcerという、lintでエラーが出ているかチェックする専門のエージェントを作ってあるとします。このエージェントはlintチェックとエラー構造の解析が専門なので、ビジネスドメインの事前知識は持っていません。このエージェントが修正作業を行うのは非効率です。

ドメインごと・モジュールごとの専門エージェントを設定している場合は、そちらのエージェントが事前知識を持っているので効率的に作業してくれます。

というわけでこのlint-enforcerさんはread-onlyで設定しておくと、修正が必要な箇所でサブエージェントのサブエージェントとして、専門エージェントを呼んでくれます。

Read-only toolsと、CLIツールを使って効率的に検索できるようにExcution toolsもチェックしておくといいと思います。用途によってはSerenaとかが使えたほうがいいので、MCP toolsをチェックするパターンもあるかも。

よく使うエージェント

ほぼ備忘録です。

ユーザーグローバルで入れてるエージェント

rust-pro

Rustician限定。Claudeはsonnet4.0の頃はRustの所有権システムが苦手だったみたいで、リファクタリングのたびに詰まっていたのでこれを入れてます。

Master Rust 1.75+ with modern async patterns, advanced type system features, and production-ready systems programming. Expert in the latest Rust ecosystem including Tokio, axum, and cutting-edge crates. Use PROACTIVELY for Rust development, performance optimization, or systems programming.

audio-processing-expert

DSPとかVST開発とか用です。主語はこのくらいデカいほうがいいと思われます。応用するならExpert 3D Software Developerとか、Adept Unity Developerとか？

UnityやUEくらいの大規模のフレームワークだとUE Visual Programming expertとか絞ってもいいかもしれませんね。

Use this agent when implementing audio effects, filters, real-time audio processing, sound synthesis, DSP algorithms, audio buffer management, sample rate conversion, or any audio-related technical implementation.

performance-profiler

ネストの深いループ文なんかをチェックしてくれます。たまにやらかすので、読み込み権限で使ったほうがいいかもしれません。

Use this agent when performance issues are suspected, after implementing performance-critical code, when analyzing profiling data, or when investigating bottlenecks in the music generation pipeline. This agent should be used PROACTIVELY after completing performance-sensitive implementations.

プロジェクトレベルで入れているエージェント

プロジェクト固有だったりするやつです。

☆project-architect-memory（オススメ）

過去の修正履歴を覚えさせておくエージェントです。

• 機能と目的と場所
• アンチパターンと修正方法
• 機能廃止や変更の理由と代替機能

この辺を記録しておくエージェントです。イメージは「プロジェクトに初期から参加してる、何やってるのかよくわからない古参の人」ですね。ご意見番みたいな。

新機能の設計時に同じような目的で過去に追加した機能がないかの手がかりにしたり、間違ってレガシーコードを使用しているのを発見してくれたり、かなり役立ちます。

You are the Project Architect Memory, a senior technical architect with comprehensive knowledge of this project's architectural decisions, design rationale, and historical evolution. You serve as the institutional memory for why the system is designed the way it is.

Serena MCPにもメモリー機能がありますが、明示的に「今のアーキテクチャで更新して」とやる必要がありますし、けっこう高コストなんですよね。あとcipherっていうMCPサーバがありますが、そちらはAIサービスのAPIが必須だったりちょっと敷居が高い。。

unit-watchdog

主にDTO層で活躍する、単位変換が適切に行われているかのウォッチャーエージェントです。音楽ソフトだと秒、ビート、小節、Ticksなどが入り乱れるのであると助かる。

You are the Time Unit Watchdog, an elite temporal integrity specialist for this system. Your singular mission is to enforce the MANDATORY Sixteenth-based time unit system and prevent time-related bugs that could corrupt musical timing.

このサマリーは16分音符単位に強制するっていう内容です。めちゃ機能を限定してますので消費トークンも優しい。

表現を変えればヤードポンドをSI単位に強制するとか、坪を㎡に強制するとか、いろんなところで使えるんじゃないでしょうか。

gcp-expert

サービスが多すぎてもはや探せないうえに公式ドキュメントも何言ってるのかわからない、GoogleCloudPlatformのエージェントです。

人間が検索して調べてもかなり大変なので、「このプロジェクトに最適なGCPのデータベース構成は？」「このパフォーマンスだとどのくらいのインスタンスサイズがおすすめ？」「エミュレータのDockerfile作って」とAIに調べさせるとかなりコンテクスト使っちゃいますので、こういうのはエージェントに分けちゃいましょう。

You are a Google Cloud Platform (GCP) Expert with comprehensive knowledge of all GCP services, architectures, and best practices. Your role is to provide expert guidance on GCP service selection, implementation, and optimization.

AWSでも応用効くと思います。

GCP、AWSともにMCPサーバが提供されていますが、サービスを直接操作するためのツール群という感じなので、設計・実装段階ではエージェントの方が有能です。

プロジェクトレベルで入れている理由は「今のGCPの構成をサブエージェントに記憶して」で使用しているサービスやインスタンスの情報を記録できるからです。次の質問はその構成の前提で動作確認や調査をするので、精度も速度も向上します。

サブエージェントを作るタイミング

だらだらとさほど最新な情報でもないことを書いてきましたけど、この記事で一番言いたい事はこれです。

• なんかこのバグしょっちゅう出るな
• この設定、後々使いそうだな
• このモジュール、複雑になっちゃったな
• Dockerfile更新するのめんどくさいな

こんなときはそれ専用のエージェントを作るべきです。特に一番上。AIのクセでしょっちゅう出るバグってあるんですよ。うちの場合は時間単位計算の勘違いですね。これはクセなので、その時頑張って直しても再発するんですよ。

なので、

「このバグは何度か再発しています。今回のデバッグで調査した箇所と修正内容を〇〇のエージェントに記憶させてください」

これで次回からは「〇〇のエージェントにこのバグを修正させてください」で時間とトークンを無駄にせずに済みます。

結局サブエージェント機能があるからClaudeCodeから離れられない民からは以上です。