Anthropic 發布 Claude Code 實戰指南：從精通到自動化的代理式編碼新典範
1. 導言：揭示代理式編碼的未來
Anthropic 近日正式推出了 Claude Code，一款專為工程師與研究人員設計的代理式編碼（agentic coding）命令列工具，旨在將 Claude 的強大能力更原生、更無縫地融入開發者的日常工作流程。本篇指南的發布，不僅僅是一份功能說明書，更是 Anthropic 內部團隊與廣大外部工程師在多樣化開發環境中，歷經反覆實踐與驗證後所提煉出的最佳實踐結晶。其核心目標，是幫助開發者駕馭 Claude Code 的靈活性與強大潛能，將其從一個工具轉化為開發流程中不可或缺的智能夥伴。
Claude Code 的設計哲學刻意追求「低階」與「無固定意見」（unopinionated）。它不強加任何特定的工作流程，而是提供近乎原始模型的存取能力。這種設計賦予了開發者最大的靈活性、高度的可客製化與可編程性，同時內建了周全的安全性考量，使其成為一把真正的開發「瑞士刀」。
本指南將全面涵蓋從基礎的環境設定、能力擴充，到核心工作流程的實踐模式，乃至最終實現自動化與多重代理協作的進階技巧，引領您一步步釋放代理式編碼的全部潛力。
2. 基礎奠基：打造個人化的開發神經中樞
高效使用 Claude Code 的第一步，是建立一個優化的個人化設定。由於 Claude Code 會自動抓取上下文資訊，這項操作會消耗時間與 tokens。因此，一個精心調校的環境不僅能提升效率，更能確保 Claude 的每一次互動都建立在最精準的資訊基礎之上，這對於打造一個反應迅速、理解深刻的開發神經中樞至關重要。
以下是客製化設定的四個核心方法：
• CLAUDE.md 的妙用： CLAUDE.md 是一個特殊的檔案，Claude Code 在啟動對話時會自動將其內容載入上下文。這使其成為記錄專案特定知識的理想場所，例如：常用指令、程式碼風格、測試指南、版本控制慣例等。您可以執行 /init 指令，讓 Claude 自動為您產生一份 CLAUDE.md 檔案。
• 此檔案的放置位置決定了其作用範圍：可位於專案根目錄（團隊共享）、父/子目錄（適用於 monorepos），或家目錄（~/.claude/CLAUDE.md）以應用於所有會話。若想儲存不應納入版控的個人設定，可使用 CLAUDE.local.md 並將其加入 .gitignore。
• 調校 CLAUDE.md： 請將 CLAUDE.md 視為一個需要持續迭代的提示詞（prompt）。僅僅堆砌大量資訊是常見的錯誤。開發者應花時間實驗，觀察哪些內容能讓模型產生最佳的指令遵循效果。Anthropic 內部甚至會使用提示詞改進器來優化其內容，或透過添加 "IMPORTANT"、"YOU MUST" 等關鍵字來強調指令。一個實用的技巧是，在會話中隨時按下 # 鍵，Claude 就會自動將您剛才的指令添加到 CLAUDE.md 中，方便您即時記錄。
• 管理工具白名單： Claude Code 預設採取保守的安全策略，對於任何可能修改系統的行為都會請求權限。您可以透過以下四種方式管理工具白名單，以平衡安全性與便利性：
|
方法 |
操作方式 |
適用情境 |
|
會話中授權 |
在收到權限請求時選擇 "Always allow" |
針對單一會話中的常用工具進行臨時授權。 |
|
指令管理 |
使用 /permissions 指令新增或移除工具 |
在會話開始後，動態調整權限設定，例如 Edit 或 Bash(git commit:*)。 |
|
檔案配置 |
手動編輯 .claude/settings.json 或 ~/.claude.json |
建立可納入版控的團隊共享配置，或個人全域設定。 |
|
CLI 旗標 |
使用 --allowedTools 旗標 |
針對特定會話，臨時賦予一次性的權限。 |
• 整合 gh CLI： 如果您的開發流程深度依賴 GitHub，強烈建議安裝官方的 gh 命令列工具。Claude Code 能夠熟練地使用 gh 來執行創建議題、發起拉取請求等操作。若未安裝 gh，Claude 也有備用方案，可透過 GitHub API 或 MCP 伺服器來完成任務。
完成這些基礎設定後，您已為 Claude Code 建立了一個堅實的基礎。下一步，便是透過擴充工具集，進一步增強其解決複雜問題的能力。
3. 能力擴展：賦予 Claude 更強大的工具集
Claude Code 的真正強大之處在於其能無縫繼承並利用開發者的既有環境。它不僅僅是一個孤立的對話模型，更是一個能與您現有工具鏈深度整合的智能代理。本章節將探討如何讓 Claude 掌握從簡單的自訂腳本到複雜 API 的各式工具，將其打造成一個能力更全面的開發夥伴。
整合 Bash 工具
Claude Code 能直接存取您 shell 環境中的所有工具。雖然它天生了解 git 等常用工具，但對於您自訂的 Bash 工具，則需要一些引導。讓 Claude 學會使用這些工具的步驟非常簡單：
1. 告知工具與範例： 直接告訴 Claude 工具的名稱，並提供一個具體的使用範例。
2. 讓其閱讀說明文件： 指示 Claude 執行該工具的 --help 指令，讓它自行學習用法與參數。
3. 記錄於 CLAUDE.md： 對於頻繁使用的工具，將其名稱與用法記錄在 CLAUDE.md 檔案中，確保 Claude 在每次對話開始時都能記住它。
運用 MCP (Model Context Protocol)
Claude Code 可作為一個 MCP 客戶端，連接至任意數量的 MCP 伺服器以獲取更多工具。配置 MCP 伺服器主要有三種方式：專案配置、全域配置、或透過一個可納入版控的 .mcp.json 檔案。後者是團隊協作的最佳方式，可確保所有成員都能開箱即用地使用如 Puppeteer（瀏覽器自動化）等共享工具。在進行 MCP 設定時，使用 --mcp-debug 旗標有助於快速診斷配置問題。
建立自訂斜線指令
對於重複性的工作流程，您可以建立自訂的斜線指令（slash commands）來將其模板化。只需在專案的 .claude/commands 資料夾（團隊共享）或您家目錄的 ~/.claude/commands（個人全域）中建立 Markdown 檔案即可。這些指令支援 $ARGUMENTS 關鍵字，允許您在調用時傳遞參數。
請分析並修復 GitHub issue: $ARGUMENTS。請遵循以下步驟：
1. 使用 gh issue view 取得議題詳情
2. 理解議題中描述的問題
3. 在程式碼庫中搜尋相關檔案
4. 實作必要的變更以修復問題
5. 撰寫並執行測試以驗證修復
6. 確保程式碼通過 linting 與型別檢查
7. 撰寫描述性的提交訊息
8. 推送並建立一個 PR
請記得使用 GitHub CLI (gh) 處理所有 GitHub 相關任務。
將上述內容存為 fix-github-issue.md 後，您便可使用 /project:fix-github-issue 1234 指令，讓 Claude 自動化處理修復 GitHub issue #1234 的完整流程。
掌握了工具擴充的方法後，真正的效率提升來自於將這些強大的能力應用於結構化的工作流程中。
4. 核心工作流程：高效能的實踐模式
Claude Code 的靈活性允許開發者自訂工作流程。然而，在無限的可能性中，Anthropic 的用戶社群已經探索出幾種極為成功的通用模式。這些模式不僅能顯著提升解決問題的品質，更能大幅提高開發效率。
探索、規劃、編碼、提交
這是適用性最廣的模式，幾乎能應對所有類型的開發任務。
1. 探索 (Explore)： 要求 Claude 閱讀相關檔案，但明確指示它「先不要寫任何程式碼」。此階段可搭配子代理（subagent）進行驗證，以保留主要上下文的清晰度。
2. 規劃 (Plan)： 這是最關鍵的一步。要求 Claude 制定計畫，並使用特定關鍵詞觸發其擴展思考模式。系統會根據 "think" < "think hard" < "think harder" < "ultrathink" 的層級，分配遞增的計算資源，讓 Claude 進行更周詳的方案評估。一個好的實踐是將確認後的計畫建立成一個 GitHub issue，以便追蹤。
3. 編碼 (Code)： 在您確認計畫可行後，再指示 Claude 根據計畫實作程式碼。
4. 提交 (Commit)： 最後，讓 Claude 提交程式碼、建立拉取請求，甚至更新相關的 README 文件。
測試驅動開發 (TDD)
代理式編碼與測試驅動開發 (TDD) 可謂天作之合。為 Claude 設定一個明確、可驗證的目標（通過所有測試），能使其迭代過程極其高效。
1. 編寫測試： 要求 Claude 根據預期行為編寫測試。
2. 確認失敗： 指示 Claude 執行測試並確認它們如預期般失敗。
3. 提交測試： 當您對測試案例滿意時，讓 Claude 提交這些測試。
4. 編寫程式碼： 要求 Claude 編寫能「通過所有測試」的程式碼。在這個階段，可以指示 Claude 使用獨立的子代理來驗證實作，避免其過度擬合（overfitting）測試案例。
5. 提交程式碼： 一旦所有測試通過，即可提交實作程式碼。
視覺驅動迭代
對於 UI 開發等視覺導向的任務，提供視覺回饋是指導 Claude 的最直觀方式。您可以透過貼上截圖、拖放圖片或提供檔案路徑來展示期望的最終效果，然後讓 Claude 反覆迭代，直到其產出與視覺目標匹配。
程式碼庫問答 (Codebase Q&A)
這是幫助團隊新人快速熟悉陌生程式碼庫的強大利器。您可以像與資深同事結對編程一樣，向 Claude 提出各種問題，它會自動搜尋並分析程式碼來提供答案。
• 「這個專案的日誌系統是如何運作的？」
• 「foo.rs 第 134 行的 async move { ... } 是什麼作用？」
• 「我要如何新增一個 API 端點？」
• 「為什麼第 333 行是呼叫 foo() 而不是 bar()？」
這種用法已成為 Anthropic 內部的核心 onboarding 流程，有效降低了團隊的溝通成本。
Git 與 GitHub 互動
許多 Anthropic 工程師超過 90% 的 Git 互動都交由 Claude 處理，包括：
• 搜尋 git 歷史來回答「這個 API 當初為什麼這樣設計？」等問題。
• 根據程式碼變更自動撰寫高品質的提交訊息。
• 處理複雜的 Git 操作，如還原檔案、解決 rebase 衝突。
• 自動化 GitHub 流程，例如根據 PR 中的審查評論直接進行修改並推送。
掌握了這些核心模式後，您還可以透過一些通用的互動技巧，進一步優化與 Claude 的協作。
5. 互動優化：從指令到結果的精準對齊
無論您採用何種工作流程，一些通用的優化技巧都能顯著提升 Claude Code 的表現。與其將 Claude 視為一個指令執行者，不如將其看作一個需要清晰溝通與有效過程管理的協作者。
• 指令要具體： 模糊的指令會導致模糊的結果。提供更具體的上下文與約束，能大幅提高首次嘗試的成功率。
|
差的指令 |
好的指令 |
|
為 foo.py 新增測試。 |
為 foo.py 撰寫一個新的測試案例，要涵蓋使用者未登入的邊界情況，並且不要使用 mocks。 |
|
為什麼 ExecutionFactory 的 API 這麼奇怪？ |
查閱 ExecutionFactory 的 git 歷史，總結其 API 是如何演變至今的。 |
|
新增一個日曆小工具。 |
參考 HotDogWidget.php 的實作模式，特別是程式碼與介面分離的方式。然後，遵循該模式實作一個新的日曆小工具，讓使用者可以選擇月份，並能向前/向後翻頁選擇年份。請從頭構建，不要引入 codebase 中尚未使用的第三方函式庫。 |
• 善用視覺資訊： 一張圖勝過千言萬語。您可以透過貼上截圖、拖放圖片或提供檔案路徑為 Claude 提供視覺上下文，這在 UI 開發和數據分析中尤其有效。
• 提及檔案時使用 tab 鍵自動完成： 在指令中提及檔案或資料夾時，善用 tab 鍵自動完成路徑。這能幫助 Claude 快速、準確地定位您想要操作的資源。
• 提供 URL 給 Claude： 直接將 URL 貼到提示詞中，Claude 就能獲取並閱讀其內容。若需頻繁存取特定網域（如內部文件），可使用 /permissions 將其加入白名單，避免重複的權限請求。
• 及早且頻繁地修正路線： 主動引導通常能更快獲得理想結果。以下是四個實用的修正工具：
1. 要求制定計畫： 在動手編碼前，先要求 Claude 提出計畫。
2. Escape 中斷： 按 Escape 鍵可隨時中斷 Claude 的當前操作。
3. 雙擊 Escape 編輯歷史： 連按兩次 Escape 鍵可以回到歷史記錄，編輯之前的提示詞。
4. 要求復原： 指示 Claude 撤銷剛才的變更。
• 使用 /clear 保持上下文清晰： 在不同任務之間頻繁使用 /clear 指令，以重置上下文，避免無關資訊干擾 Claude 的判斷。
• 利用清單與暫存區處理複雜任務： 對於大型任務（如程式碼遷移、修復大量 lint 錯誤），指示 Claude 使用一個 Markdown 檔案作為工作用的檢查清單（checklist）和暫存區（scratchpad），能顯著提高執行的可靠性。
• 將資料傳遞給 Claude： 有多種方式可以為 Claude 提供資料，最常見的是直接複製貼上。對於日誌、CSV 等大型資料，使用管道（pipe）傳遞更為高效，例如：cat foo.txt | claude。
當您掌握了與單一 Claude 實例的互動優化後，真正的生產力飛躍將來自於更進階的多實例協作與自動化應用。
6. 進階應用：自動化與多重代理協作
除了互動式使用，Claude Code 的 Headless 模式和多實例工作流程為高階用戶開啟了全新的可能性。透過將 Claude 整合到您的自動化基礎設施中，您可以將其能力從開發輔助提升到驅動整個工程系統的智能引擎。
Headless 模式與基礎設施自動化
Headless 模式（透過 -p "<prompt>" 旗標啟用）允許 Claude Code 在非互動式環境中執行，例如 CI/CD 流程或 pre-commit hooks。搭配 --output-format stream-json 旗標，更能方便地進行程式化整合。
• 議題分類 (Issue Triage)： 設定由 GitHub 事件觸發的自動化流程，調用 Headless Claude 來分析新 issue 並為其打上合適的標籤。
• 作為 Linter： Claude 能提供超越傳統工具的主觀程式碼審查，找出拼寫錯誤、過時的註解或具有誤導性的變數命名等問題。
多重 Claude 工作流程的威力
同時運行多個 Claude 實例，讓它們以不同角色協作，是另一種強大的進階用法。
• 一個寫碼，一個驗證： 讓一個 Claude 實例負責編寫程式碼，然後啟動另一個獨立實例來審查或測試。分離的上下文有助於避免單一模型產生思維盲點。您甚至可以讓不同實例透過各自的暫存盤檔案（scratchpads）進行溝通，一個負責寫入，另一個負責讀取。
• 使用多個 git checkouts 或 worktrees： 為了實現任務的並行處理，git worktree 是比多個完整 checkouts 更輕量的選擇。您可以為不同任務建立獨立的 worktree，並在其中分別啟動 Claude 實例。一些實用技巧包括：使用一致的命名慣例、為每個 worktree 維護獨立的終端分頁與 IDE 視窗、在 iTerm2 中設定通知，以及在任務完成後及時清理 worktree。
• 使用 headless 模式與自訂工具鏈： 將 Headless 模式與腳本結合，可以構建出複雜的自動化工具鏈。主要有兩種模式：
1. 分發 (Fanning out)： 適用於大規模並行任務。您可以先用一個腳本生成任務清單，然後循環調用 Headless Claude 處理每個任務。例如：claude -p “migrate foo.py from React to Vue. ...” --allowedTools Edit Bash(git commit:*)。
2. 管道 (Pipelining)： 將 Claude 作為數據處理管道中的一個環節。例如，將前一個步驟的輸出透過管道傳遞給 Claude，再將其 JSON 格式的輸出傳遞給下一個命令：claude -p “<your prompt>” --json | your_command。
• 在開發這些自動化流程時，使用 --verbose 旗標有助於調試。
Claude Code 是一個充滿潛力的強大工具，本指南所提供的僅僅是探索的起點。Anthropic 鼓勵廣大的開發者社群動手實驗，發掘更多創新的工作流程，並分享彼此的最佳實踐，共同塑造代理式編碼的未來。
--------------------------------------------------------------------------------
資料來源
• Anthropic. (2025, April 18). Claude Code: Best practices for agentic coding. Anthropic News.
