Claude Code 最佳實踐指南

概述

Claude Code 是一個代理式編程環境，它使 AI 能夠讀取檔案、執行指令並自主實作解決方案，而不僅僅是審查程式碼。為了最大化其效能，使用者必須管理上下文窗口（context window）——這包含了所有訊息、檔案讀取內容和指令輸出——因為當窗口填滿時，效能會下降。

實作自主驗證

為了防止使用者成為唯一的驗證環節，應為 Claude Code 提供確定性的訊號，以判斷任務何時完成。

驗證策略

  • 驗證標準：與其提供模糊的要求，不如提供具體的測試案例（例如：「編寫一個 validateEmail 函式；user@example.com 為 true，invalid 為 false」）並指示 Claude 執行它們。
  • 視覺驗證：對於 UI 變更，提供設計截圖並指示 Claude 擷取結果截圖並列出差異。
  • 根本原因分析：在修復建置問題時，提供具體的錯誤，並要求建置在不壓制錯誤的情況下成功完成。

閘門機制

根據所需的自主程度，可以透過以下方式實作驗證：

  • 單一提示詞：在單一訊息中請求檢查與迭代。
  • 目標條件 (/goal)：使用獨立的評估器在每一輪後重新檢查條件。
  • 停止鉤子 (Stop Hooks)：在特定檢查通過前，阻止該輪結束的腳本。
  • 驗證子代理 (Verification Subagents)：使用全新的模型來反駁主要代理的結果。

工作流程：探索、規劃與編碼

直接跳入編碼可能會導致解決錯誤的問題。Anthropic 建議使用 plan mode 的四階段工作流程，將探索與執行分離：

  1. 探索 (Explore)：理解程式碼庫和問題。
  2. 規劃 (Plan)：定義實作策略。
  3. 編碼 (Code)：執行計畫。
  4. 驗證 (Verify)：確保解決方案符合標準。

提示詞與上下文優化

提供具體上下文

提示詞的精準度可以減少歧義並防止錯誤。有效的策略包括：

  • 限定任務範圍：指定確切的檔案、情境和測試偏好（例如：「避免使用 mocks」）。
  • 引導來源：引導 Claude 查看特定的 git 歷史紀錄或檔案，以回答架構問題。
  • 引用模式：引導 Claude 參考現有的程式碼庫範例（例如：「HotDogWidget.php」）以確保一致性。
  • 描述症狀：提供錯誤、可能的位置以及「已修復」的定義。

豐富內容整合

  • @ 引用：使用 @ 直接引用檔案，以便 Claude 在回應前讀取它們。
  • 直接輸入：貼上圖片、提供文件 URL，或使用 cat error.log | claude 傳遞數據。
  • 自主擷取：指示 Claude 使用 Bash 指令或 MCP 工具來獲取必要的上下文。

環境配置

CLAUDE.md 檔案

CLAUDE.md 是一個持久的上下文檔案，會在每次會話開始時讀取。應保持其簡潔，以避免撐爆上下文窗口。

  • 應包含內容：非顯而易見的 Bash 指令、自定義程式碼風格規則、偏好的測試執行器、儲存庫規範以及專案特定的架構決策。
  • 應排除內容：標準語言慣例、詳細的 API 文件（請改用連結）以及頻繁變動的資訊。

權限與自動化

  • 自動模式 (Auto Mode)：使用分類模型僅攔截高風險動作（例如：權限提升），減少手動核准的需求。
  • 權限白名單：特別允許安全的工具，如 npm run lint。
  • 沙盒化 (Sandboxing)：透過作業系統層級的隔離來限制檔案系統和網路存取。

擴充功能與工具

  • CLI 工具：安裝如 GitHub CLI (gh) 等工具，讓 Claude 比透過 API 更高效地管理 issue 和 PR。
  • MCP 伺服器：將 Claude 連接到問題追蹤器、資料庫和 Figma 設計。
  • 鉤子 (Hooks)：在特定點執行的確定性腳本（例如：每次編輯後執行 eslint）。
  • 技能 (Skills)：儲存在 .claude/skills/ 中的專案特定知識，可透過 /skill-name 調用。
  • 子代理 (Subagents)：用於重型研究或對抗性審查的獨立上下文，以避免弄亂主會話。
  • 插件 (Plugins)：技能、鉤子和 MCP 伺服器的組合單元，包括針對強型別語言的程式碼智能插件。

會話管理

上下文維護

由於上下文窗口是主要的限制因素，因此需要積極的管理：

  • /clear：在不相關的任務之間重置上下文，防止出現「大雜燴式會話 (kitchen sink sessions)」。
  • /compact：手動觸發對話歷史紀錄的摘要化。
  • /btw：用於不應儲存到對話歷史紀錄的附帶問題。
  • 糾正方向：如果 Claude 在同一個問題上失敗了兩次，請 /clear 會話並使用更具體的提示詞重新開始。

狀態控制

  • 回溯與檢查點：使用 Esc + Esc 或 /rewind 來還原先前的程式碼狀態或對話歷史紀錄。
  • 恢復：使用 claude --continue 或 claude --resume 來接續先前的會話。

擴展與自動化

非互動模式

使用 claude -p "prompt" 可以將其整合到 CI 流水線和 pre-commit hooks 中，輸出可選為純文字、JSON 或串流 JSON。

並行執行

  • Worktrees：用於獨立 CLI 會話的隔離 git checkouts。
  • 代理團隊：由一名團隊領導者協調多個會話的自動化流程。
  • 編寫者/審查者模式 (Writer/Reviewer Pattern)：使用獨立的會話進行實作與審查，以消除偏見。

扇出模式 (Fan-out Patterns)

對於大規模遷移，使用者可以透過識別檔案、生成任務列表並執行並行的非互動式調用來分配工作。

應避免的常見錯誤模式

  • 大雜燴式會話 (The Kitchen Sink Session)：在同一個會話中混合不相關的任務；解決方法是使用 /clear。
  • 過度修正：重複修正同一個錯誤；解決方法是使用更好的提示詞重啟會話。
  • CLAUDE.md 過於冗長：規則過多導致 Claude 忽略指令；解決方法是刪減內容。
  • 信任與驗證間的落差：交付看似合理但未經測試的程式碼；解決方法是要求確定性的驗證。
  • 無限探索：範圍不明確的研究填滿了上下文；解決方法是使用子代理。

Sources

相關