路徑條件式規則載入

Path-specific rules 是 Claude Code 指令系統的條件式層——讓不同資料夾、不同檔案類型與不同子樹能各自套用不同的程式碼慣例，而不必讓所有專案都擠在同一份龐大的 CLAUDE.md 裡運作。在 Claude Certified Architect — Foundations（CCA-F）考試任務說明 3.3——「為條件式慣例載入套用 path-specific rules」——歸屬 Domain 3（Claude Code 設定與工作流程，佔比 20%），是藍圖中最常被低估備考的子主題之一。能通過這道任務說明的考生，清楚知道 .claude/rules/ 目錄是如何被探索到的、paths: glob 模式如何讓某個 rule 檔對特定目標檔案生效，以及 path-specific rules 如何與更廣泛的 CLAUDE.md 階層共同作用而非取而代之。

這份學習筆記涵蓋 CCA-F 考生需要在架構層級掌握的完整範疇：path-specific rules 存在的理由、.claude/rules/ 目錄的探索模型、rule 檔的結構（YAML frontmatter + rule 內文）、paths: glob 語法、Claude Code 在解析當前目標檔案慣例時的 rule 啟動邏輯、框架特定子樹的慣例隔離、測試檔專屬的 rule、monorepo 套件範圍的 rule、多個 rule 檔同時匹配時的優先順序、與目錄層級 CLAUDE.md 檔的關係，以及如何除錯某個 session 中究竟哪些 rule 正在生效。最後的考試陷阱章節與五道 FAQ，將所有抽象概念連回最重度練習任務 3.3 的 code-generation-with-claude-code 情境。

Path-Specific Rules — 依檔案位置套用不同慣例

位於專案根目錄的 CLAUDE.md 會在該專案的每一個任務中被載入——對小型、同質化的程式碼庫來說，這是合理的預設行為。一旦程式碼庫不再同質——後端套件使用一套框架、前端使用另一套、某個自動產生的程式碼資料夾絕對不能手動修改、測試檔使用與正式程式碼不同的斷言風格——單一根目錄的 CLAUDE.md 就會成為一堵充滿條件邏輯的文字牆（「如果你在編輯 src/api/* 則……；如果你在編輯 tests/* 則……；除非該檔案結尾是 .generated.ts 否則……」）。Claude 遵循這些條件分支的可靠性遠不如無條件指令，而這份檔案也終將膨脹成難以維護的巨型設定。

Path-specific rules 讓架構師能夠以檔案位置為條件來表達慣例，從而解決上述問題。架構師不再需要在根目錄 CLAUDE.md 塞入「如果你在編輯測試」分支，而是在 .claude/rules/ 下放一個小型 rule 檔，其 frontmatter 宣告「此 rule 只在 Claude Code 處理符合 tests/** 的檔案時才生效」。Claude Code 只在當前目標檔案符合 rule 的某個 paths: 模式時，才將該 rule 載入上下文。不相關的 rule 不占 token，相關的 rule 永遠在場，根目錄 CLAUDE.md 保持精簡。

Path-Specific Rules 在架構上為何存在

Path-specific rules 所解決的設計問題，是在編輯當下的指令相關性。當 Claude Code 即將編輯 apps/web/src/pages/index.astro 時，Astro 的慣例才重要，Python 後端的 ruff 格式化規則根本無關緊要。把後端 rule 載入前端編輯的上下文，是純粹的雜訊——消耗 token、增加跨框架混淆的風險，也稀釋了 Claude 對真正相關 rule 的注意力。Path-specific rules 是 Claude Code 的解答：把指令載入的範圍限定於檔案位置，讓每個任務都只看到最精簡、最正確的慣例集合。

與 CLAUDE.md 檔的差異

CLAUDE.md 檔在位於當前工作目錄階層之上時永遠被載入（全域、專案、目錄層級）。Path-specific rule 則是依據 Claude Code 即將操作的檔案是否符合某個 glob 模式，有條件地被載入。兩套系統共存：CLAUDE.md 承載專案層級的不變規則（「我們到處使用 TypeScript strict mode」、「所有公開函式必須有 JSDoc」）；path-specific rules 承載子樹特定的慣例（「測試使用 vitest.describe 分組」、「這個目錄是自動產生的，絕對不要手動編輯」）。把兩者視為可互換，是常見的 CCA-F 陷阱。

.claude/rules/ 目錄 — YAML Rule 檔與探索機制

Claude Code 在一個固定位置尋找 path-specific rules：專案根目錄下的 .claude/rules/ 目錄。該目錄中的每個檔案（依 Claude Code 版本，通常副檔名為 .yaml、.yml 或 .md）都是候選 rule。Claude Code 在 session 開始時讀取每個候選 rule 的 frontmatter，索引其 paths: 模式，並在 agent 即將讀取、寫入或編輯某個檔案時，逐一比對這些模式。

目錄結構

my-project/
├── CLAUDE.md                      # 專案層級，永遠載入
├── .claude/
│   ├── rules/
│   │   ├── frontend.yaml          # 套用於 apps/web/**
│   │   ├── backend.yaml           # 套用於 services/api/**
│   │   ├── tests.yaml             # 套用於 **/*.test.ts
│   │   └── generated.yaml         # 套用於 **/*.generated.ts
│   └── commands/                  # 自訂 slash commands（任務 3.2）
├── apps/
│   └── web/
│       └── CLAUDE.md              # 目錄範圍的 CLAUDE.md（任務 3.1）
├── services/
│   └── api/
└── tests/

Rule 檔很輕量——通常每個只有幾條項目符號。該目錄受版本控制，確保每位協作者與每次 CI 執行都看到相同的慣例。

使用者層級 vs 專案層級的 Rule

Claude Code 的設定階層區分了使用者層級 rule（存放於 ~/.claude/rules/，套用於開發者機器上的所有專案）與專案層級 rule（存放於 repository 內的 .claude/rules/，只套用於該專案）。使用者層級 rule 適合不應強加給隊友的個人偏好（偏好的 commit message 措辭、個人別名）。專案層級 rule 適合必須對每位協作者生效的團隊慣例。CCA-F 的考題經常測試這項區別。

探索是自動的

與必須以名稱呼叫的自訂 slash commands 不同，path-specific rules 不需要任何明確的使用者指令。Claude Code 在 session 開始時，藉由遍歷 .claude/rules/ 目錄自動探索這些 rule。不需要 CLI flag、不需要 import 陳述式、不需要 slash command——rule 在 session 一開啟時就已生效。

YAML Rule 檔結構 — paths Frontmatter、Rule 內文、優先順序

每個 path-specific rule 檔都有相同的兩段式結構：一個 YAML frontmatter 區塊和一個 rule 內文。Frontmatter 控制 rule 何時生效；內文承載實際的指令。

Frontmatter 欄位

---
name: "Frontend Astro conventions"
description: "Astro + Tailwind conventions for apps/web"
paths:
  - "apps/web/**"
  - "apps/web/src/**/*.astro"
priority: 50
---

• name — 簡短標籤，Claude Code 在顯示哪個 rule 生效時會使用到。
• description — 單行摘要（有助於團隊文件；非必填）。
• paths — glob 模式的陣列；當目標檔案符合至少一個模式時，rule 啟動。
• priority — 可選整數，當兩個 rule 同時匹配同一檔案時決定勝負（數字較高者勝）。

Rule 內文

在 --- 分隔符之後，rule 內文是自由格式的散文或項目清單，描述各項慣例。寫法與 CLAUDE.md 完全相同——使用命令式語句、簡短、易於掃描。

---
paths:
  - "apps/web/**"
---

## Astro component conventions

- Use `.astro` files for pages; colocate `.svelte` components under `src/components/`.
- Styles go in Tailwind utility classes; no inline `<style>` blocks in page files.
- Data fetching happens in the component frontmatter, never in a `<script>` tag.
- For i18n, use the `useTranslations(lang)` helper from `src/i18n.ts`.

為什麼使用 YAML Frontmatter 而非其他格式

YAML frontmatter 是靜態網站產生器（Astro、Jekyll、Hugo）、文件工具（MDX、Docusaurus），以及 Claude Code 自身的 slash commands 和 skills 共同使用的慣例。這種重複使用很重要：工程師早已熟悉這個格式，編輯器早已能語法高亮，CI linter 也能驗證。為這一個功能另外採用一套專屬設定語法，只會帶來無謂的摩擦。

paths Glob 模式 — 匹配 src/**、tests/**、*.test.ts 等

paths: 陣列使用的是 glob 模式，而非正規表達式。這是 CCA-F 任務 3.3 考題中最常被忽略的機械性細節。

你會遇到的 Glob 運算子

• * 匹配單一路徑段（segment）內的任意字元序列（不跨越 /）。
• ** 匹配任意數量的路徑段，包含零個。src/** 匹配 src/a.ts、src/a/b.ts、src/a/b/c.ts。
• ? 匹配恰好一個字元。
• [abc] 匹配括號內的任一字元。
• {json,yaml,yml} 匹配以逗號分隔的任一替代字串（大括號展開）。

常見模式及其匹配範圍

paths:
  - "src/**"                # src/ 下的所有檔案
  - "**/*.test.ts"          # 任何位置的所有 .test.ts 檔案
  - "**/*.{test,spec}.ts"   # 任何位置的所有 .test.ts 或 .spec.ts 檔案
  - "services/api/src/**"   # 只限後端套件的原始碼樹
  - "**/generated/**"       # 樹中任何位置的 generated/ 資料夾
  - "!**/node_modules/**"   # 否定 — 排除 node_modules

模式是相對於專案根目錄（包含 .claude/ 資料夾的目錄）來計算的。不支援絕對路徑、~ 展開和環境變數。

Glob 不是 Regex

src/*.ts 這個 glob 只匹配直接位於 src/ 下的 TypeScript 檔案，不匹配 src/components/Button.ts。要遞迴匹配必須使用 **。正規表達式 src/.*\.ts 兩者都能匹配，但 paths: 的解釋方式並非如此。混淆這兩種心理模型，是 CCA-F Domain 3 前五大陷阱之一。

否定模式

以 ! 開頭的模式會排除否則會匹配的檔案。否定適合用在「src/ 下的所有檔案，但排除自動產生的檔案」這類 rule：

paths:
  - "src/**"
  - "!src/**/generated/**"

計算器依序處理模式，最後一個匹配勝出，因此清單末尾的否定會覆蓋前面的包含模式。

Rule 啟動邏輯 — Claude Code 如何決定哪些 Rule 適用於當前檔案

當 Claude Code 即將讀取、寫入或編輯某個檔案時，會執行以下的啟動序列：

1. 計算該檔案相對於專案根目錄的路徑。 apps/web/src/pages/index.astro 相對於 /my-project/ 計算。
2. 遍歷所有在 .claude/rules/ 中探索到的 rule 檔。 對每個 rule，逐一比對 paths: 陣列中的每個模式與相對路徑。
3. 當至少一個 paths: 模式匹配時，rule 即啟動。 同一 rule 清單中的否定模式可以否決較早的匹配。
4. 已啟動的 rule 內文被載入 Claude 的上下文，用於產生編輯或讀取的推理輪次。
5. 未啟動的 rule 完全被略過——它們不貢獻 token，也不影響回應。

啟動是逐檔案的，而非逐 Session 的

長時間的 agent 執行可能觸及許多檔案。Path-specific rule 的啟動是逐檔案計算的（實際上是逐個指名某個檔案的工具呼叫）。編輯 apps/web/src/index.astro 時啟動 frontend rule；緊接著編輯 services/api/src/main.ts 時則改為啟動 backend rule。Claude Code 不會在 session 開始時「鎖定」一組 rule 並貫穿整個 session。

啟動在實際操作中的樣貌

想像一個 session 先讀取 tests/login.test.ts，再讀取 src/auth.ts，接著編輯 src/auth.ts，最後執行 bash pnpm test。第一個 Read 工具呼叫啟動 tests.yaml；讀取和編輯 src/auth.ts 啟動 backend.yaml（或任何以 src/** 為目標的 rule）；Bash 呼叫因為不指向某個檔案，所以不觸發任何 file-path rule。四次工具呼叫、三次不同的 rule 啟動、使用者零次手動介入。

逐檔案啟動的重要性

逐檔案啟動意味著 rule 不會跨子樹洩漏。當 agent 從 Python 套件移動到 TypeScript 套件時，Python 格式化 rule 停止被載入，TypeScript strict-mode rule 取而代之。這正是 path-specific rules 在架構上的回報：上下文中的慣例，永遠是正在處理的那個檔案所應套用的慣例。

慣例隔離 — 為框架目錄套用框架專屬的 Rule

Path-specific rules 最清晰的使用情境是異質程式碼庫中的框架隔離。一個專案若同時使用 Astro 做行銷網站、Next.js 做內部儀表板、FastAPI 做 Python 後端，就不可能合理地把三個框架的慣例全部塞進一份 CLAUDE.md。這些慣例在某些地方相互矛盾（React hook 規則 vs Astro islands、FastAPI 依賴注入 vs 完全不相關），而且對任何特定任務來說，大多數檔案的 rule 都是無關緊要的。

典型的三框架佈局

.claude/
└── rules/
    ├── astro.yaml         # paths: ["apps/marketing/**"]
    ├── nextjs.yaml        # paths: ["apps/dashboard/**"]
    └── fastapi.yaml       # paths: ["services/api/**"]

每個 rule 檔只承載其框架的慣例：元件模式、資料擷取慣用法、樣式方式、測試函式庫。當 Claude Code 在編輯行銷網站的元件時，只看到 Astro 的慣例；當它在編輯 FastAPI 路由時，只看到 Python 和 FastAPI 的慣例。沒有跨框架污染，沒有堆積在一份巨型 CLAUDE.md 裡的條件文字。

隔離降低跨框架混淆的風險

若不使用 path-specific rules，試圖在一份 CLAUDE.md 裡涵蓋三個框架的架構師，就必須寫出像這樣的句子：「編輯 Astro 檔案時使用 Tailwind 做樣式；編輯 Next.js 檔案時使用 CSS modules；編輯 FastAPI 檔案時什麼都不用，因為那是 Python。」每個條件分支都是 Claude 的認知負擔，也都有一定概率走錯分支。透過 .claude/rules/ 的慣例隔離完全消除了這些條件——Astro rule 就只是「使用 Tailwind utility classes 做樣式」，不需要任何 在編輯……時 的防護，因為這個 rule 從來不會在 Astro 檔案以外的地方啟動。

測試專屬 Rule — 測試檔與正式程式碼的不同慣例

測試檔幾乎永遠值得擁有自己的 rule 檔。讓正式程式碼出色的慣例（最少注解、小函式、共用 helper、避免重複），對測試來說往往完全相反——在測試中，明確性勝過抽象，重複的搭手腳架優於隱藏設定的共用 fixture。

典型的測試專屬 Rule

---
name: "Test file conventions"
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
  - "tests/**"
---

## Test conventions

- Use `describe` blocks to group related tests; one top-level `describe` per file.
- Every test's `it(...)` string should read as a sentence: "it returns null when input is empty."
- Prefer explicit arrange/act/assert sections with blank-line separators.
- Do NOT extract test setup into shared helpers unless it is used in 3+ files.
- Mocks are created inline inside each test, not hoisted to the top of the file.

為什麼獨立的 Rule 檔勝過 CLAUDE.md 的一個章節

根目錄 CLAUDE.md 中標題為「編輯測試檔時」的章節，仰賴 Claude 記得套用它。而帶有 paths: ["**/*.test.ts"] 的獨立 rule 檔，會在目標檔案是測試時無條件生效，不是測試時則從不生效。後者在結構上更可靠。

Code-Generation-With-Claude-Code 情境

CCA-F 的 code-generation 情境直接練習測試檔 rule。請預期會有情境題，agent 被要求「為登入流程新增測試」，而正確答案涉及 Claude Code 在開啟 login.test.ts 時載入測試專屬 rule——不是因為使用者指名了該 rule，而是因為 glob 自動觸發了它。

Monorepo 使用情境 — 單一 Repo 中各套件的語言與框架 Rule

大型 monorepo 是 path-specific rules 最自然的家。一家公司的 repo 可能包含 TypeScript 網頁應用程式、Go CLI、Python 資料 pipeline 和 Rust 服務，各自有完全不同的工具鏈、風格指南和測試慣例。單一根目錄 CLAUDE.md 可以承載跨套件的不變規則（「所有 commit message 遵循 conventional commits」），而每個套件的慣例則住在自己的 rule 檔中。

真實的 Monorepo 佈局

mono/
├── CLAUDE.md                      # 全團隊不變規則
├── .claude/
│   └── rules/
│       ├── web-app.yaml           # paths: ["packages/web/**"]
│       ├── cli-tool.yaml          # paths: ["packages/cli/**"]
│       ├── data-pipeline.yaml     # paths: ["packages/pipeline/**"]
│       └── rust-service.yaml      # paths: ["services/gateway/**"]
├── packages/
│   ├── web/
│   ├── cli/
│   └── pipeline/
└── services/
    └── gateway/

Rule 檔為何勝過單獨使用套件範圍的 CLAUDE.md

Monorepo 也可以在每個套件下嵌套 CLAUDE.md 檔案（packages/web/CLAUDE.md、packages/cli/CLAUDE.md）。這是合理且在許多小型情境中足夠的做法。Rule 檔增加價值的地方，在於某個慣例必須跨越多個套件（例如「所有自動產生的程式碼都使用這個 header comment，無論位於哪個套件」），或者某個慣例必須套用於一個套件內特定副檔名的檔案，而非整個套件。帶有 paths: ["**/*.generated.ts"] 的 path-specific rule 一次就匹配所有套件中的自動產生檔案，這是任何單一 CLAUDE.md 放置位置都無法做到的。

Monorepo Rule 衛生

保持 rule 內文簡短。一個有十個 path-specific rule 檔、每個有三百行的 monorepo，即便是瑣碎的編輯也會載入數百個 token 的額外負擔。每個 rule 內文應該精煉到工程師能在三十秒內讀完，且每個項目符號都是不可或缺的。

Rule 衝突 — 多個 Rule 同時匹配相同路徑時的優先順序

單一檔案同時匹配多個 rule 檔是常見且合理的情況。tests/integration/auth.test.ts 可能同時匹配 tests.yaml（透過 **/*.test.ts）和 integration-tests.yaml（透過 tests/integration/**）。Claude Code 不會只選一個而捨棄其他——它會載入所有匹配的 rule。當 rule 的指令互相矛盾時，衝突解決就很重要。

優先順序

當兩個或更多 rule 匹配同一檔案且其指令衝突時，優先順序依此解決：

1. 更具體的 paths: 模式勝出。 匹配更少檔案的模式被視為更具體。tests/integration/** 比 tests/** 更具體，tests/** 又比 ** 更具體。
2. 較高的 priority: 欄位勝出。 若具體程度相同，frontmatter 中 priority: 值較高的 rule 覆蓋較低的。
3. 較晚載入的 rule 作為最終平局決定。 Rule 探索順序是確定性的（通常依檔案名稱的字母序），當所有其他解決條件相同時，較晚載入的 rule 的指令優先。

非衝突的組合

大多數多重 rule 啟動並非衝突——它們是可加性的。同時匹配 tests.yaml 和 backend.yaml 的檔案，會在上下文中取得兩組指令，且它們能夠乾淨地組合（「使用 describe/it + 使用結構化錯誤回應」）。衝突解決只在真正的矛盾發生時才重要（「使用 Tailwind」vs「使用 CSS modules」）。架構師應以最小化矛盾為目標來設計 rule，而非依賴優先順序來收拾殘局。

與 CLAUDE.md 的衝突

矛盾階層中更高層 CLAUDE.md 指令的 path-specific rule，不會靜默地勝出。CLAUDE.md 指令構成預設的慣例集；path-specific rules 補充它。當兩者真正不一致時，將 path-specific rule 視為本地例外，並在 rule 內文中明確說明：「在此子樹中，我們偏離了 X 的專案層級規則，原因是 Y。請遵循此處的本地規則。」明確的說明能避免 Claude 猜測該聽誰的。

與目錄 CLAUDE.md 的互動 — Rule 疊加在 CLAUDE.md 指令之上

Path-specific rules 不取代目錄層級的 CLAUDE.md 檔——它們共存。理解這個疊加關係，是任務 3.1 和任務 3.3 的共同核心。

三層指令模型

1. 根目錄 CLAUDE.md — 永遠載入，承載專案層級的不變規則。
2. 目錄 CLAUDE.md 檔 — 當工作目錄位於或低於 CLAUDE.md 所在目錄時載入。它們添加目錄特定的無條件上下文。
3. .claude/rules/ 中的 path-specific rules — 依據目標檔案的路徑有條件地載入，與當前工作目錄無關。

三層全部疊加。對 apps/web/src/index.astro 的編輯，可以同時拉入根目錄 CLAUDE.md、apps/web/CLAUDE.md 和 .claude/rules/astro.yaml rule 檔。三者共同構成該次編輯的完整指令上下文。

各層的使用時機

• 根目錄 CLAUDE.md 用於套用到專案每個檔案的不變規則。例如：「我們使用 pnpm，不用 npm」、「commit messages 遵循 conventional commits」、「每個 PR 必須有測試」。
• 目錄 CLAUDE.md 用於整個子樹共享、與該子樹中的任何檔案都永遠相關的上下文，與副檔名或檔案類型無關。例如：apps/web/CLAUDE.md 記錄網頁應用程式的資料擷取模式與路由慣例，套用於網頁應用程式中的每個檔案。
• Path-specific rule 用於適用性以檔案模式為條件的情況（測試 vs 正式程式碼、自動產生 vs 手寫、一種副檔名 vs 另一種），或者當 rule 必須跨越多個目錄時（所有 *.generated.ts 檔案，無論位於哪個套件）。

為什麼這個疊加關係對考試很重要

CCA-F 的干擾答案習慣性地把目錄 CLAUDE.md 與 path-specific rules 混為一談。兩者相關但不可互換。目錄 CLAUDE.md 在目錄子樹內是無條件的；path-specific rules 是以 glob 模式為條件，與工作目錄無關。混淆這兩種心理模型，會產生要麼範圍不足（根目錄 CLAUDE.md 塞了太多東西）要麼範圍過寬（應該用 path-specific 的子樹特定條件卻放進了一個無條件的檔案）的設計。

除錯啟用中的 Rule — 驗證給定檔案實際套用了哪些 Rule

靜默失敗是使用 path-specific rules 最常見的挫折：rule 檔已 commit、模式看起來正確，但 Claude 卻忽略了該慣例。能夠驗證給定檔案究竟哪些 rule 正在生效，是每位 CCA-F 考生都應具備的操作技能。

三種檢查啟用中 Rule 的方式

1. 直接問 Claude。 在 session 中輸入「哪些 rule 檔目前為 apps/web/src/index.astro 載入？請列出每個 rule 檔的名稱和匹配的 paths: 模式」，Claude 就能看到什麼就列出什麼。
2. 使用 Claude Code 的診斷輸出。 依 Claude Code 版本，CLI 會提供一個指令（或等效的 slash command），列出當前設定，包含哪些 rule 檔匹配了當前工作中的檔案。
3. 乾跑一次具代表性的編輯。 請 Claude 說明它會如何編輯目標檔案；若輸出反映了該 rule 的慣例，則 rule 已生效；若沒有，請檢查 paths: 模式是否有打字錯誤。

常見的失敗模式

• Glob 打字錯誤。 漏了 **、副檔名錯誤、目錄名稱拼錯。透過逐步縮小模式來修正。
• 基礎目錄錯誤。 模式是相對於專案根目錄計算的，而非當前工作目錄。根目錄 .claude/rules/ 檔案中的 src/** 匹配的是 ./src/**，而非 ./apps/web/src/**。
• 檔案在 .gitignore 中。 被 git 忽略的自動產生檔案仍然存在於磁碟上，當 Claude Code 編輯它們時仍然符合 path-specific rules——這是正確行為，但有時令人意外。
• 使用者層級與專案層級的位置混淆。 放在 ~/.claude/rules/ 的 rule 只套用於一台機器，且不會 commit 到 repository。放在 repo 內 .claude/rules/ 的 rule 套用於每位協作者。混淆兩者會產生「在我的機器上可以執行」的 bug。

把 Rule 除錯視為一等工作流程

Rule 就是程式碼。以管理其他程式碼的同等紀律管理 .claude/rules/ 目錄：以原子性的 commit 提交變更、在 PR 中 review glob 模式，並在 PR 描述中附上具代表性的匹配檔案樣本，讓 reviewers 能夠合理確認啟動範圍。

白話說明

抽象的設定介面，一旦錨定在大多數考生已熟悉的具體情境上，就會變得直觀。以下三個類比涵蓋了 path-specific rules 的完整面貌。

類比一：辦桌場合的各攤位工作指南

想像一場大型辦桌宴席，設有多個攤位——炭烤攤、甜點桌、冷盤台、窯燒烤爐。主廚維護一本全場通用的標準手冊（「擺盤由左至右」、「份量精準到克」、「服務前先報過敏原」）。那本手冊就是根目錄 CLAUDE.md。但每個攤位的工作台上方也各自釘著一張護貝工作指南，只適用於那個攤位——甜點桌的指南寫著「調溫巧克力至 31°C」，窯燒台的指南寫著「450°C 烤九十秒」。這些指南就是 path-specific rules。炭烤師傅看不到甜點桌的指南——它不在烤肉架旁邊——但甜點師傅隨時都能看到。這些指南不取代主廚手冊；它們以各攤位專屬的慣例補充它。Claude Code 正在編輯的那個路徑，就是 agent 正在工作的那個攤位；rule 檔就是釘在每個攤位上方的護貝指南。主廚手冊和相關攤位指南同時擺在師傅面前。沒有任何師傅需要一次翻閱所有攤位的指南。

類比二：圖書館各區的區域標示

公共圖書館在入口張貼了通用規則——「禁止飲食、保持安靜、圖書借閱期限二十一天」。那些通用規則就是根目錄 CLAUDE.md。圖書館內部，各區貼有附加標示：兒童區有「說故事地毯請脫鞋」、善本室有「禁用鋼筆，請用鉛筆，禁止攝影」、電腦室有「每次使用三十分鐘，禁止使用個人 USB 隨身碟」。那些區域標示就是 path-specific rules。在兒童區的讀者看到通用規則加上兒童區標示；在善本室查閱的研究者看到通用規則加上善本室標示。通用規則不會改變——它們無處不在——但每個房間添加了自己的條件式層次。若想用類似 regex 的匹配方案，就等於試圖在一張大標示上，以一長串條件句把每個區域的例外全部寫進去。沒有人會讀，也沒有人會遵守。分開的區域標示更可靠，這正是 Claude Code 把 path-specific rules 放在 .claude/rules/ 各自獨立的檔案中的原因。

類比三：電工的接線規範疊加層

持牌電工隨身攜帶國家電工規範（永遠啟用的規則手冊——根目錄 CLAUDE.md）。但建築法規也是在地性的：特定城市可能有只在其管轄範圍內適用的修訂；特定建築類型（醫院、資料中心、住宅）可能有只套用於該建築類型的附加規範；特定房間（潮濕區域、防爆環境、戶外安裝）可能還有只在那個房間適用的進一步規範。電工在接線醫院手術室時，同時遵循國家規範、醫院規範和潮濕區域規範。三者沒有任何一個取代另一個——它們疊加。住宅廚房的接線工程遵循國家規範和住宅規範，但不遵循醫院規範。這個疊加完全以位置為基準。Claude Code 的 path-specific rules 正是這種疊加：檔案的位置（由 paths: glob 匹配）決定哪些條件式規範手冊生效，疊加在無條件的專案層級 CLAUDE.md 之上。

考試當天選用哪個類比

• 關於 path-specific rules 為何存在的題目 → 辦桌攤位類比（每個工作場所的指令相關性）。
• 關於 rule 如何與 CLAUDE.md 疊加的題目 → 圖書館標示類比（永遠啟用的規則加上區域特定規則）。
• 關於 monorepo / 條件式適用性的題目 → 電工規範疊加層類比（以管轄範圍為基礎的疊加）。

常見考試陷阱

CCA-F Domain 3 持續利用五種與 path-specific rules 相關的反覆出現陷阱模式。全部五種都有社群通過報告記錄在案，並以合理的干擾選項形式出現。

陷阱一：paths 使用 Regex 而非 Glob

paths: 模式是 glob，不是正規表達式。干擾答案使用 regex 運算子（.*、\d+、[^abc] 形式的字元類別作為否定）描述模式並聲稱是正確的。它們是錯的。Glob 使用 *、**、?、[abc]、{a,b,c} 和 !。若某個答案把 paths: 當成 regex 處理，直接排除。

陷阱二：Rule 取代了 CLAUDE.md 階層

Path-specific rules 補充 CLAUDE.md 階層；它們不取代它。干擾答案把 .claude/rules/ 定位為「更新的 CLAUDE.md 替代方案」，或建議為了 path-specific rules 而刪除 CLAUDE.md。兩種說法都是錯的。正確的架構是精簡的根目錄 CLAUDE.md 加上針對條件子樹的 path-specific rules。

陷阱三：Rule 需要被匯入或啟用

Path-specific rules 從 .claude/rules/ 自動被探索。不需要 import 陳述式、不需要 CLI flag、不需要 slash command 呼叫來啟動它們。在工作流程中加入「載入 rule」步驟的干擾答案（一個 /load-rules slash command、一個 @import path/to/rule.yaml 參照、一個 enabled: true 欄位）是過度設計且錯誤的。

陷阱四：使用者層級 Rule 套用於整個團隊

~/.claude/rules/ 中的 rule 只套用於本地開發者的機器；它們不會 commit 到 repo，也不會傳播給隊友或 CI。必須套用於每位協作者的 rule 屬於專案根目錄下的 .claude/rules/。把團隊慣例放在 ~/.claude/rules/ 或把機器特定的個人偏好放在專案 rule 目錄的干擾答案，各自在相反的方向上錯誤。

陷阱五：模式具體程度是唯一的平局決定

當兩個 rule 同時匹配一個檔案時，paths: 模式的具體程度是第一個平局決定，但不是唯一的一個。priority: frontmatter 欄位在具體程度相同的 rule 之間決定勝負，而載入順序是最終的平局決定。聲稱「路徑較長的 rule 檔永遠勝出」的干擾答案，忽略了 priority: 欄位和明確覆蓋機制。

練習錨點

Path-specific rule 的概念在六個 CCA-F 情境中，最集中地出現在其中一個。將以下內容視為情境叢集題的架構骨幹。

Code-Generation-With-Claude-Code 情境

這是最直接練習任務 3.3 的情境。其中，Claude Code 用於在非平凡的程式碼庫中產生和重構程式碼——通常是具有多個套件的 monorepo，混合了前端與後端、獨立的測試目錄，以及絕對不能手動編輯的自動產生或自動管理的檔案。該情境大量依賴 path-specific rules：預期會有題目，其正確架構是根目錄一份精簡的全團隊不變規則 CLAUDE.md、.claude/rules/ 下每個套件一份框架特定慣例的 rule 檔、一份測試慣例的 **/*.test.ts rule，以及一份告知 Claude 該檔案是自動管理的 **/generated/** 或 **/*.generated.ts rule。干擾答案習慣性地把所有慣例塞進一份根目錄 CLAUDE.md、忽略自動產生檔案的 rule（導致 Claude 手動編輯下次產生時會被覆蓋的程式碼），或把團隊 rule 放在使用者層級目錄。

同時也預期會有測試多個 rule 檔同時匹配同一檔案時優先順序的題目、測試否定模式的題目（套用於「src/ 下的所有檔案，但排除自動產生的檔案」的 rule），以及驗證 rule 啟動的題目——操作者如何確認正確的 rule 已針對特定目標檔案載入。在 agent 跨異質程式碼庫工作時，developer-productivity-with-claude 情境也會觸及 path-specific rules，但其主要重心在任務 3.1（CLAUDE.md 階層）而非任務 3.3。

FAQ — Path-Specific Rules 前五大問題

Claude Code 中的 path-specific rule 究竟是什麼？

Path-specific rule 是存放於 .claude/rules/ 的 YAML-frontmatter 檔案，其 paths: 陣列宣告了一組 glob 模式。只有當當前目標檔案符合至少一個宣告的模式時，rule 的內文才會被載入 Claude 的上下文。Path-specific rules 是疊加在無條件 CLAUDE.md 階層之上的條件式層。Rule 檔在 session 開始時自動被探索——不需要任何 import、啟用 flag 或 slash command——且它們與根目錄和目錄 CLAUDE.md 檔共存，而非取代它們。典型使用情境包括異質程式碼庫中的框架隔離、測試檔慣例、自動產生檔案保護，以及 monorepo 中的套件範圍 rule。

Rule 檔中的 paths 是 regex 還是 glob 模式？

是 glob，不是 regex。你會遇到的運算子有 *（一個路徑段，任意字元）、**（零或多個路徑段）、?（單一字元）、[abc]（字元類別）、{a,b,c}（大括號替代）和 !（否定）。試圖在 paths: 中使用 regex 運算子（如 .*、\d+，或帶錨點的量詞）會靜默地無法匹配。這個區別是 CCA-F 任務 3.3 中最常測試的機械性細節之一。建構 rule 時，從最粗糙的能運作的模式開始（** 或 src/**），在具代表性的檔案上驗證啟動，再按需縮小模式範圍。

Path-specific rules 會取代 CLAUDE.md 檔嗎？

不會。Path-specific rules 補充 CLAUDE.md 階層——它們不取代它。正確的架構是一份承載專案層級不變規則的精簡根目錄 CLAUDE.md，可選的目錄 CLAUDE.md 檔用於子樹無條件上下文，加上 .claude/rules/ 中的 path-specific rules 用於條件式子樹慣例。三層全部疊加：對一個檔案的編輯可以同時啟動根目錄 CLAUDE.md、目錄 CLAUDE.md 和多個 path-specific rule 檔，它們全部共同構成 Claude 看到的指令上下文。把 path-specific rules 定位為 CLAUDE.md 更新替代方案的 CCA-F 干擾答案是錯的；兩套系統是互補的。

當兩個 rule 檔同時匹配同一目標檔案時會發生什麼？

兩個 rule 檔都會啟動，兩份 rule 內文都會被載入上下文。若它們的指令僅僅是可加性的（一個涵蓋測試慣例，另一個涵蓋後端錯誤處理），它們能夠乾淨地組合。若它們的指令真正衝突，優先順序依此解決：（1）paths: 模式更具體的 rule 勝出；（2）具體程度相同時，priority: 欄位較高者勝出；（3）作為最終平局決定，較晚載入的 rule 勝出。架構師應以最小化真正衝突為目標來設計 rule 檔，而非依賴優先順序來收拾殘局——在更具體的 rule 中明確的「本地例外」說明，優於隱性的覆蓋。

我如何驗證給定檔案的哪些 rule 正在生效？靜默啟動失敗的原因是什麼？

三種方法有效：（1）在 session 中直接問 Claude（「哪些 rule 檔目前為 apps/web/src/index.astro 載入？」）；（2）透過 CLI 使用 Claude Code 的診斷輸出；（3）乾跑一次具代表性的編輯，檢查 Claude 的提議修改是否反映了 rule 的慣例。最常見的靜默失敗原因有：glob 打字錯誤（漏了 **、副檔名錯誤）、模式相對於錯誤的基礎目錄計算（路徑是相對於包含 .claude/ 的專案根目錄解析，而非當前工作目錄），以及把全團隊的 rule 放在使用者層級的 ~/.claude/rules/ 目錄而非專案的 .claude/rules/ 目錄。把 rule 目錄視為程式碼：版本控制它、在 PR 中 review glob 模式，並在 PR 描述中附上具代表性的匹配檔案，讓 reviewers 能夠合理確認啟動範圍。

延伸閱讀

• CLAUDE.md configuration — Claude Code Docs: https://docs.anthropic.com/en/docs/claude-code/claude-md
• Claude Code settings reference: https://docs.anthropic.com/en/docs/claude-code/settings
• Claude Code features overview: https://docs.anthropic.com/en/docs/claude-code/overview
• Custom slash commands and skills: https://docs.anthropic.com/en/docs/claude-code/slash-commands

Related ExamHub topics: Claude Code CLAUDE.md Hierarchy, Custom Slash Commands and Skills, Context Management — Large Codebase Exploration, Built-in Tools Selection and Application.