CLAUDE.mdのガイダンスの大多数は、一度に1つのプロジェクトに取り組むソロ開発者向けに書かれている。エージェンシーの仕事は異なる。クライアント・プロジェクトのポートフォリオがあり、それぞれが独自の慣例を持っており、同じエンジニアが1週間で6つのプロジェクトに携わるかもしれない。ソロ開発者向けに機能するCLAUDE.md戦略はエージェンシー規模では失敗する。これはSeahawk Mediaで200以上のアクティブなクライアント・リポジトリにわたって18ヶ月の反復を経て確立した実装アプローチである。
重要なポイント: エージェンシー規模のCLAUDE.mdには3つのレイヤーが必要です。エージェンシー全体の基準、クライアント固有のオーバーライド、そしてエンゲージメント単位での注記です。これにより、1人のエンジニアが6つのリポジトリを横断する際に、適切なコンテキストを持ちながら動くことができます。CLAUDE.md at agency scale needs three layers, agency-wide standards, client overrides, and per-engagement notes, so one engineer can move across six repos with the right context.
Claude Codeを毎日使用するエージェンシーを運営していて、エンジニアがプロジェクト全体で大きく異なる出力を得ていることに気づいている場合、このポストは構造的な解決策だ。
ソロ開発向けCLAUDE.mdのアドバイスがなぜエージェンシー規模で崩壊するのか
標準的なCLAUDE.mdのアドバイスはこうだ。一度書いて、プロジェクト用に最適化して、500行以下に収める。プロジェクトが1つのときはそれで機能する。クライアント・リポジトリが50個あるとき、3つの問題が生じる。同じエンジニアがどの慣例がどのクライアントに適用されるかを覚えられない。プロジェクトにオンボーディングする新しいエンジニアは50個の異なるCLAUDE.mdファイルに直面する。エンジニアが1つのプロジェクトを更新して他のプロジェクトを忘れるにつれて、CLAUDE.mdの内容は漂流する。
エージェンシー規模でこれを解決するには層状アプローチが必要だ。1つの場所にエージェンシー全体の標準があり、別の場所にクライアント固有のオーバーライドがあり、3番目の場所に案件ごとのコンテキストがある。層は複製ではなく積層する。
3層のCLAUDE.mdモデル
レイヤー1：エージェンシー全体の標準
単一のCLAUDE.mdテンプレートは、当社エージェンシーのプライベートGitHubリポジトリに存在します。対象言語全体のコードスタイル、禁止パターン、テスト規約、セキュリティ標準、英国綴りの編集ルール、デプロイメントのデフォルト設定をカバーしています。このファイルはおよそ400行で、1年に数回変更されます。
新しいクライアントプロジェクトはすべて、このファイルをシンボリックリンクするか、またはコピーすることで始まります。エージェンシー全体ファイルへの変更は、四半期ごとのレビューサイクルでプロジェクトに取り込まれます。エンジニアは、どのプロジェクトを開いても、これらの規約が同じであることに依存できます。
レイヤー2：クライアント固有のCLAUDE.md
各クライアントリポジトリには、エージェンシー全体のものをインポートしクライアント固有の情報を追加した独自のCLAUDE.mdがあります。対象スタック、ホスティング、プラグイン、チーム規約、編集音声、禁止プラグインがそれぞれ記載されます。このファイルは通常100～200行で、クライアント契約の性質が変わる際に変更されます。
上部に単純なインクルード指示を使用しています。「## Agency standards」とエージェンシー全体ファイルへのリンク、その後「## Client-specific」とオーバーライドを記載します。Claudeはどちらもプロジェクトツリーに存在するため、両方を読みます。
レイヤー3：各契約固有の注記
特定の期間限定コンテキスト：現在のスプリント目標、実施中のディスカバリー結果、最近の決定ログ、オープン質問リスト。CLAUDE_NOTES.mdまたは同様の形式で存在し、契約期間中は毎週更新され、契約終了時にアーカイブされます。
これはほとんどのエージェンシーがCLAUDE.mdのメンテナンスで失敗する場所です。最初の2層は整理されたままですが、3層目は漂流して陳腐化します。我々はこれを金曜午後のレビューサイクルで解決しています。各エンジニアが自分の活動中のCLAUDE_NOTES.mdをレビューし、更新するかアーカイブするかの判断をします。
複合する禁止パターンリスト
当社エージェンシー全体のCLAUDE.mdにおける単一最高レバレッジ要素は、禁止パターンリストです。20項目、四半期ごとにリフレッシュされます。現在のリストからの例：
出荷するいかなる言語でもeval()を使用しない。
WordPressでquery_posts()を使用しない（代わりにWP_Queryを使用）。WordPress (use WP_Query instead).
TypeScriptで明示的な「// suppressed: <reason>」コメントなしに「any」を使用しない。
いかなるコンテキストでもdocument.write()を使用しない。
ブランチを問わず、秘密をgitにコミットしない。絶対に。
クライアント向けコピーでemダッシュを使用しない（AI検出回避のための運用標準）。
バグ修正のためにSupabaseテーブルのRLSを無効化しない。Supabase tables to fix a bug.
mainに直接プッシュしない（常にPRを使用）。
既存のファイルが編集可能な場合は、新しいファイルを作成しないこと。
このリストは複合的に増えていく。エンジニアがこれらのルールの1つを破るたびに、ルールを追加する。Claudeは毎セッション禁止パターンリストを読み込み、それに違反するコード生成を拒否する。以前ステージング環境に送っていたバグのクラスは消滅した。
CLAUDE.mdから除外すべきこと
エージェンシーのCLAUDE.mdファイルに明確に含めない5つのもの：
プロジェクトステータスアップデート。すぐに古くなるので、LinearやNotionに置くべき。
長い設計理論。設計ドキュメントに属するもの。CLAUDE.mdはそれを参照すべきであり、複製してはいけない。
クライアント側のシークレット、認証情報、または機密情報。プライベートなCLAUDE.mdファイルでさえ、漏洩リスクが高すぎる。
個々のエンジニアの個人的好み。標準はエージェンシー全体のものであるべき。エンジニア固有の好みは、各自の.claude/settings.jsonに置くべき。
マーケティングコピーやセールス言語。CLAUDE.mdはエンジニアリングコンテキスト。シニアエンジニアが他のエンジニアのために書いたように読めるべき。
CLAUDE.mdが採用構造をどう変えるか
クライアントポートフォリオ全体でデリバリできるシニアエンジニアで、訪問するたびにプロジェクトを再学習する必要がないエンジニアは、そうでないエンジニアより圧倒的に価値が高い。3層のCLAUDE.mdシステムがそれを可能にしている。新しいエンジニアのオンボーディング時間は、慣例が部族的なものではなくコード化されたものになったため、プロジェクト固有のランプアップに約2週間かかっていたのが3日に短縮された。
同じエンジニアで、より多くのアウトプット、より少ないオンボーディングコスト、より少ないコンテキストスイッチのオーバーヘッド。このシステムが導入されるとジュニアエンジニアの採用は減り、シニアエンジニアの採用が増えた。なぜなら、ジュニアエンジニアはもはや、以前は慣例を移す唯一の方法だったプロジェクト固有のコンテキストを吸収する必要がなくなったからだ。
まとめ
エージェンシー規模のCLAUDE.mdは階層化されたシステムだ。ベースはエージェンシー全体の標準、中間層はクライアント固有のオーバーライド、最上位層はエンゲージメント単位の注記。禁止パターンリストが最もレバレッジの高いセクションだ。金曜日のレビュー頻度でエンゲージメント単位の層の古いコンテンツを避ける。
3層モデルを実装すれば、エンジニアはポートフォリオ全体で一貫性のないアウトプットのデリバリをやめる。スキップすれば、エンジニアが最後に開いたプロジェクトによって異なる成果物を生み出すAIアシスタンスに対して対価を支払っていることになる。
よくある質問
CLAUDE.mdファイルとは何ですか？
CLAUDE.mdはプロジェクトファイルで、Claude Codeに対して標準、スタック、規約を伝え、出力がコードベースに合致するようにするものです。エージェンシー規模では、プロジェクトごとの単一フラットファイルでは不足するため、複数クライアントリポジトリにわたる3層モデルを採用しています。
複数クライアントプロジェクトにわたってCLAUDE.mdをスケールさせるにはどうするのですか？
3層モデルで対応します。すべての場所に適用されるエージェンシー全体の標準、アカウントごとのクライアント固有のオーバーライド、特定プロジェクトのエンゲージメント単位のメモです。同じエンジニアが週に6つのクライアントリポジトリを行き来しても、各自で正しいコンテキストを持ち、書き直す必要がありません。
CLAUDE.mdに何を含めるべきではありませんか？
シークレット、頻繁に変更される内容、重要なルールを薄める雑音です。耐久的な標準と規約に留めてください。詰め込みすぎたCLAUDE.mdは無視されます。禁止パターンを明確に述べた、きちんと階層化された短いファイルこそが、実際に出力を変えるものです。
CLAUDE.mdは採用方法を変えますか？
オンボーディングコストを下げます。標準が階層化されたCLAUDE.mdに存在すれば、新しいエンジニアはツールを通じてエージェンシーの規約を継承でき、数ヶ月の暗黙知を習得する必要がありません。採用が社内スタイルの記憶から判断力へとシフトします。