Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

エージェント定義が background: true をサポートし、常にバックグラウンドタスクとして実行できるようになりました。

原文（英語） ​

Agent definitions support background: true to always run as a background task

概要 ​

エージェント定義ファイルに background: true を設定することで、そのエージェントは常にバックグラウンドタスクとして実行されるようになります。これにより、長時間実行されるタスクをメインのClaudeセッションをブロックせずに並行して処理でき、ユーザーは他の作業を続けながらエージェントの完了を待てます。

基本的な使い方 ​

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

yaml
---
name: background-worker
description: "バックグラウンドで動作する長時間タスク用エージェント"
model: claude-opus-4-6
background: true
---

指定されたタスクを非同期で処理します。
完了したら結果を報告してください。

実践例 ​

ユースケース1: 大規模なコードベースの解析 ​

時間のかかるコードベース解析をバックグラウンドで実行する場合。

yaml
# .claude/agents/codebase-analyzer.md
---
name: codebase-analyzer
description: "コードベース全体を解析して問題を特定するエージェント"
model: claude-opus-4-6
background: true
---

プロジェクト全体のコードを解析し、以下を特定してください：
- セキュリティの脆弱性
- パフォーマンスのボトルネック
- コードの重複
- 未使用のインポートや変数

解析完了後、優先度付きのレポートを作成してください。
bash
# メインセッションで起動
claude

# エージェントを呼び出す（バックグラウンドで実行される）
> @codebase-analyzer このプロジェクトを解析して
# → エージェントがバックグラウンドで解析を開始
# → メインセッションは引き続き他のコマンドを受け付ける

# 解析が続いている間に他の作業ができる
> ls src/
> git status

ユースケース2: テストの並行実行 ​

長時間かかるテストスイートをバックグラウンドで実行する場合。

yaml
# .claude/agents/test-runner.md
---
name: test-runner
description: "テストスイートをバックグラウンドで実行するエージェント"
model: claude-sonnet-4-6
background: true
---

指定されたテストスイートを実行し、
失敗したテストとその原因を詳細にレポートしてください。
修正案も提示してください。
bash
# テストをバックグラウンドで実行
> @test-runner フルテストスイートを実行して
# → テストがバックグラウンドで実行される
# → その間にコードの別の部分を作業できる

ユースケース3: ドキュメントの自動生成 ​

コードからドキュメントを生成するタスクをバックグラウンドで実行する場合。

yaml
# .claude/agents/doc-generator.md
---
name: doc-generator
description: "コードからAPIドキュメントを生成するエージェント"
model: claude-sonnet-4-6
background: true
---

ソースコードを解析し、APIドキュメントをMarkdown形式で生成してください。
各関数・クラス・インターフェースの説明、パラメータ、戻り値、使用例を含めてください。
bash
# ドキュメント生成をバックグラウンドで実行
> @doc-generator src/api/ のドキュメントを生成して
# → バックグラウンドでドキュメント生成が開始
# → 完了通知が届くまで他の作業を続けられる

注意点 ​

  • background: true はエージェント定義レベルの設定です。個別の呼び出しでオーバーライドはできません。
  • バックグラウンドエージェントを終了したい場合は Ctrl+F を2回押してください（v2.1.49で追加）。
  • background: true と isolation: "worktree" を組み合わせることで、完全に分離されたバックグラウンド処理が可能です。
  • バックグラウンドエージェントの実行中は、Ctrl+C等でメインセッションを終了するとエージェントも終了する場合があります。
  • バックグラウンドエージェントの状態確認方法は実装によって異なります。

関連情報 ​