Claude Code 進階設定實戰：CLAUDE.md、Rules、Skills 與環境變數

前言

Claude Code 不只是能讀取程式碼、呼叫終端機的 AI 工具。把專案規範、依路徑載入的規則、可重複執行的 Skills，以及環境變數與 Hooks 設定好之後，它才能在不同專案裡穩定使用正確的建置方式、編輯習慣和工具權限。

這篇整理 Claude Code 的幾種設定方式，並釐清一個容易搞混的問題：**.claude/rules/ 裡的 Rule 是提示 Claude 的 Markdown 指令，不能直接設定 Shell 環境變數。**本文依 Anthropic 官方文件截至 2026 年 10 月 14 日 的內容撰寫；Claude Code 仍在持續更新，實際可用欄位請以官方文件及本機版本為準。

封面為 AI 生成的概念插畫，呈現專案指令、路徑規則、工作流程與執行環境之間的關係。

先建立設定的心智模型

Claude Code 有多種可調整的層次。它們看起來都像「設定」，實際上作用不同：有的提供上下文，有的改變程式的執行環境，有的在特定事件發生時執行程式。

機制	主要用途	載入或執行方式
`CLAUDE.md`	專案架構、慣例、常用命令等持續適用的背景	進入工作階段時載入
`.claude/rules/`	依目錄或檔案類型套用的細部規範	一般規則每次載入；路徑規則在處理匹配檔案時載入
`SKILL.md`	多步驟工作流程、領域知識、常用操作	使用者呼叫，或 Claude 判斷任務相關時載入
`.claude/settings.json`	權限、Hooks、外掛與環境變數等程式設定	依設定檔作用範圍套用
Hooks	在工作階段或工具事件中自動執行命令	事件觸發時執行
Auto memory	Claude 自行保存的個人偏好與工作心得	依專案在後續工作階段載入

可以用一句話記住：CLAUDE.md 和 Rules 告訴 Claude「如何做」；Skills 提供「何時做、按什麼步驟做」；Settings 改變「Claude Code 怎麼執行」；Hooks 則讓某個動作在指定事件發生時自動執行。官方擴充功能總覽也用這些差異說明各功能的適用時機。

`CLAUDE.md`：放跨任務都需要的專案知識

CLAUDE.md 是 Markdown 指令檔。Claude Code 會把它當成上下文讀取，不是程式設定，也不是強制執行的安全政策。適合放在裡面的內容包括：

專案使用的語言、框架、架構和重要目錄。
建置、格式化、測試與啟動服務的命令。
資料庫 Migration、API 回應格式或命名慣例。
會反覆提醒 Claude 的注意事項。

根據範圍選擇檔案位置

個人、專案和組織可以各自維護指令。常見位置如下：

位置	範圍	常見內容
`~/.claude/CLAUDE.md`	目前使用者的所有專案	個人偏好、通用工作習慣
專案根目錄的 `CLAUDE.md`	專案成員共享	架構、建置命令、團隊慣例
`CLAUDE.local.md`	目前使用者的單一專案	本機測試資料、個人環境備註；應加入 `.gitignore`
子目錄的 `CLAUDE.md`	某個子目錄	該模組或服務獨有的規範

Claude Code 會從啟動目錄往上尋找適用的檔案，並把找到的指令一起放進上下文；工作進入子目錄後，也會按需載入當地的指令檔。這不是傳統設定檔「後者蓋掉前者」的機制，指令有衝突時，Claude 仍須自行判斷。因此，專案規範應該盡量一致，並把較具體的規則放在較具體的範圍。

CLAUDE.md 也可以用 @path/to/file 匯入其他文件。這有助於把內容拆開管理，但匯入檔仍會一起進入上下文，不會減少每次工作階段載入的內容量。官方建議單一 CLAUDE.md 以 200 行內為目標；細節太多時，可改用路徑規則或 Skills。記憶與指令文件有說明載入位置、匯入方式和長度建議。

別把 Auto memory 當成團隊規範

Auto memory 是 Claude 根據使用者修正和專案工作心得自動留下的筆記，通常位於本機的 ~/.claude/projects/ 資料夾。它和 CLAUDE.md 不同：前者偏向 Claude 自己累積的個人經驗，後者才適合放由團隊共同維護、每位成員都應遵守的專案約定。要查看或調整記憶，可在 Claude Code 使用 /memory。

Rules：讓規範只在處理特定檔案時出現

大型 Repository 常同時包含前端、後端、Migration 和測試程式碼。把所有要求都放在根目錄的 CLAUDE.md，會讓每種工作都背負整份規範；拆成 .claude/rules/ 可以讓內容更好維護。

沒有設定 paths 的 Rule 會套用到整個專案。加入 paths 欄位後，Claude Code 只在處理匹配檔案時載入這項規則。例如下面的 Rule 只針對 TypeScript API：

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

# API 開發規範

- 所有輸入都要先驗證。
- 錯誤回應使用專案定義的格式。
- API 變更要同步更新 OpenAPI 文件。

把檔案存成 .claude/rules/api.md。paths 使用 glob pattern，可依副檔名、目錄或多個目標來匹配。這種方式適合「只有特定程式碼才需要遵守」的規範；若一條規則在所有任務都適用，留在根目錄 CLAUDE.md 通常更清楚。

Rule 能不能設定環境變數？

不能直接設定。.claude/rules/*.md 是提供給模型閱讀的上下文，paths 只決定規則何時載入，並不會因此修改 process.env 或啟動 Shell 變數。

例如 Rule 可以要求「呼叫整合測試時使用 staging API」，但若希望 Claude Code 啟動的命令真的收到 API_BASE_URL，應設定 .claude/settings.json 的 env，或依需求使用 Shell 設定與 Hook。這個區分能避免把「告訴模型某個變數應該存在」誤認成「變數已經被設定」。

Skills：把常做的多步驟工作整理成可重用流程

Skill 是放在 SKILL.md 的工作流程或參考知識。專案共用的 Skill 放在 .claude/skills/，個人 Skill 可放在 ~/.claude/skills/。一個目錄對應一個 Skill，目錄內也能放參考文件或輔助程式，不必把所有內容塞進主檔。

例如，/prepare-pr 可以統一執行 Pull Request 前的檢查：

---
name: prepare-pr
description: 檢查目前分支的變更並整理 PR 摘要
disable-model-invocation: true
---

1. 檢查目前分支與工作目錄狀態。
2. 閱讀差異，摘要變更和可能的風險。
3. 依專案規範執行必要檢查。
4. 整理 PR 標題與說明；不要自行建立 PR。

將內容存為 .claude/skills/prepare-pr/SKILL.md，然後在對話中輸入 /prepare-pr 呼叫。預設情況下，使用者可以手動呼叫，Claude 也可能在判斷任務相關時自動載入 Skill。加入 disable-model-invocation: true 後，Claude 不會自行觸發；這對部署、發布或有副作用的操作特別有用。反過來說，user-invocable: false 可以讓 Skill 作為 Claude 自動參照的背景知識，而不出現在使用者可呼叫的指令清單。

幾個進階欄位各有用途：

description 要描述「適用什麼任務」，讓 Claude 能正確判斷是否載入。
allowed-tools 可在呼叫該 Skill 的當次工作中授權列出的工具；它不會限制所有其他工具，也不會取代一般權限規則。先檢視 Repository 中 Skill 的工具授權，再執行它。
context: fork 會在獨立的 Agent 上下文執行 Skill，適合需要大量閱讀、但不想把中間內容留在主對話的任務。
paths 可依檔案路徑決定何時自動載入 Skill。
細節太長時，將參考資料拆到同目錄的 reference.md 等文件，並在 SKILL.md 中指引何時讀取。

對於新建立的工作流程，官方建議優先使用 Skills；舊格式 .claude/commands/ 仍可用，但 Skills 支援同目錄的參考文件和輔助腳本。Skills 官方文件列出所有 Front Matter 欄位及不同觸發方式。

專案環境變數：設定在 `settings.json`，而不是 Rule

Claude Code 的 Settings 檔案有不同作用範圍：

~/.claude/settings.json：個人所有專案共用。
.claude/settings.json：專案共用，可提交到 Repository。
.claude/settings.local.json：個人只在目前專案使用，適合本機覆寫；手動建立時要確認已加入 .gitignore。

若要替專案命令設定公開、非敏感的變數，可在共用的 .claude/settings.json 中加入 env：

{
  "env": {
    "NODE_ENV": "development",
    "API_BASE_URL": "https://staging.example.com"
  }
}

Claude Code 會將值放進它的環境中，因此同一工作階段中由 Claude Code 執行的命令可以讀取它。值會以字面內容載入；檔案不會經過 Shell 展開，所以不要期待 "$HOME/project" 或 "~/project" 會自動轉成實際路徑。這類路徑應填入完整路徑。

settings.json 是嚴格 JSON，不能加註解或多餘逗號。專案共享設定中的大多數 env 值，會在使用者信任該資料夾後才套用。

請勿把 API Key、密碼或雲端憑證放進會提交的設定檔、CLAUDE.md、Rule 或 Skill。共享設定會進入版本控制，指令文件則會成為模型上下文。機敏值應從個人 Shell、作業系統憑證管理工具或團隊的 Secret 管理流程提供，並只授予執行任務真正需要的權限。

還要注意：Settings 有明確的優先順序，組織管理設定最高，其次是單次工作階段的 --settings，再來是專案本機、專案共享和使用者設定。環境變數則不完全依照這個順序；某些變數會直接覆蓋對應設定，需按變數個別查閱。遇到「改了檔案但行為沒變」，先用 /status 確認載入了哪些 Settings，再檢查該設定的優先順序。設定與優先順序文件及環境變數參考列出各欄位的適用範圍。

Hooks：需要自動化或強制檢查時使用

CLAUDE.md 和 Rules 都是給模型的指令，不能保證 Claude 每次都遵守。若某個動作要在特定事件自動發生，或需要在執行工具前攔截，就應評估 Hook 和 Permission 規則。

例如，專案可以註冊 SessionStart Hook，在每次工作階段啟動時設定環境。下列設定會在工作階段啟動時執行專案腳本：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/dev-env.sh"
          }
        ]
      }
    ]
  }
}

Hook 會取得 CLAUDE_ENV_FILE，可將變數寫入該檔案，讓同一工作階段後續執行的 Bash 命令讀取：

1
2
3

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=development' >> "$CLAUDE_ENV_FILE"
fi

這段程式只是 Hook 腳本內容；仍要在 .claude/settings.json 的 hooks.SessionStart 註冊它才會執行。若只是設定固定的專案環境變數，env 通常較簡單；若要執行版本管理工具初始化、依目錄重新載入環境或讀取受控的本機設定，才考慮 Hook。動態目錄切換可再評估 CwdChanged 事件。

安全規則也應放在正確的地方。例如，要求 Claude「不要讀取 .env」只是上下文指令；要阻止 Claude Code 的檔案工具讀取，可用 Permission 的 deny 規則。若要攔截透過 Shell 執行的存取，還要另外限制對應命令或使用 PreToolUse Hook。**指令負責引導，Permission 和 Hook 才是可執行的控制點。**Hook 會執行實際命令，團隊應先檢視其程式內容和執行範圍。Hooks 官方參考涵蓋事件名稱、輸入與環境變數持續方式。

一套適合多數 Repository 的目錄配置

先把根目錄指令保持精簡，專屬規範放 Rules，重複工作流程放 Skills，執行設定放 Settings：

project/
├── CLAUDE.md
└── .claude/
    ├── settings.json
    ├── settings.local.json
    ├── rules/
    │   ├── api.md
    │   └── database.md
    ├── skills/
    │   └── prepare-pr/
    │       ├── SKILL.md
    │       └── checklist.md
    └── hooks/
        └── dev-env.sh

實際導入時可以依序做：

從常被重複說明的建置、測試和架構資訊開始，寫入 CLAUDE.md。
把特定目錄或副檔名才適用的規範，拆到帶有 paths 的 Rule。
把可重複執行的多步驟工作整理成 Skill，並明確設定自動或手動觸發。
將公開的專案環境設定和團隊共用 Hooks 放進 .claude/settings.json；個人覆寫放本機設定。
為確實需要自動攔截的操作設定 Permission 或 Hook，不要只依靠一段提示文字。

完成後可用 /context 查看已載入的指令與規則、/memory 檢視指令及記憶位置、/status 確認作用中的設定來源，也可用 claude doctor 檢查設定錯誤。若 Skill 沒有出現在清單中，先確認目錄位置、SKILL.md 名稱及 Front Matter 格式。