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

Agentic Engineering 實戰手冊第 8 / 14 篇

這是「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 system。這不是因為我喜歡寫設定檔，是因為一個檔案真的不夠用。

但你不需要從 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 流程、specific component 的使用方式。結果 agent 的行為變得不穩定——有時候遵循 convention A，有時候遵循 convention B。

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

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

問題 3：重複的工作流

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

→ 需要可重用的 skill 模組。

設定檔層級架構

經過一年的演化，我的設定檔系統有四個層級：

~/.claude/CLAUDE.md           ← Global：所有專案通用
  └── project/CLAUDE.md       ← Project：專案特定
      └── .claude/rules/*.md  ← Rules：場景特定
          └── skills/*.md     ← Skills：可觸發的工作流

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 5 + 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:4323
npm run build # Build production site to ./dist/

## Architecture

Stack: Astro 5 + 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 是「場景特定的 context」——不是每次都需要，但在特定情境下很重要的指令。

例子：

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？當一條規則只在特定類型的任務中需要。如果你在寫測試的時候才需要知道 testing conventions，那它應該在 testing-rules.md，不是在每次 session 都會載入的 CLAUDE.md。

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

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

Skills 是 CLAUDE.md 的「按需版」——你用 /skill-name 觸發，它才會被載入到 context。

為什麼需要 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 CLAUDE.md > Global CLAUDE.md（最低）

這跟 CSS 的 specificity 邏輯一樣：越具體的越優先。Global 是預設值，project 覆蓋 global，rules 覆蓋 project，skills 覆蓋一切。

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 裡已經有 build script，不要在 CLAUDE.md 裡複製。如果 tsconfig.json 已經定義了 TypeScript 設定，不要在 CLAUDE.md 裡再寫一次。Agent 有能力讀這些檔案。

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（global）不需要 commit——那是你個人的偏好設定。但 project CLAUDE.md 一定要。

團隊共用的考量

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

避免主觀規則：「程式碼要寫得漂亮」是主觀的；「函數不超過 50 行」是客觀的
避免個人偏好：你喜歡 semicolons，同事不喜歡——這種交給 ESLint 處理
建立修改流程：修改 CLAUDE.md 也需要 PR review，就像修改 ESLint config 一樣

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

Anti-pattern 1：太長（>300 行）

症狀：CLAUDE.md 超過 300 行，什麼都寫在裡面。

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

修正：

拆到 rules files 和 skills
刪掉可以從 codebase 推斷出來的資訊
刪掉過時的資訊
目標：Project CLAUDE.md < 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 utility classes，不要寫 custom CSS」比「遵循專案的 CSS 慣例」明確 100 倍。

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 規則（project > global）
定期交叉檢查不同層級的設定
一條規則只在一個地方定義

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

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 不是寫一次就忘記的文件——它是你跟 agent 的持續溝通管道。像 code 一樣，它需要被 version control、被 review、被定期維護。過時的 CLAUDE.md 比沒有 CLAUDE.md 更糟，因為它會誤導 agent。
好的設定檔系統是分層的——Global（所有專案通用）→ Project（專案特定）→ Rules（場景特定）→ Skills（按需觸發）。每一層有各自的職責，避免一個檔案什麼都放。
從三行開始就好——build、test、tech stack。隨著需要自然成長。如果 agent 重複犯同一種錯，加一條 rule。如果你重複跟 agent 說同一件事，加一個 skill。47 個設定檔是 12 個月累積的結果，不是一天建好的。

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