Claude Code ガイド

Appearance

未追跡ファイルを含むworktreeがサブエージェントのクリーンアップで削除される問題の修正 ​

原文（日本語に翻訳） ​

古いサブエージェントworktreeのクリーンアップが、未追跡ファイルを含むworktreeを削除してしまう問題を修正しました。

原文（英語） ​

Fixed stale subagent worktree cleanup removing worktrees that contain untracked files

概要 ​

Claude Codeがサブエージェント用にGit worktreeを作成して作業を行う際、古いworktreeのクリーンアップ処理が未追跡ファイル（Gitで管理されていないファイル）を含むworktreeも削除してしまう問題がありました。この修正により、未追跡ファイルが存在するworktreeは自動クリーンアップの対象から除外され、重要なファイルが意図せず削除されなくなります。

基本的な使い方 ​

修正前の動作 ​

bash
# サブエージェントがworktreeで作業を行う場合
# 例: 新機能の実装タスク

# サブエージェントのworktreeに未追跡ファイルが存在する状態
# worktree: /tmp/claude-agent-work-abc123/
#   - new-feature.ts (未追跡: git add していない)
#   - config.json (未追跡)

# 次のセッションでクリーンアップが実行される
# 修正前: 未追跡ファイルが存在しても削除される
# → new-feature.ts と config.json が失われる

修正後の動作 ​

bash
# 同じ状況でクリーンアップが実行される場合
# 修正後: 未追跡ファイルを含むworktreeはスキップされる
# → ファイルが保護され、削除されない
# 警告メッセージが表示される場合がある:
# "Worktree /tmp/claude-agent-work-abc123 contains untracked files, skipping cleanup"

実践例 ​

### サブエージェントによる新機能実装 ​

サブエージェントが新しいファイルを作成して実装を行う場合：

# 親エージェントの指示
"新しい認証モジュールを別のworktreeで実装してください"

# サブエージェントの作業:
# 1. git worktree add /tmp/feature-auth main
# 2. auth/index.ts を新規作成（未追跡）
# 3. auth/utils.ts を新規作成（未追跡）
# 4. 途中でセッションが中断

# 次回セッション開始時のクリーンアップ
# 修正前: auth/index.ts と auth/utils.ts が削除される
# 修正後: 未追跡ファイルが存在するためworktreeが保護される

### マルチエージェントでの並列開発 ​

複数サブエージェントが異なる機能を並列で実装する場合：

bash
# サブエージェント1: feature-a ブランチで作業
# /tmp/claude-worktree-feature-a/
#   - src/feature-a.ts (未追跡、未コミット)
#   - tests/feature-a.test.ts (未追跡)

# サブエージェント2: feature-b ブランチで作業（完了済み）
# /tmp/claude-worktree-feature-b/
#   ← すべてコミット済み

# クリーンアップ実行
# 修正後の動作:
# - feature-a のworktree: 未追跡ファイルあり → 保護される
# - feature-b のworktree: クリーンな状態 → 削除される

### 安全なworktree管理のベストプラクティス ​

bash
# worktreeのクリーンな状態を確認
git worktree list

# 未追跡ファイルがあるかチェック
git -C /tmp/claude-agent-worktree status

# 手動でworktreeを削除する場合（未追跡ファイルを確認後）
git worktree remove /tmp/claude-agent-worktree  # クリーンな場合
# または
git worktree remove --force /tmp/claude-agent-worktree  # 強制削除

注意点 ​

  • この修正は自動クリーンアップの挙動を変更します。未追跡ファイルを含むworktreeは自動削除されなくなります。
  • 未追跡ファイルを含むworktreeが増えた場合、手動でクリーンアップが必要になる場合があります。git worktree list で確認し、不要なworktreeは手動で削除してください。
  • サブエージェントが作成したファイルをGitに追加（git add）してコミットしておくことで、worktreeがクリーンな状態になり自動クリーンアップの対象になります。
  • この修正はデータ損失を防ぐためのものです。重要な作業ファイルが意図せず削除されるリスクが大幅に低減されます。

関連情報 ​