知識極客電子報
Claude Code · · 28 min read

Claude Code：AI 寫程式最佳實作指南【全文翻譯】

原文：https://www.anthropic.com/engineering/claude-code-best-practices

Claude Code 是一個用於代理式編碼 (agentic coding) 的命令列工具。本篇文章涵蓋了在各種程式碼庫、語言和環境中有效使用 Claude Code 的技巧與訣竅。

我們最近 發布了 Claude Code，這是一個用於代理式編碼的命令列工具。作為一個研究專案開發，Claude Code 為 Anthropic 的工程師和研究人員提供了一種更原生的方式，將 Claude 整合到他們的編碼工作流程中。

Claude Code 刻意設計為低階且無固定模式 (low-level and unopinionated)，提供近乎原始的模型存取，而不強加特定的工作流程。這種設計哲學創造了一個靈活、可自訂、可編寫腳本且安全的強大工具。雖然功能強大，但這種靈活性對於剛接觸代理式編碼工具的工程師來說存在一個學習曲線——至少在他們發展出自己的一套最佳實踐之前。

這篇文章概述了一些已被證明有效的通用模式，無論是對於 Anthropic 的內部團隊，還是對於在各種程式碼庫、語言和環境中使用 Claude Code 的外部工程師。此列表中的任何內容都不是一成不變或普遍適用的；請將這些建議視為起點。我們鼓勵您進行實驗，找出最適合您的方法！

想了解更多詳細資訊嗎？我們在 claude.ai/code 的綜合文件中涵蓋了本篇文章提到的所有功能，並提供了額外的範例、實作細節和進階技術。

1. 自訂您的設定

Claude Code 是一個代理式編碼助理，能自動將上下文拉取到提示中。這種上下文收集會消耗時間和 tokens，但您可以透過環境調整來優化它。

a. 建立 CLAUDE.md 檔案

CLAUDE.md 是一個特殊檔案，Claude 在開始對話時會自動將其拉取到上下文中。這使其成為記錄以下內容的理想之處：

CLAUDE.md 檔案沒有固定的格式。我們建議保持其簡潔易讀。例如：

# Bash 指令
- npm run build: 建置專案
- npm run typecheck: 執行型別檢查

# 程式碼風格
- 使用 ES 模組 (import/export) 語法，而非 CommonJS (require)
- 盡可能解構匯入 (例如 import { foo } from 'bar')

# 工作流程
- 在完成一系列程式碼變更後，請務必執行型別檢查
- 為了效能，請優先執行單一測試，而非整個測試套件

您可以將 CLAUDE.md 檔案放置在多個位置：

當您執行 /init 指令時，Claude 會自動為您生成一個 CLAUDE.md。

b. 調整您的 CLAUDE.md 檔案

您的 CLAUDE.md 檔案會成為 Claude 提示的一部分，因此應該像任何頻繁使用的提示一樣進行優化。一個常見的錯誤是添加大量內容卻沒有迭代其有效性。花點時間實驗，確定什麼能從模型中產生最佳的指令遵循效果。

您可以手動將內容添加到您的 CLAUDE.md，或按下 # 鍵給 Claude 一個指令，它會自動將其整合到相關的 CLAUDE.md 中。許多工程師在編碼時頻繁使用 # 來記錄指令、檔案和風格指南，然後將 CLAUDE.md 的變更包含在 commit 中，以便團隊成員也能受益。

在 Anthropic，我們偶爾會將 CLAUDE.md 檔案透過 提示詞優化器 (prompt improver) 處理，並經常調整指令 (例如，用 "IMPORTANT" 或 "YOU MUST" 來強調) 以提高遵循度。

c. 管理 Claude 的允許工具清單

預設情況下，Claude Code 對於任何可能修改您系統的操作都會請求權限：檔案寫入、許多 bash 指令、MCP 工具等。我們以這種刻意保守的方法設計 Claude Code，以安全為優先。您可以自訂允許清單，以允許您知道是安全的額外工具，或允許易於復原的潛在不安全工具 (例如，檔案編輯、git commit)。

有四種方式可以管理允許的工具：

d. 如果使用 GitHub，請安裝 gh CLI

Claude 知道如何使用 gh CLI 與 GitHub 互動，以建立 issue、開啟 pull request、讀取留言等。如果沒有安裝 gh，Claude 仍然可以使用 GitHub API 或 MCP 伺服器 (如果您有安裝的話)。

2. 給 Claude 更多工具

Claude 可以存取您的 shell 環境，您可以在其中為它建立一系列便利的腳本和函數，就像為自己建立一樣。它還可以透過 MCP 和 REST API 利用更複雜的工具。

a. 將 Claude 與 bash 工具一起使用

Claude Code 繼承您的 bash 環境，使其可以存取您所有的工具。雖然 Claude 知道像 unix 工具和 gh 這樣的常用工具，但如果沒有指示，它不會知道您的自訂 bash 工具：

  1. 告訴 Claude 工具名稱並提供使用範例
  2. 告訴 Claude 執行 --help 以查看工具文件
  3. 在 CLAUDE.md 中記錄常用的工具

b. 將 Claude 與 MCP 一起使用

Claude Code 同時作為 MCP 伺服器和客戶端。作為客戶端，它可以透過三種方式連接到任意數量的 MCP 伺服器以存取其工具：

使用 MCP 時，以 --mcp-debug 旗標啟動 Claude 也可能會有幫助，以協助識別設定問題。

c. 使用自訂斜線指令

對於重複的工作流程——偵錯迴圈、日誌分析等——將提示詞模板儲存在 .claude/commands 資料夾內的 Markdown 檔案中。當您輸入 / 時，這些指令將可透過斜線指令選單使用。您可以將這些指令存入 git，以便您的團隊其他成員也能使用。

自訂斜線指令可以包含特殊關鍵字 $ARGUMENTS，以從指令調用中傳遞參數。

例如，這是一個您可以用來自動拉取並修復 Github issue 的斜線指令：

請分析並修復 GitHub issue：$ARGUMENTS。

請遵循以下步驟：

1. 使用 \`gh issue view\` 獲取 issue 詳細資訊
2. 理解 issue 中描述的問題
3. 在程式碼庫中搜尋相關檔案
4. 實作必要的變更以修復問題
5. 編寫並執行測試以驗證修復
6. 確保程式碼通過 linting 和型別檢查
7. 建立一個描述性的 commit 訊息
8. 推送並建立一個 PR

請記得使用 GitHub CLI (\`gh\`) 處理所有與 GitHub 相關的任務。

將以上內容放入 .claude/commands/fix-github-issue.md 使其在 Claude Code 中可用作 /project:fix-github-issue 指令。然後您就可以使用例如 /project:fix-github-issue 1234 來讓 Claude 修復 issue #1234。同樣地，您可以將您自己的個人指令添加到 ~/.claude/commands 資料夾，以便在您所有的工作階段中都可用。

3. 嘗試常見的工作流程

Claude Code 不強加特定的工作流程，讓您可以靈活地以自己想要的方式使用它。在這種靈活性提供的空間內，我們的使用者社群中浮現了幾個成功有效使用 Claude Code 的模式：

a. 探索、規劃、編碼、提交 (Explore, plan, code, commit)

這個多功能的工作流程適用於許多問題：

  1. 要求 Claude 閱讀相關的檔案、圖片或 URL，可以提供一般性的指引 (「閱讀處理日誌的檔案」) 或具體的檔名 (「閱讀 logging.py」)，但要明確告訴它暫時不要編寫任何程式碼。
    1. 這是工作流程中您應該考慮強力使用子代理 (subagents) 的部分，特別是對於複雜問題。告訴 Claude 使用子代理來驗證細節或調查它可能有的特定問題，尤其是在對話或任務的早期，往往可以在不損失太多效率的情況下保留上下文的可用性。
  2. 要求 Claude 制定一個解決特定問題的計劃。我們建議使用「思考 (think)」這個詞來觸發擴展思考模式，這給予 Claude 額外的計算時間來更徹底地評估替代方案。這些特定的詞組直接對應到系統中遞增的思考預算等級：「think」<「think hard」<「think harder」<「ultrathink」。每個等級都分配了逐漸增多的思考預算供 Claude 使用。
    1. 如果這一步的結果看起來合理，您可以讓 Claude 用它的計劃建立一個文件或一個 GitHub issue，這樣如果實作 (步驟 3) 不如您所願，您可以重置到這個點。
  3. 要求 Claude 用程式碼實作其解決方案。這也是一個好時機，要求它在實作方案的各個部分時明確驗證其解決方案的合理性。
  4. 要求 Claude 提交結果並建立一個 pull request。如果相關，這也是讓 Claude 更新任何 READMEs 或 changelogs，並解釋它剛才做了什麼的好時機。

步驟 #1-#2 至關重要——沒有它們，Claude 傾向於直接跳到編寫解決方案的程式碼。雖然有時候這正是您想要的，但對於需要預先進行更深入思考的問題，要求 Claude 先研究和規劃會顯著提高效能。

b. 編寫測試、提交；編碼、迭代、提交 (Write tests, commit; code, iterate, commit)

這是一個 Anthropic 最愛的工作流程，適用於可以透過單元、整合或端對端測試輕鬆驗證的變更。測試驅動開發 (TDD) 在代理式編碼中變得更加強大：

  1. 要求 Claude 根據預期的輸入/輸出對編寫測試。明確指出您正在進行測試驅動開發，這樣它就會避免創建模擬實作，即使對於程式碼庫中尚不存在的功能也是如此。
  2. 告訴 Claude 執行測試並確認它們失敗。在這個階段明確告訴它不要編寫任何實作程式碼通常很有幫助。
  3. 當您對測試滿意時，要求 Claude 提交測試。
  4. 要求 Claude 編寫能通過測試的程式碼，並指示它不要修改測試。告訴 Claude 繼續進行，直到所有測試都通過。Claude 通常需要幾次迭代來編寫程式碼、執行測試、調整程式碼，然後再執行測試。
    1. 在這個階段，要求它使用獨立的子代理來驗證實作沒有對測試過度擬合 (overfitting) 會有所幫助。
  5. 一旦您對變更滿意，就要求 Claude 提交程式碼。

當 Claude 有一個清晰的目標可以迭代時——一個視覺模型、一個測試案例或另一種輸出——它的表現最好。透過提供像測試這樣的預期輸出，Claude 可以進行變更、評估結果，並逐步改進直到成功。

c. 編寫程式碼、截圖結果、迭代 (Write code, screenshot result, iterate)

與測試工作流程類似，您可以為 Claude 提供視覺目標：

  1. 給 Claude 一個擷取瀏覽器螢幕截圖的方法 (例如，使用 Puppeteer MCP 伺服器、一個 iOS 模擬器 MCP 伺服器，或手動複製/貼上螢幕截圖給 Claude)。
  2. 透過複製/貼上或拖放圖片，或給 Claude 圖片檔案路徑來提供視覺模型。
  3. 要求 Claude 用程式碼實作設計，擷取結果的螢幕截圖，並迭代直到其結果與模型相符。
  4. 當您滿意時，要求 Claude 提交。

像人類一樣，Claude 的輸出通常會隨著迭代顯著改善。雖然第一個版本可能不錯，但經過 2-3 次迭代後，它通常看起來會好得多。給 Claude 工具去看見它的輸出，以獲得最佳結果。

d. 安全 YOLO 模式 (Safe YOLO mode)

與其監督 Claude，您可以使用 claude --dangerously-skip-permissions 來繞過所有權限檢查，讓 Claude 不間斷地工作直到完成。這對於修復 lint 錯誤或生成樣板程式碼等工作流程非常有效。

讓 Claude 執行任意指令是危險的，可能導致資料遺失、系統損壞，甚至資料外洩 (例如，透過提示詞注入攻擊)。為了將這些風險降到最低，請在沒有網際網路存取的容器中使用 --dangerously-skip-permissions。您可以遵循這個使用 Docker Dev Containers 的參考實作。

e. 程式碼庫問答 (Codebase Q&A)

在熟悉新的程式碼庫時，使用 Claude Code 進行學習和探索。您可以問 Claude 各種問題，就像您在結對程式設計時會問專案中的另一位工程師一樣。Claude 可以代理式地搜尋程式碼庫以回答一般性問題，例如：

在 Anthropic，以這種方式使用 Claude Code 已成為我們核心的上手工作流程，顯著縮短了熟悉時間並減輕了其他工程師的負擔。不需要特別的提示詞！只需提問，Claude 就會探索程式碼以找到答案。

f. 使用 Claude 與 git 互動

Claude 可以有效地處理許多 git 操作。許多 Anthropic 的工程師使用 Claude 處理 90% 以上的 git 互動：

g. 使用 Claude 與 GitHub 互動

Claude Code 可以管理許多 GitHub 互動：

這消除了記住 gh 命令列語法的需要，同時自動化了例行任務。

h. 使用 Claude 處理 Jupyter notebooks

Anthropic 的研究人員和資料科學家使用 Claude Code 來讀取和寫入 Jupyter notebooks。Claude 可以解釋輸出，包括圖片，提供了一種快速探索和與資料互動的方式。沒有必須的提示詞或工作流程，但我們推薦的一個工作流程是在 VS Code 中並排開啟 Claude Code 和一個 .ipynb 檔案。

您也可以要求 Claude 在將 Jupyter notebook 展示給同事之前對其進行清理或美化。明確告訴它要讓 notebook 或其資料視覺化「美觀 (aesthetically pleasing)」通常有助於提醒它正在為人類的觀看體驗進行優化。

4. 優化您的工作流程

以下建議適用於所有工作流程：

a. 在指令中要具體

Claude Code 的成功率會隨著更具體的指令而顯著提高，尤其是在初次嘗試時。預先給出清晰的方向可以減少之後修正路線的需要。

例如：

不佳的指令良好的指令
為 foo.py 增加測試為 foo.py 寫一個新的測試案例，涵蓋使用者登出時的邊界情況。避免使用 mocks。
為什麼 ExecutionFactory 的 api 這麼奇怪？翻閱 ExecutionFactory 的 git 歷史，並總結其 api 是如何演變的。
增加一個日曆小工具查看首頁上現有小工具是如何實作的，以理解其模式，特別是程式碼和介面是如何分離的。HotDogWidget.php 是一個很好的起始範例。然後，遵循該模式實作一個新的日曆小工具，讓使用者可以選擇月份並向前/向後翻頁來選擇年份。除了程式碼庫中已使用的函式庫外，不要使用其他函式庫，從頭開始建置。

Claude 可以推斷意圖，但它無法讀心。具體性能帶來更符合期望的結果。

b. 給 Claude 圖片

Claude 能透過多種方式出色地處理圖片和圖表：

這在處理設計模型作為 UI 開發的參考點，以及視覺圖表用於分析和偵錯時特別有用。如果您沒有在上下文中加入視覺資料，向 Claude 明確表示結果的視覺吸引力有多重要仍然會有幫助。

c. 提及您希望 Claude 查看或處理的檔案

使用 tab 鍵自動完成功能來快速引用您 repo 中任何地方的檔案或資料夾，幫助 Claude 找到或更新正確的資源。

d. 給 Claude URL

將特定的 URL 與您的提示詞一起貼上，讓 Claude 抓取和閱讀。為避免對相同網域 (例如 docs.foo.com) 的權限提示，請使用 /permissions 將網域添加到您的允許清單中。

e. 及早且頻繁地修正路線

雖然自動接受模式 (按 shift+tab 切換) 讓 Claude 能自主工作，但您通常會透過作為一個積極的協作者並引導 Claude 的方法來獲得更好的結果。您可以透過在開始時向 Claude 徹底解釋任務來獲得最佳結果，但您也可以隨時修正 Claude 的路線。

這四個工具有助於修正路線：

儘管 Claude Code 偶爾能在第一次嘗試時完美解決問題，但使用這些修正工具通常能更快地產生更好的解決方案。

f. 使用 /clear 保持上下文的專注

在長時間的工作階段中，Claude 的上下文視窗可能會充滿不相關的對話、檔案內容和指令。這會降低效能，有時還會分散 Claude 的注意力。在任務之間頻繁使用 /clear 指令來重置上下文視窗。

g. 對於複雜的工作流程使用檢查清單和草稿板

對於具有多個步驟或需要詳盡解決方案的大型任務——如程式碼遷移、修復大量 lint 錯誤或執行複雜的建置腳本——可以透過讓 Claude 使用一個 Markdown 檔案 (甚至是一個 GitHub issue！) 作為檢查清單和工作草稿板來提高效能：

例如，要修復大量的 lint 問題，您可以這樣做：

  1. 告訴 Claude 執行 lint 指令 並將所有產生的錯誤 (包含檔名和行號) 寫入一個 Markdown 檢查清單中
  2. 指示 Claude 逐一處理每個問題，在修復和驗證後將其勾選掉，然後再處理下一個

h. 將資料傳遞給 Claude

有幾種方法可以為 Claude 提供資料：

大多數工作階段都涉及這些方法的組合。例如，您可以透過管道傳入一個日誌檔案，然後告訴 Claude 使用工具來拉取額外的上下文以偵錯該日誌。

5. 使用無頭模式 (headless mode) 來自動化您的基礎設施

Claude Code 包含 無頭模式 (headless mode)，適用於非互動式情境，如 CI、pre-commit hooks、建置腳本和自動化。使用 -p 旗標和一個提示詞來啟用無頭模式，並使用 --output-format stream-json 進行串流式 JSON 輸出。

請注意，無頭模式在工作階段之間不會持續。您必須在每個工作階段中觸發它。

a. 使用 Claude 進行 issue 分流

無頭模式可以驅動由 GitHub 事件觸發的自動化，例如當您的 repo 中創建了一個新 issue 時。例如，公開的 Claude Code repo 使用 Claude 來檢查新進的 issues 並分配適當的標籤。

b. 使用 Claude 作為 linter

Claude Code 可以提供主觀的程式碼審查，超越傳統 linting 工具所能檢測的範圍，識別諸如拼寫錯誤、過時的註解、誤導性的函數或變數名稱等問題。

6. 透過多個 Claude 的工作流程來提升層次

除了獨立使用之外，一些最強大的應用涉及並行運行多個 Claude 實例：

a. 讓一個 Claude 編寫程式碼；用另一個 Claude 來驗證

一個簡單但有效的方法是讓一個 Claude 編寫程式碼，而另一個來審查或測試它。與多位工程師合作類似，有時分離的上下文是有益的：

  1. 使用 Claude 編寫程式碼
  2. 執行 /clear 或在另一個終端機中啟動第二個 Claude
  3. 讓第二個 Claude 審查第一個 Claude 的工作
  4. 啟動另一個 Claude (或再次 /clear) 來閱讀程式碼和審查回饋
  5. 讓這個 Claude 根據回饋編輯程式碼

您也可以用測試做類似的事情：讓一個 Claude 編寫測試，然後讓另一個 Claude 編寫程式碼以使測試通過。您甚至可以讓您的 Claude 實例透過給它們各自的工作草稿板並告訴它們寫入哪個、讀取哪個來進行交流。

這種分離通常比讓單一 Claude 處理所有事情產生更好的結果。

b. 擁有多個 repo 的 checkout

與其等待 Claude 完成每一步，許多 Anthropic 的工程師會這樣做：

  1. 在不同的資料夾中建立 3-4 個 git checkout
  2. 在不同的終端機分頁中打開每個資料夾
  3. 在每個資料夾中啟動 Claude，並分配不同的任務
  4. 循環切換以檢查進度並批准/拒絕權限請求

c. 使用 git worktrees

這種方法在處理多個獨立任務時表現出色，提供了一種比多個 checkout 更輕量的替代方案。Git worktrees 允許您將同一個 repo 的多個分支 checkout 到不同的目錄中。每個 worktree 都有自己獨立的工作目錄和檔案，同時共享相同的 Git 歷史和 reflog。

使用 git worktrees 使您能夠在專案的不同部分同時運行多個 Claude 工作階段，每個都專注於自己的獨立任務。例如，您可能讓一個 Claude 重構您的身份驗證系統，而另一個則建置一個完全不相關的資料視覺化元件。由於任務不重疊，每個 Claude 都可以全速工作，而無需等待對方的變更或處理合併衝突：

  1. 建立 worktrees：git worktree add ../project-feature-a feature-a
  2. 在每個 worktree 中啟動 Claude：cd ../project-feature-a && claude
  3. 視需要建立額外的 worktrees (在新的終端機分頁中重複步驟 1-2)

一些技巧：

d. 將無頭模式與自訂框架結合使用

claude -p (無頭模式) 將 Claude Code 以程式化的方式整合到更大的工作流程中，同時利用其內建的工具和系統提示詞。使用無頭模式主要有兩種模式：

  1. 扇出 (Fanning out) 處理大規模的遷移或分析 (例如，分析數百條日誌的情感或分析數千個 CSV)：
    1. 讓 Claude 編寫一個腳本來生成任務列表。例如，生成一個需要從框架 A 遷移到框架 B 的 2000 個檔案的列表。
    2. 遍歷任務，為每個任務以程式化的方式呼叫 Claude，並給予它一個任務和一組它可以使用的工具。例如：claude -p “將 foo.py 從 React 遷移到 Vue。完成後，如果成功，你必須返回字串 OK，如果任務失敗，則返回 FAIL。” --allowedTools Edit Bash(git commit:*)
    3. 多次運行該腳本並優化您的提示詞以獲得期望的結果。
  2. 管線化 (Pipelining) 將 Claude 整合到現有的資料/處理管線中：
    1. 呼叫 claude -p “<你的提示詞>” --json | your_command，其中 your_command 是您處理管線的下一步。
    2. 就是這樣！JSON 輸出 (可選) 可以幫助提供結構，以便於自動化處理。

對於這兩種用例，使用 --verbose 旗標進行 Claude 調用的偵錯會很有幫助。我們通常建議在生產環境中關閉詳細模式以獲得更乾淨的輸出。

您對於使用 Claude Code 有什麼技巧和最佳實踐嗎？標記 @AnthropicAI，讓我們看看您正在打造什麼！

致謝

由 Boris Cherny 撰寫。這項工作汲取了廣大 Claude Code 使用者社群的最佳實踐，他們富有創意的用法和工作流程持續啟發著我們。同時特別感謝 Daisy Hollman、Ashwin Bhat、Cat Wu、Sid Bidasaria、Cal Rueb、Nodir Turakulov、Barry Zhang、Drew Hodun 以及許多其他 Anthropic 工程師，他們對 Claude Code 的寶貴見解和實踐經驗幫助塑造了這些建議。

Share Share Share Share Share Email

Read next