Claude Code 規則：如何撰寫 CLAUDE.md 並管理代理程式編碼上下文

Claude Code 規則存在於 CLAUDE.md 檔案中——這些是你放在專案儲存庫、家目錄或組織設定中的 Markdown 檔案，Claude 會在每次工作階段開始時讀取它們。結合 .claude/rules/ 中的路徑範圍規則、用於權限設定的 settings.json，以及用於學習偏好的自動記憶，規則系統讓你能精確且持久地控制這個編碼代理程式在任何任務中的行為。

什麼是 Claude Code 規則？

每個 Claude Code 工作階段都以一個空的上下文視窗開始。規則是你預先載入 Claude 所需上下文的方式，這樣它就不必從零開始——或重複犯同樣的錯誤。

有兩個互補的系統負責處理這件事：

CLAUDE.md 檔案 是你編寫的 Markdown 檔案，Claude 會在每個工作階段開始時讀取。將那些應該始終適用的指令放在這裡：建置指令、程式碼慣例、架構決策、硬性限制。

自動記憶 是 Claude 根據你在工作階段中給予的修正和偏好而自行撰寫的筆記。這些筆記會自動累積；Claude 會判斷哪些值得保存，並在未來的工作階段中讀取這些筆記。

兩者都會在工作階段開始時載入到上下文中，但它們並非強制執行的設定。它們是 Claude 作為上下文遵循的指示。若要強制執行——無論 Claude 決定做什麼都阻擋特定指令——你需要一個 PreToolUse 鉤子或 settings.json 中的 deny 規則。這個區別對於你想要可預測行為而非機率性遵守的自動化執行尤為重要。

CLAUDE.md 檔案位置與範圍

Claude Code 會從多個位置載入 CLAUDE.md 檔案，每個位置涵蓋不同的範圍。它們會從最廣泛到最具體的順序載入：

位置	範圍	用途
~/.claude/CLAUDE.md	你機器上的所有專案	個人偏好、全域工作流程習慣
./CLAUDE.md（儲存庫根目錄）	該專案中的所有工作階段	專案慣例、建置指令、團隊共享規則
./CLAUDE.local.md（儲存庫根目錄）	僅限你當地的會話	開發者個人偏好；請加入 .gitignore
./src/CLAUDE.md（子目錄）	觸及該目錄中檔案的工作階段	不適用於整個專案的模組特定規則

所有找到的檔案會被串接起來進入上下文——它們不會彼此覆蓋。在串接過程中，從檔案系統根目錄到你工作目錄的內容會以「最特定者最後」的順序排列，因此專案指令會出現在使用者指令之後。這提供了自然的特異性：專案規則在與使用者層級規則衝突時會勝出。

你可以在任何 CLAUDE.md 內部使用 @path 引用來匯入其他檔案：

@./docs/architecture.md
@./CONTRIBUTING.md

匯入的檔案會在工作階段開始時載入，與 CLAUDE.md 本身相同。匯入對於組織很有用，但不會節省上下文——匯入的內容會計入你的 Token 預算中。

對於團隊：將專案 CLAUDE.md 提交到版本控制。這能確保每個開發者的 Claude 工作階段——以及任何基於 CI 的代理程式執行——都以相同的共享上下文開始。請將其視為 .eslintrc 或 pyproject.toml 來對待。

在 CLAUDE.md 中放入什麼內容

最有用的內容是那些你每次工作階段都得重新解釋的東西，或者新團隊成員在第一個小時內需要知道的東西。

好的候選項目：

• 與明顯預設值不同的建置和測試指令（./scripts/test.sh --ci，而不只是 npm test）
• 程式碼檢查工具未能捕捉到的程式碼慣例（「我們到處使用具名匯出；共享工具中不要使用預設匯出」）
• 從程式碼本身看不出來的架構決策（「lib/ 目錄是跨服務共享的——不要在那裡加入服務特定邏輯」）
• 已知陷阱（「config.ts 檔案在建置時生成；不要手動編輯」）
• 工作流程限制（「在進行變更前務必建立分支；在開啟 PR 之前先推送至遠端」）

應該省略的內容：

• 目錄列表和檔案樹——Claude 會從儲存庫中讀取這些資訊
• 依賴項列表——可從 package.json、pyproject.toml 等取得
• 描述現有程式碼功能的文字說明——Claude 會直接讀取原始碼
• 近期變更——Claude 在需要歷史記錄時會使用 git log 和 git diff

讓 CLAUDE.md 專注於那些無法從閱讀程式碼庫推導出來的內容。超過 200 行的檔案會消耗更多上下文並降低遵守的可靠性。Claude Code 中的 /doctor 指令會稽核已簽入的 CLAUDE.md，並建議刪除那些可從程式碼推導出來的內容——這是減少臃腫檔案的有效方法。

撰寫有效的規則

具體性很重要。比較一下：

# 模糊——一致性較差
遵循專案編碼標準。

# 具體——一致性較高
- 使用 pnpm，而不是 npm 或 yarn
- 每次提交前執行 pnpm test；如果測試失敗則不要提交
- 從 src/types/index.ts 匯出所有共享型別——不要在元件檔案中內聯定義型別
- data/ 目錄在測試中為唯讀；請改用 tests/fixtures/ 中的測試固定資料

每條規則都應該無需進一步解釋即可執行。如果你需要向某人解釋規則的背後理由，請將理由內聯加入——這有助於 Claude 在邊緣情況下正確應用規則。

使用 .claude/rules/ 的路徑範圍規則

.claude/rules/ 目錄讓你可以將規則附加到特定的檔案模式，而無需將它們載入到每個工作階段中。Claude 會發現 .claude/rules/ 中的檔案，並在你處理符合條件的檔案時載入它們。

一個典型的 TypeScript 單體儲存庫結構：

.claude/rules/
  api.md             # 適用於 src/api/** 的規則——請求驗證、錯誤格式
  components.md      # 適用於 src/components/** 的規則——屬性型別、樣式慣例
  tests.md           # 適用於 tests/** 的規則——固定資料模式、Mock 設定
  database.md        # 適用於 migrations/ 和 models/ 的規則——遷移命名、查詢模式

每個規則檔案使用帶有 paths 欄位的 YAML 前置資料來控制何時載入：

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

# API 開發規則

- 所有路由處理器必須在任何業務邏輯之前使用 zod 驗證輸入
- 錯誤回傳格式為 `{ error: string; code: string }`——絕不要使用純字串
- 速率限制在閘道器層級應用；不要在處理器內部加入

沒有 paths 欄位的規則會在會話開始時無條件載入，與專案 CLAUDE.md 中的內容相同。有 paths 的規則只會在 Claude 開啟符合這些模式的檔案時載入。

這讓專案根目錄的 CLAUDE.md 保持簡潔，並確保某一層堆疊的詳細慣例不會在專注於不同領域的工作階段中佔用上下文。

settings.json 與 CLAUDE.md 的比較

CLAUDE.md 控制 Claude 知道什麼以及打算做什麼。settings.json 控制 Claude 實際上被允許做什麼。

	CLAUDE.md	settings.json
用途	指令和上下文	權限和設定
強制執行？	否——Claude 將其作為指導來執行	是——deny 規則無條件封鎖工具呼叫
格式	自由格式的 Markdown	結構化 JSON
存放位置	./CLAUDE.md、~/.claude/CLAUDE.md	.claude/settings.json、~/.claude/settings.json

.claude/settings.json 中的專案 settings.json：

{
  "permissions": {
    "allow": [
      "Bash(pnpm test)",
      "Bash(pnpm build)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

allow 列表會預先批准特定指令，讓 Claude 無需提示即可執行它們。這可以加速你信任的操作的互動式工作階段。deny 列表則無條件封鎖指令——無論 Claude 決定做什麼，無論 CLAUDE.md 說什麼。對於生產資料或基礎設施上不可逆的操作，請使用 deny。

使用者層級的設定位於 ~/.claude/settings.json，適用於所有專案。專案設定位於 .claude/settings.json，僅在該儲存庫中適用。在重疊之處，專案設定優先於使用者設定。

自動記憶：Claude 的筆記

自動記憶是 CLAUDE.md 的對應機制。CLAUDE.md 是你編寫的指令，而自動記憶是 Claude 根據在工作階段中學到的內容自行編寫的筆記。

當你在工作階段中修正 Claude 時——「這個專案我們用 Vitest，不是 Jest」——它可以將此內容儲存為 ~/.claude/projects/<repo>/memory/ 中的筆記。下一次工作階段時，Claude 會讀取該筆記並自動套用修正，無需再次告知。

記憶目錄包含：

~/.claude/projects/<repo>/memory/
  MEMORY.md          # Claude 用來尋找其他檔案的索引；每次工作階段載入前 200 行
  debugging.md       # Claude 在解決此儲存庫問題時發現的模式
  conventions.md     # Claude 從你的修正中學到的慣例

這是機器本地且每個儲存庫獨立的。自動記憶是 CLAUDE.md 的補充而非替代：CLAUDE.md 適用於團隊共享的專案規則；自動記憶則適用於 Claude 從與你合作中學到的個人模式。

自動記憶是可讀取的 Markdown，你可以隨時編輯或刪除。在工作階段中執行 /memory 來瀏覽和編輯這些檔案。如果某個內容已經過時或錯誤，請將其刪除——Claude 就會停止套用該過時規則。

代理程式編碼的最佳實踐

透過 claude -p、Agent SDK 或 CI 管道自主執行 Claude Code，會提高對你規則設定的要求。代理程式可能在不暫停的情況下完成數十次工具呼叫，而且沒有互動式的來回溝通來在中途捕捉誤解。

撰寫明確的限制，而不只是偏好。 互動式 Claude 可以請你釐清。自主執行則只會使用它在上下文中找到的內容。如果「未先建立資料庫快照不得修改遷移檔案」很重要，那它就需要在 CLAUDE.md 中。不要假設 Claude 會從程式碼庫結構推導出這個限制。

對任何難以逆轉的操作使用 deny 規則。 預先批准 Bash(pnpm build) 可以加速互動式工作階段，且風險較低。但對於自主執行，deny 列表是你在觸及生產基礎設施、永久提交到 Git 歷史或刪除資料等操作時的安全網。

將專案 CLAUDE.md 保留在版本控制中。 提交到儲存庫根目錄的 CLAUDE.md 能一致地應用於互動式工作階段、CI 執行以及任何團隊成員的本地代理程式。這是定義你程式碼庫中「正確」含義的規則的正確位置。

對領域特定內容使用 .claude/rules/。 如果你的專案有不同的層次——前端元件、後端 API、資料庫結構、基礎設施腳本——將每個層次的規則放在 .claude/rules/ 中並設定路徑範圍。一個包含所有內容的 400 行 CLAUDE.md 會讓 Claude 更難導航，且每次工作階段耗費更多上下文。

將參考資料移至技能 (Skills)。 技能（.claude/skills/）是按需載入，而非在工作階段開始時載入。冗長的 API 文件、多步驟部署程序和故障排除手冊應歸屬於你可以透過 /deploy 或 /debug 叫用的技能——而不是放在 CLAUDE.md 中，在不相關時仍佔用上下文。

定期檢視自動記憶。 自動記憶會隨著時間累積。建置指令會改變、慣例會被重構、測試模式會轉變。一條過時的記憶筆記說「使用 v1 API 客戶端」但你已遷移到 v2，這會在自主執行中導致微妙的錯誤。當你對專案結構進行重大變更時，請稽核 ~/.claude/projects/<repo>/memory/。

將開源模型與你的規則設定搭配使用

你建立的 CLAUDE.md 上下文和 .claude/rules/ 無論使用哪個模型進行推理，其運作方式都相同。一旦規則編寫完成，切換模型後端會保留所有內容——而透過 Novita AI 的 LLM API 使用開源模型，是高流量代理程式工作的實用選擇。

設定只需一個環境變數：

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<your-novita-api-key>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"

將 ANTHROPIC_BASE_URL 指向 Novita AI 後，Claude Code 會將所有推理請求發送到 Novita 的 Anthropic 相容端點，而不是 api.anthropic.com。你的 CLAUDE.md、路徑範圍規則和 settings.json 都與之前完全一樣——規則層位於模型選擇的上游。

Novita AI 託管包括 Qwen3-Coder、GLM-4.7、MiniMax M2.5 和 DeepSeek V4 在內的程式碼導向開源權重模型。這些模型針對多步驟工具使用和函式呼叫進行了最佳化，這與 Claude Code 內部用於檔案編輯、Shell 指令和儲存庫導覽的工具呼叫模式高度契合。

對於大規模執行代理程式任務的團隊——程式碼審查管道、大型儲存庫的自動重構、測試生成——Novita 上的開源權重模型通常每百萬 Token 成本顯著低於閉源替代方案，同時仍能有效讀取和應用你的專案規則。

如果你正在對生產程式碼庫執行代理程式，並希望獲得超越 deny 規則的額外安全層，可以考慮將 Novita 的 LLM API 與 Novita 的 Agent Sandbox 搭配使用。Sandbox 為代理程式提供了一個完整的 Linux 環境來進行檔案操作和指令執行，與你的主機系統隔離。你的 CLAUDE.md 上下文會隨任務移動；執行風險則被控制在沙盒內。

常見問題

Claude Code 中的 CLAUDE.md 是什麼？

CLAUDE.md 是一個 Markdown 檔案，為 Claude Code 提供跨工作階段的持久指令。它在工作階段開始時載入，這樣 Claude 就不必每次都被重新教導你的專案慣例。你可以在多個範圍擁有 CLAUDE.md 檔案：使用者層級（~/.claude/CLAUDE.md）用於適用於所有地方的個人偏好，專案層級（儲存庫根目錄）用於提交到版本控制的團隊共享規則，以及子目錄層級用於模組特定規則。

我應該在 Claude 規則的 md 檔案中放入什麼？

寫下你每次工作階段都需要重新解釋的內容：建置和測試指令、與框架預設值不同的程式碼慣例、架構限制，以及已知的程式碼庫陷阱。省略 Claude 可以從程式碼庫本身推導出的內容——檔案樹、依賴項列表以及現有程式碼的功能描述。將檔案保持在 200 行以下以獲得一致的遵守效果。

Claude Code 中 CLAUDE.md 和 settings.json 的差別是什麼？

CLAUDE.md 是 Claude 作為指導遵循的指示。settings.json 是 Claude Code 在系統層級強制執行的設定。CLAUDE.md 中的規則塑造 Claude 的意圖；settings.json 中的 deny 條目則無條件封鎖工具呼叫。對於無論 Claude 決定什麼都絕對不能發生的事——不可逆的刪除、強制推送、生產環境操作——請使用 settings.json，而不是 CLAUDE.md。

什麼是 .claude/rules/ 目錄？

.claude/rules/ 存放路徑範圍規則檔案，這些規則僅在 Claude 處理符合規則範圍的檔案時才會載入。這讓你可以編寫詳細的領域特定規則，而無需將它們載入到每個工作階段中。規則是 Markdown 檔案，帶有可選的 YAML 前置資料，用於指定 paths 的 Glob 模式。沒有 paths 前置資料的規則會在工作階段開始時無條件載入，就像額外的 CLAUDE.md 內容一樣。

CLAUDE.md 在 CI 和自動化的 Claude Code 任務中有效嗎？

是的。任何在儲存庫目錄中執行的 claude -p 叫用、Agent SDK 呼叫或 CI 管道都會載入專案的 CLAUDE.md。這使得 CLAUDE.md 能夠有效地在互動式和自動化上下文中強制執行一致的行為。將其提交到版本控制可確保每次執行——無論本地還是 CI——都以相同的共享上下文開始。

Claude Code 上下文如何運作，我該如何管理它？

上下文是當前工作階段的 Token 預算。CLAUDE.md 檔案、匯入的參考資料、自動記憶以及對話歷史都會計入其中。透過保持 CLAUDE.md 簡潔、使用 .claude/rules/ 僅在相關時載入領域內容，以及使用 /compact 來總結較長的工作階段而不失去連續性來管理它。在 /compact 之後，Claude 會從磁碟重新讀取專案根目錄的 CLAUDE.md，並自動將其重新注入工作階段。

如何在團隊中使用 Claude Code 代理程式編碼的最佳實踐？

將專案 CLAUDE.md 提交到你的儲存庫，以便所有團隊成員和 CI 代理程式共享相同的規則。對領域特定內容使用帶有路徑範圍的 .claude/rules/。對不應在自動化上下文中執行的操作，在 .claude/settings.json 中加入 deny 規則。將自動記憶排除在 CI 之外——它是機器本地且每個開發者專屬的；已提交的 CLAUDE.md 才是共享行為的權威來源。

Novita AI 是一個 AI 雲端平台，為開發者提供透過簡單 API 部署 AI 模型的便捷方式，同時也提供價格實惠且可靠的 GPU 雲端服務，用於建置與擴展。

推薦文章

• Claude Code CLI 文件：設定、斜線指令與 LLM API 整合
• Claude Code SDK：使用 Python 與 TypeScript 建置自主代理程式
• 使用 Novita 的 Agent Sandbox 建置編碼代理程式

---

資料查核日期：2026 年 7 月 21 日：Claude Code 記憶文件、Claude Code 功能概覽、Novita AI LLM API