企業團隊的 CLAUDE.md 指南：範本、結構與最佳實踐

目前至少有十幾份流行的 CLAUDE.md 指南流傳。Builder.io 發布了一份。ClaudeFast 釋出完整套件。Dometrain、Gradually AI、scotthavird、Claude for Designers — 每個人都有範本。

它們都很好。而且都針對 solo 開發者與新創。

如果你在企業團隊中運行 Claude Code — 多個 repo、合規要求、Azure 基礎設施、共享 MCP server，以及沒有全部讀過同一篇部落格的開發者 — 那些範本是起點，不是終點。

以下是他們漏掉的，以及你的團隊真正需要的。

概覽

CLAUDE.md 是 Claude Code 的專案組態檔 — 它在每個 session 開始時讀取的第一個東西。社群已在基本面上收斂（保持簡短、以身分開頭、記錄指令與陷阱）。但企業團隊需要更多：敏感模組的安全邊界、多 repo 規則分發、MCP server 宣告、合規護欄，以及不依賴模型記憶指令的 hook 強制執行。本指南涵蓋流行範本做對了什麼、漏掉了什麼，並提供你今天就能放入 repo 的生產級企業範本。

CLAUDE.md 到底是什麼

如果你對 Claude Code 不熟，簡短版本是：CLAUDE.md 是位於 repo 根目錄的 markdown 檔案，Claude 在每個 session 開始時讀取。它告訴 Claude 專案是什麼、東西在哪、該執行哪些指令、該遵守哪些規則。

我在 The Anatomy of a Claude Code Project 中涵蓋了完整專案結構 — CLAUDE.md、技能、hooks、文件與本地覆寫。如果你需要基礎，先讀那篇。

要理解的重要事：CLAUDE.md 不是 prompt。它是組態檔。差別很重要。Prompt 是一次性的。組態跨每次互動、每個 session、你團隊上的每個開發者持久存在。

所有人都同意的標準結構

在審視每個主要範本 — Builder.io 的模組化做法、ClaudeFast 的全套件、scotthavird 的 GitHub starter、Dometrain 的 .NET 聚焦指南、Gradually AI 的 token 意識做法 — 後，社群已收斂到幾個通用原則：

1. 維持在 500 行以內。 Context token 有限。臃腫檔案降低效能。
2. 以身分開頭。 一句話：這個系統做什麼？
3. 記錄精確指令。 Build、test、lint、deploy。Claude 逐字使用這些。
4. 捕捉陷阱。 那些奇怪的東西 — 認證怪癖、禁止檔案、變通模式。
5. 分離關注點。 重量級文件放進 .claude/rules/ 或 @imported 檔案，而非主檔案。
6. 有機地成長。 當你發現自己重複指令時才加規則，不要提前加。

目錄結構也類似定案：

project/
├── CLAUDE.md                    # 身分、指令、規則（簡短）
├── .claude/
│   ├── settings.json            # Hooks、權限
│   ├── commands/                # Slash 指令
│   └── rules/                   # 自動載入規則檔
└── docs/                        # 依需求 @imported

這很穩固。Builder.io 的 Steve Sewell 推廣了 @imports 模式以保持 CLAUDE.md 精簡。Boris Cherny 展示了如何在 PR 留言中標記 @claude 以在審查工作流程中更新規則。ClaudeFast 進一步提供了 18 個預配 agent 定義與 20+ 技能模組。

都是好成果。沒有一個處理當你有 15 個開發者跨四個 repo、有 Azure landing zone 與合規團隊在後盯著時會發生什麼。

企業團隊需要什麼不同的東西

安全邊界

Solo 開發者範本不思考存取控制，因為沒有什麼需要防自己。企業 repo 有認證模組、計費邏輯、基礎設施即程式碼與密碼管理，Claude 應以極度謹慎對待 — 或根本不碰。

你需要在鋒利邊緣放上本地 CLAUDE.md 檔案：

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

每個檔案包含模組特定限制：未更新 migration 不要修改 token 輪替、絕不硬編碼連線字串、提交 Terraform 變更前一律執行合規檢查。Claude 在那些目錄中工作時會自動載入這些。

多 Repo 規則分發

CLAUDE.md 階層 — 使用者級（~/.claude/CLAUDE.md）、專案級、子目錄級 — 很強大，但沒人談如何在組織中管理它。當你有 30 個 repo，你需要不需複製貼上到每個專案的共享標準。

可行的模式：維護一個中央 claude-standards repo 存放組織的基礎規則。透過 CI/CD 分發 — 一個將共享 .claude/rules/ 檔案同步到每個 repo 的管線步驟。或用 Git submodules，如果你偏好。重點是你的 Azure 命名規範、安全基線與合規規則應撰寫一次並在各地繼承。

MCP Server 組態

Model Context Protocol server 給 Claude 存取外部工具 — 你的元件庫、文件搜尋、部署 API、Jira。Dometrain 用 Shadcn 範例觸及了這點，但企業團隊在跑多個 MCP server：內部套件註冊表、Azure 資源 API、政策引擎。

你的 CLAUDE.md 應宣告哪些 MCP server 可用及其用途，讓 Claude 知道何時該取用外部 context 而非本地檔案。

用 Hooks 強制執行

這是大事。每個範本都告訴 Claude「遵守這些規則」。企業團隊不能依賴模型記住。你需要確定性強制執行。

Claude Code hooks（.claude/settings.json）會在特定操作之前或之後自動觸發。用它們處理每次都必須發生的事：

• 每次檔案編輯後格式化程式碼
• 對基礎設施變更執行安全 lint
• 阻擋寫入受保護目錄
• 提交前執行合規檢查

Prompt 是建議。Hook 是保證。「Claude 通常遵循我們的標準」與「Claue 永遠遵循我們的標準」之間的差別，就是 hooks。

合規規則即程式碼

如果你在受監管產業，你的 CLAUDE.md 規則檔案應直接編碼你的合規要求。log 陳述中不得有 PII。不得有無身分驗證的公開端點。不得在核准的 Azure 區域外佈建資源。這些不是風格偏好 — 它們是稽核要求，屬於 .claude/rules/compliance.md，每個 session 自動載入。

企業 CLAUDE.md 範本

以下是一個生產就緒範本，適用於運行 Azure 基礎設施搭配 Terraform、.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           # 模組模式、state 管理、plan 要求

並用 .claude/settings.json 中的 hooks 強制執行不可妥協的規則：

{
  "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" }
    ]
  }
}

常見錯誤

把所有東西倒進一個檔案。 你的根 CLAUDE.md 應是目錄，不是百科全書。如果超過 500 行，你在浪費 context token，Claude 會開始漏掉指令。

沒有 hooks，只有 prompt。 若一條規則值得寫下，就值得強制執行。Hook 設定成本低且不可能忘記。

忽視階層。 每個範本都展示根級 CLAUDE.md。少數討論子目錄覆寫或使用者級預設。企業團隊需要三層一起運作。

複製貼上範本而不修剪。 Builder.io 的 ShopFront 範例很棒 — 用於 Next.js 電商應用。你的 Azure landing zone repo 需要不同指令。從 /init 開始，然後大幅刪減。

沒有團隊擁有權。 若一個人寫 CLAUDE.md 而沒人維護，它會腐爛。將規則檔案的擁有權指派給關心它們的團隊。安全團隊擁有 security.md。平台團隊擁有 azure-conventions.md。把它們當程式碼對待 — 走 pull request。

FAQ

請見下方的 FAQ 章節 — 涵蓋我們從企業團隊收到關於 CLAUDE.md 最常見的問題。

讓你的團隊上手

「使用 Claude Code 的開發者」與「大規模部署 Claude Code 的團隊」之間的差距，就是結構。範本讓你起步。企業模式 — 安全邊界、分散式規則、hook 強制執行、合規整合 — 讓你走到生產。

Big Hat Group 協助企業團隊建構這套基礎設施。我們為 IT 團隊執行 Claude Code 與 AI Agent 培訓，而我們的諮詢業務專精於此處描述的精確模式：多 repo CLAUDE.md 策略、MCP server 整合、OpenClaw 部署，以及讓合規團隊對 AI 輔助開發安心的治理框架。

如果你的團隊已過了實驗階段並準備好讓 Claude Code 營運化，與我們聯繫。

Kevin Kaminski 是 Microsoft MVP，也是 Big Hat Group 的 Principal，在此協助企業團隊部署 AI Agent、Windows 365 與現代管理解決方案。