3行まとめ
- 1責任境界
調査、レビュー、テスト、実装、監査を役割ごとに分ける
- 2渡す範囲
main conversationに残す判断とsubagentへ渡す読み取り範囲を決める
- 3運用条件
tool、MCP接続、model、上限、返却フォーマットを明示する
Subagentsは作業を速くする部品ではなく、チームの責任分担を実装する単位として扱います。
Claude Code Subagentsは、作業を並列化するためだけの機能ではありません。チームで使うなら、調査、レビュー、テスト、実装、監査を分けるための責任境界として設計した方が安全です。
最初に決めるべきなのは、どのsubagentを作るかではなく、main conversationに残す判断、subagentへ渡す読み取り範囲、許可するtool、MCP接続、model、上限、返却フォーマットです。
2026年6月16日にClaude Code公式Docsを確認した範囲では、tools省略時の継承、permissionModeの親session優先、plugin subagentsの制限、/usageのローカル推定など、導入前に見落としやすい条件がいくつもあります。
この記事でわかること
便利な裏作業ではなく、チームの責任分担として設計する
.claude/agents/に置くcustom subagentで決める項目を確認する
tools、disallowedTools、permissionMode、settings、hooksを分けて見る
subagent単位に渡すMCP serverを台帳と監査項目で管理する
model aliasを役割とコスト上限に合わせて扱う
read-only pilotから限定編集、MCP writeへ段階的に広げる
技術的な確認はClaude Code公式Docs、公式changelog、security、data usage、costs情報を中心にします。
- Claude Code Subagentsを、便利な裏作業ではなくチームの責任分担として設計する考え方
.claude/agents/に置くcustom subagentのfrontmatterで、何を決めるべきかtools、disallowedTools、permissionMode、settings、hooksの分け方- MCP serverをsubagent単位に渡す時の台帳と監査項目
haiku、sonnet、opus、fableなどのmodel aliasを、役割とコスト上限で扱う考え方- read-only pilotから、限定編集、MCP writeへ広げる導入順序
直近のXでは、Claude Codeを強いモデルに全部任せない運用、制限、サブエージェント作成に関心が集まっていました。この記事ではX投稿を事実の根拠にせず、需要の背景としてだけ扱います。技術的な確認はClaude Code公式Docs、公式changelog、公式のsecurity/data usage/costs情報に寄せています。
前提知識
- 1main conversation
要件確認、方針統合、最終判断、チームとの合意形成を残す
- 2custom subagent
独自のcontext window、system prompt、tool access、permissionsを持つ
- 3権限を持つ実行主体
調査ならread-only、修正なら編集権限、外部接続なら監査が必要になる
- 4built-inとの違い
Explore、Plan、general-purposeとは別に、Markdownでcustom subagentを設計する
subagentを「小さなClaude」と見ず、権限と責任を持つ実行主体として扱うことが出発点です。
Claude Code Subagentsは、特定の作業に特化したAI assistantです。公式のSub-agentsページでは、subagentは独自のcontext window、system prompt、tool access、permissionsを持ち、main conversationとは別の文脈で作業して結果を返すものとして説明されています。
ここで押さえたいのは、subagentが「別の小さなClaude」ではなく「権限を持つ実行主体」になることです。調査だけならread-onlyで足ります。テスト修正を任せるなら編集権限が必要です。DB、GitHub、Slack、社内APIに触るMCPを渡すなら、さらに認証、監査ログ、人間承認が必要になります。
Claude Codeにはbuilt-in subagentsもあります。たとえば、コード探索向けのExplore、plan mode中の調査に使われるPlan、複雑な作業向けのgeneral-purposeがあります。一方、この記事で主に扱うのは、.claude/agents/や~/.claude/agents/にMarkdownファイルとして置くcustom subagentsです。
すでにClaude Codeの/compactやmemory運用を整理したい場合は、先にClaude Codeの/compactをチームで使う前にを読むと、main conversation側の文脈整理がつかみやすくなります。この記事ではそこから一歩進めて、subagentそのものの権限と運用契約を扱います。
結果：Subagentsは責任を分ける単位として使う
- 1最終判断
要件、実装方針、リリース判断、合意形成はmain conversationに残す
- 2読み取り調査
自己完結した調査、PR差分の読み取り、ログ整理を任せやすい
- 3観点分担
レビュー観点やテスト失敗の原因候補出しを分ける
- 4起動条件
役割名だけでなく、どの成果物や状態で呼ぶかを書く
- 5運用契約
frontmatterに入力、出力、tool、model、停止条件を明示する
subagentを増やす前に、main conversationが統合判断を失わない設計にします。
チーム導入での結論は単純です。Claude Code Subagentsは「便利そうだから増やす」のではなく、main conversationが持ち続ける判断と、subagentに隔離する作業を先に分けてから作ります。
main conversationに残すべきものは、要件の最終確認、実装方針の統合、リリース判断、ユーザーやチームとの合意形成です。subagentへ渡しやすいものは、自己完結した調査、PR差分の読み取り、ログの整理、レビュー観点の分担、read-onlyのMCP検索、テスト失敗の原因候補出しです。
役割名ではなく起動条件を書く
根拠
custom subagentはMarkdownファイルにYAML frontmatterを書いて定義します。公式のSub-agentsページでは、nameとdescriptionが必須です。descriptionはClaudeが自動委譲を判断する材料になるため、「security reviewer」のような職種名だけでは弱いです。
定義例
たとえば、次のように「いつ使うか」「何を読ませるか」「何を返すか」を短く入れます。
---
name: readonly-pr-reviewer
description: Use proactively after code changes to review git diff, tests, and security risks without editing files or calling write-capable MCP tools.
tools: Read, Glob, Grep, Bash
model: sonnet
maxTurns: 4
---
You are a read-only PR reviewer. Review only the changed files and nearby tests.
Return findings grouped by severity, with evidence and unresolved checks.
Do not edit files. Do not run commands that modify the workspace.この例ではtoolsを明示して、編集系のEditやWriteを渡していません。Bashを入れる場合も、読み取り系コマンドだけを許す運用にし、危険なshellはsettingsやhooks側で止める前提にします。
tools省略は全権限継承に近づく
注意点
subagentのtoolsを省略すると、利用可能なtoolを継承します。公式Docsでは、toolsをallowlistとして使う方法と、disallowedToolsで継承したtoolから除外する方法が説明されています。
チーム導入の初期設定では、toolsを省略しない方がレビューしやすいです。なぜなら、subagent fileを見た時点で「このagentが何をできるか」がわかるからです。
最初のallowlist
| subagent | 最初に許可しやすいtool | 最初は外したいtool |
|---|---|---|
| コード探索 | Read, Glob, Grep | Edit, Write, write系MCP |
| PRレビュー | Read, Grep, Glob, 読み取り系Bash | git push, issue更新, Slack投稿 |
| テスト失敗調査 | Read, Grep, Bash | DB更新, 外部送信, production操作 |
| 実装修正 | Read, Edit, Bash | secrets参照, release操作, 課金操作 |
| セキュリティ確認 | Read, Grep, read-only MCP | 自動修正, 外部送信, token出力 |
disallowedToolsは便利ですが、禁止を後付けする書き方になりがちです。最初はallowlistとしてtoolsを狭く書き、必要になったら増やす方が、レビューと説明が楽です。
frontmatterは運用契約書にする
subagent定義は、promptを書くだけの場所ではありません。チームで使うなら、frontmatterを小さな運用契約書として扱います。
| field | 決めること | 見落とすと起きること |
|---|---|---|
name | 重複しない識別子 | 同名agentの衝突で期待した定義が使われない |
description | 自動委譲の条件 | Claudeが過剰または不足に委譲する |
tools | 使えるtoolのallowlist | 編集や外部APIが想定より広がる |
disallowedTools | 継承から外すtool | MCP write toolや危険shellが残る |
model | 役割ごとの標準model | 強いmodelを全部に使い、予算が読めない |
permissionMode | promptの扱いと承認方針 | 親sessionのmodeとの衝突を見落とす |
mcpServers | 渡す外部権限 | main conversation全体に不要なMCPを載せる |
hooks | 開始、tool use、終了時の監査 | 誰が何をしたか追えない |
memory | 学習内容の保存範囲 | 秘密情報や個人メモリが混ざる |
maxTurns | 1回の作業上限 | 長時間探索や再試行でtokenを使い続ける |
実装チームでは、この表をもとにsubagent台帳を作るだけでも効果があります。いきなりagent fileを書くより、まず「作りたいsubagent」「許すtool」「渡すMCP」「停止条件」を1枚に並べる方が、権限レビューができます。
permissionModeだけで安全性を判断しない
安全性は1つの設定で完結しません。危険toolの除外、projectや組織のdeny、hookの実行時チェックを組み合わせます。
Claude CodeのsubagentにはpermissionModeを設定できます。公式のSub-agentsページでは、default、acceptEdits、auto、dontAsk、bypassPermissions、planが挙げられています。
ただし、ここを名前だけで選ぶと危険です。subagentはmain conversationのpermission contextを継承します。親sessionがbypassPermissionsやacceptEditsを使う場合は親が優先され、親がauto modeの場合はfrontmatter側のpermissionModeが無視されるケースがあります。
初期導入はdefaultかplanから始める
評価基準
read-only pilotなら、defaultかplanに寄せるのが扱いやすいです。planは読み取り探索の前提にしやすく、実装修正に進む前に人間が判断できます。
acceptEditsは、作業ディレクトリやadditionalDirectories内の編集を自動承認する用途に近いので、限定編集に進む段階で検討します。dontAskはpermission promptを自動denyするため、許可済みtoolだけで完結するagentに向きます。
bypassPermissionsは、初期導入の標準にしない方がよい設定です。permission promptをskipして多くの操作を承認なしに実行できるため、どうしても使うなら、managed settings、deny rules、PreToolUse hooks、実行ログの保存、作業範囲の隔離をセットにします。
tools、settings、hooksを層に分ける
権限は1箇所で完結させません。subagent fileではtoolsとdisallowedToolsを絞り、project settingsやmanaged settingsではdeny/ask/allowを置き、hooksでは実行直前の文脈を見て止めます。
| 層 | 主な役割 | 例 |
|---|---|---|
subagent tools | そのagentの能力を狭める | reviewerはRead, Grep, Glob中心 |
disallowedTools | 継承から危険toolを外す | Write, Edit, write系MCPを除外 |
| settings deny/ask | projectや組織の禁止操作を固定する | .env、production config、git push |
permissionMode | promptを出すか、自動denyするかを調整する | default, plan, dontAsk |
| hooks | tool inputや対象resourceを見て止める | rm -rf, 外部送信, DB更新 |
| 人間承認 | 意図と影響範囲を確認する | release、課金、顧客データ更新 |
Claude Codeのsettingsには優先順位があります。Settingsページでは、managed settingsが最上位で、command line、local project settings、shared project settings、user settingsの順に適用されると説明されています。法人導入では、個人の便利設定より組織のmanaged settingsを上に置く設計が必要です。
PermissionRequest hookは「許可の自動化」だけに使わない
Hooks Docsでは、PermissionRequest hookはpermission dialogが表示される直前に動き、allowやdenyを返せると説明されています。ただし、hookがallowを返してもdeny/ask rulesの評価は残ります。
この性質は、承認の自動化よりも監査に向いています。たとえば、許可前に対象ファイル、tool名、MCP server、subagent名、permission modeをログに残し、人間があとで見返せる形にします。
すでにClaude Code Hooks全体の設計を見たい場合は、Claude Code Hooksをチームで使う前にでPreToolUse、PostToolUse、Stopの置き方を整理しています。
MCPはsubagent単位の外部権限として台帳化する
読み取りだけのsubagentに更新系MCP serverを渡さないことが、初期導入の基本になります。
MCP serverをsubagentに渡すと、Claude CodeはGitHub、Docs、DB、Slack、社内APIなどに触れる入口を持ちます。便利になる反面、外部権限が増えます。
Sub-agentsページでは、frontmatterのmcpServersでsubagentに渡すMCP serverを指定できます。inline定義にすると、main conversationには出さずsubagent側だけにMCP toolを持たせる構成もできます。一方、plugin subagentsではhooks、mcpServers、permissionModeが無視されるため、pluginから持ってきたagentに強い権限を期待している場合は注意が必要です。
MCP台帳を先に作る
確認項目
MCPはtool名だけで見ない方がよいです。業務操作として棚卸しします。
| server | 目的 | 認証 | 許可するsubagent | 許可操作 | owner | 停止条件 |
|---|---|---|---|---|---|---|
| github-readonly | Issue/PR参照 | fine-grained token | researcher, reviewer | read | 開発リード | private repo外参照で停止 |
| docs-search | 社内Docs検索 | service account | researcher | read | 情シス | secret検出で停止 |
| slack-notify | 通知 | bot token | release-assistant | write | SRE | 本文投稿は人間承認 |
| db-report | 検証DB参照 | read-only user | data-checker | read | backend | production接続で停止 |
| crm-update | 顧客情報更新 | OAuth | 原則未接続 | write | sales ops | 初期pilotでは禁止 |
この台帳で見るべき点は、「Claudeに何を接続するか」ではなく「どのsubagentに、どの業務操作を、どの認証で、どの停止条件つきで渡すか」です。
MCPの基本から整理したい場合は、MCPとは何かでTools、Resources、Promptsと権限設計を先に確認できます。
read-only開始を標準にする
GitHub、Docs、ログ、仕様書、PR差分のような読み取りだけでも、subagentは十分に役立ちます。最初からissue更新、Slack投稿、DB更新、請求操作まで渡すと、成功時は便利でも失敗時の原因調査が難しくなります。
read-only pilotでは、MCP serverごとに次を確認します。
- 誰がtokenを発行したか
- token scopeはread-onlyか
- tool callのログはどこに残るか
- prompt injectionを含む外部入力を読むか
- subagentの返却結果を誰が統合判断するか
- いつ接続を外すか
AIコーディングエージェントにIssue、Docs、MCPを読ませる時のprompt injection対策は、AIコーディングエージェントのprompt injection対策も合わせて確認しておくとよいです。
model routingは役割と上限で決める
/usageは作業中の目安です。請求や停止判断はConsole usage、plan usage、workspace spend limitsと合わせて確認します。
直近の需要シグナルで目立っていたのは、強いモデルに全部任せないという運用感です。ここは実務でも重要です。ただし、モデル名の優劣だけで決めるのではなく、役割、上限、停止条件で決めます。
Claude Code公式Docsでは、subagentのmodel fieldにsonnet、opus、haiku、fableなどのaliasやfull model IDを書けます。また、CLAUDE_CODE_SUBAGENT_MODEL、invocation時のmodel parameter、frontmatter、main conversationのmodelという解決順が説明されています。
model aliasや利用可能planは変わりやすいため、この記事では恒久的な性能序列として扱いません。チームでは次のような役割表にします。
| 役割 | 標準modelの考え方 | 上位modelを使う条件 | 上限 |
|---|---|---|---|
| codebase explorer | 低遅延、低コスト重視 | 広い設計判断が必要な時だけ | maxTurns短め |
| readonly reviewer | バランス重視 | security/architecture判断が重い時 | 差分対象だけ |
| debugger | 再現と仮説検証重視 | 失敗原因が複数moduleにまたがる時 | 再試行回数を制限 |
| implementer | 編集品質とテスト重視 | 仕様変更が大きい時 | worktreeやPR単位 |
| security reviewer | 根拠と未確認事項重視 | 権限や外部入力が複雑な時 | 外部送信なし |
opusplanやfallbackは魔法の節約ではない
根拠
Model configuration docsでは、opusplanはplan modeではopus、execution modeではsonnetへ切り替えるhybrid approachとして説明されています。複雑な設計判断と実装効率を分ける発想は参考になります。
ただし、subagent設計では「hybridだから安全」「fallbackがあるから安心」とはしません。fallback model chainsは、primary modelがoverloadやavailabilityの問題を起こした時のためのものです。rate limit、billing、request-size、transport errorなどは通常のエラー処理になります。コスト上限や停止条件の代わりにはなりません。
/usageは請求の正本ではない
Cost docsでは、/usageのSession blockに表示されるドル額はtoken countからローカル計算されたestimateであり、実際の請求とは異なる可能性があると説明されています。請求の正本はClaude Console側のUsage pageで確認します。ProやMaxのsubscriberでは、subscriptionに含まれるusageやplan usage barsの見方も別になります。
したがって、subagent運用では次を分けます。
- 作業中の目安として見る
/usage - 月次予算管理として見るConsole usage/cost
- Pro/Max/Team/Enterpriseのplan usageやusage credits
- API workspace spend limits
- subagent別、MCP server別、skill/plugin別の利用内訳
料金や制限の更新を導入判断にどう反映するかは、AIコーディングツール料金改定の見方でも扱っています。
hooksとmemoryは運用の見張り番として設計する
- SessionStart
session ID、設定、利用するsubagent候補を記録する
- SubagentStart
subagent name、model、permission mode、目的を残す
- PreToolUse
tool、MCP server、対象resourceを見て危険操作を止める
- PermissionRequest
承認結果と人間判断が必要な理由を記録する
- PostToolUse
差分、失敗理由、外部送信の有無を確認する
- SubagentStop
stop理由、未確認、次の一手をmain conversationへ返す
- SessionEnd
usage、denied calls、manual approvals、memory更新を見直す
memoryは便利ですが、秘密情報や個人情報の置き場にせず、保持範囲を決めて扱います。
Subagentsをチームで使うほど、「誰が何をしたか」が見えにくくなります。Claude Code Hooksは、ここを補うために使えます。
Hooks Docsには、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、SubagentStart、SubagentStop、ConfigChangeなど、多くのeventが並んでいます。subagent frontmatterにもhooksを書けますし、project-level hooksでSubagentStartやSubagentStopを拾うこともできます。
最低限残すログ項目
確認項目
最初から大きな監視基盤を作る必要はありません。pilot段階でも、次の項目だけは残します。
| 項目 | 理由 |
|---|---|
| session ID | どの作業単位か追う |
| subagent name | どの役割が動いたか見る |
| model | コストと品質の差をあとで見る |
| permission mode | 自動実行の度合いを見る |
| tool name | 何を使ったか見る |
| MCP server | 外部権限の利用を追う |
| target resource | 対象ファイル、repo、APIを追う |
| approval result | 人間承認の有無を見る |
| denied reason | 何で止まったか改善する |
| summary | main conversationへ返した結論を残す |
実行ログを事故調査に使う設計は、AIエージェントの実行ログ設計でも詳しく整理しています。
memoryは便利だが秘密情報の置き場にしない
Subagentsにはmemory fieldがあります。公式Docsでは、user、project、localのscopeが説明されています。projectは.claude/agent-memory/<name-of-agent>/に置かれ、version controlで共有しやすい扱いです。localはproject-specificだがversion controlに入れない用途、userは複数projectで使う個人側の知見に向きます。
ただし、memoryを有効にすると、subagentがmemory directoryを読み書きする前提になります。公式Docsでは、memory有効時にRead、Write、Edit toolsが自動的に有効になると説明されています。これは便利ですが、read-only reviewerのつもりで作ったsubagentに、memory管理のための書き込み能力が加わることも意味します。
チーム標準では、memoryに入れてよい内容を先に決めます。設計判断、命名規則、よくあるテスト手順は候補になります。APIキー、顧客情報、private incidentの詳細、個人評価、契約情報は入れません。
Data usage docsでは、account typeやpreferencesによってdata retentionが変わること、local Claude Code clientsがsession transcriptをローカルに保存することも説明されています。memoryだけでなく、transcriptやfeedback送信の扱いもチームの情報管理ルールに含めます。
失敗点とハマりどころ
返却フォーマットを固定し、未確認と人間判断を必ず返す
plugin subagentでhooks、mcpServers、permissionModeが効くか確認する
強い権限は隔離、監査、停止条件とセットで扱う
turn数、再試行、MCP呼び出し、background taskまで含めて見る
結論、根拠、未確認、危険操作、人間判断、次の一手をそろえる
速くするための分割が、統合コストや監査漏れを増やしていないかを定期的に見直します。
なんでもsubagent化してmain conversationが弱くなる
Subagentに分けるほど、main conversationが受け取る情報は要約になります。要約だけで最終判断すると、細かい制約や未確認が抜けます。
対策は、返却フォーマットを固定することです。
- 結論
- 根拠
- 未確認
- 危険な操作の有無
- 人間に判断してほしいこと
- 次の一手「全部やって」ではなく「この範囲を読み、結論と未確認だけ返して」と依頼します。
plugin subagentの制限を見落とす
公式Docsでは、plugin subagentsではhooks、mcpServers、permissionMode frontmatter fieldsがsupportされず、読み込み時に無視されると説明されています。ここを知らないと、pluginから入れたagentにMCP scopeやpermission modeを設定したつもりで、実際には効いていないという事故が起きます。
強い権限を持つsubagentは、project scopeかuser scopeにコピーして、設定が有効になる場所でレビューします。
bypassPermissionsを便利な高速化として扱う
bypassPermissionsは、承認の手間を減らすために使いたくなります。しかし、初期導入で標準にすると、チームが「どの操作を許しているか」を説明しにくくなります。
高速化したいなら、まずread-only toolを絞る、MCPを減らす、maxTurnsを短くする、contextを整理する、hooksでログを圧縮する、modelを役割別に分ける方が先です。
コストをmodel名だけで見てしまう
コストはmodelだけで決まりません。subagent数、並列数、読み込むcontext、MCP toolのdescription、再試行回数、background task、memory、skills、hooksの返却内容で変わります。
Cost docsでは、token usageを追い、team spend limitsやmodel selection、context managementでコストを下げる考え方が説明されています。運用では、1タスクあたりのsubagent数とmaxTurnsを先に決めます。
実務で使うなら
- Phase 0
agent fileを書く前に、subagent台帳だけを作る
- Phase 1
read-only pilotで、調査時間、誤提案、返却フォーマットを確認する
- Phase 2
限定編集へ進み、対象範囲、テスト、承認条件を決める
- Phase 3
MCP writeや並列化を広げる前に、人間承認と監査ログをそろえる
1回のphaseで増やす権限は1種類に絞ると、失敗時の原因を切り分けやすくなります。
Phase 0：subagent台帳だけを作る
台帳項目
最初の1日は、agent fileを書かずに台帳を作ります。
| 項目 | 書くこと |
|---|---|
| subagent名 | readonly-pr-reviewerなど |
| 役割 | どの作業で呼ぶか |
| 入力 | diff、ログ、issue、Docsなど |
| 出力 | 結論、根拠、未確認、次の一手 |
| tool | 読み取り、編集、Bash、MCP |
| model | 標準model、上位model条件 |
| MCP | server名、scope、owner |
| memory | なし、user、project、local |
| 上限 | maxTurns、再試行、時間 |
| 停止条件 | 危険操作、外部送信、secrets検出 |
この時点で役割が重複するsubagentや、広すぎるsubagentが見つかります。実装より前に削るのが大事です。
Phase 1：read-only pilotで始める
次に、1週間だけread-only pilotをします。対象は、PR差分レビュー、ログ要約、Docs検索、Issue整理など、失敗しても業務状態を壊しにくい作業です。
pilotの評価軸は次にします。
- 人間の調査時間が減ったか
- 誤提案が増えすぎていないか
- 返却フォーマットは読みやすいか
maxTurns内で終わるかtoolsが狭すぎて実用にならない箇所はどこか- MCP接続なしで足りる作業はどれか
/usageとConsole usageで極端な上振れがないか
Phase 2：限定編集へ進む
read-onlyで価値が出たら、限定編集に進みます。いきなりproduction操作や外部送信へ進まない方がよいです。最初は、Markdown更新、テスト修正、PRコメント下書き、チケット更新のdraftなど、巻き戻しやすい作業にします。
限定編集へ進む時は、次を満たしてからにします。
toolsにEditやWriteを入れる理由が説明できる- 変更対象のdirectoryが狭い
git diffを人間が確認する- test/lint/typecheckの実行条件がある
- hookで危険commandを止める
- 変更内容をmain conversationが統合判断する
Phase 3：MCP writeと並列化を広げる
最後に、MCP writeや並列化を検討します。ただし、編集権限、MCP write、background実行、強いmodel、memoryを同時に増やすと、失敗時の原因切り分けが難しくなります。
1回のphaseで増やす権限は1種類に絞ります。たとえば、まずGitHub issueのread-only、次にPRコメントdraft、次にラベル付与、という順番です。Slack投稿やCRM更新、DB更新、請求系APIは、人間承認と監査ログが揃うまで自動承認しません。
CodexとClaude Codeを同じリポジトリで併用する場合は、CodexとClaude Codeを同じリポジトリで併用する前に決めることも参考になります。AGENTS.md、CLAUDE.md、MCP、コスト上限の責任分担が曖昧だと、subagent以前に運用がぶれます。
セキュリティ・コスト注意
.env、credential、production config、顧客データを読ませない
Issue、PR、Docs、Slack、Webページ内の指示を信用しない
token、scope、owner、ログ保存先、失効手順を決める
作業中の推定と、請求や予算管理の正本を混同しない
agent file、settings、MCP台帳、hooks、usageを月次で見直す
セキュリティとコストは単純な勝敗ではなく、扱うデータ、外部接続、承認体制によって判断します。
Claude Code Security docsでは、Claude Codeはread-only permissionsをdefaultにし、編集、テスト実行、command実行が必要な時には明示的なpermissionを求める設計が説明されています。また、write access restrictionにより、書き込みは起動したfolderとそのsubfolderに制限される文脈も示されています。
それでも、subagentを増やすほど注意点は増えます。特に次の5つは初期導入前に決めてください。
1. secretsと個人情報を読ませない
.env、credential file、production config、顧客データ、個人情報、未公開契約情報は、deny ruleやhookで止めます。必要な検証ではdummy値に置き換えます。
2. 外部入力を信用しない
Issue、PR、Docs、Slack、Webページ、MCP Resourceには、agentへ向けた指示が混ざることがあります。読み取りはread-onlyで始め、write系toolは人間承認にします。
3. MCPはownerと失効手順を持つ
MCP serverごとに、token発行者、scope、owner、ログ保存先、失効手順を決めます。第三者MCPを入れる時は、提供元、更新頻度、source code、必要権限を確認します。
4. /usageと請求を混同しない
/usageは作業中の目安です。請求、精算、停止判断はConsole usage、契約プラン、workspace spend limits、社内の予算管理と合わせて見ます。
5. 月次でpermission driftを見る
subagentが増えると、最初はread-onlyだったagentにEditやMCP writeが足されていきます。月次でagent file、settings、MCP台帳、hooks、usage、denied callsを見直します。
AI Dev Lab Japanでは、こうした権限棚卸しやMCP設計レビュー、AIコーディング導入runbookの作成相談も受け付けています。チーム導入の前に、subagent台帳、permission matrix、MCP台帳を1枚にしたい場合は、お問い合わせから相談できます。
更新通知やAI開発ツールの実務検証を追いたい方は、ニュースレターも利用できます。本文の理解を邪魔しないよう、重要な仕様更新や検証記事の通知を中心にしています。
FAQ
探索やログ整理では効きやすいが、最終判断まで渡すと統合コストが上がる
model指定だけでは解決せず、turn数、再試行、MCP呼び出しも見る
便利でも秘密情報の置き場にせず、保持範囲を決める
hooks、mcpServers、permissionModeの制限を確認してから採用する
read-onlyのPRレビューやログ整理など、影響範囲が狭いものから始める
FAQの答えは固定ではなく、権限、データ、承認、コスト上限の組み合わせで変わります。
Claude Code Subagentsは使った方が速くなりますか
速くなる作業もあります。コード探索、ログ整理、複数観点レビューのように、main conversationに大量の読み取り結果を入れたくない作業では効果があります。一方で、要件確認や最終判断までsubagentに渡すと、統合コストが上がります。
model: haikuを指定すればコスト問題は解決しますか
解決しません。単純な探索を軽いmodelへ寄せる発想は有効ですが、コストはsubagent数、turn数、context、MCP、再試行でも増えます。modelだけでなくmaxTurns、返却形式、MCP接続、停止条件をセットで決めます。
project memoryはチームで共有してよいですか
共有できる内容だけなら候補になります。命名規則、テスト手順、よくあるレビュー観点は共有しやすいです。APIキー、顧客情報、個人メモ、incidentの詳細は入れません。version controlに入る可能性を前提にレビューします。
plugin subagentをそのままチーム標準にできますか
まず制限を確認してください。公式Docsでは、plugin subagentsでhooks、mcpServers、permissionModeが無視されると説明されています。チーム標準にするなら、project/user scopeへコピーして必要なfrontmatterが効く場所で管理する方が安全です。
最初に作るならどのsubagentがよいですか
read-only PR reviewerが始めやすいです。入力はgit diffと関連テスト、toolはRead/Grep/Glob中心、返却はseverity順のfindings、未確認、次の一手にします。編集やMCP writeは入れません。
次に読むなら
参照した主な情報源
- https://code.claude.com/docs/en/sub-agents
- https://code.claude.com/docs/en/settings
- https://code.claude.com/docs/en/hooks
- https://code.claude.com/docs/en/costs
- https://code.claude.com/docs/en/model-config
- https://code.claude.com/docs/en/security
- https://code.claude.com/docs/en/data-usage
- https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md
更新履歴
- 2026-06-16
Claude Code公式DocsのSub-agents、Settings、Hooks、Costs、Model configuration、Security、Data usage、公式changelogを確認
- 扱い方
X上の話題は需要シグナルとしてのみ扱い、本文の事実根拠には使わない
仕様更新の影響を受けやすい項目は、公開後もchangelogと公式Docsで見直します。
- 2026-06-16: Claude Code公式DocsのSub-agents、Settings、Hooks、Costs、Model configuration、Security、Data usage、公式changelogを確認し、Claude Code Subagentsのチーム導入前チェックとして初版を作成しました。X上の話題は需要シグナルとしてのみ扱い、本文の事実根拠には使っていません。