14. Rules 規則目錄

Rules 是 Claude Code 把規則模組化 + 條件式啟用的機制——不是「整本員工手冊每次都讀」，而是「做 X 工作打開 X 抽屜」。我們今天剛把 PAM 的 CLAUDE.md 拆成 5 個 rules，作為實例。

14.1 為什麼要 Rules？CLAUDE.md 不夠嗎？

過去您用 CLAUDE.md：

你叫 Claude 改 CSS → 整個 2400 行 CLAUDE.md 進上下文
                     （包含 SQL / migration / 測試規範）
                     ↓
                Claude 注意力分散
                Context tokens 浪費
                越長越容易被自動壓縮丟掉

Rules 解法：

你叫 Claude 改 CSS → CLAUDE.md（精簡版）+ 03-frontend.md
                     （只載入 50 行對應規則）
                     ↓
                焦點集中
                Token 省 60-70%
                該載入的才載入

14.2 結構與位置

{project}/.claude/rules/
├── 01-grading-service.md       ← Service 紅線
├── 02-controller.md             ← Controller 規範
├── 03-frontend.md               ← React UI
├── 04-tests.md                  ← 測試
└── 05-migration.md              ← DB 遷移

位置選項：

範圍	路徑
專案級（推薦）	`{repo}/.claude/rules/`
全域個人偏好	`~/.claude/rules/`

14.3 Rule 檔案格式

每個 rule 檔頭有 frontmatter：

---
description: "When to apply this rule"
glob: "tests/**/*.ts"
trigger: "auto" | "manual"
---
 
# 規則內容（Markdown）
 
- 紅線 1
- 紅線 2
- ❌ 禁止做 X
- ✅ 改用 Y

欄位	用途
`description`	描述何時適用（語意觸發 + 給 Claude 識別）
`glob`	檔案路徑匹配（最常用觸發）
`trigger`	`auto`（自動）/ `manual`（要 @rule:name）

14.4 三種觸發機制

機制 1：Glob 觸發（最常用）

glob: "Services/GradingService.cs|Controllers/HrController*"

→ Claude 偵測你動到匹配檔案 → 自動載入該 rule。

機制 2：Description 語意觸發

description: "When writing or reviewing security-sensitive code"
trigger: "auto"

→ Claude 看任務描述是否語意相符 → 自動啟用。

機制 3：Manual 手動

trigger: "manual"

對話中 @rule:my-rule 才啟用。

→ 適合特殊情況才用的規則（避免誤觸發）。

14.5 真實範例：PAM 5 個 Rules

`01-grading-service.md`

---
description: "等第與分數計算的紅線規則"
glob: "Services/GradingService.cs|Controllers/HrController*.cs|Controllers/ReviewController*.cs"
---
 
# Grading Service 紅線
 
- 所有等第判定（CalcGrade / GradeRank）只能在 GradingService 裡實作
- HrController / ReviewController 內任何分數計算 → 必須呼叫 GradingService 對應方法
- ❌ 禁止：在 Controller 內寫 `if (score >= 90) return "特優"` 之類邏輯
- 分數精度 decimal(6,3)；前端用 fmtScore 顯示 3 位小數
- 事假每小時 -0.125；病假不扣分（僅影響天花板）

`02-controller.md`

---
description: "Web API Controller 通用規則"
glob: "Controllers/**/*.cs"
---
 
# Controller 紅線
 
- 每支 API 必須加 [Authorize]
- ❌ 禁止：try-catch 吞例外
- ❌ 禁止：拼接 SQL
- ✅ 一律：EF Core LINQ + parameterized query

`03-frontend.md`、`04-tests.md`、`05-migration.md`

完整 5 個 rules：查看 PAM .claude/rules/

14.6 CLAUDE.md 的 4 層與 Rules 的搭配

1. ~/.claude/CLAUDE.md           ← 全域個人（永遠載入）
2. {project}/CLAUDE.md           ← 專案手冊（永遠載入）
3. {project}/.claude/rules/*.md  ← 條件式啟用 ← 14 章重點
4. # 對話 inline                 ← 臨時最高優先

→ Rules 是第 3 層，補強第 2 層（CLAUDE.md）。

14.7 該寫進 CLAUDE.md 還是 Rules？

規則屬性	該放哪
跨整個專案的核心規範（系統概覽、業務流程）	CLAUDE.md
跟特定目錄 / 檔案類型相關的紅線	rule + glob
跨專案的個人偏好（語言、不要過度道歉）	`~/.claude/CLAUDE.md`
一次性 / 對話特例	inline 對話
規則太多塞 CLAUDE.md 會超過 1000 行	拆 rule

14.8 拆 Rules 的時機（信號）

當你發現以下情況時，是該拆 rules 的訊號：

🚩 CLAUDE.md > 1000 行
🚩 Claude 改前端時提到 SQL 規則（誤觸發）
🚩 同樣的紅線在 CLAUDE.md 重複多次（不同章節都提）
🚩 你想分享部分規則給其他人但不要全包

14.9 拆 Rules 的步驟（實作）

Step 1：歸納你的規則類型

PAM 範例：5 個明顯領域 → Service / Controller / 前端 / 測試 / migration。

Step 2：建 `.claude/rules/` 目錄

mkdir -p {project}/.claude/rules

Step 3：每個領域寫一個 rule 檔

cat > .claude/rules/01-grading-service.md <<'EOF'
---
description: "等第與分數計算紅線"
glob: "Services/GradingService.cs"
---
 
# Grading Service 紅線
...
EOF

Step 4：CLAUDE.md 加導航

CLAUDE.md 頂部加「規則總覽」表，列出所有 rules + glob + 紅線一句話。

Step 5：精簡 CLAUDE.md（可選）

把已搬到 rule 的詳細紅線 → 改為「→ 詳見 .claude/rules/XX.md」。

14.10 跟 Hooks / Skills 的差異

	Rules	Hooks	Skills
本質	條件式紅線	事件式自動觸發	任務式 SOP
何時跑	Claude 加上下文時	工具呼叫前/後	Claude 想做某任務時
典型內容	「禁止 X」「一律 Y」	「跑測試」「prettier 格式化」	「執行流程：1.A 2.B 3.C」
角度	寫 code 的紅線	寫 code 後的動作	完整任務流程

→ 三者互補，不衝突。

14.11 跨領域工作的 Rules 觸發

當你做的工作跨多個領域（如「改 GradingService 公式 + 對應前端 UI + 加單元測試」）：

動 Services/GradingService.cs → 觸發 01-grading-service.md
動 client-app/.../Page.tsx     → 觸發 03-frontend.md
動 ExamSystem.Tests/...        → 觸發 04-tests.md

→ Claude 同時看 3 個 rule + CLAUDE.md，精準對齊每個領域的紅線。

14.12 在 Plugin 中打包 Rules

Plugin 可以包含 rules：

my-plugin.plugin/
├── .claude-plugin/plugin.json
├── skills/...
└── rules/                       ← 安裝 plugin 時 rule 也一起安裝
    ├── 01-style.md
    └── 02-security.md

→ 團隊用 plugin 接手 → 自動繼承所有紅線。

14.13 何時不該拆 Rules

❌ 規則 < 200 行 → 留 CLAUDE.md 就好
❌ 規則跨所有任務都用 → 留全域 ~/.claude/CLAUDE.md
❌ 規則一週改一次 → 拆出去後遺忘風險高
❌ 純文字偏好（如「繁中回覆」）→ Memory / CLAUDE.md 更合適

14.14 PAM 拆 Rules 之後的成果

維度	拆前	拆後
檔案結構	CLAUDE.md（670 行）	CLAUDE.md（650 行）+ 5 個 rule（64 行）
單領域任務 context	670 行全載	650 + 13 行（focused）
跨領域任務 context	670 行全載	650 + 多個相關 rule
改前端時誤觸發 SQL 規則	偶爾	不會（glob 不符不載）
未來 plugin 化	規則散在 CLAUDE.md	rules/ 直接打包
更新成本	改一條動 670 行檔	改一條動 13 行 rule

→ 架構更清晰，精準度更高，plugin-ready。

14.15 進階：用 Rules 做漸進式遷移

如果 CLAUDE.md 已經很大，不用一次全拆。建議：

階段 1（一週）

拆 1 個 rule 試水溫——選最常觸發 + 最不模糊的領域。

階段 2（兩週）

第 1 個 rule 順 → 拆第 2、3 個。

階段 3（一個月）

拆完主要 5-8 個 rule → 精簡 CLAUDE.md 對應段落。

14.16 常見錯誤

❌ 錯誤	影響	✅ 正確
glob 寫太鬆（如 `*/.cs`）	啟用過多 rule	縮小範圍（`Services/GradingService.cs`）
description 寫太抽象	語意觸發不準	列出具體場景（「修等第計算 / 改配額 / 動公式」）
Rule 跟 CLAUDE.md 重複 100%	沒省到 token	拆出後 CLAUDE.md 改成 ref 一行
Rule 內容太長（500+ 行）	失去精簡優勢	拆成多個 rule 或進 Docs/
Rule 不更新	規則過時	CHANGELOG.md 同步更新時間

14.17 Vincent 應用建議

短期（已做）

✅ PAM 拆 5 個 rules（Service / Controller / 前端 / 測試 / migration）
✅ CLAUDE.md 精簡 + 加規則總覽表

中期

🟡 觀察 1-2 週，看是否需要再拆細（如 controller 拆 hr-controller / review-controller）
🟡 加 description-only rule（如「security review」「performance audit」）

長期

⏸ 把 rules 打包進未來的 pam-dev.plugin
⏸ 全公司共享 rules（年代集團 IT 內部規範）

進階主題

詳細概念：Rules Directory
4 層機制：CLAUDE.md 4 層機制
跟 Plugin 整合：13-Plugin 建置與使用
跟 Hooks 互補：Hooks
PAM 5 個 rules 實例：查看

← 上一章：13-Plugin 建置與使用 | 回到 README

Vincent5588 Wiki

探索

Rules 規則目錄