04-2 rules：模組化規則檔，路徑範圍與分工

這個單元解決什麼問題.claude/rules/ 把 CLAUDE.md 的常駐約束切成可依路徑範圍觸達的模組。當 CLAUDE.md 膨脹、跨 domain 規則互相干擾、或某些規則只對特定副檔名有意義時，rules 是正解。本單元講 rules 與 CLAUDE.md 的分工邊界、path-scoped 觸達機制、命名與分層組織，並對照其他工具的同類機制。

學習目標

說出 rules 與 CLAUDE.md 的差別，以及何時該拆到 rules。
用 paths frontmatter 讓規則只在符合 glob 的檔案觸及時生效。
依 domain 或語言把約束拆進獨立規則檔，避免單一巨檔。
判斷一條約束該放 CLAUDE.md、獨立 rule 檔、Skill 還是 Hook，並說出判準。
對照 OpenAI Codex、Google Antigravity、GitHub Copilot、Cursor 對等機制的差異。

1. rules 是什麼

Rules 是放在 .claude/rules/ 目錄下的 Markdown 檔，與 CLAUDE.md 同一層級載入（截至 2026-06 依官方記憶章節 [1]）。基本特性：

每個 .md 為一個模組，命名依主題（testing.md、api-design.md、python-style.md）。
不寫 paths frontmatter 時，與 CLAUDE.md 等價：每次 session 啟動全量載入。
寫了 paths frontmatter 時，只在 Claude 觸及符合 glob 的檔案時才載入。
與 CLAUDE.md 同屬「context 層次」，不是「強制執行」。需要保證執行的約束，請交給 Hook（見 04-6 Hooks）。

.claude/rules/ 內的所有 .md 檔都會被遞迴讀取，可以再分子目錄（frontend/、backend/、ml/）做階層化組織 [1]。

rules 是「主動常駐」，不是「按需呼叫」寫了 paths 之後雖然只在相關檔案時載入，但仍會進入 Claude 觸達該檔案那一刻的 context。這跟 Skill 的「使用者或模型叫用時才注入完整內容」不同（見 04-4 Skills）。Rules 是「在某個子集的工作階段裡常駐」，不是「像工具一樣被叫一次」。

2. 與 `CLAUDE.md` 的分工

CLAUDE.md（使用者級、專案級、本地層）放跨任務、跨語言、跨目錄都適用的通識約束。rules 放情境化約束：只在某個路徑或副檔名才有意義的規則。判準只有一個：把這條規則唸給一個不相關任務的 agent 聽，會不會造成干擾或矛盾？ 會 → 拆到 rules。不會 → 留在 CLAUDE.md。

怎麼拆留在 CLAUDE.md：

「回應一律繁體中文，第二人稱」
「不要 commit .env」
「建構指令：make build、測試：make test」
「commit 前跑 make lint」

拆到 .claude/rules/python-style.md（path-scoped 到 **/*.py）：

「Python 用 type hints，公開函式不接受 Any」
「pytest fixture 集中放在 conftest.py，不在單一測試檔內定義跨檔 fixture」
「公開 API 函式必須有 docstring（Google 風格）」

拆到 .claude/rules/api-design.md（path-scoped 到 src/api/**）：

「每個 endpoint 必須在 OpenAPI spec 同步登記」
「輸入驗證在 handler 邊界就做完，不要丟到內部函式」
「錯誤回應統一使用 {code, message, details} 結構」

這三塊互相不干擾：寫 React 時 Python 風格不會被載入、寫 Python 時 API 設計規範不會被載入。每次 session 載入的 token 預算比把全塞進 CLAUDE.md 少一個量級。

3. path-scoped 規則：觸達機制

.claude/rules/ 內的 .md 檔可以用 YAML frontmatter 的 paths 欄位限定觸達範圍。Claude Code 在工作階段中讀到符合 glob 的檔案時，才把該 rule 注入 context [1]。基本寫法：

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

glob 語法（與 .gitignore 風格類似）：

模式	匹配
`*/.ts`	任何目錄下的所有 `.ts` 檔
`src/*/`	`src/` 下所有檔案
`*.md`	專案根目錄下的 `.md` 檔
`src/components/*.tsx`	`src/components/` 下的 `.tsx`（不含子目錄）
`src/*/.{ts,tsx}`	`src/` 下所有 `.ts` 與 `.tsx`（含子目錄）
`tests/*/.test.ts`	測試檔

可同時列多個模式，或用 brace expansion 一次匹配多副檔名 [1]。

path-scoped 規則只在讀檔時載入path-scoped rule 不是「每次 tool call 觸及都載入」，而是「Claude 讀到符合 glob 的檔案時載入」。意思是：如果你叫 Claude 改檔案前它還沒讀過符合 glob 的檔案，rule 就不在 context 裡。對話脈絡累積到這個點之前，行為可能不一致。

4. 命名與分層組織

命名原則：用具體語意名稱，不用具體行為描述（不要叫 do-not-touch.md，要叫 api-migration-safety.md）。常見分層：

.claude

CLAUDE.md

rules

common

code-style.md · 通用語言風格

testing.md · 測試原則

security.md · 安全禁則（path-scoped 到 src/）

frontend

react-style.md · React 慣例

a11y.md · 無障礙

backend

api-design.md · API 設計

db-migrations.md · 資料庫遷移

experiment-tracking.md

單一 rule 檔的長度：官方建議 SKILL.md 在 500 行以內（這是針對 skill 的建議，但同一精神也適用於 rules）。超過這個長度考慮再拆或升級為 Skill。

5. 跨專案共享：用 symlink

.claude/rules/ 支援 symlink，所以你可以在 ~/shared-claude-rules/ 維護一份共用規則集，跨多個專案 link 進來 [1]：

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

circular symlink 會被偵測並繞過，不會無窮遞迴 [1]。Windows 上建立 symlink 需要 Administrator 或 Developer Mode；如果不能 symlink，.claude/rules/ 內部用 @path 匯入 ~/shared-*.md 是另一條路。

6. 使用者級 rules

放在 ~/.claude/rules/ 的 rules 適用於所有專案，優先序在使用者級 CLAUDE.md 之後、專案級 rules 之前 [1]：

~/.claude/rules

preferences.md · 個人編碼偏好

workflows.md · 個人常用工作流

常見放法：個人工具捷徑、編輯器設定偏好、跨專案都適用的回應風格。專案 rules 則覆寫使用者 rules 的同名檔案。

7. 與 Skill、Hook 的界線

三者職責不重疊，判斷準則：

需求	放哪裡
「每次編輯 Python 都要遵守」	rules（path-scoped）
「讓模型在適當時機自動跑這套程序」	Skill
「每次 commit 前一定要跑測試」	Hook（確定性保證）
「我知道現在要跑這套程序」	Command（`/name` 主動觸發）
「這是專案通識，所有任務都該知道」	`CLAUDE.md`

決策樹的快速版：

需要模型判斷什麼時候插入 → Skill
需要使用者主動觸發 → Command
需要每次某個動作後都跑（不論模型判斷）→ Hook
常駐、每次 session 都載入且跨任務通用 → CLAUDE.md
常駐、只在特定路徑時載入 → rules（path-scoped）
要記的是事實而非指令 → 自動記憶

8. 工具對照

各家工具的規則檔機制在 path-scoped 支援與 frontmatter 細節上差異不小（截至 2026-06）：

命名澄清

OpenAI Codex 的 “rules” 是 Starlark 撰寫的可執行政策檔（用來控制 agent 行為的白名單/黑名單），不是 Markdown 規則檔。語意上接近 Hook 而非本單元討論的 CLAUDE.md 模組化。
Cursor 用 .mdc 副檔名（.md 不行），frontmatter 欄位為 description / globs / alwaysApply 三個 [3]。alwaysApply: true 等同「無條件載入」；globs 設定時只在匹配檔案時自動載入；只有 description 時由模型語意判斷載入時機；都不寫時只能 @-mention 手動引用。
GitHub Copilot 的 .instructions.md 用 applyTo 限定 glob，並可加 excludeAgent: "code-review" 或 "cloud-agent" 排除特定 agent 載入 [4]。

9. 動手做

拆一條

把 CLAUDE.md 裡的 Python 編碼風格段落整段搬到 .claude/rules/python-style.md，加 paths: ["**/*.py"]。

驗證觸達

在同一個 session 跑 /memory，確認 python-style.md 出現且附帶 path 標註。

測試無載入情境

叫 Claude 改一個 *.md 檔（不在 **/*.py glob 內），問它 Python 風格規則；它應該不引用 python-style.md。

跨專案共享

把使用者級 ~/.claude/rules/preferences.md 建出來；在兩個不同專案啟動 session 確認它都被載入。

10. 常見誤區

反模式清單

所有約束全塞 CLAUDE.md：跨 domain 規則互相干擾、每次 session 全量載入、token 預算飆高，且長規則容易被模型「分心忽略」。
照抄別人的 rules 設定：別人 repo 不需要、甚至不該有的約束，會被你的 model 強行套用。
把「保證執行」寫成 rule 的祈使句：rule 只是 context，模型可能在多步驟任務中遺漏。需要確定性保證的事必須走 Hook。
paths 寫太寬：用 **/* 當 paths，等於沒寫 path-scoped。每次 session 啟動就全量載入，浪費這個機制。
混淆 rules 與 Skill 的觸發時機：rule 是 Claude 讀到符合檔案時被注入；Skill 是 Claude 判斷語意相關時叫用（見 04-4 Skills）。把「每次編輯 Python 都要跑 ruff」寫成 rule 對；寫成 Skill 會等到使用者或模型主動叫用。

自我檢核

通過本單元的標準

你能說出 rules 與 CLAUDE.md 的差異，以及何時該拆嗎？
你能寫出正確的 paths frontmatter，並用 glob 模式限定觸達範圍嗎？
你能依需求判斷一條約束該放 CLAUDE.md、獨立 rule 檔、Skill 還是 Hook 嗎？
你能在五個工具的對照表上填出你的主力工具的規則檔機制嗎？

來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-05。

[1] Anthropic, “How Claude remembers your project,” code.claude.com, 2026. Available: https://code.claude.com/docs/en/memory （截至 2026-06；含 .claude/rules/、paths frontmatter、symlink、auto memory 完整章節）
[2] Anthropic, “Extend Claude with skills,” code.claude.com, 2026. Available: https://code.claude.com/docs/en/skills （截至 2026-06；含 Skill 與 CLAUDE.md / rules 的分工）
[3] Cursor, “Rules,” cursor.com, 2026. Available: https://cursor.com/docs/context/rules （截至 2026-06；.mdc 與 frontmatter description / globs / alwaysApply）
[4] GitHub Docs, “Adding custom instructions for GitHub Copilot,” docs.github.com, 2026. Available: https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot （截至 2026-06；.instructions.md 與 applyTo glob）
[5] Agentic AI Foundation (Linux Foundation), “AGENTS.md,” 2026. Available: https://agents.md/ （截至 2026-06；跨工具共通專案規則檔標準）

設定層級模型見 02-1 設定的層級模型。
CLAUDE.md 與自動記憶見 04-1 CLAUDE.md 與記憶檔。
Skill（按需叫用程序）見 04-4 Skills。
Hook（確定性保證）見 04-6 Hooks。
上下文工程與規則載入成本見 01-4 上下文工程。

總覽

Part I 基礎與進階認識

Part II 進階調適與設定

Part III 認知與思維

Part IV 客製化、整合與自動化

Part V Agentic 案例研究

附錄

04-2 rules：模組化規則檔，路徑範圍與分工

學習目標

1. rules 是什麼

2. 與 `CLAUDE.md` 的分工

3. path-scoped 規則：觸達機制

4. 命名與分層組織

5. 跨專案共享：用 symlink

6. 使用者級 rules

7. 與 Skill、Hook 的界線

8. 工具對照

9. 動手做

10. 常見誤區

自我檢核

來源與延伸閱讀

​學習目標

​1. rules 是什麼

​2. 與 CLAUDE.md 的分工

​3. path-scoped 規則：觸達機制

​4. 命名與分層組織

​5. 跨專案共享：用 symlink

​6. 使用者級 rules

​7. 與 Skill、Hook 的界線

​8. 工具對照

​9. 動手做

​10. 常見誤區

​自我檢核

​來源與延伸閱讀

學習目標

1. rules 是什麼

2. 與 `CLAUDE.md` 的分工

3. path-scoped 規則：觸達機制

4. 命名與分層組織

5. 跨專案共享：用 symlink

6. 使用者級 rules

7. 與 Skill、Hook 的界線

8. 工具對照

9. 動手做

10. 常見誤區

自我檢核

來源與延伸閱讀