はじめに
Claude Code でプロジェクトを増やしていくと、気づいたときには同じようなエージェント定義が複数のプロジェクトに散在している。「コードを書くエージェント」「ウェブサイトを作るエージェント」——プロジェクトごとに微妙に違うバージョンが乱立し、片方を改良してももう片方には反映されない状態が続く。
八雲は現在、Synapse（内部基盤）・montage（動画生成プロダクト）・medallion（財務データ処理）という3つの内部プロジェクトを Claude Code で並走させている。それぞれが固有のエージェント群を持ちながら、共通の能力は1箇所に集約する設計に落ち着いた。この記事ではその構造と、運用してわかった知見を整理する。
課題: プロジェクトごとに微妙に違う定義が増殖する
プロジェクト単位でエージェント定義を作ると、次のような問題が起きやすい。
コピーが増殖する。 「Synapse で使っている system-developer エージェントをmontage でも使いたい」となったとき、定義ファイルをコピーして持ち込む。最初は同じだが、それぞれ独立して改良されていくため、数ヶ月後には別物になっている。
改善が届かない。 system-developer の動作に問題を見つけて修正しても、コピーを持つプロジェクト全てに手動で反映しなければならない。反映し忘れが積み重なると、プロジェクト間で品質にばらつきが出る。
どれが最新か分からなくなる。 「このエージェントの最新版はどこか」という問いに答えられなくなる。各プロジェクトが「うちのが最新」と思いながら独自進化している状態だ。
アプローチ: グローバル定義 + プロジェクトローカルの2層
Claude Code は ~/.claude/agents/ にユーザー全体で共有されるグローバルなエージェント定義を置ける。この仕組みを活用して、再利用すべき能力はグローバルに集約し、プロジェクト固有のものだけをローカルに置く2層構造を採用した。
現在の構成を示す。
グローバル定義（~/.claude/agents/）:
system-developer/— 仕様駆動・テスト駆動でシステムを実装する汎用エージェントweb-developer/— ウェブサイト制作を一貫して担うエージェント（調査・設計・実装・レビュー）
Synapse ローカル（.claude/agents/）:
director.md— 事業責任者。全体P/L・パイプライン統括dev-director.md— 開発責任者。Drive・GitHub横断の進捗管理sales-director.md— 営業責任者。クラウドソーシング案件の処理lead-reviewer.md— リードレビュー専用（最大9並列）
montage ローカル（.claude/agents/）:
producer.md— パイプライン config を読んで実行計画を構築するアドバイザcomposer.md— データから動画シーン構成（VideoSpec）を設計researcher.md/analyst.md/scriptwriter.md/copywriter.md— 動画制作の各役割reviewer.md/improver.md/curator.md/thumbnailer.md— 品質管理・公開フロー
この分け方には明確な基準がある。「プロジェクトが変わっても能力の定義が変わらないもの」はグローバルに置く。「このプロジェクトの業務文脈・役割・指示体系を持つもの」はローカルに置く。
共通化すべきもの・固有化すべきもの
実際に運用してみると、共通化の境界は「ツールの使い方」ではなく「業務文脈を持つかどうか」で引くのが自然だとわかった。
グローバルに置くべきもの:
仕様駆動でコードを書く能力（system-developer）やウェブサイトを作る能力（web-developer）は、どのプロジェクトでも「同じ能力」を必要とする。改善すれば全プロジェクトで恩恵を受けられる。スキルの定義（dev-plan・dev-test・dev-impl・web-build 等）も同様で、~/.claude/skills/ に集約している。
グローバルエージェントが持つスキルリストも AGENT.md の frontmatter に宣言されており、呼び出し側がそのエージェントを起動するだけで、関連する全スキルが使えるようになる。
プロジェクトローカルに置くべきもの:
Synapse の director エージェントは「八雲という会社の営業と開発を束ねる」役割を持つ。montage の producer エージェントは「動画制作パイプラインのconfig を読んで計画を立てる」役割を持つ。これらは業務文脈が分かちがたく結びついており、共通化しようとすると逆に抽象度が上がりすぎて使いにくくなる。
CLAUDE.md に書いた実行ルート規約（@sales-director / @dev-director / @director の使い分け）も Synapse 固有の設計だ。montage には montage の指示体系がある。これらをグローバル化する意味はない。
バージョン管理と更新の同期
グローバル定義は ~/.claude/ 以下にあるが、このディレクトリ自体を git リポジトリで管理している。変更したら手元でコミットする。
実用上の同期問題はほとんどない。グローバル定義を変更した場合、全プロジェクトで即座に反映されるためだ。「コピーして持ち込む」方式と違い、参照先が1箇所なので同期ずれが原理的に起きない。
プロジェクトローカルのエージェントがグローバルエージェントを呼び出す場合（Synapse の dev-director が system-developer に委任するパターン等）は、CLAUDE.md に「開発系タスクは system-developer に委任する」と明記することで、ローカルとグローバルの接合点を文書化している。
更新の判断基準も明確にしている。「この変更はどのプロジェクトでも望ましいか」 という問いに Yes なら グローバルを更新し、No（このプロジェクト固有の事情がある）ならローカルを更新する。
運用してわかった効果と落とし穴
効果として実感したこと:
system-developer の改善（スキルの追加・手順の洗練）が Synapse でも montage でも即座に効く。以前は「Synapse の system-developer を直した」「montage には反映し忘れた」という事故が月に数回あったが、グローバル集約後はゼロになった。
新規プロジェクトの立ち上げ速度が上がった。プロジェクトディレクトリに CLAUDE.md と必要なローカルエージェント定義だけ置けば、system-developer・web-developer という共通能力は最初から使える状態になる。
落とし穴として気づいたこと:
グローバルエージェントに「このプロジェクトでしか使わない前提条件」を書き込んでしまうミスが初期にあった。Synapse 専用の環境変数設定手順を system-developer の AGENT.md に書いたところ、他のプロジェクトで呼び出したときに混乱が生じた。グローバルエージェントには「どのプロジェクトでも成立する記述だけ」を書くことを徹底している。
また、ローカルエージェントが暗黙的にグローバルエージェントの存在を前提にしている場合、その依存を文書化しておかないと、後から設計を把握しようとした人が混乱する。CLAUDE.md の「実行ルート」セクションに依存を明示しているのはこのためだ。
まとめ
プロジェクト間でのエージェント再利用は「グローバル定義とプロジェクトローカルの2層に分ける」という単純な原則で整理できる。分岐点は 業務文脈を持つかどうか だ。汎用的な能力はグローバルに集約し、プロジェクト固有の役割・指示体系はローカルに置く。
この設計の恩恵は、複数プロジェクトを並走させるほど大きくなる。改善が全体に届き、新規プロジェクトの立ち上げコストが下がる。Claude Code を1つのプロジェクトに閉じて使うのではなく、組織全体の能力として育てるための構造だ。
関連記事
このシリーズで取り上げてきたパターンを横断的に参照したい場合は以下を参照。
- Claude Code 新規プロジェクト onboarding — CLAUDE.md・specs・.claude/ の構成パターン — 個別プロジェクトの構成起点
- 領域責任者エージェントパターン — Claude Code を組織化する — エージェント委任チェーンの設計
- スキルファースト設計 — エージェントではなく Claude Code スキルとして実装する — エージェントとスキルの境界判断
- system-developer パターン — 実装を外部エージェントに委任する — 開発専門エージェントへの委任設計