「一人で全部やらせる」ことの限界にぶつかった
Claude Code を使い始めると、最初は「なんでも一発でやってくれる」という感動がある。しかしプロジェクトが複雑になるにつれ、いくつかの問題に直面し始める。
- コンテキスト汚染: 長い会話の中で、前の作業のゴミが邪魔になる
- 並列作業できない: 「リファクタリングしつつテストを修正する」ような並列タスクが直列になる
- 毎回同じ説明をする: 「このプロジェクトではTypeScriptを使っている」「テストフレームワークはVitestだ」を毎回伝えないといけない
この課題を解決するのが、.claude/agents/ ディレクトリへのサブエージェント定義と、Git Worktree を使った並列実行だ。実際に運用してわかったことをまとめる。
.claude/agents/ ディレクトリとは何か
.claude/agents/ はプロジェクトルートに置くディレクトリで、専門化されたサブエージェントを Markdown で定義できる場所だ。
my-project/
├── .claude/
│ ├── agents/
│ │ ├── code-reviewer.md
│ │ ├── test-writer.md
│ │ └── db-migrator.md
│ └── settings.json
├── src/
└── package.json
各エージェント定義ファイルには、フロントマターでメタデータを書き、本文にそのエージェントへの指示を書く。
---
name: code-reviewer
description: コードレビューを行うエージェント。PRのdiffを受け取り、品質・セキュリティ・命名の問題を指摘する
tools:
- Read
- Grep
- Bash
---
あなたはコードレビュアーです。以下の観点でレビューを行ってください：
1. **セキュリティ**: SQL injection, XSS, 認証漏れ
2. **品質**: 単一責任の原則、テスタビリティ
3. **命名**: 意図が伝わる変数名・関数名か
指摘は具体的に、ファイル名と行番号を含めてください。
CLAUDE.md がプロジェクト全体の方針を書く場所なのに対し、.claude/agents/ は繰り返し発生する特定タスクの手順書を置く場所だ。
実際に使ってみた：3つのユースケース
ユースケース1：PRレビューのサブエージェント化
最もシンプルな使い方が、PRレビューの定型化だ。
---
name: pr-reviewer
description: GitHub PRのdiffをレビューし、問題を指摘する
tools:
- Bash
- Read
- Grep
---
以下の手順でPRをレビューしてください：
1. `git diff main...HEAD` でdiffを取得
2. 変更されたファイルを個別に確認
3. セキュリティ・品質・命名の問題を重大度（Critical/Major/Minor）で分類して報告
## このプロジェクト固有のルール
- テストフレームワークは Vitest を使う。Jest の記法を混在させないこと
- 型引数の省略禁止（`useState<string>` を `useState` にしない）
- コミットは Conventional Commits に従う
Critical な問題がある場合は、作業を止めてユーザーに報告すること。
効果: 「このプロジェクトのルール」を毎回説明する必要がなくなった。エージェントを呼び出すたびに tools に記載したものだけが使えるので、意図しないファイル変更も防げる。
ユースケース2：Git Worktree を使った並列実行
サブエージェントの真価は、複数を同時に走らせるときに発揮される。ここで Git Worktree が活躍する。
Git Worktree は、1つのリポジトリに対して複数の作業ディレクトリを持てる機能だ。通常の git checkout では1つのブランチしか同時に扱えないが、git worktree add を使うと別ディレクトリで別ブランチを同時に開ける。
# メインの作業ディレクトリ（既存）
/my-project/ (main branch)
# 並列作業用のworktreeを2つ追加
git worktree add ../my-project-refactor feature/refactor
git worktree add ../my-project-tests feature/add-tests
これをClaude Codeと組み合わせると、2つの作業を独立して同時進行できる。
# ターミナル1: リファクタリング担当
cd ../my-project-refactor
claude "srcディレクトリのコンポーネントをリファクタリングして。テストは壊さないこと"
# ターミナル2: テスト追加担当（同時に実行）
cd ../my-project-tests
claude "カバレッジが50%以下のファイルにテストを追加して"
2つのエージェントは互いのファイル変更に干渉しない。それぞれ独立したブランチ・独立したディレクトリで作業しているからだ。
実際の体験: 本来なら直列で2時間かかる作業が、1時間強に短縮できた。重要なのは「ブランチが分かれているので、片方が失敗しても影響がない」という安心感だ。壊れたworktreeは git worktree remove で削除するだけで済む。
ユースケース3：DBマイグレーションの安全な自動化
DBマイグレーションは怖い作業だが、専用サブエージェントで安全性を高められる。
---
name: db-migrator
description: データベースマイグレーションを安全に生成・レビューする
tools:
- Read
- Bash
- Write
---
データベースマイグレーションを行います。以下のルールを必ず守ってください：
## 必須チェックリスト
- 既存のマイグレーションファイルを全て確認してから新規作成する
- ロールバック手順（down migration）を必ず含める
- NOT NULL カラムの追加には必ずデフォルト値を設定する
- インデックスの追加は CONCURRENTLY を使う（PostgreSQL）
## 禁止事項
- カラムの削除（非推奨化してから次のPRで削除すること）
- テーブルのリネーム（アプリケーション側と同時変更が必要なため）
**作業前に必ずユーザーに計画を説明し、承認を得てから実行すること。**
「やっていいこと・いけないこと」を定義しておくと、エージェントが危険な操作を自主的に避けるようになる。これは Claude Code Hooks と組み合わせると更に安全にできる（Hooks については別記事で解説している）。
運用してわかった注意点
agents/ の粒度は「週2回以上使う作業」が目安
サブエージェントを定義すると便利だが、多すぎるとどれを使えばいいか迷う。経験上、週2回以上繰り返す作業を対象にするのが適切な粒度だった。
一度しかやらない作業はその場で直接依頼すれば十分だ。現在運用中のサブエージェントは 4〜5個が管理しやすいと感じている。
Git Worktree は事後のマージコストを意識する
並列実行で速くなっても、最終的にブランチをマージする必要がある。同じファイルを2つのエージェントが変更するとコンフリクトが発生する。
対策: ファイルの担当範囲を事前に分割する。「エージェントAは src/components/、エージェントBは src/utils/」のように役割を切り分けることで、コンフリクトを大幅に減らせた。分割できない場合は、片方が完了してからもう片方を実行する直列実行に戻す。
エージェント定義は100行以内に保つ
サブエージェント定義に長大な説明を書きすぎると、トークン消費が増えてかえって遅くなる。.claude/agents/ のファイルは 100行以内を目安に、重要なルールだけを書くようにした。詳細な背景知識は CLAUDE.md に書いて全エージェントが参照できるようにする方が効率的だ。
CLAUDE.md とサブエージェントの使い分け
混乱しやすいのが、CLAUDE.md とサブエージェント定義の違いだ。
| CLAUDE.md | .claude/agents/ | |
|---|---|---|
| 対象 | 全セッション共通 | 特定の繰り返しタスク |
| 内容 | プロジェクト全体のルール | タスク固有の手順・禁止事項 |
| 粒度 | 粗い（方針レベル） | 細かい（手順レベル） |
| 更新頻度 | 低い（月1回程度） | 中程度（気づいたら随時） |
CLAUDE.md には「このプロジェクトはTypeScriptを使う」「コミットはConventional Commitsに従う」といったプロジェクト全体ルールを書く。サブエージェント定義には「PRレビューのときはこの順番で確認する」という作業固有の手順を書く。
両者を使い分けることで「全体ルールはCLAUDE.mdで一元管理、タスク固有の手順はagents/で専門化」という構造になる。
サブエージェントが変えた開発体験
.claude/agents/ と Git Worktree の組み合わせで、3つの変化を実感した。
1. 説明の重複がなくなった
毎回「このプロジェクトのルール」を説明する必要がない。定義ファイルに書いておけばエージェントが自動的に参照する。
2. 並列実行で待ち時間が減った
2つの独立したタスクを同時に進められる。片方がLLMの回答を待っている間、もう片方は別の作業を進めている。
3. エージェントの行動が予測可能になった
禁止事項を定義することでミスが減った。「なぜかDBのカラムを消された」というような意図しない操作が激減した。
まずは1つのサブエージェント定義から始めることをお勧めする。週2回以上やっている繰り返し作業があれば、それがサブエージェント化の候補だ。
Claude Code の Hooks 機能（PostToolUse, Stop, Notification など）については Claude Code Hooks 完全ガイド で詳しく解説しています。