Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

エージェント定義で isolation: worktree のサポートが追加されました。エージェントが分離されたgit worktreeで実行されることを宣言的に設定できます。

原文（英語） ​

Added support for isolation: worktree in agent definitions, allowing agents to declaratively run in isolated git worktrees.

概要 ​

エージェント定義ファイルに isolation: worktree を設定することで、そのエージェントは実行時に専用のgit worktreeが自動的に作成された独立した環境で動作します。これにより、エージェントの変更がメインの作業ブランチに影響を与えることなく、安全に作業できます。実験的な変更や並行作業に特に適しています。

基本的な使い方 ​

エージェント定義ファイル（.claude/agents/my-agent.md）に isolation: worktree を追加します。

yaml
---
name: experimental-agent
description: "実験的な変更を行うエージェント"
model: claude-opus-4-6
isolation: worktree
---

指定された実験的な変更を実施してください。
メインブランチに影響を与えずに変更を行います。

エージェントを呼び出すと、自動的に新しいgit worktreeが作成され、そのworktree内で作業が行われます。

実践例 ​

ユースケース1: リファクタリングの安全な試行 ​

大規模なリファクタリングをメインブランチに影響を与えずに試行する場合。

yaml
# .claude/agents/refactor-agent.md
---
name: refactor-agent
description: "コードのリファクタリングを安全に試みるエージェント"
model: claude-opus-4-6
isolation: worktree
---

以下のリファクタリングを実施してください：
1. 重複したコードを共通関数に抽出する
2. 命名規則をプロジェクトスタイルに統一する
3. 不要なコメントを削除する

変更後にテストが通ることを確認してください。
bash
claude

# リファクタリングエージェントを呼び出す
> @refactor-agent src/utils/ をリファクタリングして

# エージェントは新しいworktreeで作業
# → メインブランチには影響なし
# → 作業完了後にworktreeを確認してマージを判断できる

ユースケース2: 並行した機能開発 ​

複数の機能を独立したworktreeで並行開発する場合。

yaml
# .claude/agents/feature-developer.md
---
name: feature-developer
description: "独立した機能を並行開発するエージェント"
model: claude-opus-4-6
isolation: worktree
background: true
---

指定された機能を実装してください。
実装後にユニットテストを作成し、すべてのテストが通ることを確認してください。
bash
# 複数の機能を並行して開発（それぞれ独立したworktree）
> @feature-developer ユーザー認証機能を実装して
> @feature-developer 支払い処理機能を実装して
> @feature-developer 通知システムを実装して

# 各機能が独立したworktreeで開発される

ユースケース3: 自動テスト修正エージェント ​

テストが失敗した際に自動修正を試みるエージェント。

yaml
# .claude/agents/test-fixer.md
---
name: test-fixer
description: "失敗したテストを修正するエージェント"
model: claude-opus-4-6
isolation: worktree
---

失敗したテストを分析し、問題を修正してください。
修正後にすべてのテストが通ることを確認してください。
修正内容のサマリを報告してください。
bash
# テスト失敗時に修正エージェントを呼び出す
> @test-fixer 最新のテスト失敗を修正して

# 修正は独立したworktreeで行われる
# → メインブランチのコードはそのまま
# → 修正が正しければworktreeからマージ

注意点 ​

  • isolation: worktree を使用するには、プロジェクトがgitリポジトリである必要があります。
  • 各エージェント呼び出しで新しいworktreeが作成されます。作業完了後、worktreeを手動でマージ・削除するか、エージェントに任せることができます。
  • WorktreeCreate と WorktreeRemove フックイベント（v2.1.50で追加）と組み合わせることで、worktreeのセットアップとクリーンアップを自動化できます。
  • background: true と組み合わせることで、バックグラウンドで分離された環境での作業が可能です。
  • worktreeの数が増えるとディスク使用量が増加します。不要なworktreeは定期的にクリーンアップしてください。

関連情報 ​