Claude Desktopを捨てなくていい。それでもCLIを選ぶ理由──SubagentsとAgent Teams実践ガイド

1. 結論：DesktopかCLIかではなく、仕事の形に入口を合わせる

Claude DesktopとClaude Code CLIのどちらが「上」かを決める必要はない。2026年9月時点の実務的な結論は、見る・比較する・画像やPDFを渡す仕事にはDesktop、シェルと一体化した自動処理やAgent TeamsにはCLIである。

ここでいうCLIは、API専用契約や独自SDKの話ではない。Claude ProやMaxなど通常のClaude契約で、ターミナルから claude を起動して使うClaude Codeを指す。公式ドキュメントでも、Pro・Max・Team・Enterpriseのサブスクリプションでブラウザログインでき、Claude ConsoleのAPI課金は別の認証方法として整理されている。^[1][2]

筆者自身、長い間Desktopの方が便利だと感じ、CLIの利便性を深掘りせずに使ってきた。画像をドラッグ＆ドロップでき、PDFをその場で開け、Artifactsやプレビューを見ながら考えられる。Codeタブでは差分、ファイル、ターミナル、ブラウザをペインとして並べ、複数セッションも管理できる。これは単なる「初心者向けGUI」ではなく、視覚的なレビューに強い開発環境である。^[3][4]

一方で、「DesktopではSubagentsが動かない」「複数エージェントは全部CLIだけ」という説明は、もう正確ではない。DesktopのCodeタブにはsubagentペインがあり、同じClaude Codeエンジン上でSubagentsや動的ワークフローを使える。現在CLIに限定されているのは、共有タスクリストとエージェント間通信を持つAgent Teamsだ。公式のDesktop比較表も、この境界を明記している。^[3]

だから大切なのは陣営を選ぶことではない。今の仕事が「人間が画面で比較しながら一つずつ判断する仕事」なのか、「OS上のプロセス、ログ、認証、複数の独立タスクを束ねる仕事」なのかを見極めることだ。片方だけを使う場合でも、何を得て何を手放しているか理解できれば、その選択は意地ではなく設計になる。

2. Desktopの強さを過小評価しない──見えること自体が品質になる

Desktopの価値は、ボタンがあることではない。複数種類の情報を同じ視野へ置けることにある。

たとえば、デザインの修正なら、左に会話、右にブラウザプレビュー、下に差分を置く。画像やPDFはファイルパスを説明せずドラッグ＆ドロップできる。通常のChatではArtifactsを使い、文章、図表、UIのたたき台を会話と分離して確認できる。Codeタブでも、ファイル編集、ビジュアルdiff、アプリのライブプレビュー、サイドチャットを組み合わせられる。目視確認がボトルネックになる仕事では、この統合がそのまま手戻り削減になる。^[3][4]

さらにDesktopは複数セッションを並行実行し、Git worktreeで変更を分離できる。したがって、「ウィンドウが一枚だから一対一のターン制しかできない」という理解も古い。独立したセッションを複数走らせる機能と、一つのセッション内でSubagentsを動かす機能は、すでにDesktopにある。

Desktopの強みは、情報を目で比較しながら判断できること。画像・PDF・差分・実画面を往復する仕事では、GUIがレビュー装置になる。

ただし、複数ウィンドウやタブを扱えること自体は、Desktopだけの決定打ではない。iTerm2はタブ、縦横のペイン分割、別ウィンドウへのタブ移動、保存したウィンドウ配置を提供する。tmuxを足せば、SSH切断後もセッションを維持できる。CLIでも「調査」「実装」「テスト」「ログ」を別ペインに置き、別モニターへ切り離せる。^[5]

つまりUI管理の差は好みと作業内容で縮められる。決定的な差が現れるのは、その窓の中を流れるデータと、複数エージェントが協調する方式である。

3. CLIはローカル開発環境の「隣」ではなく、その配管になる

DesktopのCodeタブもローカルファイルを読み、統合ターミナルからコマンドを実行できる。ただしmacOSでDockやFinderから起動したDesktopは、常にシェル環境を完全継承するわけではない。公式資料は、シェル設定からPATHと一部のClaude Code変数は抽出する一方、そこでexportした他の変数は自動では取り込まれないため、ローカル環境エディタで設定するよう案内している。^[6]

ターミナルから起動するCLIは、いま人間が立っているカレントディレクトリと、export済み環境変数を出発点にできる。AWS SSOのセッション、AWS_PROFILE、Docker context、言語ランタイムのバージョン、PATH上の社内CLIなどが、普段の作業と同じ入口にある。認証エラーがゼロになるわけではないが、「Finderから起動したアプリに変数が届いていなかった」という別環境問題は減らせる。

注意したいのはエイリアスだ。環境変数は子プロセスへ渡せるが、shell aliasは通常exportされない。Claude Code側のシェルが同じ起動設定を読む場合は使えても、保証されたインターフェースと考えない方がよい。仕事に必須の短縮コマンドは、aliasのままではなくPATH上の小さなスクリプトかshell functionとして管理すると再現性が上がる。またClaude CodeのBashコマンドは別プロセスで動くため、あるコマンド内の export は次のコマンドへ自動継続しない。永続化には CLAUDE_ENV_FILE やSessionStart hookを使うのが公式の方法だ。^[7]

CLIらしさが最もよく出るのはパイプである。Dockerのログをファイルへ保存し、チャットに添付し、説明を書く必要はない。OSの標準出力を、そのままClaudeの標準入力へ接続できる。

docker compose logs --since=10m api \
  | grep -E 'ERROR|WARN|timeout' \
  | claude -p '原因候補を重要度順に3つ。根拠のログ行と次の確認コマンドも示して'

cat build-error.txt \
  | claude -p '最初に発生した根本原因だけを特定し、派生エラーと分けて説明して'

非対話モードのstdin上限は現行仕様で10MBである。巨大ログを丸ごと流すのではなく、--since、tail、grep、jqで人間側が対象を絞る。これは節約テクニック以上の意味を持つ。観測対象をシェルで決め、推論だけをAIへ渡すため、同じコマンドを再実行・レビュー・CI組み込みしやすい。^[8]

CLIではClaudeが開発環境の外から結果を受け取るのではなく、ログやdiffが流れる同じ配管の一部になる。切り出し方そのものが再現可能な手順になる。

4. トークンを制御する本質は、必要なファイルだけ外科的に触ること

CLIだから自動的に安い、Desktopだから大量にトークンを使う、という単純な関係ではない。両者は同じClaude Codeエンジンを共有し、読み込ませた文脈が増えるほどトークンは増える。差を作るのは操作面より、入力範囲をどれだけ明示的に絞れるかである。^[9]

ターミナルでは対象をコマンドで先に切れる。

git diff -- src/auth tests/auth \
  | claude -p '認証境界、例外処理、回帰テストだけをレビューして'

rg -n 'TODO|FIXME|deprecated' src/payments \
  | claude -p '本番障害につながる可能性があるものだけ分類して'

この運用では、リポジトリ全体を「とりあえず読んで」と頼まない。対象ディレクトリ、差分、時間帯、エラーレベルを人間側で狭める。医師が全身を毎回撮影するのではなく、症状から検査部位を決めるのと同じだ。

Subagentも同じ発想を強化する。大量の検索結果やログは独立したコンテキストで処理し、メイン会話へは要約だけを返す。公式資料も、Subagentsを使う理由としてメイン文脈の保全、ツール制限、役割の再利用、モデル選択を挙げる。Agent Teamsはさらに強力だが、各teammateが独立したClaudeインスタンスなので、公式のコスト資料ではplan modeのチームが通常セッションのおよそ7倍のトークンを使う目安も示されている。並列なら常に得、ではない。^[10][9]

判断基準は明快である。

5. 最大の差は人数ではなく、通信構造──SubagentsとAgent Teams

Subagentsは、一人の上司が専門家へ仕事を渡す組織に近い。各Subagentは独立したコンテキストとツール制限を持ち、調査・レビュー・実装などを担当し、結果を呼び出し元へ返す。DesktopのCodeタブでもCLIでも使える。バックグラウンド実行にも対応するため、メイン側で別の作業を続けられる。^[10]

Agent Teamsは、一段違う。メインセッションがteam leadになり、複数のteammateがそれぞれ独立したClaude Codeセッションとして動く。共有タスクリストから仕事を取り、相互にメッセージを送り、依存タスクが終われば次の仕事を解放する。人間はleadだけでなく個別teammateとも話せる。これは「Subagentを3体起動した」という人数の違いではなく、星型の委任から、チーム内通信を持つネットワークへ変わることだ。^[11]

Subagentsは専門作業を隔離して結果を集約する。Agent Teamsは独立した担当者が共有タスクとメッセージで協調する。差は人数より通信構造にある。

たとえば障害調査なら、次のように分けられる。

1. log-investigator：本番ログと時系列だけを読み、最初の異常を特定する。
2. code-investigator：該当コミットと呼び出し経路を読み、失敗仮説を立てる。
3. test-investigator：再現テストを作り、仮説を反証する。
4. team lead：三者の証拠を突き合わせ、修正担当へ一つの根本原因を渡す。

Subagentsでも三調査を並行化できる。Agent Teamsが効くのは、log担当が見つけた時刻をcode担当へ送り、code担当がtest担当へ具体的な入力条件を返すような、途中の相互作用が必要な場合だ。反対に、成果物が互いに独立し、最後に要約を集めるだけならSubagentsの方が軽い。

6. Agent Teamsはいつ生まれ、どこまで進化したか

Agent Teamsは長年の完成機能ではない。Claude Code 2.1.32で、2026年2月5日にresearch previewとして追加された。最初から CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が必要な、トークン消費の大きい実験機能だった。翌2月6日の2.1.33ではtmux上のteammate通信修正と、TeammateIdle・TaskCompleted hookが追加された。2月17日の2.1.45ではBedrock、Vertex、Foundry利用時に、tmuxで起動したteammateへプロバイダー環境変数が渡らない問題が修正された。2月19日の2.1.49ではSubagent側にworktree隔離と常時background実行が加わり、並列作業の安全性と観測性が底上げされた。^[12]

Agent Teamsは完成品が突然現れたのではない。伝言、共有タスク、環境継承、background実行と、協働の足場を短い周期で組み直してきた。

2026年9月時点の公式Agent Teams資料は、2.1.178以降の仕組みを説明している。初期に必要だったteamの明示作成・削除はなくなり、セッション起点で自動構成・終了時自動cleanupへ簡素化された。一方で、再開、タスク調整、終了処理には既知の制約があり、今もexperimentalかつ初期状態では無効である。^[11]

有効化はAPIキーではなく、通常のClaude Code設定で行う。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

または、そのセッションだけ環境変数を付ける。

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

起動後は、独立性の高い役割とファイル境界を自然言語で指定する。

Agent Teamを作ってください。
- investigator: 読み取り専用で障害ログと直近diffを調査
- test-owner: 再現テストだけを担当
- fixer: investigatorとtest-ownerの合意後に修正

同じファイルを同時編集しないこと。根拠と担当ファイルを共有タスクに残すこと。

Desktopへいつ来るかについて、公式の公開日程は確認できない。Desktopにはすでに並列セッション、subagentペイン、統合ターミナル、タスク表示があり、UIの受け皿だけを見れば将来統合は不自然ではない。しかしAgent Teamsは、独立セッションの起動、権限継承、共有タスク、相互通信、停止と再開を一体で扱う必要があり、公式資料自身がその部分の制約を認めている。したがって「時間の問題」と断言する根拠はない。将来性はあるが、現時点の設計判断ではCLI限定機能として扱うのが誠実だ。

7. 設定ファイルでリポジトリを汚さない──共有と個人設定を分ける

Subagent定義はMarkdownとYAML frontmatterで書く。配置には二つの正規ルートがある。~/.claude/agents/ はMac全体の全プロジェクト、.claude/agents/ は現在のプロジェクトだけに効く。プロジェクト側の定義が同名なら優先される。^[10]

共有設定と個人設定は、置き場所だけで役割が変わる。全プロジェクト用はホームへ、共有前の固有設定は箱の内側へ、チーム規約は見える場所へ置く。

方法1：ホームへ置き、全プロジェクトで使い回す

レビュー方針やログの読み方が個人の作業スタイルなら、最初からGitリポジトリの外へ置く。

mkdir -p ~/.claude/agents
$EDITOR ~/.claude/agents/code-reviewer.md
$EDITOR ~/.claude/agents/log-watcher.md
claude

これなら誤コミットの余地がなく、どのプロジェクトでも同じ名前で呼べる。機密のURL、個人用sandbox名、ローカルだけのコマンドは、共有 CLAUDE.md ではなく CLAUDE.local.md またはホーム側へ分離する。公式資料も CLAUDE.local.md を個人用・プロジェクト固有の場所として案内している。^[13]

方法2：プロジェクト内へ置くが、Git監視からローカル除外する

プロジェクト固有のパスやテストコマンドを含む一方、チームへ配る合意はまだない場合に向く。

mkdir -p .claude/agents
cp ~/.claude/agents/code-reviewer.md .claude/agents/

printf '\n/.claude/agents/\n/CLAUDE.local.md\n' >> .git/info/exclude
git check-ignore -v .claude/agents/code-reviewer.md CLAUDE.local.md
git status --short

.git/info/exclude は、そのリポジトリだけに効き、通常はコミットされない。複数リポジトリで毎回同じ除外を使うならglobal ignoreへ移す。

touch ~/.gitignore_global
printf '\n**/.claude/agents/\n**/CLAUDE.local.md\n' >> ~/.gitignore_global
git config --global core.excludesFile ~/.gitignore_global
git check-ignore -v .claude/agents/code-reviewer.md

Git公式資料は、チーム共有の生成物を .gitignore、一つのリポジトリだけの個人用ファイルを .git/info/exclude、全リポジトリ共通の個人用パターンを core.excludesFile に置く、と使い分けている。なおignoreは未追跡ファイルにしか効かない。すでに追跡済みなら、まず git ls-files .claude CLAUDE.local.md で確認し、チームと合意して追跡解除する必要がある。勝手に git rm --cached しない。^[14]

CLAUDE.mdは別である。ビルド、テスト、設計規約のように全員が守る内容は、むしろコミットしてレビューすべきだ。個人の好みだけを除外する。共有すべきルールまで隠すと、他のメンバーやCIのエージェントが同じ判断を再現できない。

8. コピペで使える二つのSubagent──権限を役割に合わせる

最初の一体は、書かないreviewerがよい。~/.claude/agents/code-reviewer.md に保存する。

---
name: code-reviewer
description: 変更後のコードを読み取り専用でレビューし、重大度順に指摘する。実装は変更しない。
tools: Read, Grep, Glob
model: sonnet
---

あなたはシニアコードレビュアーです。

指定された変更と周辺コードだけを調べ、次の順で報告してください。
1. セキュリティ、データ損失、認証・認可の欠陥
2. 実行時バグ、競合状態、境界値の欠落
3. テスト不足と保守性

各指摘には、ファイル名、行、再現条件、最小の修正方針を付けます。
証拠のない推測は「要確認」と明記します。
ファイルを作成・編集せず、コミットやpushも実行しません。
問題がなければ「重大な指摘なし」と明記します。

二体目は、観測だけを続けるlog watcherである。~/.claude/agents/log-watcher.md に保存する。

---
name: log-watcher
description: ローカルのDocker・アプリログを監視し、新しい異常と根拠だけを要約する。修正や再起動はしない。
tools: Bash, Read, Grep, Glob
disallowedTools: Write, Edit
permissionMode: plan
model: sonnet
background: true
---

あなたは読み取り専用のログ監視担当です。

開始時に対象サービス、監視時間、正常の基準を確認します。
ログは --since、--tail、grep、jqなどで必要範囲だけ読みます。
既知の反復行はまとめ、最初の異常時刻、直前の関連イベント、
原因仮説、次に人間が実行すべき確認コマンドを報告します。

ソース、設定、DB、コンテナを変更しません。
サービスの起動・停止・再起動、kill、デプロイ、commit、pushをしません。
異常がなければ、観測範囲と「新規異常なし」だけを返します。

disallowedToolsでWriteとEditを外しても、Bashには書き込み可能なコマンドが存在する。そこで permissionMode: plan と明示的な禁止指示を重ねる。さらに本当に壊せないことが必要なら、監視専用ユーザー、読み取り専用Docker socket proxy、CloudWatchのread-only IAM権限など、OS・クラウド側でも制約する。プロンプトは安全境界の一層であって、権限管理そのものではない。

定義を保存したら、次のように使う。

code-reviewerを使ってsrc/authの変更をレビューして。
log-watcherをバックグラウンドで起動し、apiを15分監視して。

Subagentの description は自動委任の判断に使われ、全定義の説明文は起動時コンテキストへ入る。公式資料は合計15,000トークンを超えると警告するとしている。長い手順は本文へ、descriptionは「いつ使うか」だけへ絞るのがよい。^[10]

9. まとめ：片方への忠誠ではなく、制御面と作業面を分ける

Claude Desktopは、画像、PDF、Artifacts、diff、プレビュー、複数セッションを視覚的に扱う仕事に強い。Subagentsも使える。CLIは、標準入力・標準出力、DockerやGitとのパイプ、現在のシェル環境、スクリプト・CIへの組み込み、そして現時点でDesktopにはないAgent Teamsに強い。

実務では、Desktopを「目で判断する制御面」、CLIを「OSとエージェントをつなぐ作業面」として併用すると自然である。片方だけなら、次の問いで決めればよい。

• 画像・PDF・実画面・diffを何度も比較するならDesktop。
• ログ、Git差分、JSONをパイプで絞って解析するならCLI。
• 独立した調査を隔離するだけなら、DesktopでもCLIでもSubagents。
• 担当者同士が途中で情報を渡し、共有タスクを自律的に進めるならCLIのAgent Teams。
• 同じファイルを順番に直す小仕事なら、どちらでも一つのセッション。

AI開発ツールの選択は、キーボード派かマウス派かという性格診断ではない。どのデータを、どの権限で、何人のエージェントへ、どの通信構造で流すかというシステム設計である。

Desktopの便利さを知っている人ほど、CLIの配管とAgent Teamsを理解すると仕事の分け方が変わる。CLIを使い込んでいる人ほど、Desktopの視覚レビューとSubagentsを理解すると、ターミナルへ押し込める必要のない仕事が見える。両方の特性を知ったうえで選ぶなら、今日は片方しか開かなくても、その選択には理由がある。