Claude Code Team 企業導入與 AI 推動計畫－企業級教學手冊

Enterprise Adoption and AI Enablement Program for Claude Code Team 把 Claude Code Team 從「買了授權的工具」變成「有制度、有治理、有度量、可持續改善的企業 AI 軟體工程能力」的完整導入手冊

文件資訊

可信度標示制度（請務必先讀）

Claude Code 的產品架構在 2025–2026 年間變動幅度極大：預設權限模式反轉、沙箱與 Managed Settings 由選配變成企業標配、官方文件站整站遷移。網路上（包含中文技術部落格、影片、AI 產生的文章）有大量內容已經過時，而過時的部分往往正是企業最在意的權限、沙箱、資料保護與計費設定。

為避免讀者把「本手冊的企業實務建議」誤讀成「Anthropic 官方規範」，本手冊在敘述後標註來源等級：

⚠️ 關於時效性的重要聲明

本手冊中所有涉及 方案（Plan）、席位（Seat）、定價（Pricing）、用量限制（Usage Limit）、模型（Model）、Analytics 指標、Claude Code 功能與治理設定鍵 的敘述，皆以「截至 2026-09-24」為基準。

這些資訊由 Anthropic 官方文件查證而得，但變動頻率極高（官方每週發布 What’s New）。實際導入時請務必以 Anthropic 最新官方文件與貴組織實際合約為準。

凡本手冊未能查證的事項，一律標示為「【待確認】」或「需依組織實際環境決定」，不做臆測填補。設定鍵名稱請一律以 All settings 官方頁面為最終依據。

目錄

📌 目錄為兩層結構：章 + 小節，全部可點擊跳轉；每一部可點選標題收合或展開。每章開頭另有該章的迷你目錄，### 子節請由迷你目錄或章內導覽。第 47～51、53 章為改版新增章節，依主題分屬各部，但實體位置在第 46 章之後。標示「（v2.0 新增）」「（v2.1 新增）」者為改版新增的內容。

第 1 章　導讀：如何使用本手冊

本章目錄：1.1 本手冊要解決什麼問題 ｜ 1.2 讀者地圖：你該先讀哪幾章 ｜ 1.3 本手冊的閱讀約定 ｜ 1.4 三個必須先建立的觀念 ｜ 1.5 本章實務案例 ｜ 1.6 本章注意事項 ｜ 1.7 本章檢查清單

1.1 本手冊要解決什麼問題

很多組織導入 AI 開發工具時，只做了三件事：

1. 買授權
2. 發帳號
3. 開一場教育訓練

三個月後的結果通常是：少數人用得很兇、多數人幾乎沒用、沒有人說得出到底省了多少時間、也沒有人知道 AI 產出的程式碼是否安全。

本手冊的目的，不是教你「Claude Code 有哪些指令」——那是官方文件的工作。

本手冊要回答的是一個更難的問題：

當企業把 Claude Code Team 正式納入軟體開發流程之後，整個軟體工程組織應該如何重新設計工作方法？

具體而言，本手冊會逐章回答下列問題：

1.1.1 本手冊與姊妹文件的關係

本 repo 另有兩份 Claude Code 文件，定位不同：

📌 本手冊自成完整。凡導入決策會用到的機制，即使姊妹文件已寫過，本手冊仍會以「導入與治理」視角重新寫一次，不預設讀者先讀過其他文件。差別在視角：姊妹文件問「這個設定鍵怎麼設」，本手冊問「這個設定鍵該由誰決定、誰核准、怎麼稽核、出事誰負責」。

1.2 讀者地圖：你該先讀哪幾章

本手冊共 53 章，沒有人需要從頭讀到尾。請依角色挑選：

flowchart TD
    Start["我是誰？"] --> Mgr["管理階層 / CIO / 處長"]
    Start --> Gov["AI Governance / 資安"]
    Start --> Arch["架構師 / Tech Lead"]
    Start --> Dev["PG / SD / 開發同仁"]
    Start --> QA["QA / 測試工程師"]
    Start --> Ops["DevOps / 平台團隊"]
    Start --> PMSA["PM / SA"]

    Mgr --> M1["第 2、4、34、38、43、46 章"]
    Gov --> G1["第 12、16、23、36、37、49、53 章"]
    Arch --> A1["第 4、7～13、14、15、19、47、51 章"]
    Dev --> D1["第 6、8、10、11、17、20、21 章"]
    QA --> Q1["第 16、21、22、48 章"]
    Ops --> O1["第 5、6、20、23、33、47、48、49 章"]
    PMSA --> P1["第 13、14、17、18、35 章"]

v2.0 新增章節的建議讀者：

v2.1 新增與重大更正的建議讀者：

建議的閱讀順序（新進同仁）：

1. 第 1 章（本章）→ 建立心智模型
2. 第 6 章 → 把環境裝起來
3. 第 8 章 → 看懂 CLAUDE.md
4. 第 17 章 → 跟著做一次完整開發流程
5. 第 52 章附錄 B → 拿走檢查清單，開始工作

1.3 本手冊的閱讀約定

1.3.1 提示方塊

本手冊統一使用四種提示方塊：

⚠️ 警告：做錯會造成實際損害（資安事件、生產故障、資料外洩）。

✅ 建議：經驗法則，照做通常會比較順。

📌 註記：補充說明、易變資訊、待確認事項。

🎯 結論：本節最重要的一句話。

1.3.2 章節固定結構

從第 2 章起，每一章都遵守相同結構，方便你快速跳到想看的部分：

📌 v2.0 變更：章末三個固定小節在 v1.0.0 時沒有編號，導致 46 章共 138 個同名標題、錨點互相衝突而無法建立子目錄。v2.0 起一律編號（例如 1.5 本章實務案例），全書 H1/H2 標題皆唯一。

1.3.3 名詞使用原則

• 技術名詞與產品名稱保留英文原文（Claude Code、Subagent、Skill、Hook、MCP、SSDLC…），避免翻譯造成歧義。
• 中文採台灣用語（例：軟體、程式碼、專案、版本、資料庫、伺服器）。
• 完整名詞對照表見第 52 章附錄 C。

1.4 三個必須先建立的觀念

在往下讀之前，請先接受三個前提。這三個前提如果不成立，後面 51 章都會變成形式主義。

觀念一：Claude Code 是 Agent，不是 Chat

AI Chat 的互動模型是：你問 → 它答 → 你自己把答案貼進程式碼。

AI Coding Agent 的互動模型是：你交付一個任務 → 它自己讀檔案、跑指令、改多個檔案、執行測試、看測試結果、再修正 → 回報結果給你審查。

這個差異會直接改變三件事：

觀念二：AI 越快，治理越重要

這是本手冊最重要的一句話，會在第 44 章再次強調：

🎯 AI 產生程式碼的速度越快，Human Review、Architecture Governance、Testing、Security 與品質治理的重要性就越高，而不是越低。

理由很直觀：當一個人一天能產生 3,000 行程式碼而不是 300 行時，未經審查的錯誤也同步放大 10 倍。原本靠「人寫得慢，所以有時間想清楚」這個天然煞車消失了，就必須用制度把煞車裝回來。

觀念三：工程師的角色在轉型，不是被取代

從 Code Producer 轉型為 AI Agent Orchestrator、Reviewer、Architect、Problem Solver。

這不是安慰話。實際觀察到的變化是：

• 「把規格翻譯成程式碼」的比重下降
• 「判斷這個設計對不對」「判斷這段程式碼能不能上線」的比重上升
• 「拆解問題、定義驗收標準、設計測試」的比重大幅上升

也就是說，資淺工程師的學習路徑會改變（第 35 章會深入討論這個組織課題）。

1.5 本章實務案例

情境：某金融資訊部門在 2025 年導入 Copilot，一年後檢討發現「授權買了 200 套，月活躍只有 60 人」。

當時的檢討結論（錯誤）：「工具不好用，換一個。」

深入訪談後的真實原因：

1. 沒有人告訴同仁「什麼情況下該用 AI」——大家只在寫 CRUD 時用，遇到難題反而不敢用。
2. 沒有共用的 prompt / rule 資產——每個人都從零開始摸索，摸索失敗就放棄。
3. 資安沒有明確政策——同仁怕「貼程式碼上去會不會違規」，乾脆不用。
4. 沒有衡量機制——主管不知道誰用得好，也就無法擴散好做法。

與本手冊的對應：這四個問題分別對應第 17 章（使用場景）、第 7～13 章（共用資產）、第 23 章（安全政策）、第 29～31 章（衡量）。

🎯 換工具不會解決上面任何一個問題。導入方法才會。

1.6 本章注意事項

⚠️ 不要把本手冊當成「一次性導入文件」。第 27 章的知識回饋循環要求本手冊本身也要每季更新一次，並由 AI Governance 小組維護版本。

⚠️ 不要跳過第 5、6 章直接做第 17 章。環境與權限沒標準化，後面所有流程都會在「我這邊跑不起來」的雜訊中崩潰。

📌 本手冊假設組織已具備基本的 Git 工作流程（branch / PR / code review）與 CI/CD。若尚未具備，請先補齊這部分，AI 導入的效益高度依賴既有工程基礎設施。

1.7 本章檢查清單

• 我知道自己的角色該先讀哪幾章（1.2 節）
• 我理解「Agent ≠ Chat」的差異（觀念一）
• 我接受「AI 越快、治理越重要」這個前提（觀念二）
• 我理解工程師角色轉型的方向（觀念三）
• 我的組織已具備 Git + PR + CI/CD 基礎（否則請先補齊）

第 2 章　Executive Summary：為什麼從 Copilot 轉向 Claude Code Team

本章目錄：2.1 先說清楚：這不是產品優劣比較 ｜ 2.2 從 Assistant 到 Agent：能力模型的本質差異 ｜ 2.3 從十四個角度分析轉型的必要性 ｜ 2.4 核心論點：這是 Operating Model 的改變 ｜ 2.5 轉型的效益與成本（誠實版） ｜ 2.6 給決策者的三句話總結 ｜ 2.7 本章實務案例 ｜ 2.8 本章注意事項 ｜ 2.9 本章檢查清單

2.1 先說清楚：這不是產品優劣比較

本章不會得出「Claude Code 比 GitHub Copilot 好」這種結論。

原因很簡單：這兩個產品解決的問題層級不同，拿來排名沒有意義，就像不會去比較「IDE 的自動完成」和「CI/CD 平台」誰比較強。

真正該問的問題是：

組織現在需要解決的問題，落在哪一層？

flowchart LR
    L1["第 1 層<br/>程式碼補全<br/>Code Completion"] --> L2["第 2 層<br/>對話式協助<br/>Chat Assistant"]
    L2 --> L3["第 3 層<br/>編輯器內 Agent<br/>In-IDE Agent"]
    L3 --> L4["第 4 層<br/>Repository 級 Agent<br/>Terminal + Multi-file + Test"]
    L4 --> L5["第 5 層<br/>AI Agent Team<br/>納入 SSDLC 的工程體系"]

    style L1 fill:#e8f4f8
    style L2 fill:#d1e9f0
    style L3 fill:#b9dee8
    style L4 fill:#a2d3e0
    style L5 fill:#8ac8d8

• 第 1～3 層：解決「工程師打字慢」的問題。效益是個人生產力。
• 第 4～5 層：解決「一個變更要橫跨 40 個檔案、要跑測試、要驗證沒破壞既有功能」的問題。效益是工程流程生產力。

組織現在面臨的三大工程課題——Legacy 逆向工程、框架升版、大規模重構——全部落在第 4～5 層。

🎯 轉向 Claude Code Team 的真正理由，不是「它比較聰明」，而是組織要處理的問題已經超出第 1～3 層工具的能力邊界。

2.2 從 Assistant 到 Agent：能力模型的本質差異

2.2.1 Assistant 的能力模型

sequenceDiagram
    participant D as 開發者
    participant A as AI Assistant
    participant C as 程式碼

    D->>A: 貼上片段 + 提問
    A-->>D: 回傳建議
    D->>C: 人工套用
    D->>C: 人工執行測試
    D->>A: 測試失敗，再貼一次
    A-->>D: 再給建議
    Note over D,C: 迴圈的執行者是「人」

關鍵特徵：AI 不接觸真實檔案系統，不執行任何指令。所有驗證動作都由人執行。

成本結構：AI 每輪成本很低，但人的成本很高——人要負責搬運上下文、執行、判斷、再搬運。

2.2.2 Agent 的能力模型

sequenceDiagram
    participant D as 開發者
    participant A as AI Agent
    participant F as 檔案系統
    participant T as 測試 / 建置

    D->>A: 交付任務 + 驗收標準
    A->>F: 搜尋 / 讀取相關檔案
    A->>A: 建立計畫
    A->>D: 提出計畫，請求確認
    D-->>A: 核准
    A->>F: 修改多個檔案
    A->>T: 執行建置與測試
    T-->>A: 測試失敗訊息
    A->>F: 依失敗訊息修正
    A->>T: 再次執行
    T-->>A: 通過
    A-->>D: 回報變更摘要，請求審查
    D->>D: Code Review
    Note over A,T: 迴圈的執行者是「AI」，人只在起點與終點介入

關鍵特徵：AI 擁有檔案讀寫與指令執行能力，能自我驗證（跑測試看結果）。

成本結構：AI 每個任務成本較高（多輪推理 + 工具呼叫），但人的成本大幅下降——人只做「定義」與「審查」。

2.2.3 這個差異對企業的實際意義

⚠️ 請特別注意最後兩列。Agent 模型帶來的不只是效益，還有新的風險類別——這是第 23 章與第 36 章存在的理由。

2.3 從十四個角度分析轉型的必要性

以下逐一分析組織關切的十四個面向。每一項都說明：現況痛點 → Agent 模型如何處理 → 企業要付出什麼代價。

📌 v2.0 變更：原本為十一個角度。2.3.12～2.3.14 為 v2.0 新增，反映 Claude Code 在 2026 年新增的三類能力（平行化、非互動式執行、官方導入素材），這三項在 v1.0.0 撰寫時尚未成熟或尚未公開。

2.3.1 AI Coding Assistant 的能力天花板

痛點：補全式 AI 對「新增程式碼」很有效，但組織 70% 的工作是修改既有程式碼。修改既有程式碼需要先理解既有程式碼，補全式 AI 看不到足夠的上下文。

Agent 如何處理：Agent 會主動搜尋（grep / glob）、讀取相關檔案、追蹤呼叫鏈，再決定要改哪裡。

代價：每個任務消耗的 token 明顯較多（第 29、31 章會談成本管理）。

2.3.2 Agentic Software Development

痛點：傳統開發流程中，「分析 → 設計 → 實作 → 測試」是四段人工接力，每段交接都有資訊損耗。

Agent 如何處理：可將四段定義成四個 Agent，用**結構化文件（Artifact）**交接，資訊損耗可控且可稽核（第 15 章）。

代價：必須先定義好 Artifact 格式與交接契約，這是一次性的建置成本。

2.3.3 Repository-level Reasoning

痛點：問「這個欄位改了會影響哪些地方？」，補全式 AI 答不出來。

Agent 如何處理：Agent 可實際搜尋整個 repository，列出所有引用點，並判斷影響範圍。

代價：大型 repository 需要良好的 CLAUDE.md 導引（第 8 章），否則 Agent 會在無關目錄中浪費大量 token。

2.3.4 Multi-file Change

痛點：一個典型的後端功能變更會橫跨 Controller / Service / Repository / DTO / Entity / Test / Migration 至少 7 個檔案。人工逐檔修改容易遺漏。

Agent 如何處理：一次性規劃並修改全部檔案，並以測試驗證一致性。

代價：單次變更的 review 負擔變大。第 21 章會說明如何用「分層 review」處理這個問題。

2.3.5 Terminal Workflow

痛點：很多工程任務不是「寫程式碼」，而是「跑指令」——mvn dependency:tree、git log、kubectl describe、psql 查詢。

Agent 如何處理：Agent 能執行這些指令並解讀輸出，把「查資料」這件事自動化。

代價：指令執行權限是最大的安全風險點。必須建立 allowlist 與 Hook 攔截（第 12、23 章）。

2.3.6 Test Execution

痛點：AI 產生的測試常常「看起來對，但根本沒跑過」。

Agent 如何處理：產生測試 → 實際執行 → 看到失敗 → 修正 → 再執行，直到通過。

代價：專案的測試必須可以在本機快速執行。若測試需要連線到共用資料庫或需要 10 分鐘才跑完，這個迴圈就會失效（第 22 章會談測試環境準備）。

2.3.7 Refactoring

痛點：大規模重構風險高，人工做要好幾週，做到一半常被插件的需求打斷。

Agent 如何處理：可依既有測試作為安全網，分批執行重構並逐批驗證。

代價：重構前必須有測試。沒有測試的 Legacy 系統要先補測試（第 19、41 章的標準流程第一步就是這件事）。

2.3.8 Reverse Engineering

痛點：組織有大量無文件的 Legacy 系統（Java、VB、C#、Stored Procedure、Batch）。逆向工程極度耗時，而且做完的文件常常不準。

Agent 如何處理：能系統性讀完整個 codebase，抽取商業規則、資料流、相依關係，產出結構化文件。

代價：AI 會把推測寫得像事實。這是逆向工程最大的風險，第 18 章的 Fact / Inference / Unknown 三層標記制度就是為了解決這個問題。

2.3.9 Framework Upgrade

痛點：Java 8 → 21、Spring Boot 2 → 3 的升版，涉及數百個 breaking change，人工比對 release note 極為耗時。

Agent 如何處理：可掃描相依樹、比對已知 breaking change、產生升版計畫、執行自動重構、編譯、測試、修正。

代價：AI 對「尚未廣泛採用的新版本」知識可能不足。第 19 章要求以官方 migration guide 作為 Agent 的輸入，而非依賴 AI 的既有知識。

2.3.10 Automation

痛點：很多重複性工程任務（補測試、更新文件、修正 lint、相依套件升級）沒人想做。

Agent 如何處理：可排程執行，產出 PR 供人審查。

代價：自動化過頭是真實風險。第 42 章有 Over Automation 的失敗案例。

2.3.11 Enterprise Governance

痛點：管理階層問「AI 到底幫我們省了多少？」「AI 產生的程式碼有沒有資安問題？」，沒有人答得出來。

Agent 如何處理：Claude Code Team 提供組織層級的 Usage Analytics（第 31 章），配合企業自建的工程指標，可組成完整衡量體系（第 29～33 章）。

代價：Analytics 很容易被誤用成員工排名工具。第 30 章專門處理這個管理課題。官方 Analytics Dashboard 本身就內建 Leaderboard（排行榜）功能，這讓誤用的門檻變得更低，組織必須主動訂定使用規範。

2.3.12 平行化：一個人同時推進多條工作線【官方】

痛點：工程師一次只能專注一件事。等待建置、等待測試、等待 Code Review 的空檔就是純粹的浪費，而且「等一下再回來做」會付出重新載入上下文的成本。

Agent 如何處理：Claude Code 已提供多種平行化機制，讓一個人可同時推進數條獨立工作線：

代價：平行化會同時放大產出與風險。一個人同時開四條工作線，代表同一時間有四份未經審查的變更在累積；Review 會成為新的瓶頸，且人類對每條線的掌握度都會下降。第 13、15 章定義企業可接受的平行度上限與必要的收斂機制。此外，disableAgentView 與 Corporate Launcher（processWrapper）是組織可用的控制手段（第 49 章）。

2.3.13 非互動式執行：AI 在沒有人盯著的時候工作【官方】

痛點：Assistant 時代的 AI 只在工程師開著 IDE 時才有價值。下班後、CI 執行中、例行維運時段，AI 完全缺席。

Agent 如何處理：Claude Code 現已延伸到多個無人值守的執行面：

• Cloud sessions（Claude Code on the web）：在 Anthropic 託管的隔離 VM 中執行，可設定網路白名單，git push 限制於當前分支，全程稽核日誌
• GitHub Actions / GitLab CI/CD：在 CI pipeline 中執行審查與修正
• Routines（/schedule）：排程重複性任務
• Headless 模式：以程式化方式呼叫，整合進既有自動化
• Self-hosted environments：在組織自有基礎設施上執行雲端 session

代價：這是本次改版中風險性質變化最大的一項。當 AI 在沒有人即時監看的情況下執行，原本「工程師會看到並攔截」這道隱性防線就消失了。所有核准邊界必須事前以設定固定下來，不能依賴當下判斷。第 48 章專門處理這個課題。

2.3.14 官方導入素材已經成熟【官方】

痛點：組織推動新工具時，最常見的失敗不是技術問題，而是「推動小組自己摸索出一套說法，講得不夠好、也不一致」。

Agent 如何處理：Anthropic 已發布兩份官方導入素材，可直接作為企業推動計畫的骨幹：

代價：官方素材是以一般軟體團隊為對象設計的，預設環境較寬鬆（例如預設可用雲端 session、預設鼓勵公開分享 prompt）。金融、醫療、公部門等受監管產業不能直接照搬，必須先過一次治理篩選。第 50 章逐項對照官方素材與本手冊制度，標出「可直接採用」「需加嚴」「不適用」三類。

2.4 核心論點：這是 Operating Model 的改變

把上面十四點收斂起來，會得到一個結論：

🎯 Copilot 與 Claude Code 並不是單純的產品替換，而是 Software Development Operating Model 的改變。

「Operating Model」指的是一個組織如何組織人、流程與技術來交付價值。具體改變如下：

flowchart TB
    subgraph Old["舊 Operating Model（Assistant 時代）"]
        O1["需求 → 人分析"]
        O2["人設計"]
        O3["人寫程式碼<br/>（AI 補全加速 20%）"]
        O4["人寫測試"]
        O5["人 Review"]
        O1 --> O2 --> O3 --> O4 --> O5
    end

    subgraph New["新 Operating Model（Agent 時代）"]
        N1["需求 → 人定義驗收標準"]
        N2["Agent 分析 + 人審查"]
        N3["Agent 設計 + 架構師決策"]
        N4["Agent 實作 + 執行測試"]
        N5["Agent Review + 人最終把關"]
        N6["治理層：權限 / 稽核 / 指標"]
        N1 --> N2 --> N3 --> N4 --> N5
        N6 -.貫穿全流程.-> N2
        N6 -.-> N3
        N6 -.-> N4
        N6 -.-> N5
    end

    Old ==>|轉型| New

三個最重要的變化：

⚠️ 第 2 點是很多組織導入失敗的主因：實作變快了，但 review 還是靠原本那兩位資深同仁，結果 PR 大排長龍，整體 lead time 沒有改善。第 21 章會提出解法。

2.5 轉型的效益與成本（誠實版）

2.5.1 可預期的效益

2.5.2 必須誠實面對的成本

⚠️ 最常被低估的是「Review 負擔轉移」。請在 Pilot 階段（第 25 章）就實際量測 review 工時，不要等到全面導入才發現。

2.6 給決策者的三句話總結

1. 導入理由：組織的主要工程課題（Legacy 逆向、框架升版、大規模重構）已超出補全式 AI 的能力邊界，需要 Repository 級的 Agent。
2. 導入本質：這是 Operating Model 的改變，不是工具替換。人的工作重心從「產出」移到「定義與判斷」，並且必須新增「AI 治理」這個能力。
3. 成功條件：平台標準化（第 5～13 章）＋ 流程重設計（第 14～23 章）＋ 治理與衡量（第 29～37 章）三者同時到位。只做其中一項，會失敗。

2.7 本章實務案例

情境：某銀行核心系統的「交易明細查詢」模組，需要從 Spring Boot 2.7 升到 3.2（含 javax → jakarta 命名空間變更）。

Assistant 模型下的做法：

1. 工程師手動搜尋所有 javax.persistence 引用（約 180 處）
2. 逐檔修改，每檔問一次 AI「這樣改對嗎」
3. 編譯 → 出現 60 個錯誤 → 逐個 Google
4. 預估工時：12 人天

Agent 模型下的做法：

# 步驟 1：讓 Agent 先做盤點（不修改任何檔案）
claude "盤點本專案所有 javax.* 的使用點，依 package 分類統計，
        並對照 Spring Boot 3.2 官方 migration guide 標示每一類的處理方式。
        只產出報告，不要修改任何檔案。"

# 步驟 2：人工審查報告，確認範圍與風險後，再授權執行
claude "依照上一步的報告，分批執行 javax → jakarta 的遷移。
        每完成一個 package 就執行 mvn -q compile，
        編譯失敗就先修正再繼續。不要修改測試以外的行為。"

# 步驟 3：驗證
claude "執行 mvn verify，分析所有失敗的測試，
        逐一判斷是「遷移造成的破壞」還是「測試本身寫死了舊行為」，
        分別列出並提出修正建議。"

實際結果（該案例）：

• Agent 執行時間：約 4 小時（含人工審查兩次）
• 人工修正時間：1.5 人天（主要處理 Agent 判斷不確定的 12 處）
• 總計約 2 人天，相較原估 12 人天

但要注意的是：

⚠️ 該案例成功的前提是「這個模組有 78% 的測試覆蓋率」。同一個做法套用在另一個覆蓋率只有 12% 的模組時，Agent 改完「編譯通過、測試通過」，但上線後出現 3 個生產問題——因為根本沒有測試去驗證那些行為。

🎯 Agent 的自我驗證能力，上限等於你的測試品質。 這是第 22 章的核心論點。

2.8 本章注意事項

⚠️ 不要用「省了多少人天」作為唯一的導入理由向管理階層簡報。這個數字在 Pilot 階段很漂亮，全面推廣後會回歸平均，屆時會造成信任危機。建議同時呈現第 29 章的四層 KPI。

⚠️ 不要在沒有測試的專案上先導入 Agent 模型。優先順序應該是：補測試（可用 AI 協助）→ 再做重構或升版。

📌 Copilot 不必立刻全面停用。第 3 章會說明「共存期」策略——兩者的能力層級不同，在過渡期並行使用是合理的。

📌 本章所有效益數字皆為情境示意，實際數值請以貴組織 Pilot 階段的實測為準（第 25 章）。

2.9 本章檢查清單

• 我能說明「為什麼不是產品優劣比較」（2.1 節）
• 我理解 Assistant 與 Agent 的能力模型差異（2.2 節）
• 我能列出至少 5 個轉型面向及其代價（2.3 節）
• 我理解「Operating Model 改變」的三個具體變化（2.4 節）
• 我已誠實評估六類導入成本，特別是 Review 負擔轉移（2.5 節）
• 我知道「Agent 的驗證能力上限 = 測試品質」（本章實務案例）

第 3 章　Copilot → Claude Code Team 完整對照

本章目錄：3.1 對照的正確方法 ｜ 3.2 完整對照表 ｜ 3.3 三個維度的深入解讀 ｜ 3.4 共存期策略：不必立刻全面切換 ｜ 3.5 本章實務案例 ｜ 3.6 本章注意事項 ｜ 3.7 本章檢查清單

3.1 對照的正確方法

先說明本章的分析方法，避免被誤讀成產品評比。

本章從三個維度分析，每個維度問不同的問題：

📌 重要前提：GitHub Copilot 自身也在快速演進（Copilot Chat、Copilot Edits、Copilot Workspace、Copilot Coding Agent 等）。本章的對照基準為截至 2026-09-24 兩個產品的一般可用（GA）能力，且本 repo 另有 github copilot生態圈教學手冊 可對照。實際評估時請以當下版本為準。

3.2 完整對照表

📌 下表為截至 2026-09-24 的能力對照，並以「能力模型」而非「功能清單」描述。請以兩家官方最新文件為準。

📌 對照表的閱讀提醒：本表的重點不是「誰的功能多」，而是兩者需要的治理投資完全不同。Copilot 的治理重心在「平台政策」；Claude Code 的治理重心在「端點上的技術強制」——因為 Agent 是在工程師的機器上、以工程師的身分執行指令的。這一點決定了第 47～49 章為什麼必須獨立成章。

3.3 三個維度的深入解讀

3.3.1 能力模型：差異的根源是「工具存取權」

把上表濃縮成一句話：

🎯 兩者最根本的差異，是 AI 是否擁有「檔案系統 + 指令執行」的存取權。

所有其他差異（多檔修改、測試執行、逆向工程、升版）都是這個根本差異的衍生結果。

flowchart TD
    Root["AI 是否能存取<br/>檔案系統與執行指令？"]
    Root -->|否| NoTool["能力上限：<br/>建議 / 生成 / 解釋"]
    Root -->|是| HasTool["能力上限：<br/>執行 / 驗證 / 迭代"]

    NoTool --> N1["人負責搬運與驗證"]
    NoTool --> N2["風險低"]
    NoTool --> N3["治理需求低"]

    HasTool --> H1["AI 自我驗證"]
    HasTool --> H2["風險高：誤刪 / 誤改 / 外洩"]
    HasTool --> H3["治理需求高：權限 / 稽核 / 核准"]

    style HasTool fill:#ffe6cc
    style H2 fill:#ffcccc
    style H3 fill:#ffcccc

3.3.2 工作模型：從「連續互動」到「批次委派」

⚠️ 「錯誤發現時機延後」是 Agent 模型的核心風險。緩解方式有三：(1) 要求 Agent 先出計畫再執行；(2) 用 Hook 攔截危險操作；(3) 小批次交付而非一次交付大任務。這三點分別在第 10、12、17 章展開。

3.3.3 導入模型：組織要準備什麼

🎯 導入成本的差異，主要不在授權費，而在「組織要新建一整套治理與資產體系」。 這就是本手冊第 5～13 章與第 29～37 章存在的理由。

3.4 共存期策略：不必立刻全面切換

由於兩者能力層級不同，在過渡期並行使用是合理且建議的做法。

3.4.1 建議的任務分派原則

flowchart TD
    Task["收到一個開發任務"] --> Q1{"這個任務需要<br/>跨多個檔案嗎？"}
    Q1 -->|否| Q2{"我已經知道<br/>該怎麼寫嗎？"}
    Q1 -->|是| CC["用 Claude Code<br/>（任務委派模式）"]

    Q2 -->|是| CP["用 Copilot<br/>（補全加速）"]
    Q2 -->|否| Q3{"需要執行指令<br/>或跑測試驗證嗎？"}

    Q3 -->|是| CC
    Q3 -->|否| Q4{"是探索性問題<br/>還是實作問題？"}
    Q4 -->|探索| CC
    Q4 -->|實作| CP

    style CC fill:#d4edda
    style CP fill:#cce5ff

3.4.2 共存期的分工建議表

3.4.3 共存期的時程建議

📌 下列時程為建議範本，實際排程請依第 38 章的 Roadmap 與組織狀況調整。

⚠️ 不要在第 1 個月就宣布「明年起停用 Copilot」。這會讓尚未熟悉 Claude Code 的同仁陷入「舊的不能用、新的不會用」的空窗期，導致生產力下降與抗拒情緒。

3.5 本章實務案例

情境：某開發團隊（8 人）在共存期的第 5 個月做了一次內部檢討，統計各自的工具選擇。

發現的問題：

深入了解資淺同仁的原因：

1. 「我不知道要交付什麼樣的任務給它」→ 任務定義能力不足
2. 「它改了一堆檔案，我看不懂它改了什麼」→ Review 能力不足
3. 「我怕它把專案弄壞」→ 缺乏安全網的信心

採取的行動：

1. 針對第 1 點：提供第 10 章的標準 Command，讓資淺同仁從標準流程開始，不必自己設計任務（例如直接用 /implement，而非自由發揮 prompt）。
2. 針對第 2 點：導入第 21 章的「分層 review」方法，並要求 Agent 在完成後主動產出變更摘要。
3. 針對第 3 點：建立第 6 章的 git worktree 隔離工作流程，確保「弄壞了也只是弄壞一個暫存目錄」。

三個月後的結果：3 位資淺同仁的 Claude Code 使用比例提升至 50%～60%。

🎯 低使用率通常不是「不想用」，而是「不會定義任務」或「不敢審查結果」。解法是流程與訓練，不是施壓。 第 30 章會系統性處理這個議題。

3.6 本章注意事項

⚠️ 不要把對照表拿去做「採購決策簡報」的比較欄位。表中很多項目是「設計取向不同」而非「有無之分」，斷章取義會誤導決策。

⚠️ 兩個工具同時安裝在同一個 IDE 時，行內補全可能互相干擾。建議在 IDE 設定中明確擇一啟用行內補全功能，避免建議打架。具體設定方式需依組織使用的 IDE 版本決定。

📌 Copilot 的能力持續演進中。本章對照為截至 2026-09-24 的狀態，建議每半年由 AI Governance 小組重新檢視一次（第 28 章的社群活動可作為檢視場合）。

📌 成本結構不同：Copilot 通常為固定席位費；Claude Code Team 為席位費 + 可能的超額用量。預算編列方式需要調整（第 5、31 章）。

3.7 本章檢查清單

• 我理解本章的三個對照維度（能力 / 工作 / 導入模型）
• 我能說出兩者最根本的差異是「工具存取權」（3.3.1 節）
• 我理解「錯誤發現時機延後」的風險與三種緩解方式（3.3.2 節）
• 我知道導入成本的重點不在授權費，而在治理體系建置（3.3.3 節）
• 我的團隊有共存期的任務分派原則（3.4 節）
• 我沒有在導入初期就宣布停用舊工具

第 4 章　Claude Code Team 企業架構

本章目錄：4.1 為什麼需要「企業架構」這一層 ｜ 4.2 企業架構全景圖 ｜ 4.3 八層架構逐層說明 ｜ 4.4 架構落地的優先順序 ｜ 4.5 架構決策紀錄（ADR）的必要性 ｜ 4.6 方案功能矩陣：架構決策前必須先看的一張表 ｜ 4.7 本章實務案例 ｜ 4.8 本章注意事項 ｜ 4.9 本章檢查清單

4.1 為什麼需要「企業架構」這一層

很多組織直接讓同仁各自安裝 Claude Code 就開始用，三個月後會出現以下症狀：

這些都不是「工具問題」，是架構問題。本章定義企業層級的整體架構，後續第 5～13 章逐層實作。

4.2 企業架構全景圖

flowchart TB
    subgraph GOV["治理層 Enterprise AI Governance"]
        direction LR
        POL["Policy<br/>政策與規範"]
        SEC["Security<br/>安全控制"]
        AUD["Audit<br/>稽核與留存"]
        MET["Metrics<br/>指標與衡量"]
    end

    subgraph PROV["供應層 Provider &amp; Gateway"]
        direction LR
        SUB["Claude 訂閱<br/>Team / Enterprise"]
        CLOUD["Bedrock / Vertex<br/>Foundry / AWS"]
        GW["LLM Gateway<br/>集中稽核與限額"]
    end

    subgraph PLAT["平台層 Claude Code Team Platform"]
        direction LR
        ORG["Organization<br/>組織 / 席位 / SSO"]
        USR["User<br/>使用者與角色"]
        ANA["Analytics<br/>使用分析"]
        MS["Managed Settings<br/>組織強制政策"]
    end

    subgraph ASSET["資產層 Company AI Repository"]
        direction LR
        AG["Agents"]
        RL["Rules"]
        CM["Commands"]
        SK["Skills"]
        HK["Hooks"]
        PL["Plugins"]
        TM["Templates"]
    end

    subgraph EXEC["執行層 Execution Surfaces"]
        direction LR
        IDE["IDE<br/>VS Code / JetBrains"]
        CLI["Terminal CLI"]
        DESK["Desktop App"]
        WEB["Cloud Sessions<br/>Claude Code on the web"]
        CI["CI/CD Pipeline<br/>GitHub Actions / GitLab"]
    end

    subgraph REPO["專案層 Development Repository"]
        direction LR
        CMD_MD["CLAUDE.md"]
        PRJ_RULE["專案 rules/"]
        SRC["原始碼"]
        TEST["測試"]
    end

    subgraph SSDLC["流程層 SSDLC"]
        direction LR
        REQ["Requirement"]
        DES["Design"]
        IMP["Implementation"]
        TST["Test / Security"]
        REL["Release"]
    end

    subgraph TOOL["工具層 Tools & Integrations"]
        direction LR
        MCP["MCP Servers<br/>（allowlist 管控）"]
        GIT["Git / GitHub / GitLab"]
        DB["Database / Infra"]
    end

    GOV ==> PROV
    GOV ==> PLAT
    GOV ==> ASSET
    PROV ==> PLAT
    PLAT ==> EXEC
    ASSET ==> EXEC
    EXEC ==> REPO
    REPO ==> SSDLC
    EXEC <==> TOOL
    SSDLC ==> REL2["Production Release"]
    SSDLC -.回饋.-> MET
    SSDLC -.知識沉澱.-> ASSET
    MS -.強制下發.-> EXEC

    style GOV fill:#fff3cd
    style PROV fill:#cfe2ff
    style PLAT fill:#d1ecf1
    style ASSET fill:#d4edda
    style EXEC fill:#e2e3e5
    style REPO fill:#f8d7da
    style SSDLC fill:#e7d4f0
    style TOOL fill:#ffe5d0

📌 v2.0 變更：新增「供應層（Provider & Gateway）」，並在平台層加入「Managed Settings」。v1.0.0 預設所有人都以 Claude 訂閱直接連線，但實際上 Provider 的選擇會不可逆地決定哪些功能可用（第 47 章），而 Managed Settings 是把治理政策從「文件」變成「機器會擋」的唯一機制（第 49 章）。這兩者都必須在架構層就決定，不能留到實作階段。

4.3 八層架構逐層說明

4.3.1 治理層（Enterprise AI Governance）

職責：定義「什麼可以做、什麼不可以做、做了要留什麼證據」。

⚠️ 治理層必須在 Pilot 之前就存在（至少是簡化版）。等到全面推廣才補治理，會面臨「既有做法無法回收」的困境。

4.3.2 供應層（Provider & Gateway）【官方】

職責：決定 Claude Code 向哪裡取得模型能力、由誰計費、繼承誰的法遵與合規姿態。

這是 v2.0 新增的一層，也是最早必須決定、且最難事後更改的一層。

⚠️ 這是不可逆決策。Provider 決定了哪些功能永遠不可用。例如選擇 Bedrock，就等於放棄官方 Analytics Dashboard——而第 31～33 章整套度量體系有一半建立在它之上。請在 Pilot 之前就完成這個決策，完整決策樹見第 47 章。

📌 混合部署是常見解：組織可讓多數開發者走 Claude 訂閱，特定受監管專案走 Bedrock。此時 Managed Settings 必須同時部署 Server-managed（給 claude.ai 使用者）與檔案／registry 版本（給其他使用者），否則部分人員不受政策管控。

4.3.3 平台層（Claude Code Team Platform）

職責：帳號、席位、權限、使用分析，以及組織政策的技術下發。

📌 截至 2026-09-24，Claude Code 包含於每個 Team 方案席位中；席位與用量的具體管理位於 Organization settings。詳見第 5 章。

🎯 Managed Settings 是本架構中「治理層」與「執行層」之間唯一的技術橋樑。 沒有它，治理層寫的所有政策都只是文件——工程師可以在自己機器上用 .claude/settings.local.json 全部覆寫掉。

4.3.4 資產層（Company AI Repository）

職責：組織的 AI 工程資產集中管理。這是本架構中最容易被忽略、但長期價值最高的一層。

company-ai-development/          ← 企業唯一的 AI 工程資產來源
├── agents/       16 個標準 Agent
├── rules/        12 份規則
├── commands/     14 個標準 Command
├── skills/       30+ Skill Catalog
├── hooks/        安全與品質 Hook
├── plugins/      內部 Plugin
└── templates/    21 份範本

完整目錄結構與各目錄用途見第 7 章。

🎯 判斷 AI 導入是否成功的一個簡單指標：這個 repo 在半年後有沒有長大。 沒長大，代表知識沒有沉澱，每個專案都在重新發明輪子。

4.3.5 執行層（Execution Surfaces）

職責：Claude Code 實際被使用的各個介面。風險等級的關鍵判準是「出事時人在不在現場」。

📌 截至 2026-09-24，各介面的使用共用同一組方案額度。這表示成本管理不能只看其中一個介面（第 31 章）。

⚠️ CI/CD 與 Cloud Session 上的 Agent 必須使用獨立的、權限最小化的憑證，絕不可沿用開發者個人憑證。詳見第 20、23、48 章。

⚠️ 「人不在場」的介面必須先完成核准邊界設計才可開放。第 16 章的 Approval Matrix 原本假設「工程師會看到每一步」，這個假設在 Cloud Session 與 CI 上並不成立。第 48 章提供替代的控制設計。

4.3.6 專案層（Development Repository）

職責：讓 Agent 理解「這個專案的規矩」。

my-project/
├── CLAUDE.md                 ← 專案的 AI 行為契約（第 8 章）
├── .claude/
│   ├── agents/               ← 專案特有 Agent（覆寫或擴充企業版）
│   ├── commands/             ← 專案特有 Command
│   ├── skills/               ← 專案特有 Skill
│   ├── settings.json         ← 專案共用設定（進版控）
│   └── settings.local.json   ← 個人設定（加入 .gitignore）
├── docs/
│   └── ai/                   ← AI 產出的 Artifact 存放處（第 15 章）
└── src/

✅ 建議：.claude/settings.json 進版控、.claude/settings.local.json 加入 .gitignore。前者是團隊共識，後者是個人偏好。

4.3.7 流程層（SSDLC）

職責：定義每個開發階段中，人與 AI 各自做什麼、要留什麼證據。

完整的 13 階段 × 7 欄矩陣見第 14 章。

4.3.8 工具層（Tools & Integrations）

職責：Agent 可以接觸的外部系統。這是安全控制的重點區域。

4.4 架構落地的優先順序

七層不必同時建置。建議順序如下：

flowchart LR
    S1["階段 1<br/>平台層 + 最小治理<br/>（第 5、6、23 章）"]
    S2["階段 2<br/>專案層<br/>（第 8 章 CLAUDE.md）"]
    S3["階段 3<br/>資產層<br/>（第 7、9～13 章）"]
    S4["階段 4<br/>流程層<br/>（第 14～22 章）"]
    S5["階段 5<br/>完整治理 + 衡量<br/>（第 29～37 章）"]

    S1 --> S2 --> S3 --> S4 --> S5

    style S1 fill:#d4edda
    style S5 fill:#fff3cd

⚠️ 不要把階段 3（資產層）延後太久。每晚一個月，就多一個月的「重複造輪子」與「各自為政」。

4.5 架構決策紀錄（ADR）的必要性

Agent 會做出很多技術決策。若不記錄，三個月後沒有人知道「為什麼當初這樣設計」。

建議做法：所有由 Agent 參與的架構決策，一律產出 ADR，存放於 docs/adr/。

# ADR-012：交易查詢採用 CQRS 讀寫分離

- **狀態**：已採納
- **日期**：2026-09-17
- **決策者**：架構師 王小明（人）
- **AI 參與方式**：Architect Agent 提供 3 個方案與權衡分析
- **AI 產出檔案**：docs/ai/2026-09-17-architect-cqrs-options.md

## 背景
交易明細查詢的 P95 延遲為 2.8 秒，超過 SLA 的 1.5 秒。

## 考量的方案
1. 加索引（AI 評估：改善有限，預估降至 2.1 秒）
2. 加快取（AI 評估：資料一致性風險）
3. CQRS 讀寫分離（AI 評估：改善大，但增加運維複雜度）

## 決策
採用方案 3。

## 人類覆核紀錄
- AI 原始建議為方案 2，理由是「實作成本低」。
- 架構師駁回：AI 未考慮本行的交易一致性法規要求。
- **這是 AI 知識邊界的典型案例，已回饋至 rules/architecture.md。**

## 後果
- 需新增讀取模型同步機制
- 運維需監控同步延遲

🎯 「人類覆核紀錄」是這份範本最有價值的欄位。它記錄了 AI 判斷錯誤的地方，這些紀錄會成為第 27 章知識回饋循環的原料。

4.6 方案功能矩陣：架構決策前必須先看的一張表

📌 本節為 v2.0 新增。截至 2026-09-24，依 Anthropic 官方 Feature availability 頁面整理。功能可用性會隨版本變動，導入前請重新查證。

架構設計最容易犯的錯，是先畫好架構圖，才發現貴組織的方案根本沒有那個功能。下表是動手之前應先確認的清單。

4.6.1 依訂閱方案（以 claude.ai 帳號登入時）【官方】

⚠️ SCIM 的文件不一致（v2.1 新增）：截至 2026-09-24，「What is the Team plan」支援頁的功能清單列有「SCIM support」；但 Feature availability 頁、「Set up JIT or SCIM provisioning」頁（明文：SCIM provisioning is available for Enterprise and Console organizations only）與 Enterprise 方案頁三處都寫 SCIM 為 Enterprise 專屬。本手冊以三處一致的說法（Team 無 SCIM）作為規劃基準，並列入 C.3。若 Team 方案的 JML 自動化設計仰賴 SCIM，必須先取得 Anthropic 書面確認。

⚠️ 「內建起始權限模式」是 v2.1 最重要的新增事實【官方】：自 2026-08-14 起，Pro、Max、Team 方案在終端機與 VS Code 擴充中，新 session 的內建起始模式是 Auto Mode；Enterprise、Console API key 與第三方雲端 Provider 則是 Manual（設定值 default）。Team 方案若沒有部署任何 Managed Settings，全組織預設就是由分類器代替人審核動作。治理意涵見第 16 章 16.5 與第 49 章 49.5。

這張表對架構決策的四個直接影響：

1. 若組織需要 SCIM 自動化人員異動（第 5 章 JML 流程），以目前多數官方文件的說法，Team 方案做不到，必須走 Enterprise。這會直接改變第 5 章的席位管理設計。Team 方案可改用 JIT＋IdP 群組對應做到「半自動」（第 5 章 5.6.3）。
2. 若組織需要程式化取得用量資料來建自己的 Dashboard（第 33 章），Team 方案沒有 Analytics API，只能靠 CSV 匯出或 OpenTelemetry。
3. 若法遵要求 ZDR，必須是 Enterprise 且通過 Anthropic 資格審核；且開啟 ZDR 後 Contribution 指標、Code Review、Ultrareview 都不可用（第 21、31 章），度量體系需改用 OpenTelemetry 重建。
4. 若組織要依角色限制模型或 effort（例如「一般成員不可用 Opus」），Team 方案沒有 admin console 的伺服器端管控，只能以 Managed Settings 的 availableModels、enforceAvailableModels、maxEffortLevel 在用戶端強制（第 5 章 5.5.6、第 49 章 49.4）。

4.6.2 依 Provider（以認證方式區分）【官方】

所有 Provider 都支援的核心能力：CLI、Agent SDK、VS Code 與 JetBrains 擴充、Subagents、Hooks、Commands、Skills、CLAUDE.md、Plugins、MCP、Checkpoints、Sandboxing、Workflows、OpenTelemetry metrics、檔案式 Managed Settings。

差異集中在下列項目：

^※ 指 Cloud sessions、Desktop、行動 App、Slack、Routines、Ultrareview、Code Review、Remote Control、Chrome 擴充、Computer use、Artifacts、語音輸入等。

⚠️ 最常見的規劃失誤：組織為了「繼承 AWS 合規控制」而選 Bedrock，卻同時在第 31～33 章規劃了以官方 Analytics Dashboard 為核心的度量體系——這兩件事互斥。走 Bedrock 就必須從第一天起以 OpenTelemetry 自建度量（第 33 章提供對應設計）。

📌 混合部署的政策覆蓋缺口：Server-managed settings 只到得了 claude.ai 與 Console 使用者。若組織有人走 Bedrock/Vertex/Foundry，必須額外部署檔案式或 registry 版本的 Managed Settings，否則這群人完全不受組織政策管控。詳見第 49 章。

4.7 本章實務案例

情境：某組織在導入第 4 個月時，發生「用量費用比預期高 3 倍」的事件。

當時的架構狀態：

調查發現的三個主因：

1. 沒有 CLAUDE.md → Agent 每次都要重新探索專案結構，單次任務平均多讀 40 個無關檔案。
2. 沒有標準 Command → 同仁自由發揮 prompt，常常一次交付過大的任務，導致 Agent 反覆試錯。
3. 沒有 /clear 習慣 → 同一個 session 連續做 8 個不相關的任務，上下文累積到極大。

修正措施與效果：

🎯 成本失控通常不是「用太多」，而是「用得沒有結構」。 架構層的建置本身就是最有效的成本控制手段。

4.8 本章注意事項

⚠️ 不要在沒有治理層的情況下開放 CI/CD 執行 Agent。無人監督 + 高權限 = 最高風險組合。

⚠️ 資產層的擁有權必須明確。若 company-ai-development 沒有明確 owner，它會在三個月內變成沒有人維護的垃圾場。建議由 AI Governance 小組擔任 owner，各專案以 PR 貢獻（第 7、27 章）。

📌 架構圖不是一次畫完就不動。建議每季度依實際狀況更新一次，並在第 28 章的月度社群中檢視。

📌 本章的七層架構是建議參考模型。若貴組織已有既有的 IT 架構治理框架（如 TOGAF），應將本架構對映進去，而非另起爐灶。

4.9 本章檢查清單

• 我理解七層架構各自的職責
• 我的組織已確定「治理層」的負責單位
• 我的組織已確定「資產層」repo 的 owner
• 我知道三個執行介面（IDE / CLI / CI）的風險差異
• 我知道 CI/CD 上的 Agent 必須用獨立最小權限憑證
• 我的組織有架構落地的優先順序與時程
• 我的組織已決定 ADR 的存放位置與格式

第 5 章　Team 組織、席位與權限管理

本章目錄：5.1 本章要建立什麼 ｜ 5.2 Team 與 Enterprise 方案的基本事實 ｜ 5.3 角色體系與職責設計 ｜ 5.4 席位配置策略：誰該拿 Premium ｜ 5.5 用量額度與成本治理 ｜ 5.6 身分整合：HR → IAM → SSO → Claude ｜ 5.7 JML 流程（Joiner / Mover / Leaver） ｜ 5.8 本章實務案例 ｜ 5.9 本章注意事項 ｜ 5.10 本章檢查清單

5.1 本章要建立什麼

本章要完成三件事：

1. 把 Anthropic 組織的角色與席位，對應到企業既有的組織與權限體系
2. 建立 JML（Joiner / Mover / Leaver） 標準流程
3. 建立席位配置與用量預算的決策依據

📌 本章所有方案、席位、定價、用量相關敘述皆為「截至 2026-09-24」的查證結果，Anthropic 可能隨時調整。實際導入請以官方最新文件與貴組織合約為準。

5.2 Team 與 Enterprise 方案的基本事實

5.2.1 Team 方案已查證的事實（截至 2026-09-24）【官方】

📌 「1.25 倍 / 6.25 倍」該怎麼用：這是相對於 Pro 方案單一 session 的倍率，不是絕對 token 數。它可用於相對比較（Premium 約為 Standard 的 5 倍），但不足以據此推算絕對用量預算——因為 Pro 的基準值本身未公開。編列預算請以 Pilot 實測值為準（第 25 章），不要用倍率反推。

5.2.2 Enterprise 方案的差異（架構決策相關）【官方】

若組織有下列任一需求，Team 方案無法滿足，必須走 Enterprise：

Enterprise 的席位形態（v2.1 依 Enterprise 方案頁更新）：

用量計費型的 Enterprise 方案沒有每席位用量上限，而是依實際消耗以 API 費率計費。這種方案的預算控制邏輯與席位制完全不同，第 29～33 章的成本管理設計需相應調整。官方 consumption guide 的原則是「先保守設限，依申請再調高」——調高上限比事後處理超支容易得多。

⚠️ Team 與舊版 Enterprise 客戶的續約風險【建議】：若目前是舊版席位制 Enterprise，續約後會轉為用量計費，第 5.4 節的席位配置策略、第 32 章月報中的成本欄位、第 29 章的成本 KPI 都要重新設計。請在續約前 1～2 季開始以 OpenTelemetry 蒐集實際 token 用量作為議價與預算依據。

⚠️ HIPAA 相關的重要限制【官方】：官方於 2026-06-11 更新說明，HIPAA-ready 的 Enterprise 方案，其 HIPAA 涵蓋範圍不包含 Claude Code，即使席位已內含 Claude Code。醫療照護或處理 PHI 的組織，不可假設 Claude Code 受既有 BAA 保護。導入前必須與法務及 Anthropic 窗口逐項確認，詳見第 23、36 章。

5.2.3 Analytics API 的可得性（v1.0.0 標示為「待確認」，v2.0 已查證）【官方】

v1.0.0 將「Analytics 是否提供 API 介接」列為待確認。截至 2026-09-24 已可確認：

🎯 這件事會直接決定第 33 章管理 Dashboard 的建置方式。 Team 方案沒有 API，自動化報表只有兩條路：官方 CSV 匯出（人工、每月）或 OpenTelemetry 匯出（自動、即時）。若組織要做自動化 Dashboard 又只有 Team 方案，OpenTelemetry 是唯一實務解（第 31、33 章）。

5.2.4 仍未查證、不得虛構的項目

⚠️ 下列項目本手冊刻意不填，請導入時向 Anthropic 業務窗口確認並補上：

⚠️ 「支出上限＝硬性阻擋」對衝刺期的影響【建議】：v2.0 將此列為待確認並建議實測。v2.1 已查證為硬性阻擋，因此必須事先設計「緊急放行」程序：由誰（Owner／Primary Owner）、在多長時間內（建議 1 個工作小時內）、依什麼條件（專案經理書面申請＋部門主管核准）調高個人上限；並在第 32 章月報中揭露每次放行紀錄。

5.2.5 官方文件不一致與本手冊採用的規劃基準（v2.1 新增）【⚠️ 文件不一致】

🎯 處理文件不一致的原則：(1) 以「多數且較新的技術文件」為規劃基準；(2) 把差異列入 C.3；(3) 凡會影響稽核控制設計的項目，一律向 Anthropic 窗口取得書面確認後才寫進內規。

5.3 角色體系與職責設計

5.3.1 角色對應

Anthropic 組織提供角色型權限。企業必須先把這些角色對應到自己的組織職務，否則會出現「誰都能改設定」或「沒人能改設定」兩種極端。

📌 官方文件描述為「角色型權限，可自訂存取層級並控制整個組織的使用者權限」，但未逐一列出角色名稱清單。下表的角色名稱以 Analytics 文件中出現的用詞（Primary Owner / Owner / Admin / Member）為準，實際可用角色需依貴組織方案與後台實際畫面確認。

📌 v2.1 補充：IdP 群組對應時使用的角色名稱【官方】。依「Set up JIT or SCIM provisioning」支援文件，IdP 群組可對應到的角色為 Owner、Admin、User、Custom（「User」即上表的 Member）。其中 Custom（自訂角色）為 Enterprise 專屬；Primary Owner 不透過群組對應指派。另外，只有 Primary Owner 能啟用 Enterprise Analytics API，且 Enterprise 的 Admin 看不到 Spend 區塊——這兩點在設計「誰能看成本」時必須納入。

⚠️ Primary Owner 只能有一位，且必須有明確的代理人安排。若該人員離職或長假，組織會無法處理計費與席位問題。建議在企業內規中明訂代理機制。

【⚠️ 文件不一致】 截至 2026-09-24，Anthropic 官方兩處文件對 Analytics 檢視權限的描述並不一致：

來源	描述
Support 文章〈View usage analytics for Team and Enterprise plans〉	Team 方案僅 Owner 與 Primary Owner；Enterprise 方案另含 Admin，但 Admin 看不到 Spend
官方文件〈Track team usage with analytics〉	「Admins and Owners 可檢視儀表板」，未區分方案

兩者可能指涉不同的頁面（組織分析設定頁 vs Claude Code 分析儀表板），但官方未明確說明。

⚠️ 本手冊的處理原則：第 31～33 章「誰能看報表」的設計一律以較嚴格的 Support 文章版本為準（即假設 Team 的 Admin 看不到），並在導入時於貴組織後台實測確認。切勿在未實測的情況下，對管理階層承諾某個角色看得到某張報表。

5.3.2 權責分離（Segregation of Duties）

金融業通常有權責分離要求。建議設計：

⚠️ 最後一列很重要。個人層級的使用資料屬於員工個人資料，匯出與使用方式必須符合貴組織的個資政策。第 30 章會詳述。

5.4 席位配置策略：誰該拿 Premium

Standard 與 Premium 的價差約 5 倍，用量差距約 5 倍（1.25x vs 6.25x，截至 2026-09-24）。因此問題不是「誰比較重要」，而是**「誰的工作型態會大量消耗用量」**。

5.4.1 用量消耗的主要驅動因子

flowchart TD
    Usage["用量消耗量"] --> F1["任務規模<br/>（跨檔數量）"]
    Usage --> F2["Repository 大小<br/>（搜尋成本）"]
    Usage --> F3["模型選擇<br/>（Opus > Sonnet > Haiku）"]
    Usage --> F4["迭代次數<br/>（測試失敗重試）"]
    Usage --> F5["使用頻率<br/>（每日 session 數）"]

    F1 --> High["高消耗工作型態"]
    F2 --> High
    F3 --> High
    F4 --> High

    High --> P1["Legacy 逆向工程"]
    High --> P2["框架升版"]
    High --> P3["大規模重構"]
    High --> P4["架構分析"]

    style High fill:#ffe6cc

5.4.2 席位配置決策表

5.4.3 席位配置的動態調整機制

✅ 建議：不要一次配置到位，採用「先給 Standard、依實測升級」的策略。

flowchart LR
    A["新成員<br/>預設 Standard"] --> B["使用 1 個月"]
    B --> C{"是否頻繁<br/>觸及用量上限？"}
    C -->|否| D["維持 Standard"]
    C -->|是| E{"是否為高消耗<br/>工作型態？"}
    E -->|是| F["升級 Premium"]
    E -->|否| G["先做使用方法輔導<br/>（第 30 章）"]
    G --> H{"輔導後仍觸及上限？"}
    H -->|是| F
    H -->|否| D

    style G fill:#fff3cd

⚠️ 注意 E → G 這條路徑。頻繁觸及上限不一定代表工作量大，也可能代表使用方法有問題（不清除上下文、任務切得太大、該用 Haiku 卻用 Opus）。直接升級 Premium 等於用錢掩蓋問題。

5.5 用量額度與成本治理

5.5.1 三層防線

flowchart TB
    L1["第 1 層：使用方法<br/>（個人・行為）"] --> L2["第 2 層：預算與監控<br/>（團隊・偵測）"]
    L2 --> L3["第 3 層：credits 與支出上限<br/>（組織・強制）"]
    L3 --> L4["第 4 層：技術強制<br/>（組織・Managed Settings）"]

    L1 --> L1D["/clear、/compact、/cost<br/>模型分級、精簡 CLAUDE.md<br/>先出計畫再執行"]
    L2 --> L2D["月度用量檢視<br/>OpenTelemetry 即時告警<br/>Team Lead 輔導"]
    L3 --> L3D["是否啟用 credits<br/>組織 / 個人支出上限<br/>超額核准流程"]
    L4 --> L4D["availableModels 限制可用模型<br/>maxEffortLevel 限制推理強度<br/>Gateway per-user spend limit"]

    style L1 fill:#d4edda
    style L2 fill:#fff3cd
    style L3 fill:#f8d7da
    style L4 fill:#e7d4f0

📌 v2.0 變更：新增第 4 層。前三層都依賴「人會遵守」或「事後發現」，第 4 層則是機器直接擋下來。經驗上，只有第 1～3 層的組織，成本失控事件仍會週期性發生（見 4.7 本章實務案例）。第 4 層的設定細節見第 49 章。

5.5.2 第 1 層：官方建議的成本節約習慣（截至 2026-09-24）

官方在「Models, usage and limits in Claude Code」中提出五項習慣，本手冊將其轉化為可執行的團隊規範：

5.5.3 模型選擇指引

📌 官方立場：Claude Code 可用的模型會隨時間變動，官方明確表示 /model 指令是唯一的真實來源。下表以**模型別名（alias）**為主軸，版本代號只作為「截至查證日」的參考，實際可用模型請在貴組織環境執行 /model 確認。

v2.1 重大更新：預設模型與模型陣容已經改變【官方】。截至 2026-09-24，官方 Model configuration 頁面所列，以 Claude 訂閱（Pro／Max／Team Standard／Team Premium／Enterprise）登入時，/model 的 Default 選項為 Opus 5.5，且 Opus 5.5 的預設 effort 為 medium（其他支援 effort 的模型預設為 high）。v2.0 所寫的「Sonnet 為預設」已不再成立。

⚠️ Fable 的計費陷阱【官方】：在部分方案上，Fable 的用量計入 usage credits。互動式 session 會先顯示同意提示；但 -p 非互動模式會直接計費、不會詢問；使用組織計費的 Enterprise 成員也不會看到提示。若組織在 CI 或排程腳本（第 48 章）中寫了 --model fable 或 best，可能在沒有任何人察覺的情況下持續消耗 usage credits。建議以 availableModels 在 CI 環境排除 fable（第 49 章 49.4），並列為風險 R-31（第 37 章）。

⚠️ 第三方 Provider 的別名解析不同：sonnet 在 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 上解析為 Sonnet 4.5，在 Claude Platform on AWS 上解析為 Sonnet 4.6；Microsoft Foundry 的預設模型也與訂閱方案不同。混合 Provider 的組織，同一份團隊規範在不同 Provider 上會跑到不同模型，需以 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL 等環境變數釘選版本（第 47 章）。

effort（推理強度）分級【官方】：

另有特殊等級 ultracode（claude --effort ultracode 或 /effort ultracode）：以 xhigh 搭配 dynamic workflows 一次協調大量 subagent。它的 token 消耗遠高於一般 session，組織停用 workflows 或 effort 上限低於 xhigh 時即不可用。

團隊規範建議【建議】：

## 模型使用規範（v2.1）

1. **日常開發使用 `sonnet`**。Team Standard 席位的額度只有 Pro 的 1.25 倍，
   若沿用官方預設的 Opus 5.5，額度會明顯較快耗盡（見 5.5.6 的預設模型設定）。
2. **使用 `opus` 或 `opusplan` 的條件**（需符合任一）：
   - 影響 3 個以上模組的架構決策
   - 超過 50 個檔案的重構規劃
   - Legacy 系統的商業規則抽取
   - 框架升版的相容性分析
3. **使用 `fable` 的條件**：需 Tech Lead 事前同意，且只能在互動式 session 使用；
   **禁止在 CI、排程、`-p` 腳本中使用 `fable` 與 `best`**。
4. **使用 `haiku` 的條件**：單檔、無跨檔影響的機械性修改；subagent 可預設 `haiku`。
5. **effort 預設不超過 `high`**；`xhigh`、`max`、`ultracode` 限架構與升版任務使用。
6. **Opus／Fable 的使用需在 PR 描述中說明理由**（供第 31 章成本分析使用）。

✅ 以「推理強度（effort level）」做更細的成本控制【官方】。除了換模型，組織可用 maxEffortLevel 設定 effort 上限（全域或逐模型、所有 Provider 皆適用）。這比「禁止使用 Opus」更精細——允許使用高階模型但限制其推理深度。Enterprise 方案另可在組織後台設定「依角色、依模型的 effort 上限」，由伺服器端強制（v2.1.195+）。完整的模型治理設計見 5.5.6 與第 49 章 49.4。

5.5.4 第 3 層：usage credits 與支出上限政策

截至 2026-09-24，席位制方案在成員達到內含額度後，組織可選擇啟用 usage credits 讓成員繼續工作。此外，Team 方案已支援在組織層級與個人層級設定支出上限（spend cap）。

企業必須事先決定以下政策，不要等到有人被擋住才臨時決定：

⚠️ 支出上限觸及後的行為（v2.1 已查證）【官方】：硬性阻擋。成員「在下一個計費週期之前，或上限被調整之前，無法再使用 Claude、Cowork 或 Claude Code」。因此必須事先規劃「衝刺期緊急放行」的作業程序（見 5.2.4 的建議），否則會在最忙的時候讓整個團隊停擺。Pilot 期間仍建議以低額度實測一次，確認通知路徑與放行時效。

支出上限的層級與設定位置（v2.1 補充）【官方】：

成員端的可見性：成員執行 /usage 可看到自己本月的 usage credits 花費與適用於自己的上限（組織層級的上限不會顯示）；沒有帳單權限的成員執行 /usage-credits 時，只會送出申請給管理員（互動模式下會先確認；-p 模式與 Remote Control 不送出）。另可用 /insights 產生個人使用模式的 HTML 報告（第 30 章）。

📌 哪些功能一定走 usage credits【官方】：Code Review（平均每次 $15–25）、Ultrareview（Team／Enterprise 沒有免費次數，每次約 $5–25）與部分方案上的 Fable 模型，不消耗席位額度，而是直接計入 usage credits。若組織沒有啟用 usage credits，這些功能就無法使用；若啟用了，這些用量會和一般超額混在同一份支出報表，第 32 章月報需拆開呈現（第 21 章 21.5.2、第 37 章 R-31）。

⚠️ 成本分析的重大盲點：截至 2026-09-24，對於席位制方案且啟用 usage credits 的組織，匯出的花費報表只反映超出席位額度的花費，不包含席位內含的用量。

這代表：一個「花費報表為 $0」的使用者，可能是完全沒用，也可能是用好用滿但剛好沒超額——兩者在報表上無法區分。若要看到完整用量（含席位內含的部分），必須改用 OpenTelemetry 匯出（第 31 章）。第 30 章「個人使用率管理」若誤用花費報表作為使用率指標，會得到完全錯誤的結論。

5.5.5 成本治理的責任分工

🎯 成本失控幾乎從來不是「模型太貴」，而是「使用方法不對」。第 30 章會說明：頻繁觸及上限的使用者，通常是不清除上下文、任務切得太大、或該用低階模型卻用高階模型——直接提高額度等於用錢掩蓋問題。

5.5.6 組織層級的模型與 effort 管控（v2.1 新增）【官方】

v2.1 查證後，模型治理已經從「寫在規範裡請大家遵守」變成「可以技術強制」。依方案不同，可用的管控手段分成兩條路：

📌 Enterprise admin console 的模型管控，到不了 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 與 Claude Platform on AWS 的 session。混合 Provider 的組織，必須兩條路一起做。

Team 方案的建議設定（依席位分級）【建議】：

⚠️ Team 的 Server-managed settings 是「全組織一份」。若要依席位或專案套用不同模型政策，需搭配檔案式或 MDM 版本的 Managed Settings 依裝置群組投遞（第 49 章 49.3）；或者乾脆以「Standard 預設 sonnet」作為全組織預設，Premium 成員再自行切換。

🎯 模型治理的正確順序：先以 Pilot 資料（第 25 章）確認各類任務在不同模型與 effort 下的品質差異，再設上限。沒有資料就先鎖死 Opus，常見結果是「成本省了，但架構類任務的重工成本更高」。

5.6 身分整合：HR → IAM → SSO → Claude

5.6.1 整體流程

flowchart TB
    HR["HR 系統<br/>（人員異動來源）"] --> IAM["企業 IAM<br/>（AD / LDAP / IdP）"]
    IAM --> SSO["SSO<br/>（SAML / OIDC）"]
    SSO --> PROV["User Provisioning<br/>（JIT 或批次）"]
    PROV --> TEAM["Anthropic Organization"]
    TEAM --> ROLE["角色指派<br/>Owner / Admin / Member"]
    ROLE --> SEAT["席位指派<br/>Standard / Premium"]
    SEAT --> PROJ["專案 / Repository 授權"]
    PROJ --> CC["Claude Code 可用"]

    HR -.離職觸發.-> DEPROV["Deprovisioning"]
    DEPROV -.立即.-> TEAM

    style HR fill:#d1ecf1
    style DEPROV fill:#f8d7da

📌 v2.0 更新：截至 2026-09-24，Team 方案提供 SSO、JIT provisioning、網域擷取（domain capture） 與角色型權限；SCIM 為 Enterprise 方案專屬【官方】。

這對本節流程設計有直接影響：

方案	人員異動如何反映到 Claude 組織	對 JML 流程的意義
Team	無 SCIM（官方文件有不一致，見 5.2.5）。新進靠 SSO/JIT 自動建立；JIT＋群組對應可在下次登入時更新角色與席位等級（5.6.3）；離職必須人工處理	5.7 節的 Leaver 流程必須有人工檢核點與月度對帳，否則席位會殘留
Enterprise	SCIM 可由 IdP 自動同步建立、更新、停用	可自動化，但仍建議保留季度對帳

⚠️ Team 方案最常見的稽核缺失就是「離職人員席位未釋出」，根因正是沒有 SCIM 而流程又只靠人記得。5.7.3 節的月度對帳機制在 Team 方案是必要控制，不是選配。

5.6.2 網域擷取的注意事項

「網域擷取」可讓使用企業信箱網域註冊的使用者自動納入組織管理。

⚠️ 啟用前必須先盤點：組織內是否已有同仁用公司信箱註冊了個人付費帳號？啟用網域擷取可能影響這些既有帳號。請先發公告並給予緩衝期。

5.6.3 以 IdP 群組對應角色與席位等級（v2.1 新增）【官方】

v2.1 查證發現：JIT 與 SCIM 都支援「群組對應（group mapping）」，而且在 Team 與席位制 Enterprise 上，群組除了能對應角色，還能對應席位等級（Premium／Standard）。這讓沒有 SCIM 的 Team 方案也能做到「半自動」的 JML。

Team 方案的建議群組設計【建議】：

⚠️ JIT 的關鍵限制：「下次登入才生效」。對 Joiner 與 Mover（升降席位）來說這已經夠用；但對 Leaver 而言，從 IdP 移除群組並不會立即讓 Claude 組織中的成員消失——已登入的 session 與既有成員資格仍會存在，直到管理員手動移除。因此：

1. Leaver 仍必須人工「移除組織成員＋釋出席位」（5.7.3），並保留月度對帳；
2. 席位降級（Premium → Standard）的生效時間要以「下次登入」計算，財務月結時請留意跨月情形；
3. 群組對應的規則本身屬於權限設定，其變更應走 AI Governance 的變更流程，並納入季度稽核（附錄 A.14）。

📌 SSO 啟用前的注意事項：官方另有一篇「啟用 SSO 與 JIT／SCIM 前的重要考量」支援文件（support.claude.com/en/articles/10276682），涵蓋既有帳號轉移、網域驗證與緊急存取。請在 Pilot 前由 IAM 團隊逐項確認。

5.7 JML 流程（Joiner / Mover / Leaver）

這是資安稽核必查項目。以下提供可直接採用的 SOP。

5.7.1 Joiner（到職 / 加入專案）

sequenceDiagram
    participant HR as HR 系統
    participant IAM as 企業 IAM
    participant ADM as Claude Admin
    participant TL as Team Lead
    participant U as 新成員

    HR->>IAM: 建立帳號（含部門、職務）
    IAM->>ADM: 通知需開通 Claude
    TL->>ADM: 提出席位申請（含席位類型與理由）
    ADM->>ADM: 檢查席位餘額
    ADM->>U: 發送組織邀請
    U->>U: SSO 登入 + 執行 claude 完成 OAuth
    TL->>U: 指派必修訓練（第 24 章 Workshop 1-3）
    U->>TL: 完成訓練評量
    TL->>ADM: 確認可存取專案 Repository
    Note over U: 開始使用

Joiner 檢查清單：

• HR 系統已建立人員資料
• 企業 IAM 帳號已開通
• 席位申請已核准（含席位類型理由）
• 組織邀請已發送並接受
• 已完成 SSO 登入與 Claude Code OAuth 授權
• 已完成必修訓練（Workshop 1～3）
• 已簽署 AI 使用規範同意書（第 23 章）
• 已取得所需 Repository 權限
• 開發環境已依第 6 章標準完成設定
• Team Lead 已說明專案的 CLAUDE.md 與 Rules

5.7.2 Mover（部門 / 專案異動）

最容易被遺漏的環節。人員異動後，舊專案的 Repository 權限常常沒有回收。

⚠️ 特別注意本機殘留：使用者本機可能存有舊專案的 MCP 設定、API token、資料庫連線字串。Mover 流程必須包含「本機環境清理」這一步，且需要使用者自行確認（因為管理端看不到本機檔案）。

5.7.3 Leaver（離職）

⚠️ 席位釋出必須在當日完成，否則會產生無謂費用，且是稽核缺失。建議設定月度對帳機制（5.3.2 節）。

5.8 本章實務案例

情境：某組織導入 6 個月後接受內部稽核，稽核發現三項缺失。

缺失 1：席位與在職人員不符

• 稽核發現：組織內有 62 個席位，但在職且需使用的人員只有 55 人。
• 根因：5 位離職同仁的席位未釋出，2 位轉調同仁的 Premium 未降級。
• 影響：每月無謂支出約 $400（依 5.2.1 定價估算）。
• 改善：建立 5.7.3 的 Leaver 當日流程 + 每月第一個工作日的對帳機制。

缺失 2：無法說明誰有 Analytics 檢視權

• 稽核發現：組織說不出「目前有哪些人可以看到個人層級的使用資料」。
• 根因：Owner 角色曾為了方便，一次給了 6 個人。
• 影響：個人資料存取範圍過大，違反最小權限原則。
• 改善：Owner 縮減至 3 人（5.3.1 節），並建立 5.3.2 的權責分離表。

缺失 3：離職人員的本機仍可能殘留 MCP 憑證

• 稽核發現：Leaver 流程未涵蓋本機環境清理。
• 根因：只想到「雲端帳號要停用」，沒想到「本機設定檔中的憑證」。
• 影響：潛在的憑證外洩風險。
• 改善：Leaver 流程新增「本機 .claude/ 目錄清理確認」步驟，並由資安在裝置回收時驗證。

🎯 三項缺失的共通點：都是「開通很積極、回收很隨便」。JML 流程中，L（Leaver）是最重要但最常被忽略的一環。

5.9 本章注意事項

⚠️ 不要用「使用量」作為席位升級的唯一依據。先確認不是使用方法問題（5.4.3 節的 G 路徑）。

⚠️ 個人層級的 Analytics 資料屬於員工個人資料。存取、匯出、保存都必須符合貴組織個資政策與勞動法規。務必先諮詢法遵與 HR（第 30 章）。

⚠️ Primary Owner 必須有代理人安排，並在企業內規中明訂。

📌 所有方案 / 定價 / 用量數字皆為截至 2026-09-24 的查證結果。Anthropic 可能調整，請以官方最新文件為準，並建議每季度複查一次。

📌 待確認事項清單（5.2.2 節）請務必在正式簽約前向 Anthropic 業務窗口確認，不要依賴本手冊或任何二手資料。

5.10 本章檢查清單

• 已確認 Team 方案的席位數需求與上限（最多 150）
• 已完成 Anthropic 角色與企業職務的對應表
• Primary Owner 已指定，且有代理人安排
• Owner 人數已控制在 2～3 人
• 已建立權責分離表（5.3.2 節）
• 已建立席位配置決策表與動態調整機制
• 已建立模型選擇規範（sonnet／opus／opusplan／haiku／fable，含 effort 上限）（v2.1 更新）
• 已確認官方預設模型（截至 2026-09-24 為 Opus 5.5）對 Standard 席位額度的影響，並決定是否以 Managed Settings 改預設（5.5.6）
• CI／排程環境已排除 fable 與 best，避免非互動模式靜默計入 usage credits（5.5.3）
• 已決定 usage credits 政策與月度上限
• 已建立「支出上限觸及＝硬性阻擋」的緊急放行程序（5.2.4、5.5.4）
• 已評估採用 JIT＋IdP 群組對應角色與席位等級（5.6.3）
• 已向 Anthropic 窗口書面確認 Team 方案是否支援 SCIM（5.2.5）
• 已完成 HR → IAM → SSO → Claude 的整合設計
• 網域擷取啟用前已盤點既有個人帳號
• Joiner / Mover / Leaver 三份 SOP 已文件化並生效
• 已建立每月席位對帳機制
• 個人層級 Analytics 的存取已取得法遵 / HR 同意
• 5.2.2 的「待確認事項」已向官方窗口確認

第 6 章　Claude Code 安裝與環境標準化

本章目錄：6.1 為什麼環境必須標準化 ｜ 6.2 企業標準開發環境定義 ｜ 6.3 Windows 標準安裝 SOP ｜ 6.4 macOS / Linux / WSL 標準安裝 SOP ｜ 6.5 企業標準設定檔 ｜ 6.6 環境驗收腳本 ｜ 6.7 隔離工作流程：git worktree ｜ 6.8 本章實務案例 ｜ 6.9 本章注意事項 ｜ 6.10 本章檢查清單

6.1 為什麼環境必須標準化

不標準化的後果很具體：

🎯 環境標準化不是為了整齊，是為了讓「治理設定」能真正被套用到每一台機器上。

6.2 企業標準開發環境定義

6.2.1 標準環境清單

📌 Claude Code 的安裝方式可能隨版本調整。請以官方安裝文件為準；本手冊不列出可能過時的安裝指令細節，改以「驗證方式」為主（6.6 節）。

6.2.2 四種平台的導入考量

⚠️ WSL 的常見陷阱：把專案放在 /mnt/c/Users/... 下，Agent 執行大量檔案搜尋時會慢數倍，導致任務逾時或成本暴增。務必放在 ~/projects/ 之類的 WSL 原生路徑。

⚠️ WSL 的治理陷阱（v2.0 新增）【官方】：WSL 內的 Claude Code 行程預設只讀取 Linux 路徑的 Managed Settings（/etc/claude-code/managed-settings.json），Windows 端的 registry 政策與 C:\Program Files\ClaudeCode\managed-settings.json 不會自動套用。

這代表：組織以為已對所有 Windows 機器下發政策，但只要工程師在 WSL 裡工作，政策就失效。解法是在 Windows 的管理員專用來源中設定 wslInheritsWindowsSettings: true。詳見第 49 章。

另需注意：WSL 2 utility VM 內的行程對 Windows 端的端點偵測（EDR）感測器不可見。若資安要求監看行程與檔案活動，需在發行版內另行部署 Linux 感測器。

6.2.3 執行介面（Surface）的標準化範圍【官方】

📌 v2.0 新增。v1.0.0 僅涵蓋 CLI 與 IDE，但 Claude Code 的介面已大幅擴張。組織必須明確宣告哪些介面「允許使用」，未宣告等同於默許。

🎯 「預設關閉、逐項開通」是本手冊對所有非互動式介面的一致立場。 理由見 2.3.13：這些介面讓 AI 在無人監看下執行，原本依賴工程師即時攔截的防線不存在。

6.2.4 應納入標準訓練的內建功能【官方】

下列功能可顯著降低成本與風險，但不主動教就不會有人用。建議納入第 24 章的必修 Workshop：

6.3 Windows 標準安裝 SOP

6.3.1 前置檢查

# 檢查作業系統版本
Get-ComputerInfo | Select-Object OsName, OsVersion, OsArchitecture

# 檢查 PowerShell 版本（需 7 以上）
$PSVersionTable.PSVersion

# 檢查 Git
git --version

# 檢查 Node.js（若採用 npm 安裝方式）
node --version
npm --version

# 檢查是否有企業 Proxy
[System.Net.WebRequest]::GetSystemWebProxy().GetProxy("https://api.anthropic.com")

6.3.2 企業網路設定

# 設定 Proxy（依貴組織實際 Proxy 位址調整）
[System.Environment]::SetEnvironmentVariable('HTTPS_PROXY', 'http://proxy.corp.local:8080', 'User')
[System.Environment]::SetEnvironmentVariable('HTTP_PROXY',  'http://proxy.corp.local:8080', 'User')
[System.Environment]::SetEnvironmentVariable('NO_PROXY',    'localhost,127.0.0.1,.corp.local', 'User')

# 若企業使用 TLS 攔截（SSL inspection），需信任企業根憑證
# 注意：以下為示意，實際憑證路徑需依組織環境決定
[System.Environment]::SetEnvironmentVariable('NODE_EXTRA_CA_CERTS', 'C:\corp\certs\corp-root-ca.pem', 'User')

⚠️ 絕對不要用 NODE_TLS_REJECT_UNAUTHORIZED=0 來「解決」憑證問題。這會關閉所有 TLS 驗證，是嚴重資安缺失。正確做法是安裝企業根憑證（如上）。

6.3.3 Git 設定（Windows 特別重要）

# 換行符處理：避免 AI 修改檔案後整份檔案被判定為變更
git config --global core.autocrlf input

# 支援長路徑（Windows 預設 260 字元限制）
git config --global core.longpaths true

# 大小寫敏感（避免 Windows 大小寫不敏感造成的檔名衝突）
git config --global core.ignorecase false

# 驗證
git config --global --list | Select-String "autocrlf|longpaths|ignorecase"

⚠️ core.autocrlf 設錯是 Windows 團隊最常見的災難。若設成 true，Agent 修改一個檔案後，git diff 可能顯示「整份檔案都變了」，導致 Code Review 無法進行。

6.3.4 防毒軟體白名單

企業防毒常會攔截 Claude Code 的檔案讀寫與程序啟動，造成執行極慢或失敗。

需向資安申請白名單的項目（實際路徑需依安裝方式確認）：

📌 申請白名單時，建議附上「效能影響實測數據」（開啟前後的任務完成時間對比），資安通常比較容易核准。

6.4 macOS / Linux / WSL 標準安裝 SOP

6.4.1 前置檢查

# 作業系統
uname -a

# Shell
echo "$SHELL"

# Git（需 2.40+）
git --version

# Node.js（若採 npm 安裝方式）
node --version

# 網路連通性（檢查是否被企業防火牆阻擋）
curl -I https://api.anthropic.com 2>&1 | head -5

6.4.2 企業網路設定

# 寫入 shell profile（zsh 用 ~/.zshrc，bash 用 ~/.bashrc）
cat >> ~/.zshrc <<'EOF'

# ===== 企業 Claude Code 環境設定 =====
export HTTPS_PROXY="http://proxy.corp.local:8080"
export HTTP_PROXY="http://proxy.corp.local:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.local"

# 企業根憑證（若有 TLS 攔截）
export NODE_EXTRA_CA_CERTS="$HOME/.certs/corp-root-ca.pem"
EOF

source ~/.zshrc

6.4.3 WSL 特別設定

# 1. 專案務必放在 WSL 原生檔案系統（效能關鍵）
mkdir -p ~/projects
cd ~/projects

# 2. 確認不是在 /mnt/c 下工作
pwd | grep -q '^/mnt/' && echo "⚠️ 警告：目前位於 Windows 掛載區，檔案操作會很慢！"

# 3. WSL 的 Proxy 常需指向 Windows 主機
#    取得 Windows 主機 IP（WSL2）
export WIN_HOST=$(ip route show default | awk '{print $3}')
echo "Windows host: $WIN_HOST"

# 4. Git 換行設定
git config --global core.autocrlf input

✅ 建議：在 WSL 的 ~/.bashrc 或 ~/.zshrc 加入上述第 2 點的檢查，讓同仁一進入錯誤目錄就看到警告。

6.5 企業標準設定檔

6.5.1 設定檔的五個層級與優先順序【官方】

📌 v2.0 重大更正：v1.0.0 只描述了三個層級（使用者／專案／個人專案），遺漏了最重要的一層——組織強制的 Managed Settings，也未說明命令列層級。更嚴重的是，v1.0.0 的圖示暗示「使用者層 → 專案層 → 個人層」是由弱到強，容易被誤讀。正確的優先順序如下（由高至低，高者勝出）：

flowchart TB
    M["1. Managed Settings（最高）<br/>組織強制政策<br/>Server-managed / MDM / plist / registry / 檔案"]
    C["2. 命令列<br/>claude --settings"]
    L["3. 個人專案層<br/>&lt;repo&gt;/.claude/settings.local.json<br/>（.gitignore）"]
    P["4. 專案共用層<br/>&lt;repo&gt;/.claude/settings.json<br/>（進版控）"]
    U["5. 使用者層（最低）<br/>~/.claude/settings.json"]

    M --> C --> L --> P --> U

    M --- MD["由組織決定<br/>工程師無法覆寫"]
    L --- LD["個人覆寫<br/>本機路徑、個人偏好"]
    P --- PD["團隊共識<br/>權限、Hook、MCP"]
    U --- UD["個人偏好<br/>套用到所有專案"]

    style M fill:#f8d7da
    style P fill:#d4edda
    style L fill:#fff3cd

兩種不同的合併語意，務必分清楚【官方】：

🎯 本節的關鍵認知：本章 6.5.2 之後的所有「企業標準設定檔」範本，若只放在專案層或使用者層，工程師隨時可以自行加上更寬鬆的 allow 規則（因為陣列是合併的）。若要讓政策真正無法被繞過，必須搭配 Managed Settings 的 allowManagedPermissionRulesOnly 等鍵——這是第 49 章的主題。本章提供的是「團隊共識版」，第 49 章提供的是「強制版」。

⚠️ settings.local.json 必須列入 .gitignore。若不慎提交，可能洩漏個人 token 或內部路徑。建議用 Hook 攔截（6.5.4 節）。

⚠️ Managed Settings 有少數安全性相關的例外，並非所有鍵都一定由管理層勝出。部署前請以 /status 的 Setting sources 實際驗證生效來源（第 49 章）。

6.5.2 企業標準專案設定範本

📌 下列設定的欄位名稱與可用選項可能隨版本調整，請以官方 settings 文件為準，並在採用前於測試環境驗證。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(git branch:*)",
      "Bash(mvn -q compile)",
      "Bash(mvn -q test:*)",
      "Bash(mvn dependency:tree)",
      "Bash(npm run build)",
      "Bash(npm run test:*)",
      "Bash(npm run lint)",
      "Read(**)",
      "Grep(**)",
      "Glob(**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force *)",
      "Bash(git reset --hard:*)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(kubectl:*)",
      "Bash(aws:*)",
      "Bash(az:*)",
      "Bash(psql:*)",
      "Bash(mysql:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(**/id_rsa)",
      "Read(**/*.pem)",
      "Read(**/*credentials*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/guard-dangerous-command.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/scan-secrets.sh"
          }
        ]
      }
    ]
  }
}

設計說明：

⚠️ curl / wget 被禁止是刻意的。允許 Agent 任意對外連線是 data exfiltration 的主要途徑（第 23 章）。若專案確實需要，應以 allowlist 指定特定網域，並經資安核准。

📌 補充（官方預設行為）：截至 2026-09-24，會從網路取得內容的指令（如 curl、wget）在 Manual 模式下本來就不會被自動核准，需逐次確認。上述 deny 規則的作用是把「需確認」升級為「完全禁止」。

⚠️ v2.0 重要更正：permission rules 擋不住決心繞過的人【官方】

官方明確說明：deny 規則是比對「指令字面」的。這代表下列情況 deny: Bash(curl:*) 並不會生效：

• 以別的方式呼叫：bash -c "cur""l https://..."、透過腳本檔間接執行
• 換一個工具：python -c "import urllib.request; ..."、nc、ssh
• 專案自有的建置腳本內部本來就會對外連線

同理，禁止 WebFetch 工具並不會阻止 Bash 對外連線——那是兩個不同的層。

正確的分層設計：

層	機制	擋得住什麼	擋不住什麼
應用層	permissions.deny	直接、字面相符的指令	改寫過的指令、間接呼叫
OS 層	Sandbox 網路隔離（sandbox.network.allowedDomains）	任何行程的任何對外連線，不論指令怎麼寫	白名單內的網域
網路層	企業防火牆 / Proxy	所有流量	—

🎯 結論：把 deny 當成「防手滑」是合理的，把它當成「防惡意」則是錯誤的安全假設。真正的網路管控必須靠沙箱或企業網路層。詳見第 23 章（威脅模型）與第 49 章（強制設定）。

6.5.3 危險指令攔截 Hook 範例

#!/usr/bin/env bash
# .claude/hooks/guard-dangerous-command.sh
# 用途：在 Bash 工具執行前攔截高風險指令
# 回傳非 0 即阻擋該次工具呼叫

set -euo pipefail

# Hook 由標準輸入取得工具呼叫資訊（JSON）
INPUT="$(cat)"
CMD="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')"

if [[ -z "$CMD" ]]; then
  exit 0
fi

# 高風險樣式（依組織需求擴充）
DANGEROUS_PATTERNS=(
  'rm[[:space:]]+-rf[[:space:]]+/'
  'git[[:space:]]+push[[:space:]]+.*--force'
  'DROP[[:space:]]+TABLE'
  'TRUNCATE[[:space:]]+TABLE'
  'DELETE[[:space:]]+FROM.*WHERE[[:space:]]+1=1'
  'chmod[[:space:]]+777'
  '>[[:space:]]*/dev/sd'
  'mkfs'
  'prod|production'
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if printf '%s' "$CMD" | grep -Eiq "$pattern"; then
    echo "🚫 已阻擋高風險指令（樣式：${pattern}）" >&2
    echo "指令內容：${CMD}" >&2
    echo "如確有需要，請由人員手動執行並記錄於 PR 說明中。" >&2
    # 記錄稽核軌跡
    mkdir -p .claude/audit
    printf '%s\t%s\t%s\n' "$(date -Is)" "${USER:-unknown}" "$CMD" \
      >> .claude/audit/blocked-commands.log
    exit 2
  fi
done

exit 0

📌 Hook 的輸入格式、退出碼語意與事件名稱可能隨版本調整。採用前請依官方 Hooks 文件驗證，並先在測試專案實測。詳細說明見第 12 章。

6.5.4 密鑰掃描 Hook 範例

#!/usr/bin/env bash
# .claude/hooks/scan-secrets.sh
# 用途：Agent 寫入檔案後，掃描是否寫入了疑似密鑰

set -euo pipefail

INPUT="$(cat)"
FILE="$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')"

[[ -z "$FILE" || ! -f "$FILE" ]] && exit 0

# 常見密鑰樣式（依組織需求擴充）
if grep -Enq \
  -e '(password|passwd|pwd)[[:space:]]*[:=][[:space:]]*["'"'"'][^"'"'"']{6,}' \
  -e '(api[_-]?key|apikey|secret|token)[[:space:]]*[:=][[:space:]]*["'"'"'][A-Za-z0-9_\-]{16,}' \
  -e 'BEGIN (RSA|OPENSSH|EC|DSA) PRIVATE KEY' \
  -e 'jdbc:[a-z0-9]+://[^[:space:]]*password=' \
  "$FILE"; then
  echo "⚠️ 偵測到 ${FILE} 可能含有硬編碼的機敏資訊，請立即確認。" >&2
  echo "企業規範：機敏資訊一律使用環境變數或 Secret Manager。" >&2
  exit 2
fi

exit 0

6.6 環境驗收腳本

新人設定完環境後，應執行驗收腳本確認全部到位。

6.6.1 PowerShell 版（Windows）

# verify-claude-env.ps1
# 用途：驗證 Claude Code 企業標準環境

$ErrorActionPreference = 'Continue'
$results = @()

function Test-Item {
    param([string]$Name, [scriptblock]$Check, [string]$Expected)
    try {
        $actual = & $Check
        $pass = $null -ne $actual -and $actual -ne ''
        $script:results += [PSCustomObject]@{
            項目 = $Name; 結果 = if ($pass) { 'PASS' } else { 'FAIL' }
            實際值 = "$actual"; 期望 = $Expected
        }
    } catch {
        $script:results += [PSCustomObject]@{
            項目 = $Name; 結果 = 'FAIL'; 實際值 = $_.Exception.Message; 期望 = $Expected
        }
    }
}

Test-Item '對話式 CLI 可執行' { (Get-Command claude -ErrorAction SilentlyContinue).Source } '有路徑'
Test-Item 'Git 版本'          { (git --version) } '2.40+'
Test-Item 'Git autocrlf'      { (git config --global core.autocrlf) } 'input'
Test-Item 'Git longpaths'     { (git config --global core.longpaths) } 'true'
Test-Item 'PowerShell 版本'   { $PSVersionTable.PSVersion.ToString() } '7.0+'
Test-Item 'HTTPS_PROXY'       { $env:HTTPS_PROXY } '已設定（若組織有 Proxy）'
Test-Item '企業根憑證'         { $env:NODE_EXTRA_CA_CERTS } '已設定（若組織有 TLS 攔截）'
Test-Item '專案 settings.json' { if (Test-Path '.claude/settings.json') { '存在' } } '存在'
Test-Item 'gitignore 含 local' {
    if ((Test-Path '.gitignore') -and (Select-String -Path '.gitignore' -Pattern 'settings\.local\.json' -Quiet)) { '已忽略' }
} '已忽略'

$results | Format-Table -AutoSize
$failed = @($results | Where-Object { $_.結果 -eq 'FAIL' })
if ($failed.Count -gt 0) {
    Write-Host "`n❌ 有 $($failed.Count) 項未通過，請依第 6 章 SOP 修正。" -ForegroundColor Red
    exit 1
}
Write-Host "`n✅ 環境驗收全數通過。" -ForegroundColor Green

6.6.2 Bash 版（macOS / Linux / WSL）

#!/usr/bin/env bash
# verify-claude-env.sh
# 用途：驗證 Claude Code 企業標準環境

PASS=0; FAIL=0

check() {
  local name="$1"; local expected="$2"; shift 2
  local actual
  actual="$("$@" 2>/dev/null || true)"
  if [[ -n "$actual" ]]; then
    printf '✅ %-28s %s\n' "$name" "$actual"; PASS=$((PASS+1))
  else
    printf '❌ %-28s （期望：%s）\n' "$name" "$expected"; FAIL=$((FAIL+1))
  fi
}

echo "===== Claude Code 企業環境驗收 ====="
check "CLI 路徑"        "有路徑"    command -v claude
check "Git 版本"        "2.40+"     git --version
check "Git autocrlf"    "input"     git config --global core.autocrlf
check "Shell"           "zsh/bash"  bash -c 'echo $SHELL'

# 非指令類檢查
[[ -n "${HTTPS_PROXY:-}" ]] \
  && { echo "✅ HTTPS_PROXY                 ${HTTPS_PROXY}"; PASS=$((PASS+1)); } \
  || { echo "⚠️  HTTPS_PROXY                 未設定（若組織有 Proxy 需設定）"; }

[[ -f ".claude/settings.json" ]] \
  && { echo "✅ 專案 settings.json          存在"; PASS=$((PASS+1)); } \
  || { echo "❌ 專案 settings.json          不存在"; FAIL=$((FAIL+1)); }

grep -q 'settings\.local\.json' .gitignore 2>/dev/null \
  && { echo "✅ .gitignore 已忽略 local     是"; PASS=$((PASS+1)); } \
  || { echo "❌ .gitignore 未忽略 local     請補上"; FAIL=$((FAIL+1)); }

# WSL 路徑檢查
if grep -qi microsoft /proc/version 2>/dev/null; then
  if pwd | grep -q '^/mnt/'; then
    echo "❌ WSL 工作路徑                位於 /mnt（效能差），請移至 ~/projects"
    FAIL=$((FAIL+1))
  else
    echo "✅ WSL 工作路徑                原生檔案系統"; PASS=$((PASS+1))
  fi
fi

echo "====================================="
echo "通過：${PASS}　未通過：${FAIL}"
[[ $FAIL -gt 0 ]] && exit 1
exit 0

6.7 隔離工作流程：git worktree

Agent 會直接修改工作目錄的檔案。為了讓「弄壞了也不怕」，建議大型任務使用 git worktree 隔離。

# 1. 為任務建立獨立 worktree（不影響主工作目錄）
git worktree add ../myproj-upgrade-springboot3 -b feature/upgrade-springboot3

# 2. 在該 worktree 中執行 Agent 任務
cd ../myproj-upgrade-springboot3
claude "執行 Spring Boot 2.7 → 3.2 升版，依 rules/upgrade.md 的流程"

# 3. 驗證結果
mvn -q verify

# 4. 滿意就推送；不滿意就整個刪掉，主工作目錄完全不受影響
git push -u origin feature/upgrade-springboot3
# 或
cd .. && git worktree remove myproj-upgrade-springboot3 --force

優點：

✅ 建議將 worktree 列為「高風險任務」的標準作業：框架升版、大規模重構、Legacy 逆向改造，一律先開 worktree。

6.7.1 四種隔離手段的選擇【官方】

📌 v2.0 新增。worktree 只隔離檔案變更範圍，不隔離指令執行能力——Agent 在 worktree 裡一樣可以讀取整台機器、連上任何網路位置。企業需要依威脅模型選擇適當的隔離層級。

建議的企業預設組合：

⚠️ Sandbox 的附帶好處常被低估：啟用沙箱後，因為 OS 層已保證安全邊界，Claude Code 可以減少權限詢問次數。也就是說，沙箱同時改善了「安全性」與「使用體驗」——這是說服工程師接受管控的最有力論點。設定方式見第 23、49 章。

6.8 本章實務案例

情境：某團隊 12 人，新人到職平均需要 2 天才能開始正常使用 Claude Code。

問題盤點：

改善措施：

1. 撰寫本章的 SOP 與驗收腳本（6.3～6.6 節），放入新人報到包
2. 一次性向資安申請全部門的防毒白名單（而非個案申請）
3. 建立 company-ai-development/scripts/setup-dev-env.ps1 一鍵設定腳本
4. 把 verify-claude-env.ps1 列為新人到職檢核項目

結果：新人可用時間從 2 天降至 1.5 小時，且不再出現關閉 TLS 驗證的資安缺失。

🎯 環境標準化的投資報酬率極高：一次性投入約 3 人天撰寫 SOP 與腳本，之後每位新人節省約 1.5 人天。

6.9 本章注意事項

⚠️ 絕對不要用 NODE_TLS_REJECT_UNAUTHORIZED=0 繞過憑證問題。正確做法是安裝企業根憑證。

⚠️ Windows 的 core.autocrlf 必須設為 input，否則 Code Review 會被大量假變更淹沒。

⚠️ WSL 使用者務必把專案放在原生檔案系統（~/projects），不要放 /mnt/c。

⚠️ settings.local.json 必須進 .gitignore，並建議用 pre-commit hook 再檢查一次。

📌 Claude Code 的安裝方式、設定檔欄位、Hook 格式皆可能隨版本調整。本章刻意以「驗收標準」為主、安裝指令為輔。請以官方文件為準，並在版本升級時重新驗證 Hook 腳本。

📌 Node.js 的必要性與版本需求需依實際安裝方式確認，本手冊不做假設。

6.10 本章檢查清單

• 已定義企業標準環境清單（OS / 版本 / 工具）
• Claude Code 版本 ≥ 2.0.28（Analytics 需求）
• Proxy 與企業根憑證設定已文件化
• 未使用 NODE_TLS_REJECT_UNAUTHORIZED=0
• Git core.autocrlf=input、core.longpaths=true 已設定（Windows）
• 已向資安申請防毒白名單（部門層級，非個案）
• WSL 使用者的專案位於原生檔案系統
• 專案 .claude/settings.json 已建立並進版控
• .claude/settings.local.json 已列入 .gitignore
• 危險指令攔截 Hook 已部署並測試
• 密鑰掃描 Hook 已部署並測試
• 環境驗收腳本已納入新人報到流程
• 高風險任務已採用 git worktree 隔離

第 7 章　企業共用 Repository 標準

本章目錄：7.1 為什麼需要一個共用 Repository ｜ 7.2 標準目錄結構 ｜ 7.3 每個目錄的用途、擁有者與變更流程 ｜ 7.4 資產的生命週期 ｜ 7.5 共用資產如何進到專案 ｜ 7.6 版本策略 ｜ 7.7 本章實務案例 ｜ 7.8 本章注意事項 ｜ 7.9 本章檢查清單

7.1 為什麼需要一個共用 Repository

回顧第 4 章的結論：

🎯 判斷 AI 導入是否成功的一個簡單指標：company-ai-development 這個 repo 在半年後有沒有長大。

沒有共用 repo 的組織會出現三個現象：

1. 重複發明：五個專案各自寫了五份「Spring Boot 開發規範」給 AI 看，內容還互相矛盾。
2. 知識隨人走：那位很會用 AI 的資深同仁離職了，他的 prompt 也一起走了。
3. 治理無法落地：資安訂了規範，但沒有機制讓規範自動出現在每個專案的 AI 設定中。

7.2 標準目錄結構

company-ai-development/
│
├── README.md                    # 入口：本 repo 是什麼、怎麼用、怎麼貢獻
├── CHANGELOG.md                 # 資產變更紀錄（重要！）
├── CODEOWNERS                   # 各目錄的審查責任人
│
├── governance/                  # 治理文件
│   ├── ai-coding-policy.md      #   MUST/SHOULD/MAY/MUST NOT（第 36 章）
│   ├── approval-matrix.md       #   人工核准矩陣（第 16 章）
│   ├── risk-register.md         #   風險登錄簿（第 37 章）
│   └── mcp-allowlist.md         #   核准的 MCP Server 清單（第 12 章）
│
├── constitution/                # 組織的 AI 工程原則（不常變動的最高原則）
│   └── ai-engineering-principles.md
│
├── standards/                   # 技術標準
│   ├── java-coding-standard.md
│   ├── api-design-standard.md
│   ├── database-standard.md
│   └── frontend-standard.md
│
├── agents/                      # 16 個標準 Agent（第 13 章）
│   ├── pm-agent.md
│   ├── sa-agent.md
│   ├── architect-agent.md
│   └── ...
│
├── commands/                    # 14 個標準 Command（第 10 章）
│   ├── analyze.md
│   ├── reverse-engineer.md
│   └── ...
│
├── rules/                       # 12 份規則（第 9 章）
│   ├── architecture.md
│   ├── coding.md
│   ├── security.md
│   └── ...
│
├── skills/                      # Skill Catalog（第 11 章）
│   ├── java-25/
│   │   ├── SKILL.md
│   │   └── references/
│   ├── spring-boot/
│   └── ...
│
├── hooks/                       # 共用 Hook 腳本（第 12 章）
│   ├── guard-dangerous-command.sh
│   ├── scan-secrets.sh
│   └── mark-ai-generated.sh
│
├── plugins/                     # 內部 Plugin（第 12 章）
│   └── corp-java-toolkit/
│
├── scripts/                     # 環境與維運腳本（第 6 章）
│   ├── setup-dev-env.ps1
│   ├── setup-dev-env.sh
│   ├── verify-claude-env.ps1
│   └── sync-to-project.sh       #   把共用資產同步到專案的腳本
│
├── prompts/                     # 可重用 prompt 片段（尚未成熟為 Command/Skill 者）
│   └── incubator/
│
├── templates/                   # 21 份範本（第 52 章附錄 A）
│   ├── CLAUDE.md.template
│   ├── agent.md.template
│   ├── monthly-report.md.template
│   └── ...
│
├── examples/                    # 可執行的完整範例
│   ├── banking-web-app/         #   第 39 章
│   ├── legacy-reverse/          #   第 40 章
│   └── framework-upgrade/       #   第 41 章
│
├── workshops/                   # 教育訓練教材（第 24 章）
│   ├── w01-claude-code-basics/
│   └── ...
│
├── sddlc/                       # SSDLC 流程文件（第 14 章）
│   ├── ssdlc-matrix.md
│   └── phase-checklists/
│
├── architecture/                # 企業架構文件（第 4 章）
│   ├── enterprise-ai-architecture.md
│   └── adr/                     #   組織層級的 ADR
│
├── security/                    # 資安文件（第 23 章）
│   ├── ai-coding-security-policy.md
│   ├── data-classification.md
│   └── incident-response.md
│
├── testing/                     # 測試策略與範本（第 22 章）
│   ├── ai-testing-strategy.md
│   └── test-templates/
│
└── metrics/                     # 指標定義與報表（第 29～33 章）
    ├── kpi-definitions.md
    ├── dashboard-spec.md
    └── monthly-reports/

7.3 每個目錄的用途、擁有者與變更流程

✅ prompts/incubator/ 免審查是刻意設計。它是「還沒成熟的想法」的存放處，降低貢獻門檻。成熟後再經審查升級為 Command 或 Skill（第 27 章的晉升機制）。

7.4 資產的生命週期

flowchart LR
    A["個人實驗<br/>本機 prompt"] --> B["prompts/incubator/<br/>（免審查）"]
    B --> C{"被 3 個以上<br/>專案使用？"}
    C -->|否| B
    C -->|是| D["提案晉升"]
    D --> E{"類型判斷"}
    E -->|可重用流程| F["commands/"]
    E -->|領域知識| G["skills/"]
    E -->|行為約束| H["rules/"]
    E -->|角色化任務| I["agents/"]

    F --> J["正式資產<br/>（有版本、有 owner）"]
    G --> J
    H --> J
    I --> J

    J --> K{"季度檢視"}
    K -->|仍在使用| J
    K -->|6 個月無人使用| L["標記 deprecated"]
    L --> M["下一季度移除"]

    style B fill:#fff3cd
    style J fill:#d4edda
    style L fill:#f8d7da

⚠️ 必須有「淘汰機制」。沒有淘汰的 repo 會在兩年後變成 300 個沒人用的檔案，反而增加 AI 的認知負擔與 token 消耗。

7.5 共用資產如何進到專案

有三種做法，各有取捨：

7.5.1 同步腳本範例（方式 B）

#!/usr/bin/env bash
# sync-to-project.sh
# 用途：把企業共用 AI 資產同步到單一專案
# 使用：./sync-to-project.sh /path/to/my-project

set -euo pipefail

TARGET="${1:?用法：$0 <專案路徑>}"
SOURCE="$(cd "$(dirname "$0")/.." && pwd)"

[[ -d "$TARGET/.git" ]] || { echo "❌ $TARGET 不是 git 專案"; exit 1; }

echo "同步來源：$SOURCE"
echo "同步目標：$TARGET"
echo "共用資產版本：$(git -C "$SOURCE" describe --tags --always)"
echo

mkdir -p "$TARGET/.claude"/{agents,commands,rules,hooks}

# 以 rsync 同步，--delete 只作用於受管理的子目錄
sync_dir() {
  local name="$1"
  echo "→ 同步 $name/"
  rsync -a --delete \
    --exclude '.git' \
    "$SOURCE/$name/" "$TARGET/.claude/$name/"
}

sync_dir agents
sync_dir commands
sync_dir rules
sync_dir hooks

# 記錄來源版本，方便日後追溯
cat > "$TARGET/.claude/ASSET_VERSION" <<EOF
# 本目錄下的 agents/ commands/ rules/ hooks/ 由企業共用 repo 同步而來
# 請勿直接修改，如需調整請對 company-ai-development 發 PR
source_repo: company-ai-development
version: $(git -C "$SOURCE" describe --tags --always)
commit: $(git -C "$SOURCE" rev-parse HEAD)
synced_at: $(date -Is)
synced_by: ${USER:-unknown}
EOF

chmod +x "$TARGET/.claude/hooks/"*.sh 2>/dev/null || true

echo
echo "✅ 同步完成。請執行 git diff 檢視變更後再提交。"

⚠️ 注意 --delete 的風險：它會刪除目標目錄中不存在於來源的檔案。因此專案特有的 Agent / Command 不可放在這四個目錄，應另建 .claude/agents-local/ 之類的目錄。這一點必須在專案 CLAUDE.md 中明確寫出。

7.5.2 同步的自動化與稽核

# .github/workflows/check-ai-asset-version.yml
# 用途：每週檢查各專案的 AI 資產是否落後共用 repo 太多
name: 檢查 AI 資產版本

on:
  schedule:
    - cron: '0 1 * * 1'   # 每週一 09:00 (UTC+8)
  workflow_dispatch:

jobs:
  check-version:
    runs-on: ubuntu-latest
    steps:
      - name: 取得專案原始碼
        uses: actions/checkout@v4

      - name: 讀取目前資產版本
        id: current
        run: |
          if [[ -f .claude/ASSET_VERSION ]]; then
            echo "version=$(grep '^version:' .claude/ASSET_VERSION | cut -d' ' -f2)" >> "$GITHUB_OUTPUT"
          else
            echo "version=none" >> "$GITHUB_OUTPUT"
          fi

      - name: 比對共用 repo 最新版本
        run: |
          echo "本專案資產版本：${{ steps.current.outputs.version }}"
          echo "（實際比對邏輯需依組織的 repo 存取方式實作）"
          # 待確認：內部 repo 的存取方式需依組織 Git 平台決定

📌 上述 workflow 為結構範例，實際的 repo 存取方式（GitHub App token、deploy key、內部 GitLab API）需依組織環境決定。

7.6 版本策略

CHANGELOG 範本：

# CHANGELOG

## [v1.4.0] - 2026-09-01

### 新增
- `agents/performance-agent.md`：效能分析 Agent（貢獻者：後端組）
- `skills/archunit/`：ArchUnit 架構測試 Skill

### 變更
- `rules/security.md`：新增「禁止在 prompt 中貼上生產環境資料」條文
  - **對專案的影響**：無需修改專案設定，同步後即生效
- `commands/review.md`：Review 檢查項目由 8 項增至 11 項
  - **對專案的影響**：Review 產出會變長，請留意 PR 篇幅

### 棄用
- `commands/quick-fix.md`：已被 `commands/implement.md` 取代
  - **移除時程**：v1.6.0（預計 2026-11）
  - **遷移方式**：將 `/quick-fix` 改為 `/implement --scope=small`

### 修正
- `hooks/scan-secrets.sh`：修正 JDBC 連線字串誤判問題

7.7 本章實務案例

情境：某組織建立共用 repo 後 4 個月，發現只有 2 個專案在同步，其他 11 個專案沒動靜。

訪談結果：

改善措施：

1. 可見度：在每個專案的 CLAUDE.md 最上方加入共用 repo 連結與同步指令（第 8 章範本已含）。
2. 降低門檻：把 sync-to-project.sh 包成 /sync-ai-assets Command（第 10 章），同仁只要打一個指令。
3. 自動提醒：建立 7.5.2 的週期性檢查，資產落後 2 個 MINOR 版本以上就自動開 Issue。
4. 解決覆蓋問題：明確區分 .claude/agents/（同步管理）與 .claude/agents-local/（專案自有），並在 ASSET_VERSION 檔案中寫明。
5. 納入專案啟動檢核：新專案的 Kick-off 檢核表新增「已完成 AI 資產同步」一項（第 26 章）。

三個月後：13 個專案中有 12 個維持在最新的 2 個 MINOR 版本內。

🎯 共用資產的最大敵人不是品質，是「沒有人知道它存在」。可見度與自動化提醒比內容本身更重要。

7.8 本章注意事項

⚠️ 必須明確區分「同步管理的目錄」與「專案自有的目錄」，否則同步腳本的 --delete 會刪掉專案的心血。

⚠️ hooks/ 與 plugins/ 含可執行程式碼，變更必須經資安審查。這兩個目錄是供應鏈攻擊的潛在入口（第 23 章）。

⚠️ 不要把機敏資訊放進共用 repo（連線字串、內部 IP、客戶名稱）。這個 repo 會被所有開發同仁讀取，範圍很廣。

✅ CODEOWNERS 一定要設定，否則 PR 不知道該找誰審。

📌 repo 大小要控制。若 skills/ 塞入大量參考文件，同步會變慢且佔用磁碟。建議大型參考資料以連結方式引用，而非全文複製。

7.9 本章檢查清單

• company-ai-development repo 已建立
• 19 個標準目錄已建立且有 README.md 說明
• CODEOWNERS 已設定，每個目錄都有明確審查人
• 每個目錄的 Owner 與變更流程已文件化（7.3 節表格）
• prompts/incubator/ 已開放免審查貢獻
• 資產晉升機制（incubator → 正式資產）已定義
• 淘汰機制已定義（6 個月無人使用則 deprecated）
• 已選定資產同步方式（Submodule / 腳本 / Plugin）
• 同步腳本已測試，且不會誤刪專案自有資產
• ASSET_VERSION 機制已建立，可追溯來源版本
• 版本策略與 CHANGELOG 規範已建立
• 週期性版本落後檢查已設定
• hooks/ 與 plugins/ 的資安審查流程已建立
• 新專案 Kick-off 檢核表已納入「AI 資產同步」

第 8 章　CLAUDE.md 企業標準

本章目錄：8.1 CLAUDE.md 是什麼，不是什麼 ｜ 8.2 企業標準骨架（19 個區塊） ｜ 8.3 完整範本（可直接複製） ｜ 8.4 CLAUDE.md 的分層機制 ｜ 8.5 CLAUDE.md 的品質檢查 ｜ 8.6 本章實務案例 ｜ 8.7 本章注意事項 ｜ 8.8 本章檢查清單

8.1 CLAUDE.md 是什麼，不是什麼

CLAUDE.md 是放在專案根目錄的檔案，Claude Code 會自動讀取它作為專案上下文。

🎯 最常見的錯誤：把 CLAUDE.md 寫成 600 行的專案百科全書。 這會造成兩個問題：(1) 每次 session 都消耗大量 token；(2) 重點被淹沒，AI 反而抓不到關鍵規則。

✅ 企業規範建議：CLAUDE.md 控制在 200 行以內。細節放在 rules/ 並用連結引用（第 9 章）。

8.2 企業標準骨架（19 個區塊）

8.3 完整範本（可直接複製）

以下範本以「Java 25 + Spring Boot + Vue 3」的企業專案為例。

# CLAUDE.md — 交易查詢服務（txn-query-service）

> 本檔為 AI 行為契約。修改前請先閱讀 `docs/ai/how-to-edit-claude-md.md`。
> 企業共用 AI 資產同步指令：`/sync-ai-assets`
> 目前資產版本：見 `.claude/ASSET_VERSION`

## 1. Project Overview

本服務提供行內交易明細的查詢 API，供網銀與行動銀行前端呼叫。
日均請求約 120 萬次，P95 延遲 SLA 為 1.5 秒。
資料來源為核心系統的交易主檔（唯讀）。

## 2. Architecture

- 架構風格：Hexagonal Architecture（Ports & Adapters）+ DDD 戰術模式
- 依賴方向：`adapter` → `application` → `domain`（**domain 不可依賴任何外層**）
- 架構規則以 ArchUnit 測試強制執行，見 `src/test/java/.../ArchitectureTest.java`

## 3. Technology Stack

| 類別 | 技術 | 版本 |
| --- | --- | --- |
| 語言 | Java | 25 |
| 框架 | Spring Boot | 3.4.x |
| 建置 | Maven | 3.9+ |
| 資料庫 | PostgreSQL | 16 |
| 前端 | Vue 3 + TypeScript + PrimeVue + Pinia + Tailwind | 見 `frontend/package.json` |
| 測試 | JUnit 5、Testcontainers、Playwright、JMeter | — |

## 4. Directory Structure

```text
src/main/java/com/corp/txnquery/
├── domain/          # 實體、值物件、領域服務（無框架依賴）
├── application/     # Use Case、Port 介面
└── adapter/
    ├── in/web/      # REST Controller
    └── out/persistence/  # JPA Repository 實作
frontend/src/        # Vue 3 前端
docs/adr/            # 架構決策紀錄
docs/ai/             # AI 產出的分析文件
```

## 5. Coding Standard

完整規範見 `.claude/rules/coding.md`。最關鍵三條：

1. **不得在 `domain/` 出現任何 Spring 或 JPA 註解**
2. 所有對外 API 的 DTO 必須與 domain 物件分離，禁止直接暴露 Entity
3. 例外處理統一使用 `BusinessException` + `ErrorCode` 列舉，禁止拋出裸 `RuntimeException`

## 6. Build

```bash
# 後端
mvn -q clean package -DskipTests

# 前端
cd frontend && npm ci && npm run build
```

前置條件：JDK 25、Node.js LTS、已設定企業 Maven repository（`~/.m2/settings.xml`）。

## 7. Test

```bash
mvn -q test                                   # 單元測試（約 40 秒）
mvn -q verify -Pintegration                   # 整合測試（需 Docker，約 4 分鐘）
mvn -q test -Dtest=TxnQueryServiceTest#shouldReturnEmptyWhenNoRecord   # 單一測試
cd frontend && npm run test:unit               # 前端單元測試
cd frontend && npx playwright test             # E2E（需先啟動後端）
```

**測試覆蓋率門檻**：`domain/` 與 `application/` 需 ≥ 85%，由 JaCoCo 於 CI 檢查。

## 8. Security

- 交易資料屬於**機密等級 C2**，見 `.claude/rules/security.md`
- **禁止**將任何真實交易資料、帳號、身分證字號寫入程式碼、測試資料或提交訊息
- 測試資料一律使用 `src/test/resources/fixtures/` 中的去識別化樣本
- 所有外部輸入必須經 `@Valid` 驗證
- 日誌不得輸出完整帳號（須遮罩為 `****1234`）

## 9. Database

- Migration 工具：Flyway，腳本位於 `src/main/resources/db/migration/`
- **禁止手動修改已套用的 migration 檔案**，一律新增新版本
- **禁止在程式碼中出現任何連線字串或密碼**，一律由環境變數注入
- 本服務對交易主檔為**唯讀**，任何 INSERT/UPDATE/DELETE 皆為錯誤

## 10. API

- 風格：REST，遵循 `.claude/rules/api.md`
- 錯誤回應統一格式：`{ "code": "TXN_001", "message": "...", "traceId": "..." }`
- 版本策略：URL path 版本（`/api/v1/...`）
- OpenAPI 規格由 springdoc 自動產生，**不得手動編輯 `openapi.yaml`**

## 11. Git

分支策略：GitHub Flow（`main` 為保護分支，所有變更經 PR）

## 12. Branch

命名規則：`<type>/<issue-id>-<short-desc>`
範例：`feature/TXN-1234-add-date-range-filter`、`fix/TXN-1250-npe-on-empty-result`

## 13. Commit

格式：Conventional Commits

```text
<type>(<scope>): <subject>

<body>

Co-Authored-By: Claude <noreply@anthropic.com>
```

**AI 參與的提交必須保留 `Co-Authored-By` 標記**（企業稽核要求，見 `.claude/rules/git.md`）。

## 14. Pull Request

PR 描述必填：

- [ ] 變更摘要
- [ ] 關聯 Issue
- [ ] **AI 參與程度**（無 / 輔助 / 主要產出）
- [ ] 測試結果（貼上實際輸出）
- [ ] 影響範圍評估
- [ ] 是否需要 DB migration

## 15. CI/CD

Pipeline 會執行且**會擋住合併**的檢查：

1. `mvn verify`（含單元 + 整合測試）
2. JaCoCo 覆蓋率門檻
3. ArchUnit 架構測試
4. SAST 掃描（Semgrep）
5. 相依套件漏洞掃描
6. 密鑰掃描（gitleaks）

## 16. AI Rules

1. **先計畫再執行**：任何影響 3 個以上檔案的變更，必須先提出計畫並等待確認
2. **不要猜測**：若對商業邏輯不確定，標示為「需確認」並提問，**不要自行假設**
3. **以路徑引用**：引用程式碼時使用 `檔案:行號`，不要整段複製到對話中
4. **測試優先**：修改既有邏輯前，先確認有對應測試；若無，先補測試
5. **保持架構分層**：任何違反 Hexagonal 依賴方向的修改一律不可接受
6. **變更後自行驗證**：修改完成後必須執行相關測試，並回報實際結果（不要只說「應該可以」）

## 17. Forbidden Actions（絕對禁止）

AI **在任何情況下都不得**執行下列操作：

- ❌ 連線或查詢**生產環境**的任何資源
- ❌ 執行 `git push --force`、`git reset --hard`
- ❌ 修改 `.github/workflows/` 下的檔案（需 DevOps 核准）
- ❌ 修改已套用的 Flyway migration 檔案
- ❌ 新增任何未經核准的相依套件（需先走第 23 章的相依審查）
- ❌ 修改 `pom.xml` 的 `<version>` 或 parent 版本（需架構師核准）
- ❌ 讀取或輸出 `.env`、`*.pem`、`*credentials*` 等檔案
- ❌ 對外發送任何網路請求（`curl`、`wget` 已於 settings 禁用）
- ❌ 刪除任何測試檔案（即使該測試失敗）
- ❌ 將真實客戶資料寫入任何檔案

## 18. Human Approval（必須先取得人工核准）

| 操作 | 核准者 |
| --- | --- |
| 架構決策（影響分層或引入新模式） | 架構師 |
| 新增 / 升級相依套件 | 架構師 + 資安 |
| 資料庫 schema 變更 | DBA + 架構師 |
| API 破壞性變更 | 架構師 + 前端負責人 |
| 超過 20 個檔案的重構 | Tech Lead |
| 修改安全相關程式碼（認證、授權、加解密） | 資安 |

完整核准矩陣見 `.claude/governance/approval-matrix.md`。

## 19. Definition of Done

一項工作視為完成，必須同時滿足：

- [ ] 程式碼符合第 5 節的編碼標準
- [ ] 新增或修改的邏輯有對應的單元測試
- [ ] `mvn verify` 在本機通過（需貼上實際輸出）
- [ ] 覆蓋率未低於變更前
- [ ] ArchUnit 測試通過
- [ ] 無新增的 SAST 高風險發現
- [ ] PR 描述已填寫完整（含 AI 參與程度）
- [ ] 若涉及 API 變更，OpenAPI 文件已更新
- [ ] 若涉及 DB 變更，已附 migration 腳本與回滾方案

8.4 CLAUDE.md 的分層機制

Claude Code 支援多層級的上下文檔案。企業建議的分層策略：

flowchart TB
    U["~/.claude/CLAUDE.md<br/>使用者層"] --> P["&lt;repo&gt;/CLAUDE.md<br/>專案層"]
    P --> S["&lt;repo&gt;/frontend/CLAUDE.md<br/>子目錄層"]

    U --> UD["個人偏好<br/>例：回覆用繁體中文<br/>不放團隊規則"]
    P --> PD["專案契約<br/>19 個區塊<br/>200 行內"]
    S --> SD["子模組特有規則<br/>例：前端專用的<br/>元件命名規範"]

    style P fill:#d4edda

⚠️ 不要在使用者層放團隊規則。那樣新人的環境會缺少這些規則，造成行為不一致。

8.4.1 組織層 CLAUDE.md 與 AGENTS.md 的處理（v2.1 新增）【官方】

上圖的三層之上，其實還有一層組織政策層（Managed policy CLAUDE.md），由 IT／DevOps 部署到固定路徑，每個 session 都會載入，且使用者無法以 claudeMdExcludes 排除：

🎯 建議放進組織層的內容【建議】：只放「任何專案都不可違反」的少數條文（例如第 23 章 AI Coding Security Policy 的 MUST NOT 摘要、資料分級的禁止事項），控制在 50 行以內（與第 49 章 49.4.5 一致）。它會出現在全組織每一個 session 的上下文裡，寫得越長，全組織的成本越高（5.5.2）。

AGENTS.md 後援（v2.1.277 起）：許多 repository 已為其他 coding agent 準備了 AGENTS.md。Claude Code 的讀取規則如下：

⚠️ 兩個陷阱：(1) Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 上目前不支援直接讀 AGENTS.md；(2) 同時存在兩個檔案時 AGENTS.md 會被靜默忽略，其中的規則等於不存在。企業標準做法：以 CLAUDE.md 為準（8.2 的 19 個區塊），若需與其他工具共用，就在 CLAUDE.md 中 import AGENTS.md，並在 8.5 的品質檢查腳本加入「偵測到 AGENTS.md 但未被 import」的警告。

8.5 CLAUDE.md 的品質檢查

建議建立 lint 腳本，納入 CI。

#!/usr/bin/env bash
# scripts/lint-claude-md.sh
# 用途：檢查 CLAUDE.md 是否符合企業標準

set -uo pipefail

FILE="${1:-CLAUDE.md}"
ERRORS=0

fail() { echo "❌ $1"; ERRORS=$((ERRORS+1)); }
pass() { echo "✅ $1"; }

[[ -f "$FILE" ]] || { echo "❌ 找不到 $FILE"; exit 1; }

# 1. 長度檢查（企業規範：200 行內）
LINES=$(wc -l < "$FILE")
if (( LINES > 200 )); then
  fail "長度 ${LINES} 行，超過企業上限 200 行（請將細節移至 rules/）"
else
  pass "長度 ${LINES} 行，符合規範"
fi

# 2. 必要區塊檢查
REQUIRED=(
  "Project Overview" "Architecture" "Technology Stack" "Directory Structure"
  "Coding Standard" "Build" "Test" "Security" "Git" "Branch" "Commit"
  "Pull Request" "AI Rules" "Forbidden Actions" "Human Approval" "Definition of Done"
)
for section in "${REQUIRED[@]}"; do
  if grep -q "^## .*${section}" "$FILE"; then
    pass "含必要區塊：${section}"
  else
    fail "缺少必要區塊：${section}"
  fi
done

# 3. 機敏資訊檢查（最重要）
if grep -Eniq \
  -e 'password[[:space:]]*[:=][[:space:]]*[^ ]' \
  -e 'jdbc:[a-z]+://[^ ]*:[^ ]*@' \
  -e '(api[_-]?key|secret|token)[[:space:]]*[:=][[:space:]]*["'"'"']?[A-Za-z0-9]{16,}' \
  -e '\b(10|172|192)\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\b' \
  "$FILE"; then
  fail "偵測到疑似機敏資訊（密碼 / 連線字串 / 金鑰 / 內部 IP），請立即移除"
else
  pass "無偵測到機敏資訊"
fi

# 4. Forbidden Actions 不可為空
if grep -A 5 "Forbidden Actions" "$FILE" | grep -q '❌\|不得\|禁止'; then
  pass "Forbidden Actions 有實際內容"
else
  fail "Forbidden Actions 區塊為空或無實際禁止項目"
fi

echo
if (( ERRORS > 0 )); then
  echo "共 ${ERRORS} 項未通過。"
  exit 1
fi
echo "CLAUDE.md 檢查全數通過。"

8.6 本章實務案例

情境：某專案的 CLAUDE.md 有 640 行，同仁抱怨「AI 常常忽略重要規則」。

分析結果：

改寫後：182 行，其中 AI 行為規則佔 95 行。

改寫原則：

🎯 如果 AI 可以從 repo 裡自己讀到，就不要寫進 CLAUDE.md；只寫「AI 讀不到的組織知識」與「必須遵守的約束」。

實測效果對比：

8.7 本章注意事項

⚠️ CLAUDE.md 中絕對不可出現任何連線字串、密碼、金鑰、內部 IP、真實客戶資料。這個檔案會進版控，且每次 session 都會被讀取。務必用 8.5 節的 lint 檢查。

⚠️ Forbidden Actions 是最重要也最常被遺漏的區塊。沒有這一段，AI 不知道邊界在哪裡。

⚠️ 不要在 CLAUDE.md 裡貼完整的規範全文。用連結指向 rules/，並在 CLAUDE.md 只寫最關鍵的 3～5 條。

✅ Definition of Done 要寫得可驗證。「程式碼品質良好」不可驗證；「mvn verify 通過且需貼上輸出」可驗證。

✅ CLAUDE.md 的變更也應該走 PR 審查。它是行為契約，不是隨手改的筆記。

📌 CLAUDE.md 的檔名、載入機制與分層規則可能隨版本調整，請以官方文件為準。

8.8 本章檢查清單

• 專案根目錄有 CLAUDE.md
• 長度控制在 200 行以內
• 19 個標準區塊中，16 個必要區塊皆存在
• Forbidden Actions 有實際的禁止項目清單
• 無任何連線字串、密碼、金鑰、內部 IP
• Test 區塊寫明了「如何跑單一測試」
• Commit 區塊寫明了 AI 標記要求
• Human Approval 區塊列出了核准矩陣
• Definition of Done 的每一條都可驗證
• 細節規範已移至 rules/ 並以連結引用
• lint-claude-md.sh 已納入 CI
• CLAUDE.md 的變更走 PR 審查流程
• 使用者層 CLAUDE.md 只放個人偏好，不放團隊規則

第 9 章　Rules Standard

本章目錄：9.1 Rule 要解決什麼問題 ｜ 9.2 標準 Rules 清單（12 份） ｜ 9.3 Rule 的標準寫法 ｜ 9.4 責任分工：Rule 與其他機制的界線 ｜ 9.5 Rule 的強制機制對應 ｜ 9.6 本章實務案例 ｜ 9.7 本章注意事項 ｜ 9.8 本章檢查清單

9.1 Rule 要解決什麼問題

CLAUDE.md 有 200 行的長度限制（第 8 章），但企業的規範遠不止 200 行。

Rule 就是「被拆出去的細節規範」，由 CLAUDE.md 用連結引用，在 AI 需要時才載入。

flowchart LR
    C["CLAUDE.md<br/>200 行<br/>（永遠載入）"] -->|連結引用| R1["rules/coding.md"]
    C -->|連結引用| R2["rules/security.md"]
    C -->|連結引用| R3["rules/api.md"]
    C -->|連結引用| R4["rules/testing.md"]

    R1 -.需要時才讀.-> AI["Agent"]
    R2 -.需要時才讀.-> AI
    R3 -.需要時才讀.-> AI
    R4 -.需要時才讀.-> AI
    C ==>|一律讀取| AI

    style C fill:#d4edda

🎯 設計原則：CLAUDE.md 是「一定要知道的」，rules/ 是「做到那件事時才需要知道的」。

9.2 標準 Rules 清單（12 份）

rules/
├── architecture.md    # 架構規則：分層、依賴方向、模式使用
├── coding.md          # 編碼規則：命名、格式、例外處理、日誌
├── security.md        # 安全規則：輸入驗證、加解密、機敏資料
├── testing.md         # 測試規則：分層、命名、覆蓋率、Mock 原則
├── database.md        # 資料庫規則：命名、索引、migration、交易
├── api.md             # API 規則：REST 風格、錯誤格式、版本、分頁
├── frontend.md        # 前端規則：元件、狀態管理、樣式、可及性
├── backend.md         # 後端規則：服務邊界、非同步、快取、重試
├── documentation.md   # 文件規則：ADR、註解、API 文件
├── git.md             # Git 規則：分支、commit、PR、AI 標記
├── ci-cd.md           # CI/CD 規則：pipeline、品質門檻、部署
└── sddlc.md           # SSDLC 規則：各階段必要產出與核准

9.2.1 每份 Rule 的職責與關鍵內容

9.3 Rule 的標準寫法

9.3.1 Rule 檔案範本

---
title: 架構規則
owner: 首席架構師
version: 1.3.0
last_reviewed: 2026-09-01
applies_to: 所有 Java 後端服務
enforcement: ArchUnit 測試 + Code Review
---

# 架構規則

## 適用範圍

本規則適用於所有採用 Hexagonal Architecture 的 Java 後端服務。
前端請見 `frontend.md`。

## MUST（必須遵守，違反即為缺陷）

### A-M-001　domain 層不得依賴任何外部框架

- **規則**：`domain/` 套件下的類別不得 import `org.springframework.*`、
  `jakarta.persistence.*`、`com.fasterxml.jackson.*`
- **理由**：保持領域模型的技術獨立性，使其可被單元測試且可替換基礎設施
- **強制方式**：`ArchitectureTest#domainShouldNotDependOnFrameworks`
- **違反範例**：

  ```java
  // ❌ 錯誤
  package com.corp.txnquery.domain;

  import jakarta.persistence.Entity;

  @Entity
  public class Transaction { }
  ```

- **正確範例**：

  ```java
  // ✅ 正確：domain 為純 Java
  package com.corp.txnquery.domain;

  public class Transaction {
      private final TransactionId id;
      private final Money amount;
      // ...
  }

  // ✅ 持久化模型放在 adapter 層
  package com.corp.txnquery.adapter.out.persistence;

  import jakarta.persistence.Entity;

  @Entity
  class TransactionJpaEntity { }
  ```

### A-M-002　依賴方向只能由外向內

- **規則**：`adapter` → `application` → `domain`，不可反向
- **強制方式**：`ArchitectureTest#layeredArchitectureIsRespected`

## SHOULD（建議遵守，違反需在 PR 說明理由）

### A-S-001　Use Case 應為單一職責

- **規則**：一個 Use Case 類別只處理一個業務動作
- **例外情況**：批次處理可將高度相關的動作合併，但需在類別註解說明

## MUST NOT（絕對禁止）

### A-N-001　禁止在 Controller 中撰寫業務邏輯

- **規則**：Controller 只負責協議轉換（HTTP ↔ DTO ↔ Use Case 輸入）
- **判定標準**：Controller 方法內出現 `if` 的業務判斷、迴圈計算、資料庫呼叫

## 與其他規則的關係

- 測試相關要求見 `testing.md`
- 資料庫存取細節見 `database.md`

## 變更紀錄

| 版本 | 日期 | 變更 | 變更人 |
| --- | --- | --- | --- |
| 1.3.0 | 2026-09-01 | 新增 A-N-001 | 王架構師 |
| 1.2.0 | 2026-07-15 | A-M-001 新增 Jackson 限制 | 王架構師 |

9.3.2 Rule 撰寫的六個原則

⚠️ 原則 1「可判定」最重要。不可判定的規則對 AI 完全無效，AI 會用自己的標準解讀，結果因任務而異。

9.4 責任分工：Rule 與其他機制的界線

這是本章最重要的一節。很多組織的問題不是規則寫得不好，而是同一件事同時寫在五個地方，還互相矛盾。

9.4.1 七種機制的責任分工表

9.4.2 決策樹：這件事該放哪裡

flowchart TD
    Q0["我要讓 AI 遵守某件事"] --> Q1{"違反時必須<br/>「技術上被阻擋」嗎？"}
    Q1 -->|是| HOOK["→ Hook<br/>（唯一能阻擋的機制）"]
    Q1 -->|否| Q2{"是「某個技術領域<br/>的通用知識」嗎？"}

    Q2 -->|是| SKILL["→ Skill<br/>（可跨專案重用）"]
    Q2 -->|否| Q3{"是「一連串固定步驟」<br/>還是「單一約束」？"}

    Q3 -->|固定步驟| Q4{"需要特定角色視角<br/>與產出格式嗎？"}
    Q3 -->|單一約束| Q5{"重要到每次<br/>都必須知道嗎？"}

    Q4 -->|是| AGENT["→ Agent"]
    Q4 -->|否| CMD["→ Command"]

    Q5 -->|是| CMD_MD["→ CLAUDE.md<br/>（注意 200 行上限）"]
    Q5 -->|否| RULE["→ Rule"]

    style HOOK fill:#f8d7da
    style RULE fill:#d4edda

9.4.3 常見的分工錯誤

⚠️ 最嚴重的錯誤是第一列：把「必須阻擋」的事只寫成文字規則。文字規則對 AI 是「強烈建議」，不是「技術限制」。真正不能發生的事，一定要用 Hook 或權限設定攔截。

9.5 Rule 的強制機制對應

每一條 Rule 都應該說明「靠什麼檢查」。建議對應表：

🎯 一條沒有強制機制的 Rule，長期而言等於不存在。 撰寫 Rule 時，若想不出強制方式，要先問「這條規則真的必要嗎？」

9.6 本章實務案例

情境：某組織的 rules/ 有 18 份文件、共 4,200 行，但 Code Review 時發現違規率仍高。

盤點結果：

整理行動：

1. 刪除 23 條失效規則
2. 31 條通用知識移至 skills/
3. 12 條重複規則統一到 CLAUDE.md，Rule 中改為連結
4. 47 條不可判定規則：22 條改寫為可判定、25 條刪除
5. 89 條無強制機制：為其中 51 條建立自動檢查（ArchUnit 11 條、Semgrep 規則 28 條、ESLint 12 條），其餘 38 條降級為「Code Review 參考」並移至獨立章節

整理後：rules/ 縮減為 12 份、1,350 行，其中 83% 的 MUST 規則有自動強制機制。

三個月後的效果：

🎯 規則不是越多越好。62 條有強制機制的規則，勝過 300 條純文字規則。

9.7 本章注意事項

⚠️ 不可判定的規則對 AI 無效。「應該易讀」「避免過度設計」這類規則會被 AI 用自己的標準解讀。

⚠️ 真正不能發生的事，一定要用 Hook 或權限設定攔截，不能只寫文字規則。

⚠️ Rule 與 Skill 的界線要守住：專案特有 → Rule；跨專案通用 → Skill。混在一起會造成大量重複。

✅ 每條 Rule 給編號（如 A-M-001），Code Review 時可直接引用，溝通效率大幅提升。

✅ 每季度檢視一次 Rule 的有效性，刪除失效規則。規則膨脹會增加 AI 的認知負擔與 token 消耗。

📌 Rule 的檔案位置與載入機制需依 Claude Code 版本確認。本章的 rules/ 目錄為企業組織慣例，實際被 AI 讀取的方式是透過 CLAUDE.md 的連結引用，或由 Command / Agent 明確指定。

9.8 本章檢查清單

• 12 份標準 Rule 已建立（或已決定哪幾份適用）
• 每份 Rule 有 frontmatter（owner、version、last_reviewed、enforcement）
• 每條規則有編號
• 每條規則分級（MUST / SHOULD / MUST NOT）
• 每條 MUST 規則有正反範例
• 每條 MUST 規則有明確的強制機制
• 無不可判定的規則
• 通用技術知識已移至 skills/，未重複寫在 Rule
• CLAUDE.md 與 Rule 之間無內容重複
• 「必須阻擋」的事項已用 Hook 或權限設定實作，非僅文字規範
• 已建立季度檢視機制，淘汰失效規則
• 每份 Rule 有明確 Owner

第 10 章　Commands Standard

本章目錄：10.1 Command 的價值：把專家的做法變成一個指令 ｜ 10.2 企業標準 Command 清單（14 個） ｜ 10.3 Command 的標準結構 ｜ 10.4 完整實作範例一：/review ｜ 10.5 完整實作範例二：/implement ｜ 10.6 其餘 12 個 Command 的要點 ｜ 10.7 本章實務案例 ｜ 10.8 本章注意事項 ｜ 10.9 本章檢查清單

10.1 Command 的價值：把專家的做法變成一個指令

Command（slash command）是把一段標準作業流程封裝成可重複呼叫的指令。

它解決的問題是：

🎯 Command 是降低「AI 使用門檻」最有效的手段。第 3 章的實務案例中，資淺同仁使用率低的第一個原因就是「不知道要交付什麼樣的任務」——Command 直接解決這個問題。

10.2 企業標準 Command 清單（14 個）

commands/
├── analyze.md           # 分析既有程式碼
├── reverse-engineer.md  # Legacy 逆向工程
├── spec.md              # 產出需求規格
├── design.md            # 技術設計
├── implement.md         # 實作功能
├── test.md              # 產生與執行測試
├── review.md            # 程式碼審查
├── security-review.md   # 安全審查
├── refactor.md          # 重構
├── upgrade.md           # 框架升版
├── migrate.md           # 資料 / 系統遷移
├── performance.md       # 效能分析與優化
├── document.md          # 文件產出
└── release.md           # 發版前檢查

10.2.1 完整規格表

10.3 Command 的標準結構

每個 Command 檔案應包含七個區塊：

---
description: 一行說明（會出現在指令選單）
argument-hint: <參數提示>
---

# 1. 目的
# 2. 使用時機與不適用情況
# 3. 執行步驟（給 AI 的指示）
# 4. 輸出格式
# 5. 風險與限制
# 6. 人工核准要求
# 7. 使用範例

10.4 完整實作範例一：/review

---
description: 依企業標準對變更進行程式碼審查，產出分級審查報告
argument-hint: [branch|PR 編號|檔案路徑]（預設：目前工作區的變更）
---

# /review — 企業標準程式碼審查

## 1. 目的

對指定的程式碼變更執行結構化審查，產出**可行動、已分級**的審查報告。

本 Command 產出的是**審查意見**，不是「可以合併」的結論。
最終合併決策由人類 Reviewer 做出（見第 21 章）。

## 2. 使用時機

**適用**：

- 提交 PR 之前，先做一輪自我審查
- 擔任 Reviewer 時，先取得 AI 的初步意見再人工複核
- 接手他人程式碼時，快速理解風險點

**不適用**：

- 不可作為「唯一的審查」（企業規範：AI Review ≠ Human Review）
- 不適用於架構層級的決策審查（請改用 Architect Agent）

## 3. 執行步驟

請依序執行，**每一步都要實際執行指令，不要憑推測**：

### 步驟 1：取得變更範圍

```bash
# 若參數為空，審查目前工作區
git diff --stat
git diff

# 若參數為分支名
git diff --stat main...$ARGUMENTS
git diff main...$ARGUMENTS
```

### 步驟 2：載入企業規範

讀取下列檔案作為審查依據（若不存在則略過並在報告中註明）：

- `CLAUDE.md`
- `.claude/rules/coding.md`
- `.claude/rules/architecture.md`
- `.claude/rules/security.md`
- `.claude/rules/testing.md`

### 步驟 3：逐檔審查

對每個變更檔案，依下列 11 個面向檢查：

1. **Correctness（正確性）**：邏輯是否正確？邊界條件是否處理？
2. **Architecture（架構）**：是否違反分層與依賴方向？
3. **Security（安全）**：輸入驗證、輸出編碼、機敏資料處理、注入風險
4. **Performance（效能）**：N+1 查詢、不必要的迴圈、缺少索引、同步阻塞
5. **Maintainability（可維護性）**：命名、複雜度、重複、魔術數字
6. **Test Coverage（測試）**：新增邏輯是否有對應測試？測試是否有意義？
7. **Coding Standard（編碼標準）**：是否違反 `rules/coding.md` 的編號規則
8. **Dependency（相依）**：是否引入新相依？是否經核准？
9. **Error Handling（例外處理）**：是否吞掉例外？錯誤訊息是否洩漏內部資訊？
10. **Logging（日誌）**：是否記錄了機敏資料？關鍵路徑是否有日誌？
11. **Observability（可觀測性）**：是否有必要的 metric / trace？

### 步驟 4：驗證你的發現

對於每一個「正確性」或「安全」類的發現，**必須實際驗證**：

- 讀取相關的完整檔案（不要只看 diff）
- 追蹤呼叫鏈，確認影響範圍
- 若可行，撰寫一個能重現問題的測試來驗證

**若無法驗證，該發現必須標示為「待確認」，不可斷言為缺陷。**

### 步驟 5：產出報告

依第 4 節的格式輸出。

## 4. 輸出格式

```markdown
# 程式碼審查報告

- **審查範圍**：<branch / 檔案清單>
- **變更規模**：<n> 個檔案，+<n> / -<n> 行
- **審查時間**：<ISO 日期>
- **依據規範**：<實際讀取到的規範檔案清單>

## 摘要

<3 行內的整體評估>

## 🔴 Blocker（必須修正才能合併）

### B-1　<標題>

- **位置**：`檔案:行號`
- **問題**：<描述>
- **影響**：<具體的失敗情境：什麼輸入 → 什麼錯誤結果>
- **驗證方式**：<你如何確認這是真的問題>
- **建議修正**：<具體做法或程式碼>

## 🟡 Major（強烈建議修正）

（格式同上）

## 🔵 Minor（可選）

（格式同上）

## ⚪ 待確認（無法驗證，需開發者確認）

### U-1　<標題>

- **位置**：`檔案:行號`
- **疑慮**：<描述>
- **無法驗證的原因**：<說明>

## 檢查面向覆蓋狀況

| 面向 | 狀態 | 備註 |
| --- | --- | --- |
| Correctness | ✅ 已檢查 | — |
| ... | | |

## 人類 Reviewer 應特別注意

<列出 AI 無法判斷、需要人類商業知識的部分>
```

## 5. 風險與限制

> ⚠️ 本 Command 的限制：

- AI **無法判斷商業邏輯是否符合業務需求**——這需要人類的領域知識
- AI **可能遺漏跨系統的整合問題**——只看得到本 repo
- AI **可能產生誤報**——因此要求每個發現都需驗證，無法驗證者列為「待確認」
- 本 Command 為**唯讀**，不會修改任何檔案

## 6. 人工核准要求

- 本 Command 執行**不需要**核准（唯讀）
- 但**審查結果不可作為合併依據**，必須有人類 Reviewer 覆核（企業 MUST 規範，見 `governance/ai-coding-policy.md`）

## 7. 使用範例

```bash
# 審查目前工作區的變更
/review

# 審查某個分支相對於 main 的變更
/review feature/TXN-1234-add-filter

# 只審查特定檔案
/review src/main/java/com/corp/txnquery/application/QueryTxnUseCase.java
```

10.5 完整實作範例二：/implement

---
description: 依設計文件或 Issue 實作功能，強制先計畫後執行
argument-hint: <Issue 編號或設計文件路徑>
---

# /implement — 企業標準功能實作

## 1. 目的

將已確認的設計或 Issue 轉換為程式碼與測試，並**自行驗證**後回報。

## 2. 使用時機

**適用**：設計已確認、驗收條件明確的功能實作。

**不適用**：

- 設計尚未確認 → 請先用 `/design`
- 需求不明確 → 請先用 `/spec`
- 大範圍重構 → 請用 `/refactor`

## 3. 執行步驟

### 階段 A：理解（不修改任何檔案）

1. 讀取 `CLAUDE.md` 與相關 `rules/`
2. 讀取指定的 Issue 或設計文件
3. 搜尋並讀取**相關的既有程式碼**（至少包含：將被修改的類別、其呼叫者、其測試）
4. 確認既有測試的涵蓋狀況

### 階段 B：計畫（**必須停下來等待確認**）

輸出下列計畫，然後**停止，等待使用者確認後才繼續**：

```markdown
## 實作計畫

### 我的理解
<用自己的話重述要做什麼，包含驗收條件>

### 待確認事項
<列出所有不確定的點。若無則寫「無」。
 ⚠️ 重要：不確定的事項必須列出，不可自行假設。>

### 將修改的檔案
| 檔案 | 動作 | 說明 |
| --- | --- | --- |

### 將新增的檔案
| 檔案 | 說明 |
| --- | --- |

### 測試策略
<要新增哪些測試？測試什麼情境？>

### 風險
<可能影響到的其他功能>

### 需要人工核准的項目
<依 CLAUDE.md 第 18 節判斷，列出需核准項目；若無則寫「無」>
```

> ⚠️ **若計畫涉及 `CLAUDE.md` 第 17 節（Forbidden Actions）的任何項目，必須立即停止並說明，不可執行。**

### 階段 C：實作

使用者確認後才執行：

1. **先寫測試**（若專案採 TDD）或**先確認既有測試可通過**
2. 依計畫逐一修改檔案
3. **每完成一個邏輯單元就執行一次相關測試**，不要全部改完才測

### 階段 D：驗證（**必須實際執行**）

```bash
mvn -q test                     # 單元測試
mvn -q verify -Pintegration     # 整合測試（若專案有）
```

**必須貼上實際輸出**。不可只說「測試應該會通過」。

若測試失敗：

1. 分析失敗原因
2. 判斷是「實作錯誤」還是「測試預期需更新」
3. **若是後者，必須明確說明理由並請使用者確認**——不可自行修改測試來讓它通過

> ⚠️ **嚴禁為了讓測試通過而修改或刪除測試的斷言**。這是企業 MUST NOT 規範。

### 階段 E：回報

```markdown
## 實作完成報告

### 變更摘要
<做了什麼>

### 變更檔案
| 檔案 | 變更類型 | 行數 |
| --- | --- | --- |

### 測試結果
```text
<貼上 mvn test 的實際輸出>
```

### 覆蓋率變化
<變更前 → 變更後>

### Definition of Done 檢核
<逐項對照 CLAUDE.md 第 19 節>

### 我沒有做的事
<列出計畫中但未完成的項目與原因>

### 建議人類 Reviewer 重點檢查
<列出你最不確定的部分>
```

## 4. 輸出格式

見上述階段 B 與階段 E。

## 5. 風險與限制

> ⚠️ 本 Command **會修改檔案**。建議在 git worktree 中執行（見第 6 章 6.7 節）。

- AI 可能誤解需求 → 階段 B 的計畫確認是主要防線
- AI 可能破壞既有功能 → 階段 D 的測試是主要防線
- **若專案測試覆蓋率低，風險顯著提高**

## 6. 人工核准要求

| 時點 | 核准者 | 說明 |
| --- | --- | --- |
| 階段 B 結束 | 任務指派者 | **必要**，確認計畫正確 |
| 若涉及架構變更 | 架構師 | 見 `CLAUDE.md` 第 18 節 |
| 若涉及 DB schema | DBA | 見 `CLAUDE.md` 第 18 節 |
| 合併前 | Reviewer | 必要 |

## 7. 使用範例

```bash
/implement TXN-1234
/implement docs/design/2026-09-15-date-range-filter.md
```

10.6 其餘 12 個 Command 的要點

由於篇幅，以下列出其餘 Command 的關鍵設計要點，完整檔案請依 10.3 的結構撰寫並存放於共用 repo。

10.7 本章實務案例

情境：某團隊導入 /implement 前後的對比實測（同一批 12 個中小型 Issue，6 人參與）。

導入前（自由 prompt）：

導入後（使用 /implement）：

效果最顯著的三個設計：

1. 階段 B 強制停下來確認計畫 → 誤解需求的問題在成本最低的時候被發現
2. 階段 D 強制貼出測試實際輸出 → 杜絕「應該可以」這種未經驗證的宣稱
3. 「我沒有做的事」欄位 → 讓未完成項目顯性化，不會被默默略過

🎯 Command 最大的價值，是把「資深同仁的謹慎」制度化，讓每個人都得到同樣的謹慎。

10.8 本章注意事項

⚠️ 高風險 Command（/refactor、/upgrade、/migrate）必須在 git worktree 中執行（第 6 章 6.7 節）。

⚠️ /migrate 絕對禁止操作生產資料。這應該同時由 settings.json 的 deny 規則與 Hook 雙重攔截。

⚠️ 不要讓 Command 變成「黑箱」。每個 Command 都應該在輸出中說明「我讀了哪些檔案、執行了哪些指令」，讓使用者可以判斷它的結論是否可信。

✅ Command 要有「不適用情況」區塊。告訴使用者什麼時候該用別的，比列出功能更有價值。

✅ 要求 AI 貼出實際執行輸出，是提升可信度最有效的單一設計。

📌 Command 的檔案格式（frontmatter 欄位、$ARGUMENTS 變數、存放位置）需依 Claude Code 版本確認，請以官方文件為準。

10.9 本章檢查清單

• 14 個標準 Command 已建立（或已決定優先建立哪幾個）
• 每個 Command 有 7 個標準區塊
• 每個 Command 標明了「不適用情況」
• 每個 Command 標明了風險等級與人工核准要求
• /implement 有強制的「計畫確認」停頓點
• 所有會修改檔案的 Command 都要求實際執行測試並貼出輸出
• 高風險 Command 已註明需在 worktree 中執行
• /reverse-engineer 已強制 Fact/Inference/Unknown 標記
• /refactor 有「前置條件：目標範圍需有測試」的檢查
• /upgrade 要求以官方 migration guide 為輸入
• /migrate 已明確禁止操作生產資料
• Command 已同步至各專案（第 7 章同步機制）
• 已對團隊說明「哪個任務該用哪個 Command」

第 11 章　Skills Standard

本章目錄：11.1 Skill 不只是 Prompt ｜ 11.2 Skill 的三個層級 ｜ 11.3 企業 Skill Catalog ｜ 11.4 Skill 的標準結構 ｜ 11.5 Skill 的生命週期管理 ｜ 11.6 本章實務案例 ｜ 11.7 本章注意事項 ｜ 11.8 本章檢查清單

11.1 Skill 不只是 Prompt

很多人把 Skill 理解成「存起來的 prompt」。這個理解會讓 Skill 的價值被嚴重低估。

🎯 Skill 是「可重複使用的 AI Engineering Capability」——一個被封裝的、可被自動載入的專業能力單元。

11.2 Skill 的三個層級

企業建議把 Skill 分為三級，管理方式不同：

flowchart TB
    L1["L1 知識型 Skill<br/>Knowledge Skill"]
    L2["L2 流程型 Skill<br/>Process Skill"]
    L3["L3 可執行 Skill<br/>Executable Skill"]

    L1 --> L1D["內容：框架用法、API、最佳實務<br/>例：spring-boot、vue3、primevue<br/>風險：低<br/>審查：領域專家"]
    L2 --> L2D["內容：多步驟的專業流程<br/>例：ddd-tactical-design、archunit-setup<br/>風險：中<br/>審查：領域專家 + 架構師"]
    L3 --> L3D["內容：含可執行腳本<br/>例：jmeter-run、db-schema-diff<br/>風險：高（會執行程式碼）<br/>審查：領域專家 + 架構師 + 資安"]

    style L1 fill:#d4edda
    style L2 fill:#fff3cd
    style L3 fill:#f8d7da

⚠️ L3 可執行 Skill 含有會被執行的程式碼，必須經資安審查。這是供應鏈風險的入口（第 23 章）。

11.3 企業 Skill Catalog

以下為建議建立的 Skill 清單，依組織的技術棧分類。

11.3.1 後端語言與框架

11.3.2 前端

11.3.3 資料庫

11.3.4 整合與中介軟體

11.3.5 安全

11.3.6 測試

11.3.7 架構與設計

📌 本 repo 已有多份相關教學可作為 Skill 內容來源：Clean Architecture教學.md、Hexagonal Architecture設計教學.md、Domain-Driven Design教學.md、Refactoring重構教學.md、Jmeter使用教學.md 等。建議引用而非複製，避免內容分歧。

11.4 Skill 的標準結構

11.4.1 目錄結構

skills/
└── java-25/
    ├── SKILL.md              # 主檔（必要）
    ├── references/           # 參考資料（依需要載入）
    │   ├── virtual-threads.md
    │   ├── pattern-matching.md
    │   └── migration-from-21.md
    └── scripts/              # 僅 L3 需要
        └── check-preview-features.sh

11.4.2 SKILL.md 範本

---
name: java-25
description: Java 25 的新特性與正確用法，包含 Virtual Threads、Pattern Matching、Records、Sealed Classes 與從 Java 21 遷移的注意事項。在撰寫或審查 Java 25 程式碼、評估新特性適用性、或處理 Java 版本遷移時使用。
level: L1
owner: Java 架構師
version: 1.2.0
last_reviewed: 2026-09-01
---

# Java 25 開發指引

## 何時使用本 Skill

- 撰寫或審查以 Java 25 為目標的程式碼
- 評估是否該使用某個新特性
- 從 Java 21 或更舊版本遷移

## 核心原則

1. **新特性不是為了用而用**。每個特性都有適用情境與代價。
2. **企業專案優先考慮可維護性**，而非展示最新語法。
3. 涉及並行的變更**必須有壓測佐證**。

## Virtual Threads

### 適用情境

✅ **適合**：

- I/O 密集的任務（資料庫查詢、HTTP 呼叫、檔案讀寫）
- 高並發、每個任務等待時間長的場景

❌ **不適合**：

- CPU 密集的運算（用 platform thread 或 ForkJoinPool）
- 需要 thread-local 大量狀態的既有程式碼

### 正確用法

```java
// ✅ 正確：I/O 密集任務
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    List<Future<TxnDetail>> futures = txnIds.stream()
        .map(id -> executor.submit(() -> txnClient.fetch(id)))
        .toList();
    // ...
}
```

### 常見錯誤

```java
// ❌ 錯誤 1：在 virtual thread 中使用 synchronized 造成 pinning
//    （視 JDK 版本而定，部分版本會使 virtual thread 被釘住）
synchronized (lock) {
    httpClient.send(request);   // I/O in synchronized block
}

// ✅ 修正：改用 ReentrantLock
private final ReentrantLock lock = new ReentrantLock();
lock.lock();
try {
    httpClient.send(request);
} finally {
    lock.unlock();
}
```

```java
// ❌ 錯誤 2：為 virtual thread 建立 pool
//    virtual thread 很便宜，不需要 pool
var pool = Executors.newFixedThreadPool(200, Thread.ofVirtual().factory());
```

> ⚠️ **企業規範**：改用 Virtual Threads 前，必須先以 JMeter 壓測取得基線數據，
> 改完後再次壓測比對。見 `rules/backend.md` B-M-014。

## Pattern Matching 與 Sealed Classes

（內容略，結構同上：適用情境 → 正確用法 → 常見錯誤 → 企業規範）

詳細說明見 `references/pattern-matching.md`。

## 從 Java 21 遷移

見 `references/migration-from-21.md`。

## 不確定時

> 📌 若對某個特性在本組織的適用性不確定，**標示為「待確認」並詢問 Java 架構師**，
> 不要自行假設。

## 相關資源

- 企業 Java 編碼規範：`rules/coding.md`
- 本 repo 的 Java 25 教學：`content/posts/教學/程式語言/Java25升版教學.md`
- 官方文件：以 OpenJDK 官方發行說明為準

11.4.3 description 欄位的寫法（最關鍵）

description 決定了 AI 會不會在正確的時機載入這個 Skill。寫得不好，Skill 等於不存在。

✅ 建議公式：<涵蓋的內容，含關鍵字> + 「在 <情境 1>、<情境 2>、<情境 3> 時使用。」

11.5 Skill 的生命週期管理

flowchart LR
    A["需求提出<br/>（某專案反覆需要某知識）"] --> B["撰寫草稿<br/>prompts/incubator/"]
    B --> C["試用 2～4 週<br/>至少 2 個專案"]
    C --> D{"確實有效？"}
    D -->|否| E["修正或放棄"]
    D -->|是| F["提 PR 至 skills/"]
    F --> G{"層級判斷"}
    G -->|L1/L2| H["領域專家審查"]
    G -->|L3| I["領域專家 + 架構師<br/>+ 資安審查"]
    H --> J["納入 Catalog"]
    I --> J
    J --> K["季度檢視"]
    K -->|技術仍適用| J
    K -->|技術已汰換| L["deprecated → 移除"]

    style I fill:#f8d7da
    style J fill:#d4edda

11.5.1 Skill 品質檢查清單

新增 Skill 時，審查者應確認：

• description 包含「內容」與「何時使用」
• 有明確的「適用 / 不適用」說明
• 有正確範例與錯誤範例（錯誤範例往往更有價值）
• 有企業特有的規範（而非只是官方文件摘要）
• 有「不確定時該問誰」的指引
• 版本與 owner 已填寫
• L3 Skill 的腳本已經資安審查
• 內容與既有 Rule / Skill 無矛盾
• 檔案大小合理（過大應拆至 references/）

11.5.2 claude.ai 同步技能的治理（v2.1 新增）【官方】

v2.1 查證時最需要注意的變化：Skill 的來源不再只有 repo。以 claude.ai 帳號登入的終端機 session，會自動載入成員在 claude.ai 啟用的 skills（v2.1.275 起同步 plugins），不需要任何設定。