Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

サブエージェントはデフォルトでバックグラウンド実行されるようになりました。これにより、Claudeはサブエージェントの実行中も作業を継続でき、完了時に通知を受け取れます（これまでは段階的なロールアウトによる提供でした）。

原文（英語） ​

Subagents now run in the background by default, so Claude keeps working while they run and is notified when they finish (previously a gradual rollout)

概要 ​

サブエージェントはフォアグラウンド（結果が返るまでメイン会話をブロックする）とバックグラウンド（並行して動作し続ける）のどちらでも実行できます。v2.1.198でバックグラウンドをデフォルトにする変更が導入されましたが、これは段階的なロールアウトとして提供されていました。v2.1.199でこの挙動が正式に既定動作となり、Claudeはサブエージェントの結果をすぐに必要とする場合を除き、基本的にサブエージェントをバックグラウンドで起動し、メインの会話での作業を止めずに進められるようになりました。完了時には通知を受け取ります。

基本的な使い方 ​

特別な設定は不要です。通常どおりサブエージェントを使う（Claudeにタスクを任せる、@メンションでサブエージェントを指定するなど）だけで、Claudeが必要に応じて自動的にバックグラウンド実行を選択します。

text
> 認証まわりのコードを調査して、既知の問題がないかレポートして

このような調査タスクは、多くの場合バックグラウンドのサブエージェントとして実行され、Claudeはその間もメインの会話で他の作業を続けられます。

実践例 ​

明示的にフォアグラウンド実行させる ​

サブエージェントの結果をすぐに使いたい場合は、フォアグラウンドで実行するようClaudeに依頼できます。

text
> このリファクタリングの前に、まずフォアグラウンドでテストカバレッジを調査して結果を教えて

実行中のタスクを手動でバックグラウンド化する ​

Ctrl+B を押すと、現在フォアグラウンドで実行中のタスクをバックグラウンドに切り替えられます。

サブエージェント定義で常にバックグラウンド実行を強制する ​

カスタムサブエージェントのfrontmatterに background: true を指定すると、Claudeが結果をすぐに必要とする場面でも常にバックグラウンドで実行されます。

yaml
---
name: log-analyzer
description: Analyze application logs for anomalies
background: true
---

Analyze the recent application logs and report anomalies.

バックグラウンド実行を完全に無効化する ​

すべてのサブエージェントを常にフォアグラウンドで実行させたい場合は、環境変数でバックグラウンドタスク機能自体を無効化できます。

bash
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

注意点 ​

  • バックグラウンド実行はサブエージェントが「どこで動くか」を変えるだけで、「何をしてよいか」は変わりません。バックグラウンドで動くサブエージェントも、権限確認が必要なツール呼び出しはメインセッションにそのまま表示され、承認するかそのツール呼び出しだけをEscで拒否できます。
  • サブエージェントの入れ子は最大5階層までで、フォアグラウンド/バックグラウンドを問わず変更できません。
  • CLAUDE_CODE_FORK_SUBAGENT=1 を設定してフォークモードを有効にしている場合、すべてのサブエージェント起動が強制的にバックグラウンドになり、background frontmatterフィールドは効果を持ちません（CLAUDE_CODE_DISABLE_BACKGROUND_TASKS の方が優先されます）。
  • agent view（claude agents）を開いている間は、バックグラウンドセッションが入力待ちになった・完了した・失敗した際に、設定した通知チャンネル（preferredNotifChannel）経由で通知されます。
  • レート限界やサーバーエラーでバックグラウンドのサブエージェントが中断した場合は、失敗として扱われつつ、それまでの出力を含むメッセージがメインエージェントに返るため、途中経過が失われることはありません（v2.1.199で導入）。

関連情報 ​