Claude Code v1.5.0で並列開発が安定した理由。権限設定の二重化が開発を加速させる

バックグラウンドエージェントが黙って止まってた話

Claude Code v1.5.0がリリースされた。

並列エージェントを使っている開発者にとっては大きなアップデートだ。

v1.4.0で導入されたworktree分離による並列開発。複数のエージェントを同時に走らせる設計だった。

実際には2つ目のエージェントが必ず失敗するバグがあった。

「Already in a worktree session」。このエラーに遭遇した開発者は多い。

v1.5.0でこの問題は修正された。修正の過程で、権限設定の二重化という設計上の事実が浮き彫りになった。

Claude Code v1.5.0で何が変わったか

並列エージェントの競合バグが修正された

v1.4.0では「EnterWorktree」という仕組みが使われていた。複数のエージェントが独立したGit worktreeで作業する設計だ。

2つのエージェントが同時にEnterWorktreeを呼び出すと、2つ目がエラーで落ちる。1つ目がセッションを掴んだまま離さないからだ。

v1.5.0ではAgentツールの「isolation: worktree」パラメータを使う設計に切り替わった。

このパラメータを指定すると、ランタイムが自動的に専用のGit worktreeを生成する。エージェントごとに独立したworktreeが割り当てられるため、競合は起きない。

修正したら今度は「サイレント失敗」が起きた

「isolation: worktree」に切り替えたエージェントは、ファイル書き込みやgitコマンドの実行で承認待ちが発生する。

バックグラウンドエージェントのため、承認ダイアログに気づくことはない。エージェントはただ待ち続ける。

原因は仕様だ。isolation: worktreeモードのエージェントは、プロジェクトの「settings.json」を読まない。

読むのは「.claude/settings.local.json」だけだ。

しんたろー：
v1.4.0のリリースノートを見て並列開発を試したとき、2つ目のエージェントが毎回コケる現象に悩まされた。設定が悪いのかと小一時間試行錯誤した。v1.5.0で根本的な使い方の違いが判明したのは驚きだ。

開発者として「これは何が起きてるか」を整理する

権限設定の二重化という現実

「settings.json」と「settings.local.json」。2つのファイルは別々の役割を持つ。

settings.jsonはリポジトリにコミットできる。チームで共有する設定をここに書く。

settings.local.jsonは通常gitignoreされる。マシン固有のパスや、worktreeエージェントが使う権限設定がここに入る。

この2つは独立して管理される。settings.jsonに書いた権限設定は、worktreeエージェントには効かない。同じ内容をsettings.local.jsonにも書く必要がある。

v1.5.0ではセットアップスクリプトが同梱された。setup.sh（またはsetup.ps1）を実行することで、settings.local.jsonを正しく生成・同期できる。

Claude Codeは「マルチエージェント・オーケストレーション環境」になっている

Claude Codeをチャットツールとして使う分には、この複雑さは関係ない。コード生成や修正を1つのコンテキストで完結させるなら、settings.jsonだけで管理できる。

並列エージェントを使い始めた瞬間に話が変わる。

メインの会話コンテキストと、worktreeエージェントのコンテキストは完全に分離される。

それぞれに適用される権限設定と、バックグラウンド実行中の承認待ち検知の仕組みを管理する必要がある。

SkillsとSub-agentsの使い分けが設計の核になる

Skillsはマクロに近い。スラッシュコマンドで呼び出すと、専門的な指示がメインの会話コンテキストに注入される。

Sub-agentsはワーカーだ。独立したコンテキストウィンドウで動く。メインの会話履歴は見えない。

並列実行できるのはSub-agentsの強みだ。コードベースの探索、テストの実行、レビューを3つのエージェントが同時に走らせられる。

しんたろー：
バックグラウンドでテストを実行させている間に別の機能を書く、といった使い方が現実的になった。ただ、settings.local.jsonの同期管理が増えるのは懸念点だ。セットアップスクリプトを整備しないと、ローカル環境が壊れたときに原因特定に時間がかかる。

実務への影響。今すぐ確認しておきたいこと

1. 現在の権限設定がworktreeで効いているか確認する

プロジェクトの「.claude/」ディレクトリに「settings.local.json」があるか確認する。なければ、worktreeエージェントは権限ゼロで動いている。

settings.jsonに書いてある許可ルールを、settings.local.jsonにも同じ内容で記述する。これをやらないとworktreeエージェントがサイレントに止まる。

2. 承認待ちを検知する通知の仕組みを入れる

バックグラウンドで動いているエージェントが承認を求めても、画面を見ていなければ気づかない。気づいたら30分止まっていた、という事態が発生する。

Claude Codeには「hooks」という仕組みがある。「Notification hook」を使うと、承認待ち（permission_prompt）が発生したときだけスクリプトを走らせる設定が可能だ。

スマートフォンへのプッシュ通知が実用的だ。画面のフォーカスを奪わず、手元に通知が届く。

3. SkillsとSub-agentsの使い分けを設計段階で決める

設計段階でどちらを使うか決めておく。

直前の会話内容や設計方針を共有しながら作業させたい場合はSkillsを使う。

コードベース探索やテスト実行を並列で行う場合はSub-agents（isolation: worktree）を使う。

両方のメリットが欲しい場合は、Skillsのフロントマターで「context: fork」を指定する。

4. settings.local.jsonをgitignoreに入れる運用を確認する

settings.local.jsonはマシン固有の設定を含むため、通常gitignoreに入れる。

チーム開発では、新しいメンバーがリポジトリをクローンしてもsettings.local.jsonは存在しない。セットアップ手順にsettings.local.jsonの生成ステップを入れておく。

しんたろー：
「動くはずなのに動かない」の原因が権限設定の同期漏れというのはデバッグ体験として厳しい。ログを見ても「承認待ち」としか書いていない。通知の仕組みを先に入れておくのと、設定ファイルのセットアップを自動化しておくのは必須だ。

よくある質問

Q1. Claude Codeで並列エージェントを動かすと、なぜ権限エラーが頻発するのですか？

原因はisolation: worktreeモードの権限読み込み仕様にある。通常の「settings.json」はworktreeエージェントに適用されない。worktreeエージェントが読むのは「.claude/settings.local.json」のみだ。解決策は「.claude/settings.local.json」に同じ権限設定を記述すること。Read、Write、Edit、Bash等の権限を明示的に許可する。

Q2. SkillsとSub-agents、どちらを使うべきか判断基準は？

コンテキストを共有するか、独立させるかで決まる。直前の会話内容や設計方針を踏まえて作業させたい場合はSkillsが適している。コードベースの探索やテスト実行など、メインの会話と切り離して並列処理させたいタスクにはSub-agentsが向いている。両方のメリットが必要なら、Skillsのフロントマターで「context: fork」を指定する。

Q3. バックグラウンドエージェントの承認待ちを見逃さないためのベストプラクティスは？

通知の仕組みを外部に持つのが現実解だ。Claude Codeのhooks機能で「Notification hook」の「permission_prompt」マッチャーを設定すると、承認待ちが発生したときだけスクリプトが走る。スマートフォンへのプッシュ通知が実用的だ。また、settings.jsonとsettings.local.jsonの両方に、よく使うBashコマンドの許可リストを設定し、承認の頻度自体を減らすことも重要だ。

まとめ

「並列エージェントが止まっていた」の原因は、設定ファイルの読み込み仕様の違いだった。

v1.5.0はバグを修正した。同時に、Claude Codeがチャットツールからオーケストレーション環境へと進化したことを示している。

settings.jsonとsettings.local.jsonの二重管理、承認待ちの通知設計、SkillsとSub-agentsの使い分け。これらを管理することで、並列エージェントは安定する。

👉 ThreadPostでSNS運用を自動化する