Claude Codeのマルチエージェント組織は、大きな変更をしていなくても静かに腐敗が進む。本記事では、誤ったディレクトリでの起動によってCLAUDE.mdが意図せず増殖したケースと、参照元が切れたまま誰にも呼ばれなくなったPlaybookというケースを実例で記録する。いずれも「問題を起こそうとして行った操作」ではない。日常的な操作ミス1つ、更新漏れ1本——それだけで腐敗は積み上がる。発見の動機が外部から来ない種類の腐敗をどう検出するかが、この記事のテーマだ。
この記事はマルチエージェント組織シリーズの後編。前編では「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入門（西見 公宏・吉田 真吾・大嶋 勇樹 著）
この記事は はてなブログ からのクロスポストです。