やす研究所 AI Lab
戻る

Claude Code サブエージェント実践設計2026:並列開発を回す.claude/agents 構成

Claude Code サブエージェント実践設計2026:並列開発を回す.claude/agents 構成

Claude Code を毎日触っていて、最近一番効いた変化は何かと聞かれたら、私は迷わず「サブエージェントを真面目に設計したこと」と答えます。CLAUDE.md に全部詰め込んでいた頃と比べて、レビュー精度も並列処理の速度も別物になりました。

ただ、世の中の解説は「サブエージェントは便利です」で終わっているものが多い。実際に .claude/agents/ をどう切り、どのモデルを割り当て、どこでフックと組み合わせるかまで踏み込んでいる記事は意外と少ないんですよね。

この記事では、私が3週間運用してみて落ち着いた構成と、ハマりどころをまとめます。コピペで動く YAML も置いておきます。

結論:サブエージェントは「役割×ツール権限×モデル」で設計する

先に結論だけ言います。サブエージェントを使いこなす鍵は、次の3軸を意識して切り分けることです。

この3軸が決まれば、サブエージェント定義はだいたい30行以内に収まります。長くなったら設計が間違っているサインだと思っていい。

なぜ CLAUDE.md だけでは足りないのか

正直、最初は「CLAUDE.md に書けばいいじゃん」と思っていました。実際それで半年くらいは回っていたんです。

でも、ある dev.to の解説で見かけた一節がしっくり来ました。CLAUDE.md の指示はあくまでアドバイザリで、モデルが従うのは約8割程度だという話です。コーディングスタイルなら許せますが、「main に force push するな」「lint を必ず通せ」みたいな非交渉ルールには弱い。

もう一つの理由はコンテキスト汚染です。grep の生出力やログを main の会話に流すと、肝心の設計議論が薄まる。サブエージェントは独立したコンテキストウィンドウで動くので、要約だけが手元に返ってきます。これが想像以上に効きました。

.claude/agents/ の最小構成

まずは Markdown + YAML frontmatter の基本形を押さえます。Claude Code 公式ドキュメントによると、サブエージェントは .claude/agents/(プロジェクト共有)か ~/.claude/agents/(個人)に Markdown ファイルとして配置します。

---
name: code-reviewer
description: コード品質・セキュリティ・保守性をレビュー。コード編集直後に自動起動。
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたはシニアコードレビュアーです。
以下の観点で diff をチェックしてください:
- 命名・責務分離
- N+1 や境界条件
- 秘密情報の混入
- テストカバレッジの抜け

指摘は重要度(High/Med/Low)を付けて、修正パッチ案を添えてください。

ポイントは description の書き方です。ここに「いつ起動すべきか」を明示的に書くと、Claude が自動デリゲートしてくれる確率が上がります。「Use immediately after writing or modifying code」のような能動的な表現を入れるのがコツ。

tools フィールドで権限を絞る

tools: を省略すると親エージェントのツール権限を継承します。これは便利な反面、レビュー専門のエージェントに Write を渡してしまうとか、思わぬ事故が起きやすい。

私は明示派です。例えば調査専門の researcher には Read, Grep, Glob, WebFetch だけ渡し、書き込み系は一切持たせません。手が滑って読むだけのつもりが書き換える、という事故を構造的に潰せます。

私が運用している3つのサブエージェント

抽象論ばかりだと使えないので、実際に手元で動かしている構成を晒します。

1. researcher(調査・要約専門)

---
name: researcher
description: ドキュメントやコードベースを横断調査し、要約だけを返す。設計検討時に自動起動。
tools: Read, Grep, Glob, WebFetch
model: haiku
---

モデルを Haiku 系に寄せているのが味噌です。grep して結果を要約するだけなら Sonnet を呼ぶ必要はない。コストが体感で3〜4割落ちました(計測可能な範囲の話で、ワークロードによります)。

2. test-runner(テスト実行・修正)

---
name: test-runner
description: 失敗したテストを実行し、原因を特定して修正案を返す。
tools: Bash, Read, Edit
model: sonnet
---

こちらは Sonnet。失敗ログから原因を推論する仕事なので、ケチると逆に往復が増えます。

3. pr-writer(コミット&PR文生成)

---
name: pr-writer
description: git diff を読み、コミットメッセージと PR 説明を生成する。
tools: Bash, Read
model: haiku
---

地味ですが効果が大きいエージェントです。先週 Claude Code で Astro サイトのコンポーネントを6つほどリファクタした際、PR 文を pr-writer に任せたら、書きながら自分の頭が次のタスクに移れた。コンテキストスイッチのコストが消えた感じ。

Hooks と組み合わせて「人が判断しない」状態を作る

サブエージェントだけだと、結局起動するかどうかを毎回判断することになります。ここで Hooks が効いてくる。

Claude Code の Hooks はライフサイクルイベントでシェルコマンドを発火させる仕組みで、PreToolUse・PostToolUse・SessionStart など複数のイベントポイントが用意されています。公式ドキュメントによると、PreToolUse はツール実行前のセキュリティチェックポイントとして機能し、Exit code 2 でその操作をブロックできます。

私が常用しているのは PostToolUse でテストを自動実行するパターン。~/.claude/settings.json にこんな感じで書きます。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "cd $CLAUDE_PROJECT_DIR && npm test -- --bail 2>&1 | tail -20"
      }]
    }]
  }
}

ファイルが編集された瞬間にテストが走り、結果が <system-reminder> として Claude に返る。Claude は自分が壊したことに気づいて、何も言われる前に修正に入ります。受け身から先回りに変わる、ちょうど自動運転のレーンキープが効きはじめた瞬間みたいな感覚です。

Agent SDK との関係をどう捉えるか

ここ、混乱する人が多いので整理しておきます。

Anthropic は2026年3月に「Claude Code SDK」を「Claude Agent SDK」にリネームしました。これは別物ではなく、Claude Code を動かしているエージェントハーネスを Python/TypeScript ライブラリとして公開したものです。エントリポイントは query() という async generator で、プロンプトとオプションを渡すと型付きメッセージがストリームで返ってきます。

対話的に使いたい(VS Code 内、ターミナル):Claude Code 本体 アプリ側から駆動したい(CI、Slack bot、自作ツール):Agent SDK

そしてもう一つ、2026年6月15日から課金が変わる点に注意してください。Anthropic の公式ヘルプによると、その日以降は Claude Agent SDK と claude -p の使用がサブスクリプションの使用上限とは別の月次クレジットでカバーされる仕組みに切り替わります。対象は Pro / Max / Team / Enterprise プラン。プロダクションで claude -p を回している人は、自分のワークロードがどっちのバケットに乗るか棚卸ししておくと事故りません。

サブエージェントを設計するときの3つのつまずきポイント

3週間運用してみて、これは先に知っておくべきだった、という落とし穴です。

1つめは、description を曖昧に書きすぎること。「コードを良くする」みたいな粒度だと、Claude が自動デリゲートしてくれません。「コード編集直後に走らせる」「PR 作成前に呼ぶ」のように、トリガー条件を入れる。

2つめは、サブエージェント間で状態を共有しようとすること。これは公式ドキュメントでも示唆されていますが、サブエージェントは独立コンテキストで動くのが強み。状態共有が必要な瞬間に設計を疑ってください。たいてい、main エージェントに統合役を任せた方が綺麗にまとまります。

3つめは、Sonnet を全エージェントに割り当てること。これは私もやりました。grep するだけの researcher を Sonnet で動かしていた頃と、Haiku 系に切り替えた今では、月のクレジット消費が体感で目に見えて違います。重い推論と軽い情報収集を混ぜない。

まとめ:今日からやる3つのアクション

ここまで読んでくれたあなたへ、最小ステップで効果を出すための具体アクションです。

  1. .claude/agents/code-reviewer.md を1つだけ作る。上記のテンプレをそのまま貼って、/agents コマンドで認識されているか確認する
  2. tools: を明示し、model: を役割で出し分ける。調査系は Haiku、推論系は Sonnet
  3. PostToolUse Hook で自動テストを一つ仕込む。settings.json に5行追加するだけで、編集→検証ループが手放しになる

サブエージェントは「便利機能」ではなく、Claude Code を対話ツールから開発インフラに変えるための土台です。最初の1ファイルを書いた瞬間から、世界がほんの少し静かになります。試してみて、自分の役割設計を一つ晒してもらえたら嬉しいです。

参考リンク

この記事をシェア:
X で共有 Facebook で共有 Telegram で共有
次の記事
AIマイクロSaaSを2週間で立ち上げる手順|バイブコーディング個人開発マネタイズ術