Claude Code 最佳實踐指南
Claude Code 各面向最佳實踐完整研究報告 日期：2026-05-16
來源：research/best-practices/（29 篇）+ research/claude-blog/（52 篇）
目標字數：≥ 10,000 中文字
驗證：autoresearch + research-hub 三方確認
執行摘要 Claude Code 已從「AI 輔助編程工具」演進為完整的「開發者作業系統」。本報告基於 Anthropic 官方文件、社群實踐（Boris Cherny、Thariq Shihipar 等核心貢獻者），以及 52 篇官方 claude-blog 文章，系統梳理 Claude Code 在以下九個面向的最佳實踐：
CLAUDE.md 與記憶系統設計 Hooks 自動化架構 Prompt Caching 與 Context 工程 Subagent 委派策略 Skill 知識封裝與生命週期 MCP 整合與工具擴展 安全部署與權限控制 Routines 排程自動化 成本工程與效能優化
核心論點：Context Engineering（在執行時組裝正確資訊並正確排序）是 Claude Code 真正的工程護城河，遠比 Prompt 撰寫技巧更重要。
第一章：CLAUDE.md 與記憶系統 1.1 CLAUDE.md 設計原則 CLAUDE.md 是 Claude Code 的靈魂文件，每次 session 自動載入。但大多數開發者都犯了同一個錯誤：把它寫得太長、太詳細，反而降低模型遵從率。 黃金法則：CLAUDE.md 長度 ≤ 200 行，最佳 60 行。研究數據顯示，超過 200 行後，模型對規則的遵從率從 76% 跌至 52%。 每行都應通過這個問題的測試：「如果移除這行，Claude 會犯錯嗎？」答案是否 → 立即刪除。 應該寫什麼：
Claude 無法從程式碼猜測的 bash 指令（如 npm run test:unit --reporter=verbose） 與語言預設不同的 code style（如「強制使用 ES modules，禁止 CommonJS」） 測試執行方式與偏好的 test runner Branch 命名與 PR 慣例 專案特定的架構邊界（如「業務邏輯只放 src/services/，不放 routes/`」） 開發環境特殊性（必要的環境變數、工具依賴） 常見陷阱與非直覺行為
不應該寫什麼：
Claude 讀程式碼就能知道的事（框架版本、目錄結構） 標準語言慣例（PEP8、ESLint 推薦規則） 詳細 API 文件（放連結即可） 頻繁變更的資訊（放 <system-reminder> 或讓 hook 動態注入）
<span class="pl-mh"># <span class="pl-en">CLAUDE.md 最簡範本</span></span>
<span class="pl-mh">## <span class="pl-en">指令</span></span> <span class="pl-v">-</span> 測試：<span class="pl-s">`</span><span class="pl-c1">npm run test:unit -- --reporter=verbose</span><span class="pl-s">`</span> <span class="pl-v">-</span> 型別檢查：<span class="pl-s">`</span><span class="pl-c1">npm run typecheck</span><span class="pl-s">`</span> <span class="pl-v">-</span> 格式化：<span class="pl-s">`</span><span class="pl-c1">npm run format</span><span class="pl-s">`</span>（提交前必跑）
<span class="pl-mh">## <span class="pl-en">架構約束</span></span> <span class="pl-v">-</span> API 路由：<span class="pl-s">`</span><span class="pl-c1">src/routes/</span><span class="pl-s">`</span>（只放路由定義） <span class="pl-v">-</span> 業務邏輯：<span class="pl-s">`</span><span class="pl-c1">src/services/</span><span class="pl-s">`</span>（禁止在 routes 中寫邏輯） <span class="pl-v">-</span> 資料庫：<span class="pl-s">`</span><span class="pl-c1">src/repositories/</span><span class="pl-s">`</span>（所有 DB 操作必須在此）
<span class="pl-mh">## <span class="pl-en">非顯而易見的規則</span></span> <span class="pl-v">-</span> <span class="pl-s">`</span><span class="pl-c1">.env.test</span><span class="pl-s">`</span> 用於測試，但 <span class="pl-s">`</span><span class="pl-c1">.env.local</span><span class="pl-s">`</span> 覆蓋一切 <span class="pl-v">-</span> 新功能必須寫對應 E2E 測試（<span class="pl-s">`</span><span class="pl-c1">tests/e2e/</span><span class="pl-s">`</span>） 1.2 Path-Scoped Rules：按路徑觸發的規則 大型 codebase 不需要巨型 CLAUDE.md，而是要用 path-scoped rules： <span class="pl-s">---</span> <span class="pl-ent">paths</span>:
- <span class="pl-s"><span class="pl-pds">"</span>src/api/**/*.ts<span class="pl-pds">"</span></span> <span class="pl-s">---</span>
<span class="pl-mh"># <span class="pl-en">API 開發規範（只在讀取 API 相關檔案時載入）</span></span>
<span class="pl-v">-</span> 所有端點必須包含輸入驗證（Zod schema） <span class="pl-v">-</span> 使用標準錯誤回應格式（<span class="pl-s">`</span><span class="pl-c1">{ error: string, code: string }</span><span class="pl-s">`</span>） <span class="pl-v">-</span> 包含 OpenAPI 文件 JSDoc 將規則放在 .claude/rules/ 目錄，只有在 Claude 讀取符合 glob pattern 的檔案時才自動載入，避免不相關規則污染 context。 1.3 Auto Memory：Claude 的長期記憶 Auto Memory 是 Claude Code 的自學機制，存放在 ~/.claude/projects/<project>/memory/MEMORY.md。Claude 會自動判斷值得記住的資訊並寫入。 關鍵限制：每次 session 自動載入前 200 行或 25KB（以先到者為準）。超過限制的詳細筆記應移到 topic files（debugging.md、patterns.md），需要時手動讀取。 雙層記憶架構（建議）： <code>Auto Memory（~/.claude/projects/.../ memory/MEMORY.md）
→ 自動寫入，存放 session 間學習成果
MEMORY.md（Git 追蹤，workspace 根目錄）
→ 手動維護，存放跨裝置共享的決策與狀態 </code> 自我改進觸發（Boris Cherny 方法）：每次 Claude 犯錯並被糾正後，立即更新 CLAUDE.md 加入防範規則。隨時間累積，CLAUDE.md 成為最有價值的 codebase 知識庫。 1.4 大型 Codebase 的三層 Context 架構 Brendan MacLean（MacCoss Lab）用此架構管理 70 萬行 C# codebase，讓 Claude 在兩週內完成原本需一年的功能： 層一：Context Repository（獨立 Git Repo） <code>pwiz-ai/ （獨立 repo，跨所有 branch 適用） ├── CLAUDE.md
# 根目錄高層概述 ├── docs/ │
├── architecture.md
# 系統架構說明 │
└── api-contracts.md
# API 約定文件 └── indexes/
# 重要檔案索引（供 Claude 快速定位） </code> 層二：Skills Library（可重用領域知識） <code>skills/ ├── skyline-development/
# 開發工作流 ├── version-control/
# Git 慣例 └── debugging/
# 常見除錯模式 </code> 層三：MCP Integrations（真實資料接入）
連接自動化測試結果（真實失敗勝於猜測） 接入異常報告系統 連接支援帖庫（讓 Claude 查到真實用戶問題）
原則：「參考不嵌入」——Skills 指向文件而非複製內容，保持輕量。
第二章：Hooks 自動化架構 2.1 Hooks 三層架構 Hooks 是 Claude Code 的自動化引擎，讓你在工具呼叫的生命週期插入自訂邏輯： <code>Event → Matcher Group → Handler </code> 事件種類（25 種）：
類別 事件 典型用途
Session SessionStart、SessionEnd、SessionStop 環境初始化、通知
工具前後 PreToolUse、PostToolUse 防守、驗證
Agentic SubagentStart、SubagentEnd 子任務監控
檔案 各種 file events 語法驗證、格式化
Exit Code 規約（必記）：
0：成功，繼續執行 1：警告，繼續執行（Claude 看到警告訊息） 2：阻斷，完全停止當前操作
2.2 防守型 Hooks（PreToolUse） PreToolUse 是你的第一道防線，在 Claude 執行任何工具前攔截： <span class="pl-c"><span class="pl-c">#!</span>/usr/bin/env bash</span> <span class="pl-c"><span class="pl-c">#</span> ~/.claude/hooks/block-dangerous.sh</span> <span class="pl-c1">set</span> -euo pipefail
INPUT=<span class="pl-s"><span class="pl-pds">$(</span>cat<span class="pl-pds">)</span></span> COMMAND=<span class="pl-s"><span class="pl-pds">$(</span>echo <span class="pl-s"><span class="pl-pds">"</span><span class="pl-smi">$INPUT</span><span class="pl-pds">"</span></span> <span class="pl-k">|</span> jq -r <span class="pl-s"><span class="pl-pds">'</span>.tool_input.command // ""<span class="pl-pds">'</span></span><span class="pl-pds">)</span></span>
<span class="pl-c"><span class="pl-c">#</span> 阻斷危險命令</span> BLOCKED_PATTERNS=(
<span class="pl-s"><span class="pl-pds">"</span>rm -rf /<span class="pl-pds">"</span></span>
<span class="pl-s"><span class="pl-pds">"</span>DROP TABLE<span class="pl-pds">"</span></span>
<span class="pl-s"><span class="pl-pds">"</span>TRUNCATE TABLE<span class="pl-pds">"</span></span>
<span class="pl-s"><span class="pl-pds">"</span>terraform destroy<span class="pl-pds">"</span></span>
<span class="pl-s"><span class="pl-pds">"</span>git push --force.*main<span class="pl-pds">"</span></span> )
<span class="pl-k">for</span> <span class="pl-smi">pattern</span> <span class="pl-k">in</span> <span class="pl-s"><span class="pl-pds">"</span><span class="pl-smi">${BLOCKED_PATTERNS[@]}</span><span class="pl-pds">"</span></span><span class="pl-k">;</span> <span class="pl-k">do</span>
<span class="pl-k">if</span> <span class="pl-c1">echo</span> <span class="pl-s"><span class="pl-pds">"</span><span class="pl-smi">$COMMAND</span><span class="pl-pds">"</span></span> <span class="pl-k">|</span> grep -qiE <span class="pl-s"><span class="pl-pds">"</span><span class="pl-smi">$pattern</span><span class="pl-pds">"</span></span><span class="pl-k">;</span> <span class="pl-k">then</span>
<span class="pl-c1">echo</span> <span class="pl-s"><span class="pl-pds">"</span>⛔ Blocked: 偵測到危險操作 '<span class="pl-smi">$pattern</span>'<span class="pl-pds">"</span></span> <span class="pl-k">>&2</span>
<span class="pl-c1">exit</span> 2
<span class="pl-k">fi</span> <span class="pl-k">done</span>
<span class="pl-c"><span class="pl-c">#</span> 生產環境警告</span> <span class="pl-k">if</span> <span class="pl-c1">echo</span> <span class="pl-s"><span class="pl-pds">"</span><span class="pl-smi">$COMMAND</span><span class="pl-pds">"</span></span> <span class="pl-k">|</span> grep -q <span class="pl-s"><span class="pl-pds">"</span>prod\|production<span class="pl-pds">"</span></span><span class="pl-k">;</span> <span class="pl-k">then</span>
<span class="pl-c1">echo</span> <span class="pl-s"><span class="pl-pds">"</span>⚠️ Warning: 此操作涉及生產環境，請確認<span class="pl-pds">"</span></span> <span class="pl-k">>&2</span>
<span class="pl-c1">exit</span> 1 <span class="pl-k">fi</span>
<span class="pl-c1">exit</span> 0 settings.json 配置： {
<span class="pl-ent">"hooks"</span>: {
<span class="pl-ent">"PreToolUse"</span>: [
{
<span class="pl-ent">"matcher"</span>: <span class="pl-s"><span class="pl-pds">"