Claude Code のエージェント定義に isolation: worktree が追加された
はじめに
Claude Code のアップデートで、エージェント定義に isolation: worktree を指定できるようになりました。
これにより、サブエージェントを自動的に独立した git worktree で実行させることが可能になりました。複数のエージェントが並列で動いても、お互いのファイル変更が衝突しなくなります。
簡単なサンプルを見てみましょう。
---
name: isolated-implementer
description: 独立した worktree で実装を行うエージェント
isolation: worktree
---
あなたは実装専門のエージェントです。
独立した git worktree 環境で安全にコードを編集します。
たったこれだけで、このエージェントが呼び出されるたびに専用の worktree が作られ、メインブランチを汚さずに作業できます。
3行まとめ
- エージェント定義のfrontmatterに
isolation: worktreeを追加するだけで、エージェントが専用の git worktree で実行される - 複数エージェントが並列動作しても変更が衝突しなくなり、安全な並列開発が可能に
- エージェント終了時に変更がなければ worktree は自動削除されるので後片付け不要
🔧 isolation: worktree とは
git worktree とは、1つのリポジトリから複数の作業ディレクトリを作成できる Git の機能です。それぞれのディレクトリは独立したブランチを持ち、同時に異なるブランチで作業できます。
Claude Code の isolation: worktree は、この仕組みをエージェントに適用したものです。エージェントが起動されるたびに専用の worktree（= 専用の作業ディレクトリ + ブランチ）が自動作成され、メインの作業環境を汚染せずにエージェントが自由に動けます。
リポジトリ
├── .claude/worktrees/
│ ├── agent-abc123/ ← エージェントAの専用worktree
│ │ └── (全ファイルのコピー)
│ └── agent-def456/ ← エージェントBの専用worktree
│ └── (全ファイルのコピー)
└── (メインの作業ディレクトリ)
📋 設定方法
エージェント定義ファイルに追記するだけ
エージェント定義ファイル（.claude/agents/<name>.md）のfrontmatterに isolation: worktree を追加します。
---
name: feature-implementer
description: フィーチャー実装を担当するエージェント。新しい機能の追加や既存コードの修正を行います。
isolation: worktree
tools:
- Read
- Write
- Edit
- Bash
---
あなたはフィーチャー実装専門のエージェントです。
指示された機能を実装し、変更内容を適切にコミットしてください。
Task ツールからの利用時
Claude Code の会話中に Task ツールでエージェントを呼び出す際、エージェント定義に isolation: worktree があれば自動で適用されます。
> use the feature-implementer subagent to add user authentication
⚙️ 動作の仕組み
worktree の作成
エージェントが起動されると、以下の場所に worktree が作成されます。
<リポジトリルート>/.claude/worktrees/<ランダムな名前>/
ブランチ名は worktree-<名前> という形式で自動生成されます。
worktree のライフサイクル
| 状態 | 動作 |
|---|---|
| エージェント起動時 | worktree とブランチが自動作成 |
| エージェント終了（変更なし） | worktree とブランチが自動削除 |
| エージェント終了（変更あり） | worktree が保持され、結果が返される |
変更がない場合は自動でクリーンアップされるので、後片付けが不要です。
フックイベント
WorktreeCreate と WorktreeRemove フックを設定することで、worktree の作成・削除時にカスタム処理を実行できます。
// .claude/settings.json
{
"hooks": {
"WorktreeCreate": [
{
"command": "npm install"
}
],
"WorktreeRemove": [
{
"command": "echo 'worktree removed'"
}
]
}
}
これにより、git 以外のバージョン管理システム（SVN、Perforce、Mercurialなど） にも対応できます。
🚀 実際の使用例
例1: 並列フィーチャー開発
複数の機能を同時に実装させる際に効果を発揮します。
> フロントエンドエージェントにユーザー一覧画面を実装させて、
同時にバックエンドエージェントにAPIを実装させてください
各エージェントが独立した worktree で作業するため、ファイルの競合が発生しません。
例2: コードレビューと実装の並列化
---
name: code-reviewer
description: コードの品質レビューを行う
isolation: worktree
---
レビューと実装を並列で実行しても、お互いの変更が干渉しません。
例3: 実験的な変更の試行
---
name: experimental-implementer
description: 実験的なアプローチで実装を試みる。失敗してもメインブランチに影響しない
isolation: worktree
---
失敗してもメインの作業環境には影響がないため、気軽に実験できます。
💡 ベストプラクティス
.gitignore への追加
worktree のコンテンツがメインリポジトリで未追跡ファイルとして表示されないよう、.gitignore に追加しておきましょう。
# Claude Code worktrees
.claude/worktrees/
worktreeが必要なエージェントの見極め
isolation: worktree はすべてのエージェントに必要なわけではありません。以下のような場合に有効です。
✅ worktreeが有効なケース
- ファイルを作成・編集するエージェント
- 並列実行される可能性があるエージェント
- 実験的な変更を試みるエージェント
❌ worktreeが不要なケース
- 読み取り専用のエージェント（調査・分析など）
- ファイルを変更しないエージェント
WorktreeCreate フックで環境を整える
エージェントが動作するために依存パッケージのインストールが必要な場合、WorktreeCreate フックで対応できます。
{
"hooks": {
"WorktreeCreate": [
{
"command": "npm install && npx prisma generate"
}
]
}
}
まとめ
isolation: worktree は、エージェント定義のfrontmatterに1行追加するだけで、エージェントの実行環境を完全に分離できる便利な機能です。
- 🔒 安全性: エージェントの変更がメインブランチに直接影響しない
- ⚡ 並列化: 複数エージェントが同時実行しても衝突しない
- 🧹 自動クリーンアップ: 変更がなければ worktree は自動削除される
- 🔧 拡張性: フックで非git VCSにも対応可能
複数のエージェントを使った自動化ワークフローを構築している方は、ぜひ試してみてください。