CLAUDE.md とは何で、なぜ重要ですか?

CLAUDE.md はリポジトリのルートに置かれ、Claude Code がプロジェクトでどう振る舞うかを指示する設定ファイルです。プロジェクトのアイデンティティ、コーディング標準、コマンド、ガードレールを定義します。新しいエンジニアに与えるオンボーディングドキュメントと考えてください —— 違いは Claude が毎セッションこれを読むことです。

CLAUDE.md ファイルはどのくらいの長さにすべきですか?

ルートの CLAUDE.md は 300〜500 行未満に保ちましょう。すべての行がコンテキストトークンを消費し、肥大化したファイルは Claude が重要な指示を見逃す原因になります。詳細なドキュメントは .claude/rules/ ファイル(自動読み込み)または docs/ ファイル(@imports でオンデマンド読み込み)に移動しましょう。

CLAUDE.md はコード以外のプロジェクトにも使えますか?

はい。CLAUDE.md はあらゆるワークフローで機能します —— 執筆、意思決定ブリーフ、会議メモ、運用プレイブック。Artificial Corner のようなテンプレートは、開発者だけでなくナレッジワーカー向けの CLAUDE.md の構造化方法を示しています。

.claude/rules/ と @imports の違いは何ですか?

.claude/rules/ 内のファイルはメインの CLAUDE.md と共に毎セッション自動読み込みされます —— コードスタイルやセキュリティルールなど常に有効なガイダンス向けに使いましょう。@path/to/file で参照されるファイルは関連時にオンデマンドで取り込まれます。アーキテクチャドキュメント、API リファレンス、その他状況依存のコンテキストには @imports を使いましょう。

エンタープライズチームは複数のリポジトリ間で CLAUDE.md をどう管理しますか?

3 階層アプローチを使いましょう: 組織全体の標準向けに共有ユーザーレベル ~/.claude/CLAUDE.md、プロジェクト固有のルール向けにリポジトリごとの CLAUDE.md、敏感なモジュール向けにサブディレクトリ CLAUDE.md。共有ルールを中央リポジトリに保存し、CI/CD パイプラインまたは Git サブモジュール経由で配布しましょう。

エンタープライズチーム向け CLAUDE.md ガイド: テンプレート、構造、ベストプラクティス

現在、少なくとも 12 の人気 CLAUDE.md ガイドが出回っています。Builder.io がひとつを公開しました。ClaudeFast は完全なキットを出荷しています。Dometrain、Gradually AI、scotthavird、Claude for Designers —— 誰もがテンプレートを持っています。

それらはすべて良いものです。そしてそれらはすべて、ソロ開発者とスタートアップを対象にしています。

複数のリポジトリ、コンプライアンス要件、Azure インフラ、共有 MCP サーバー、そして同じブログ記事を読んだわけではない開発者たちがいるエンタープライズチームで Claude Code を実行しているなら、それらのテンプレートは到達点ではなく出発点です。

ここにそれらが見落としていること、そしてあなたのチームが実際に必要なものを示します。

概要

CLAUDE.md は Claude Code のプロジェクト設定ファイル —— 毎セッションの最初に読むものです。コミュニティは確固たる基礎(短く保つ、アイデンティティで始める、コマンドと落とし穴を文書化する)に収束しています。しかしエンタープライズチームにはより多くが必要です: 敏感なモジュール向けのセキュリティ境界、マルチリポジトリのルール配布、MCP サーバー宣言、コンプライアンスガードレール、そしてモデルが指示を覚えることに依存しないフックベースの強制。このガイドは人気のテンプレートが正しく捉えていること、見落としていること、そして今日リポジトリにドロップできる本番エンタープライズテンプレートを提供します。

CLAUDE.md が実際に何であるか

Claude Code に初めての場合、短い要約: CLAUDE.md はリポジトリのルートにある Markdown ファイルで、Claude が毎セッションの開始時に読むものです。プロジェクトが何か、物事がどこにあるか、どのコマンドを実行するか、どのルールに従うかを Claude に伝えます。

完全なプロジェクト構造 —— CLAUDE.md、スキル、フック、ドキュメント、ローカルオーバーライド —— は The Anatomy of a Claude Code Project で取り上げました。基礎が必要なら最初にそれを読んでください。

理解すべき重要なこと: CLAUDE.md はプロンプトではありません。設定ファイルです。違いは重要です。プロンプトはワンショットです。設定はすべての相互作用、すべてのセッション、チームのすべての開発者にわたり持続します。

誰もが同意する標準構造

すべての主要なテンプレート —— Builder.io のモジュラーアプローチ、ClaudeFast のバッテリー同梱キット、scotthavird の GitHub スターター、Dometrain の .NET 中心ガイド、Gradually AI のトークン意識アプローチ —— をレビューした結果、コミュニティはいくつかの普遍的な原則に収束しています:

500 行未満に保つ。 コンテキストトークンは有限です。肥大化したファイルは性能を低下させます。
プロジェクトのアイデンティティで始める。 一文で: このシステムは何をするか?
正確なコマンドを文書化する。 ビルド、テスト、lint、デプロイ。Claude はこれらを逐語的に使用します。
落とし穴を捉える。 奇妙なもの —— 認証の特異性、禁止ファイル、回避パターン。
懸念を分離る。 重いドキュメントは .claude/rules/ または @imported ファイルに置き、メインファイルには置かない。
有機的に成長させる。 指示を繰り返している自分に気づくときにルールを追加し、事前には追加しない。

ディレクトリ構造も同様に定着しています:

project/
├── CLAUDE.md                    # ID、コマンド、ルール(短く)
├── .claude/
│   ├── settings.json            # フック、権限
│   ├── commands/                # スラッシュコマンド
│   └── rules/                   # 自動読み込みルールファイル
└── docs/                        # @import でオンデマンド

これは堅実です。Builder.io の Steve Sewell は CLAUDE.md をリーンに保つための @imports パターンを普及させました。Boris Cherny は PR コメントで @claude をタグ付けし、レビューワークフローの一部としてルールを更新する方法を示しました。ClaudeFast はそれをさらに進め、18 の事前設定エージェント定義と 20 以上のスキルモジュールを同梱しました。

すべて良い仕事です。しかしいずれも、Azure ランディングゾーンとコンプライアンスチームが首を締めている 4 つのリポジトリにまたがる 15 人の開発者がいるときに何が起きるかには触れていません。

エンタープライズチームが異なる必要を持つもの

セキュリティ境界

ソロ開発テンプレートは自分自身から保護するものがないためアクセス制御を考えません。エンタープライズリポジトリには、Claude が極度に慎重にアプローチすべき —— またはまったく触れるべきでない —— 認証モジュール、課金ロジック、Infrastructure-as-Code、シークレット管理があります。

鋭いエッジにはローカル CLAUDE.md ファイルが必要です:

src/auth/CLAUDE.md
src/billing/CLAUDE.md
infra/terraform/CLAUDE.md

それぞれにモジュール固有の制約が含まれます: マイグレーションを更新せずにトークンローテーションを変更しない、接続文字列をハードコードしない、Terraform 変更をコミットする前に常にコンプライアンスチェックを実行する。Claude はそれらのディレクトリで作業するときにこれらを自動的に読み込みます。

マルチリポジトリのルール配布

CLAUDE.md の階層 —— ユーザーレベル(~/.claude/CLAUDE.md)、プロジェクトレベル、サブディレクトリレベル —— は強力ですが、組織全体でどう管理するかには誰も触れません。30 のリポジトリがあるとき、すべてのプロジェクトにコピーペーストを必要としない共有標準が必要です。

機能するパターン: 組織の基本ルールを持つ中央 claude-standards リポジトリを維持。CI/CD 経由で配布 —— 各リポジトリに共有 .claude/rules/ ファイルを同期するパイプラインステップ。または好みに応じて Git サブモジュールを使用。ポイントは、Azure の命名規則、セキュリティベースライン、コンプライアンスルールが一度作成され、どこにでも継承されるべきということです。

MCP サーバー設定

Model Context Protocol サーバーは Claude に外部ツールへのアクセスを与えます —— コンポーネントライブラリ、ドキュメント検索、デプロイ API、Jira。Dometrain は Shadcn の例でこれに触れましたが、エンタープライズチームは複数の MCP サーバーを運用しています: 内部パッケージレジストリ、Azure リソース API、ポリシーエンジン。

CLAUDE.md はどの MCP サーバーが利用可能で何のためかを宣言すべきで、Claude がいつローカルファイル対外部コンテキストに手を伸ばすべきかを知れるようにします。

強制のためのフック

これが大きなものです。すべてのテンプレートは Claude に「これらのルールに従え」と伝えます。エンタープライズチームはモデルが覚えることに頼れません。決定論的な強制が必要です。

Claude Code フック(.claude/settings.json)は自動的に発火します —— 特定の操作の前または後に。毎回必ず起こるべきことすべてに使いましょう:

すべてのファイル編集後にコードをフォーマット
インフラ変更にセキュリティ lint を実行
保護されたディレクトリへの書き込みをブロック
コミット前にコンプライアンスチェックを実行

プロンプトは提案です。フックは保証です。「Claude は通常標準に従う」と「Claude は常に標準に従う」の違いはフックです。

コードとしてのコンプライアンスルール

規制産業にいる場合、CLAUDE.md ルールファイルはコンプライアンス要件を直接エンコードすべきです。ログステートメントに PII を入れない。認証なしの公開エンドポイントを作らない。承認された Azure リージョン外でリソースをプロビジョニングしない。これらはスタイルの好みではなく監査要件であり、毎セッション自動読み込みされる .claude/rules/compliance.md に属します。

エンタープライズ CLAUDE.md テンプレート

Terraform による Azure インフラ、.NET または Node.js アプリケーション層、Intune 管理のエンドポイントを持つエンタープライズチーム向けの本番対応テンプレートを以下に:

# Project: ContosoCloud Platform

Enterprise SaaS platform — .NET 8 APIs, React frontend, Azure landing zone.
Managed by the Platform Engineering team at Contoso.

## Commands

- Build: `dotnet build src/ContosoCloud.sln`
- Test: `dotnet test --no-build --verbosity normal`
- Lint: `dotnet format --verify-no-changes && npx eslint src/web/`
- Deploy (staging): `az deployment group create -g rg-contoso-staging -f infra/main.bicep`
- Terraform plan: `cd infra/terraform && terraform plan -var-file=env/staging.tfvars`

## Architecture

- `src/api/` — .NET 8 Web API (Clean Architecture)
- `src/web/` — React 18 + TypeScript frontend
- `infra/bicep/` — Azure Bicep templates (landing zone)
- `infra/terraform/` — Terraform modules (networking, DNS)
- `scripts/` — CI/CD pipeline scripts
- `.claude/rules/` — Auto-loaded team standards

## Rules

- Never hardcode secrets. Use Azure Key Vault references.
- All API endpoints require authentication. No anonymous access.
- Follow Azure naming convention: `{resource}-{project}-{env}-{region}`
- Terraform changes require `terraform plan` output in PR description.
- No `any` types in TypeScript. No `dynamic` in C# unless justified.

## MCP Servers

- `azure-docs` — Search Azure documentation (use for service limits, SKU details)
- `component-lib` — Internal React component library (check before building new UI)
- `jira` — Project tracking (reference ticket numbers in commits)

## Gotchas

- Auth uses MSAL with custom token cache — see `src/api/Auth/CLAUDE.md`
- Database migrations are EF Core — never modify generated migration files
- The staging Key Vault has a different access policy than prod — check before assuming
- Bicep modules in `infra/bicep/modules/` are shared across 3 teams — coordinate changes

@docs/architecture.md
@docs/adr/
@docs/runbooks/incident-response.md

これをコードスタイル、セキュリティポリシー、コンプライアンス向けの .claude/rules/ ファイルとペアにします:

.claude/rules/
├── code-style.md          # フォーマット、命名、パターン
├── security.md            # 認証要件、シークレット処理、入力バリデーション
├── compliance.md          # データ居住性、PII 処理、監査ログ
├── azure-conventions.md   # 命名、タグ付け、リソースグループ構造
└── terraform.md           # モジュールパターン、状態管理、プラン要件

そして .claude/settings.json のフックで交渉不可のルールを強制します:

{
  "hooks": {
    "postFileEdit": [
      { "command": "dotnet format src/ContosoCloud.sln --include ${file}" },
      { "command": "npx eslint --fix ${file}" }
    ],
    "preCommit": [
      { "command": "dotnet test --no-build" },
      { "command": "scripts/compliance-check.sh" }
    ]
  }
}

よくある間違い

すべてを 1 ファイルにダンプする。 ルート CLAUDE.md は百科事典ではなく目次であるべきです。500 行を超えるなら、コンテキストトークンを無駄にし、Claude は指示を見逃し始めます。

プロンプトだけでフックがない。 ルールが書き留める価値があるなら、強制する価値もあります。フックは設定が安く、忘れることが不可能です。

階層を無視する。 すべてのテンプレートはルートレベル CLAUDE.md を示します。サブディレクトリのオーバーライドやユーザーレベルのデフォルトにはほとんど触れません。エンタープライズチームは 3 階層すべてを連携して動かす必要があります。

トリミングせずにテンプレートをコピーペーストする。 Builder.io の ShopFront の例は素晴らしいですが、Next.js の eコマースアプリ向けです。Azure ランディングゾーンリポジトリには異なる指示が必要です。/init で始め、積極的に削りましょう。

チームの所有権がない。 ひりとが CLAUDE.md を書き、誰も保守しないなら、それは腐ります。ルールファイルの所有権をそれらを気にするチームに割り当てましょう。セキュリティチームが security.md を所有。プラットフォームチームが azure-conventions.md を所有。これらをコードとして扱い —— プルリクエストを経由させます。

FAQ

以下の FAQ セクションを参照してください —— エンタープライズチームから寄せられる CLAUDE.md に関する最も一般的な質問をカバーしています。

チームを加速させる

「Claude Code を使う開発者」と「Claude Code をスケールでデプロイするチーム」のギャップは構造です。テンプレートはスタートさせます。エンタープライズパターン —— セキュリティ境界、分散ルール、フック強制、コンプライアンス統合 —— が本番に到達させます。

Big Hat Group はエンタープライズチームがこのインフラを構築するのを支援します。IT チーム向けの Claude Code と AI エージェントのトレーニングを運営し、私たちのコンサルティングプラクティスはここで説明された正確なパターンを専門とします: マルチリポジトリ CLAUDE.md 戦略、MCP サーバー統合、OpenClaw デプロイ、そして AI 支援開発にコンプライアンスチームを安心させるガバナンスフレームワーク。

チームが実験段階を過ぎ、Claude Code を運用化する準備ができているなら、ご連絡ください。

Kevin Kaminski は Microsoft MVP であり、Big Hat Group の Principal です。同社ではエンタープライズチームが AI エージェント、Windows 365、モダンマネジメントソリューションをデプロイするのを支援しています。