Claude Codeのマルチエージェント組織は、大きな変更をしていなくても静かに腐敗が進む。本記事では、誤ったディレクトリでの起動によってCLAUDE.mdが意図せず増殖したケースと、参照元が切れたまま誰にも呼ばれなくなったPlaybookというケースを実例で記録する。いずれも「問題を起こそうとして行った操作」ではない。日常的な操作ミス1つ、更新漏れ1本——それだけで腐敗は積み上がる。発見の動機が外部から来ない種類の腐敗をどう検出するかが、この記事のテーマだ。

この記事はマルチエージェント組織シリーズの後編。前編では「244ファイル移動という大手術の後に腐敗が見つかった」という話を書いた。

前編: Claude Codeのマルチエージェント組織は「作ったら腐る」——244ファイル整理後の健康診断全記録

前編の腐敗は「大手術がトリガー」だった。今回は違う。何か大きなことをしたわけではないのに、腐敗は静かに始まっていた。

腐敗パターン1: 変なディレクトリで起動したら、CLAUDE.mdが生まれた

2026年4月13日、devops/CEOエージェントが組織健全性点検レポートを提出してきた。レポートの結論は「全体的に健全」だった（content/reports/research/2026-04-13_org-health-check.md）。

ただし、そのレポートのきっかけとなったのは別の問題だった。

CLAUDE.mdが3つ、意図せず増殖していた。

workspaces/writer/CLAUDE.md
workspaces/secretary/CLAUDE.md
workspaces/resarcher/CLAUDE.md

これらは私が意図して作ったファイルではない。作業中に誤ったディレクトリでClaude Codeを起動した際に、Claude Codeが自動生成して残したファイルだ。git log で辿ると、ルートの CLAUDE.md が先に存在し、これらのワークスペース配下のファイルはコミット 6f3057fe（2026-04-07）でリポジトリに取り込まれている。そして重複ルールを整理するコミット 171f2d4（2026-04-12）で対応するまでの間、古いルールを抱えたまま存在し続けた。

問題はこのファイルが「古いルールを持ったまま生き残っていた」ことだ。

具体的には次の3つのルールが、4箇所（ルート CLAUDE.md + ワークスペース3つ）に重複していた。

日本語で応答する
パスは相対パスで記述する
成果物に引き継ぎヘッダーを付ける

これらは後から global-rules.md に集約されたルールだ。集約後もワークスペースのファイルには古い記述がそのまま残っていた。

私はこの状態を知らなかった。

devops/CEOエージェントがスキャンして初めて検出した。健全性点検レポートに記載されたのは「ルールファイル間の矛盾: ◯（矛盾なし）」だが、重複の整理は別途コミットで対応した。コミット 171f2d4 の変更内容を確認すると、5ファイルの変更で7行追加・23行削除。そのコミットメッセージはこう書いてある。

refactor: 日本語応答・パス記述・引き継ぎヘッダーの重複をglobal-rulesに一本化

CLAUDE.md・ワークスペース3つ・agents/writer.mdから
global-rules.mdと重複するルール記述を削除。
各ファイルはエージェント固有の業務・出力先のみに絞った。

あわせて a567fa1 のコミットでは、エージェント名のスペルミス resarcher を researcher に修正している。ディレクトリ名・エージェント定義・各種参照ファイル合計15ファイルに渡る修正だ。このスペルミスがいつから存在していたか、私は把握していなかった。

腐敗に事件は要らない。変なディレクトリでうっかり起動しただけで、意図しないファイルが生まれ、古いルールが増殖する。

腐敗パターン2: 書いたPlaybookが、誰にも呼ばれていなかった

もう1つのパターンはさらに静かだ。

あるとき、cowork-mining-rules.md というPlaybookを書き換えようとした。その瞬間、ユーザーから問いが来た。

「このルール、いつトリガーされるの？」

調べると、global-rules.md からの参照がすでに削除されていた。session-idea-mining.md に参照が残っていたが、そのセクション自体が機能していない状態だった。つまり cowork-mining-rules.md はどこからも呼ばれていない孤立したPlaybookになっていた。

私は「削除しますか？」と提案した。

ユーザーの返答はこうだった。「正しく呼ばれるようにしたい」

この違いは大きい。削除は現状の否定だが、再接続は機能の回復だ。削除してしまうとCoWorkが再び活用されるときにゼロから書き直しになる。ユーザーの意図は「使わないから消す」ではなく「正しく機能させる」だった。

対応として session-idea-mining.md のCoWorkセクションをClaude Code/Chat向けに書き直し、global-rules.md に参照を復活させた。

なぜPlaybookは孤立するのか

Playbookを書くとき、人は「何をするか」を書く。そこで止まる。「いつ・誰から・どのルールを経由して呼ばれるか」を書かない。

参照元がないPlaybookは技術的には存在するが、機能的には存在しない。棚に仕舞われたマニュアルと同じだ。丁寧に書かれているほど「参照されているはず」という思い込みが強くなり、孤立に気づきにくい。

コミット b2266cb（タイムゾーン説明の global-rules.md への一本化）も同じ構造だ。2ファイルで重複していたルールを1箇所に集約するとき、参照元が正しく更新されていないと集約後のルールが到達しなくなる。

2つのパターンに共通する構造

前編の腐敗は「大手術がトリガーで発見した」。今回の2パターンは、どちらも**「日常的な操作」がトリガーで腐敗が始まった**。

パターン	発生原因	検出方法
前編（8件の不整合）	244ファイル移動後の整合崩れ	大手術のついでの健康診断
パターン1（CLAUDE.md増殖）	誤ったディレクトリでの起動	devops/CEOの定期スキャン
パターン2（Playbook孤立）	参照元の削除時に更新漏れ	ユーザーからの問い

前編の8件は「大手術の後」という文脈があったから点検しようという動機が生まれた。今回の2パターンは、その動機すら生まれないところで腐敗した。

「何もしていないのに」 というのは正確には正しくない。何かをしている——ただし、腐敗を意図していない。誤ったディレクトリで起動することも、Playbookの参照元を更新し忘れることも、どちらも「問題を起こそうとして行った操作」ではない。腐敗は意図しない操作の副産物として積み上がる。

検出の仕組みがなければ、腐敗は見えない

前編での8件は「ディレクトリ整理のついで」という偶然の文脈で発見した。CLAUDE.mdの増殖は devops/CEO の定期スキャンで発見した。Playbookの孤立はユーザーの「いつトリガーされるの？」という問いで発見した。

3パターンの発見、どれも「意図的に検出しようとした」わけではなかった。

これが問題の本質だ。腐敗は静かに進む。動いているように見える間は誰も気づかない。発見は偶然に依存している。

対策として考えているのは2点だ。

1. 構造変更（ディレクトリ追加・Playbook新規作成）を行うとき、参照元をセットで確認する

新しいPlaybookを作るとき、「何をするか」だけでなく「どのルールファイルから参照されるか」を同時に決める。参照元がなければ、完成した瞬間に孤立する。

既存のPlaybookが孤立していないかを確認するには、各PlaybookファイルのファイルパスをPlaybook群の外から grep で検索し、参照ゼロのファイルを洗い出す手順が有効だ。参照されているはずという思い込みを外部から崩すのが目的で、結果に驚くことになる。

CLAUDE.mdの意図しない増殖を確認するには、リポジトリ内に存在するすべてのCLAUDE.mdを一覧し、ルート以外のパスで想定外の場所にファイルがないかを確認する。私の場合は、それまで存在を認識していなかったワークスペース配下の3ファイルがこの方法で可視化された。

2. 健全性点検を「大手術のついで」に設計する

前編で学んだ教訓の再確認でもある。定期点検のスケジュールを決めると「今は他の作業が優先」になりがちだ。しかし構造変更・エージェント追加・スクリプト移動は、すでに全体を見渡すコンテキストが揃っている。その流れで健康診断を行うのが最も自然に機能する。

腐敗に事件は要らない

前編と後編を並べると、腐敗には2つの起点があることが分かる。

大手術のついでに発見する腐敗（前編）: 事件があるから気づく機会が生まれる
日常運用が積み上げていく腐敗（後編）: 事件がないから気づく機会が生まれない

後者の方が深刻だ。発見の動機が外部から来ない。

Claude Code のマルチエージェント組織を運用していると、Playbookは増え続ける。CLAUDE.mdへの記述は積み上がる。エージェントは追加される。そのたびに参照関係が更新されない可能性が生まれ、意図しないファイルが生まれる可能性が生まれる。

腐敗に事件は要らない。組織が存在するだけで、日常的に腐敗は始まる。だから、発見の仕組みを意図して設計する必要がある。

まず一歩を踏むとすれば、自分のリポジトリにあるすべてのCLAUDE.mdの場所を確認することだ。意図していないパスにファイルがあれば、それが現在の腐敗の起点になっている可能性が高い。次に、直近で書いたPlaybookを1本取り出して「このファイル名は他のルールファイルから参照されているか」を確認してみる。参照元がなければ孤立している。この2つの確認は、大がかりな点検の前の準備体操として、今すぐ実行できる。

この記事で扱ったマルチエージェント組織の設計・運用の全体像——役割定義の仕方、権限設計の考え方、Playbookの管理方法——は Zenn Books にまとめている。いずれも序章は無料で読める。

コードを書けない私がClaude Codeで「AIチーム」を作るまで（¥900 / 序章・第1部無料）
コードを書けない私がClaude Codeで「AIチーム」を回すまで（¥900 / 序章無料）

Claude Code でマルチエージェント運用を試みたい方には、実践的な入門書が出ている。組織設計の前に基礎的な使い方を固めておくと、エージェント間の権限設計や Playbook の書き方が整理しやすくなる。

Claude CodeによるAI駆動開発入門（平川知秀著）
実践Claude Code入門（西見公宏・吉田真吾・大嶋勇樹著）

この記事ははてなブログからのクロスポストです。