CLAUDE.md 與 Rules Files 大師班：我維護 40+ 份設定檔學到的事

這是「Agentic Engineering 實戰手冊」系列的第八篇。上一篇：Prompt 到 Production

我曾經把 ~/.claude/ 養到 47 個設定檔

一年前，我的整個 agent 設定就是一個 CLAUDE.md，裡面寫了三行：build command、test command、和「請用 TypeScript」。

寫這篇初稿時，我盤點到 47 個相關檔案：Global CLAUDE.md、12 個專案的 project CLAUDE.md、23 個 skills，再加 hooks 與 memory。這是當時的個人快照，不是建議規模；有些後來也被合併或淘汰。

但你不需要從 47 個檔案開始。這篇分享的是這套系統怎麼一步步長出來的，以及你在每個階段需要什麼、不需要什麼。

從一個檔案到一套系統

問題浮現的時刻

問題 1：跨專案衝突

我同時在做一個 Astro 部落格和一個 Next.js 專案。Global CLAUDE.md 裡寫了「用 Astro 的 file-based routing」，結果在 Next.js 專案裡 agent 也嘗試用 Astro 的方式處理 routing。

→ 需要 per-project 設定。

問題 2：CLAUDE.md 太長

有一陣子我的 project CLAUDE.md 膨脹到了 400 行。裡面什麼都有——build 指令、coding conventions、deploy 流程、特定 component 的使用方式。結果 agent 的行為變得不穩定——有時候遵循 convention A，有時候遵循 convention B。

原因是 Context Engineering 裡提到的 “Lost in the Middle” 效應：CLAUDE.md 中間的指令比頭尾更容易被忽略。

→ 需要拆分，讓每份檔案都精簡。

問題 3：重複的工作流

我發現自己經常在不同專案裡跟 agent 說同樣的事：「先跑 linter」、「commit 前做 review」、「用 conventional commits 格式」。每次新開一個 session 都要重複。

→ 需要可重用的 skill 模組。

設定檔層級架構

經過一年的演化，我會把長期 context 分成四種 scope。它們不是一路巢狀覆蓋的 CSS cascade，而是用途不同的來源：

~/.claude/CLAUDE.md                    ← Personal：個人、跨專案
project/CLAUDE.md                      ← Project：團隊共用
project/.claude/rules/*.md             ← Rules：可按檔案路徑套用
~/.claude/skills/<name>/SKILL.md       ← Personal skill
project/.claude/skills/<name>/SKILL.md ← Project skill

Layer 1: Global CLAUDE.md（~100 行）

位置：~/.claude/CLAUDE.md

放什麼：

開發哲學：incremental progress、composition over inheritance、test-driven
通用 conventions：prefer TypeScript、conventional commits、no —no-verify
工具偏好：prefer npm over yarn、GitHub CLI for CI/CD
行為規範：不要自動 git push、不要自動加 emoji、stop after 3 failed attempts

不放什麼：

任何專案特定的技術棧或 build 指令
任何會跟其他專案衝突的規則

原則：如果這條規則適用於你所有的專案，放 global。否則，放 project。

Layer 2: Project CLAUDE.md（~50 行）

位置：project root 的 CLAUDE.md

放什麼：

Build/test/dev 指令：npm run dev、npm run build、npm run test
技術棧：Astro 6 + MDX + Tailwind CSS 4 + TypeScript
專案結構：key directories 和 file conventions
專案特有的慣例：命名規則、component patterns、design tokens

我的 bobo-blog-2026 的 CLAUDE.md 大概長這樣：

# CLAUDE.md

## Commands

npm run dev # Start dev server at localhost:4321
npm run build # Build production site to ./dist/
npm run check # Run Astro and worker type checks

## Architecture

Stack: Astro 6 + MDX + Tailwind CSS 4 + TypeScript

- src/pages/ — File-based routing
- src/content/blog/ — MDX blog posts
- src/components/ — Astro components (PascalCase)
- src/layouts/ — BaseLayout.astro, BlogLayout.astro

## Content Schema

Blog posts require: title, description, pubDate
Optional: tags, featured, image, draft

## Theme System

CSS Custom Properties: --color-_, --glass-_, --radius-\*
Dark mode: .dark class on <html>

## Conventions

- lang="zh-TW"
- Component files: PascalCase
- Use existing CSS custom properties over hardcoded values

50 行以內。每一行都跟這個專案直接相關。

關鍵原則：Project CLAUDE.md 應該被 commit 進 git。它是專案文件的一部分，就像 README.md 或 tsconfig.json 一樣。團隊成員 pull 下來就能用。

Layer 3: Rules Files（按場景分）

位置：.claude/rules/*.md

Rules files 適合把大型專案的指令模組化。Claude Code 也支援在 frontmatter 用 paths 限定檔案 glob，讓規則只在處理相符路徑時載入。官方 memory 文件有現行格式。

例子：

testing-rules.md：「test 要用 vitest、prefer integration test over unit test、mock 只在必要時使用」
deploy-rules.md：「deploy 到 Cloudflare Workers、使用 wrangler.jsonc、先 deploy staging 再 production」
content-rules.md：「部落格文章用繁中、frontmatter 必須有 title/description/pubDate」

什麼時候用 rules file 而不是 CLAUDE.md？當內容需要依目錄拆分，或只跟某些檔案路徑有關。若只是「部署時才用」的多步驟流程，skill 通常比假設 rules 會按任務語意自動載入更合適。

Layer 4: Skills（可觸發的工作流）

位置：~/.claude/skills/skill-name/SKILL.md

Skills 是 CLAUDE.md 的「按需版」：完整內容只有在使用時載入。你可以用 /skill-name 明確觸發；若未設定 disable-model-invocation: true，Claude 也可能依 description 自動選用。官方 Skills 文件說明了 personal、project、plugin 與 managed scope。

為什麼需要 skills？因為有些工作流太複雜、太長、而且不是每次都需要。比如 pre-commit review 的 4-agent 並行 review 流程，有 200 行的指令——這些如果放在 CLAUDE.md 裡，每個 session 都會佔用 context window，但 90% 的時間根本用不到。

寫初稿時我有 23 個 skills，大致分四類：

類別	數量	例子
開發工作流	8	`commit`、`pre-commit-review`、`iterative-tdd-loop`、`self-healing-deploy`
內容創作	7	`content-research-writer`、`lesson-to-blog`、`translation-zh-tw`
寫作風格	5	`will-pao-style`、`fireship-style`、`lenny-newsletter-style`
工具自動化	3	`gcp-log-check`、`notion-workflow-bobo`、`wordhunter-image-processor`

不要自己發明一條「覆蓋順序」

我早期把它想成 Skills > Rules > Project > Global，後來發現這個說法太簡化。CLAUDE.md 與 rules 都是交給模型的指令，含糊或互相衝突時，不保證像 CSS 一樣機械式覆蓋；同名 skill 的 scope 倒是有官方明定的優先序。

實務做法是：同一件事只留一個權威來源，其他地方改成連結；再用 /memory、/skills 等診斷入口確認當前 session 實際載入什麼。不要拿 production 變更去測模型會選哪條矛盾規則。

Skills 系統深入

一個好的 skill 有三個部分：

1. Trigger Condition

什麼時候觸發？寫在 description field 裡：

description: >
  Smart git commit skill. Triggers on "commit", "/commit",
  "幫我 commit", "提交", or any request to create a git commit.

這讓 Claude Code 知道什麼時候該自動載入這個 skill。

2. Step-by-Step Instructions

具體怎麼執行：

## Step 1: Gather Context (parallel)

Run: git status, git diff --cached, git log --oneline -10

## Step 2: Stage Check

Confirm staging is correct...

## Step 3: Draft Commit Message

Analyze diff, follow conventional commits...

## Step 4: Execute

Use HEREDOC format...

3. Safety Rules

什麼不能做：

## Safety Rules

- NEVER use --no-verify
- NEVER use --amend on pushed commits
- NEVER auto-push
- NEVER commit .env files

Skills vs CLAUDE.md 的選擇

情境	放哪裡
每次 session 都需要	CLAUDE.md
特定類型任務才需要	Rules file
需要明確觸發的工作流	Skill
很少用、但用到時很關鍵	Skill
團隊共用的慣例	CLAUDE.md（commit 進 git）
個人的工作偏好	Global CLAUDE.md 或 Skill

知識放哪裡的決策框架

這是我在一年中最常遇到的問題：「這個資訊應該放在哪裡？」

以下是我的決策樹：

這個知識...
├── 每次 session 都需要？
│   ├── 是 → 所有專案都需要？
│   │   ├── 是 → Global CLAUDE.md
│   │   └── 否 → Project CLAUDE.md
│   └── 否
│       ├── 特定任務類型需要？
│       │   ├── 是 → Rules file 或 Skill
│       │   └── 否
│       │       ├── 跨 session 需要記住？
│       │       │   ├── 是 → Memory system
│       │       │   └── 否 → 不需要持久化
│       │       └── 專案文件已有？
│       │           ├── 是 → 不要重複（讓 agent 自己讀）
│       │           └── 否 → 考慮加到 README 或 docs/
│       └── 給人看的？
│           └── 是 → README / docs/

核心原則：不要重複規則，但要留下操作入口。package.json 已經定義 script 的實作，CLAUDE.md 仍值得列出 npm run check、npm run build 這些 canonical commands，避免 agent 猜錯；不需要再複製 script 內部做了什麼。tsconfig.json 也是權威來源，不必把每個 compiler option 重寫一次。

CLAUDE.md 放的應該是那些檔案裡看不出來的隱性知識——比如「我們偏好 composition over inheritance」或「deploy 前一定要先跑 staging」。

維護的藝術：設定檔也需要重構

定期 Review

設定檔跟 code 一樣，會腐化。三個月前加的一條 rule，可能因為 codebase 已經改了而不再需要。

我的習慣：每月花 30 分鐘做一次「設定檔 review」。具體做什麼：

讀一遍 CLAUDE.md，刪掉過時的內容
看最近一個月 agent 犯過什麼重複的錯——需要加 rule 嗎？
看 skills 的使用頻率——完全沒用過的 skill 考慮歸檔
確認多個設定檔之間沒有矛盾

Version Control

如果 CLAUDE.md 是團隊工作流的一部分，通常應該 commit 進 git：

團隊成員 clone 下來就能用
可以 track 變更歷史
可以 code review
跟 codebase 保持同步

~/.claude/CLAUDE.md 是個人偏好，不該混進專案；project CLAUDE.md 是否提交則看團隊是否共同使用 Claude Code。若團隊同時使用多種 agent，也可以把共同規則放在 AGENTS.md 或一般 docs，避免綁死單一工具。

團隊共用的考量

當團隊共用同一份 CLAUDE.md 時，注意：

避免空泛規則：「程式碼要寫得漂亮」無法驗收；「優先維持單一職責，超長函數在 review 說明理由」至少能討論。單純卡 50 行雖然客觀，也可能逼出更差的拆分。
避免個人偏好：你喜歡 semicolons，同事不喜歡——這種交給 ESLint 處理
建立修改流程：修改 CLAUDE.md 也需要 PR review，就像修改 ESLint config 一樣

Anti-patterns：太長、太嚴格、太模糊

Anti-pattern 1：長到找不到重點

症狀：CLAUDE.md 把架構文件、部署手冊、風格規則和歷史故事全塞在一起，重要命令很難找到。

問題：Agent 的注意力被稀釋。中間的指令可能被忽略（Lost in the Middle）。每次 session 啟動時，大量 token 被設定檔佔用。

修正：

拆到 rules files 和 skills
刪掉可以從 codebase 推斷出來的資訊
刪掉過時的資訊
目標：先保留每次任務都需要的資訊；沒有通用的 100 行門檻

Anti-pattern 2：太嚴格

症狀：規則寫得太死——「每個函數不能超過 10 行」、「每個模組不能超過 5 個 export」、「所有變數必須用全名不能縮寫」。

問題：Agent 會為了遵守規則而寫出更爛的 code。為了讓函數不超過 10 行，它把一個清晰的函數拆成 5 個意義不明的小函數。為了不縮寫，它寫出 currentlyAuthenticatedUserEmailAddress 這種變數名。

修正：用 guideline 取代 hard rule。「函數盡量保持短小」比「函數不能超過 10 行」好。給 agent 判斷空間，讓它在合理範圍內做決策。

Anti-pattern 3：太模糊

症狀：「寫好的 code」、「遵循最佳實踐」、「保持 code 品質」。

問題：等於沒說。Agent 會用它 training data 裡的「最佳實踐」，那可能跟你的專案完全不合。

修正：具體。「優先使用 Tailwind utilities；只有既有 token 無法表達時才新增 component CSS」比「遵循專案的 CSS 慣例」更能驗收，也不會把必要的 custom CSS 一刀切掉。

Anti-pattern 4：矛盾

症狀：Global CLAUDE.md 說「用 tabs」，Project CLAUDE.md 說「用 spaces」。或者 rules 裡說「prefer functional components」，但 CLAUDE.md 說「follow existing patterns」（而 existing patterns 有 class components）。

問題：Agent 隨機選一個，或者更糟，在同一個 PR 裡兩種都用。

修正：

刪掉衝突，不要只補一條自訂 override 宣告
定期交叉檢查不同 scope 的設定
一條規則只在一個地方定義，其他地方用連結指向

讀者範本：從零開始的三階段路線圖

Week 1：基礎版（5 行）

# CLAUDE.md

## Commands

npm run dev
npm run build
npm run test

## Stack

TypeScript + [你的框架]

就這麼多。這 5 行就能讓 agent 知道怎麼跑你的專案。

Month 1：進階版（30 行）

# CLAUDE.md

## Commands

npm run dev # Start dev server
npm run build # Build production
npm run test # Run tests

## Architecture

Stack: [框架] + [語言] + [CSS 方案]

- src/pages/ — Routes
- src/components/ — UI components (PascalCase)
- src/lib/ — Utilities and helpers

## Conventions

- Language: [zh-TW / en]
- Naming: [PascalCase components, camelCase functions]
- Use [design tokens / CSS variables] over hardcoded values
- Prefer [composition over inheritance]

## Key Patterns

- [列出 2-3 個專案裡最常用的 pattern]
- [比如：所有 API endpoints 在 /api/ 目錄下]
- [比如：用 Zod 做 input validation]

這 30 行涵蓋了 agent 最常需要的資訊。

Month 3：完整系統

~/.claude/CLAUDE.md            ← 你的開發哲學（~50 行）
project/CLAUDE.md              ← 專案技術棧和慣例（~50 行）
.claude/rules/testing.md       ← 測試規範
.claude/rules/deploy.md        ← 部署流程
~/.claude/skills/commit/       ← git commit 工作流
~/.claude/skills/review/       ← pre-commit review

不需要一次建好。每次你發現 agent 重複犯同一種錯、或你重複跟 agent 說同一件事的時候，那就是該加一條 rule 或一個 skill 的時機。

從少開始，需要時再加。CLAUDE.md 是有機生長的文件，不是一次性的架構設計。

Takeaway

CLAUDE.md 不是寫一次就忘記的文件——團隊共用版本應跟 code 一起 review 與更新；個人版本則留在 home directory。過時內容會誤導 agent。
好的設定系統按 scope 與生命週期分工——Personal、Project、path-scoped Rules、按需 Skills 各有用途，但不是一條可以任意覆蓋的 CSS cascade。
從三行開始就好——build、test、tech stack。隨著需要自然成長。如果 agent 重複犯同一種錯，加一條 rule。如果你重複跟 agent 說同一件事，加一個 skill。47 個設定檔是 12 個月累積的結果，不是一天建好的。

上一篇：Prompt 到 Production 下一篇：MCP 與 A2A 協議實戰