本篇使用 AI 翻譯濃縮原文，筆者人工校稿完成！
本篇適合正開始準備使用 Claude Code、甚至在觀望的你，官方針對這個工具 Highlight 的幾個重點！如果你還在猶豫，可以先看我的心得！
原始文章：Claude Code: Best practices for agentic coding
原始文章如下：
Claude Code 是一個用於 agentic coding 的命令列工具。本文整理了 Anthropic 官方經實務驗證的技巧與建議，協助開發者更有效地在不同的程式碼庫、語言與環境中使用 Claude Code。
此外，本文也歸納了 Anthropic 內部及外部使用 Claude Code 的有效模式與方法。這些建議並非放諸四海皆準，而是鼓勵大家將其視為起點，透過不斷嘗試找出最適合自己的方式。
還沒安裝 Claude Code 嗎？快來安裝：https://docs.anthropic.com/en/docs/claude-code/overview
一、自訂初始設定
1.建立 CLAUDE.md
真正生成 Claude.md：
> /init
CLAUDE.md 是 Claude 在啟動對話時會自動讀取的說明檔，非常適合用來紀錄專案相關的關鍵資訊，例如常用指令、核心檔案與工具函式、程式碼風格...，此檔案不限定格式，但要簡潔易讀！
功用條列如下：
- 常用的 bash 指令
- 核心文件與函式
- 程式碼風格指南
- 測試指令
- 專案的開發規範（分支命名規則等）
- 開發環境設定
- 專案中特殊的行為或警告
通常都放在專案根目錄，但也可以放在像是~/.claude/CLAUDE.md 等位置。
常用放置位置：
- 專案根目錄（通常放此）
- 父目錄（適合 monorepo）
- 子目錄（依需求引入）
- 家目錄 (~/.claude/CLAUDE.md)
Anthropic 團隊強調， CLAUDE.md 會成為 Claude Prompt 的一部分，因此它的內容品質會直接影響 Claude 回應的精準度。建議定期檢視與優化這份檔案，而不是單純塞入大量內容。
也因此，除了手動更新，也可透過輸入 # 開頭的指令，讓 Claude 自動新增內容到 CLAUDE.md。許多工程師習慣在寫程式過程中同步更新這份說明，並一併納入 commit 中，讓整個團隊都受益。Anthropic 團隊也會用 Claude 的 prompt 改寫工具來優化 CLAUDE.md，甚至透過加強語氣（例如加入「IMPORTANT」「YOU MUST」）來提升指令遵守程度。
2.Claude Code 需要一些工具整合，需優先設定
Claude Code 預設採取保守策略，對所有可能改動系統的操作（如編輯檔案、執行 bash 指令或呼叫 MCP 工具）都會要求使用者明確允許。
你可以透過幾種方式自訂允許清單，例如：在提示時選擇「Always allow」、使用 /permissions 指令新增允許項目、手動編輯 .claude/settings.json 或使用 --allowedTools CLI 參數。
如果你的專案與 GitHub 整合，建議安裝 GitHub CLI（gh）。Claude 可透過它建立 issue、提交 pull request、讀取評論等操作。若未安裝 gh，Claude 仍可改用 GitHub API 或 MCP server 進行互動。
二、給予 Claude Code 更多工具，讓 AI 變成你的得力助手！
使用 Bash
Claude 不僅能存取你的 shell 環境，也能像人類工程師一樣使用你常用的工具與腳本。它可以善用 bash 指令、自訂工具、REST API，甚至更進階的 MCP 工具系統。若希望 Claude 發揮最大效能，建議在 CLAUDE.md 中補充工具的使用方式，或直接請它執行 --help 查閱說明（摘自 2a）。
使用 MCP
此外，Claude 同時支援作為 MCP server 與 client。你可以透過專案設定、全域設定，或在 repo 中建立 .mcp.json 文件來連接不同 MCP server，讓整個團隊共享像是 Puppeteer 或 Sentry 等自訂工具（摘自 2b）。
使用自定義 / 指令
Claude Code 可以自訂 slash / 指令！
若你的開發流程常常重複某些提示需求，也能將這些提示封裝成 markdown 檔，放進 .claude/commands 目錄中，成為自訂的斜線指令（slash command）。
舉例來說，你可以建立一個 /fix-github-issue 指令，讓 Claude 自動拉取特定 issue、分析錯誤、修改程式並建立 PR。
以下範例：
Please analyze and fix the GitHub issue: $ARGUMENTS.
Follow these steps:
1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR
Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.
- 自訂斜線指令可以包含特殊關鍵字
$ARGUMENTS來傳遞指令呼叫的參數。 - 將上述內容放入
.claude/commands/fix-github-issue.md中，即可在 Claude Code 中將其用作/project:fix-github-issue指令。 - 例如，您可以使用
/project:fix-github-issue 1234讓 Claude 修復問題 #1234。同樣，您可以將自己的個人命令新增至~/.claude/commands資料夾中，以便在所有會話中使用這些命令。
- 例如，您可以使用
三、嘗試常見的工作流程
Anthropic 社群與內部團隊已逐步發展出幾種高效的使用模式：
1.先規劃：探索 → 規劃 → 撰寫程式 → 提交
- 請 Claude 閱讀相關的檔案、截圖或網址。
- 可以是抽象提示（如「讀一下 logging 的處理邏輯」），也可以明確指出檔名（如「logging.py」）。
- 但明確告訴它現在不要編寫任何程式碼。
- 若問題較複雜，可善用 Claude 的 subagent 功能，將子任務分派出去調查或驗證特定細節。
- 請 Claude 撰寫解決方案規劃，並使用「think」「think harder」等指令進入延伸思考模式。（官方表示： "think" < "think hard" < "think harder" < "ultrathink." 每個級別都會逐步為 Claude 分配更多推理 token 花費。）
- 完成規劃後，要求 Claude 在程式碼中實現其解決方案 。
- 完成後提交程式碼並建立 PR，並請它補充 README、changelog 等說明文件。
編按：subagent 使用可參考此，「use subagent to perform code review, pay attention to ....」步驟 1~2 「探索、規劃」至關重要——如果沒有這些步驟，Claude 往往會直接開始編寫解決方案。雖然有時你希望這樣做，但讓 Claude 先進行研究和規劃，可以顯著提高需要深入思考的問題的效率。
2.測試先行：測試，提交（迭代）
這是 Anthropic 最喜歡的工作流程
透過單元測試、整合測試或端到端測試輕鬆驗證的變更。
- 請 Claude 根據預期的輸入與輸出組合撰寫測試案例。要特別強調這是進行 test-driven development（TDD），以避免 Claude 產生虛構的 mock 實作，即使是尚未存在於程式碼中的功能也一樣。
- 執行測試並確認其失敗。這階段非常關鍵，務必明確告訴 Claude 暫時不要撰寫任何實作程式碼，只需確認測試尚未通過。
- 當你對測試內容感到滿意後，請 Claude 將測試提交。
- 要求 Claude 撰寫實作程式碼，目標是讓剛剛的測試通過。請明確要求它不要修改測試本身，並持續迭代直到所有測試都成功。通常 Claude 會進行數輪修正程式碼、執行測試、再修正的循環。
- 在這個階段，也可考慮請另一個 Claude（subagent）獨立檢查是否出現過擬合情況，確認其實作沒有僅針對測試資料做出特化解。
- 當你對實作結果滿意後，請 Claude 提交正式程式碼。
這種流程在 Claude 擁有明確對照標的時效果最佳，例如 UI mockup、測試案例、或明確輸出格式等。
編按：可能是程式開發經驗不多，但這樣用AI的方式我覺得很酷！
3.寫程式 -> 截圖（迭代）
與上述第二方法雷同，只是提供 Claude Code 更多視覺參考（可使用截圖、MCP 等工具輔佐）。
4.安全 YOLO 模式（Safe YOLO mode）
如果你想讓 Claude 自動完成整個任務、不被中斷，也可以使用 --dangerously-skip-permissions 參數跳過所有許可確認流程。這個模式特別適合處理像是自動修復 lint 錯誤、產生樣板程式碼（boilerplate code）等重複性高、風險較低的任務。
不過，讓 Claude 自由執行任意指令也伴隨風險，包括資料遺失、系統損壞，甚至可能因提示注入攻擊（prompt injection）而造成機密外洩。
因此，若要使用 YOLO 模式，建議務必將 Claude 限制在無網路的容器中執行，例如搭配 Docker Dev Container，最大程度降低風險。
5.Codebase Q&A
當你剛接手一個新專案時，Claude Code 可以成為你的最佳導覽員。你可以把它當作一位熟悉此程式的同事，問出所有你在 pair programming 時會提的問題。例如：
- Logging 機制是怎麼設計的？
- 要怎麼新增一個 API endpoint？
async move { ... }在foo.rs第 134 行做了什麼？CustomerOnboardingFlowImpl處理了哪些.....？- 第 333 行為什麼是呼叫
foo()而不是bar()？ baz.py第 334 行在 Java 中會怎麼寫？
Anthropic 團隊將 Claude 的這種使用方式作為工程師熟悉新專案的標準流程，它不僅大幅縮短上手時間，也減輕了資深同仁的協助負擔。你無需任何特殊提示，只要直接問，Claude 就會自主在程式碼中尋找答案。
6.Git 操作輔助
Anthropic 工程師有超過 90% 的 Git 任務都是透過 Claude 完成的，包含：
- 查詢 Git 歷史：如「哪些變更被納入 v1.2.3？」「這段功能是誰維護的？」「這個 API 為什麼是這樣設計？」等等。
- 撰寫 commit message：Claude 會自動分析你修改的內容與上下文，產出精確且具描述性的訊息。
- 處理進階 Git 操作：如還原特定檔案、解決 rebase 衝突、比對與移植 patch 等操作。
在與 GitHub 整合的場景中，Claude 也能處理多數常見操作，包括：
- 建立 PR：Claude 能理解
pr這類縮寫，並根據差異與上下文撰寫合適的 commit message。 - 一鍵解決 review 留言：你只需告訴 Claude 修正評論，它會修改後直接推回對應的 PR 分支。
- 協助處理建置失敗、Linter 警告。
- 分類與標註 open issues：你可要求 Claude 逐一檢視並標記 GitHub issues，節省 triage 時間。
這些功能能有效降低你記憶 CLI 指令的負擔，並加速日常協作。
7.Jupyter Notebook 協作
Anthropic 的研究人員與資料科學家也廣泛使用 Claude 協助閱讀與編輯 Jupyter Notebook。Claude 不僅能理解 notebook 內容，也能解析其中的圖片輸出，提供快速的互動體驗。
建議你在 VS Code 中同時開啟 Claude Code 與 .ipynb 檔案，讓 Claude 能針對內容直接給出分析與建議。你也可以請它幫忙整理 notebook 格式、調整視覺呈現，讓輸出更適合對外展示。尤其是明確說明希望結果「美觀一點」，能幫助 Claude 更聚焦於人類閱讀體驗。
優化工作流程
想要讓 Claude 發揮最佳效能，使用者本身的指令與上下文給法也很重要。以下是幾個經過驗證的優化技巧：
說得越清楚越好
Claude 的成功率會隨著指令具體程度而提升，特別是在第一次嘗試時。清楚說明需求，能減少後續反覆修正的時間。
Claude 雖然能理解語意，但並不能讀心。越具體的指令，越能讓結果符合你的預期。
給 Claude 看圖 Claude 對圖片與圖表的理解能力很強
- macOS 使用
cmd+ctrl+shift+4擷取螢幕並ctrl+v貼上（注意：不是 cmd+v） - 拖拉圖片至輸入框
- 提供圖片檔案路徑
這對於 UI mockup 參考或資料圖表的分析與除錯特別有效。即使未提供圖片，也建議明確說明「輸出需有視覺吸引力」，Claude 才會更注重美觀。
指定要參考的檔案
使用 tab 鍵自動補齊檔案或資料夾路徑，幫助 Claude 找到正確位置修改或分析。
貼上網址讓 Claude 閱讀
提供具體網址讓 Claude 抓取內容閱讀。若你常查閱同一網域的內容，可用 /permissions 指令將該網域加入白名單。
及早糾正 Claude 的方向
雖然 Claude 支援 auto-accept 模式（shift+tab 切換），但效果最好還是搭配使用者積極指導。
以下四個功能有助於糾正方向：
- 請 Claude 先規劃解法，並明說「不要先寫程式」。
- 使用
Esc鍵隨時中斷 Claude 的操作（包含思考、工具呼叫、編輯），保留上下文方便你修改指令。 - 雙按
Esc回到歷史訊息，編輯前一次提示並重新嘗試。 - 請 Claude 撤銷變更，常與步驟 2 搭配使用。
雖然 Claude 有時一次就解對問題，但這些調整工具通常能加速達成理想解法。
用 /clear 清除上下文
長時間使用 Claude 時，記憶上下文的視窗可能塞入太多內容，導致干擾與效能下降。每完成一個任務就使用 /clear 重置上下文，是維持穩定表現的好習慣。
使用清單與草稿頁協助複雜任務
對於步驟繁多的任務（如程式碼搬移、大量 lint 修正、複雜建置流程），可以讓 Claude 使用 Markdown 檔或 GitHub issue 作為 checklist 與 scratchpad：
- 請 Claude 執行 lint 指令並將錯誤寫入 Markdown 清單（包含檔案與行數）
- 接著依序處理，每解決一個問題就打勾確認，再進行下一個
使用 headless 模式
Claude Code 支援 headless 模式，適用於非互動式環境，如 CI、pre-commit hook、自動化建置腳本等情境。啟用方式是在執行命令時加上 -p 搭配 prompt，並可加上 --output-format stream-json 來獲得串流式 JSON 輸出。
請注意，headless 模式不會在 session 間保留狀態，因此每次執行都需要重新觸發設定。
claude -p "explain this function"
- 用於 issue 自動分類與標註（Issue triage）：當你的 GitHub repo 中產生新 issue 時，可以透過 Claude 的 headless 模式自動處理。例如 Anthropic 的 Claude Code 公開 repo 就是這樣運作：一旦偵測到新 issue，就會請 Claude 閱讀內容並自動標註合適的 labels。這樣的流程可以嵌入 GitHub Actions 等自動化流程，讓 Claude 成為你 issue 管理的第一道防線。
- 當作語意型 Linter 使用：除了標準 Lint 工具會抓的格式錯誤外，Claude 還能提供主觀判斷的語意層級建議，例如：拼字錯誤、陳舊註解、函式或變數命名不清、可能誤導的註解或文件。
多個 Claude Code 同時運作！
實際上，最強大的應用之一就是「平行運行多個 Claude 實例」。這能讓你在不同任務之間拆分上下文、提升處理效率，甚至模擬「團隊合作」。
區分角色，平行協作
你可以讓一個 Claude 撰寫程式，另一個 Claude 驗證或測試它的輸出：
- Claude A 撰寫程式碼
- 使用
/clear開新終端或第二個 Claude - Claude B 閱讀並審查 Claude A 的程式
- Claude C 綜合 Claude A 的程式與 Claude B 的回饋，進行優化修改
你也可以讓 Claude A 撰寫測試，Claude B 寫出通過測試的實作，再讓 Claude C 驗證兩者之間的契合。這種上下文隔離能大幅減少錯誤與過擬合。
多重 repo checkout 加速任務並行
Anthropic 工程師常會為大型專案開三至四個不同的 git checkout，並分別在不同資料夾中開啟 Claude，各自負責不同任務。
實際流程如下：
- 建立 3~4 個專案資料夾，各自 git checkout
- 在單獨的終端選項卡中打開每個資料夾
- 在每個資料夾中啟動 Claude 並執行不同的任務
- 分配任務、交錯處理、審核 Claude 的請求與輸出
使用 git worktrees 取代多份 clone
如果你希望更輕量的方式，可以使用 git worktree
git worktree可讓您從相同倉庫檢出多個分支到不同的目錄。每個worktree都有自己的工作目錄，其中包含相互隔離的文件，同時共用相同的 Git 歷史記錄和參考日誌。
- 建立工作樹 ：
git worktree add ../project-feature-a feature-a - 在每個工作樹中啟動 Claude ：
cd ../project-feature-a && claude - 根據需要建立其他工作樹 （在新的終端選項卡中重複步驟 1-2）
例如你可以讓一個 Claude 改寫登入機制，另一個同時處理資料視覺化元件。兩者互不干擾，也不會發生合併衝突。
Tips：
- 使用一致的命名規則來管理 worktree 目錄
- 建議每個 worktree 搭配一個終端視窗與 IDE 視窗
- Mac 使用 iTerm2 可設定通知提醒 Claude 等待互動
- 任務結束後可用
git worktree remove清理乾淨
結合 headless 模式打造自動化系統
透過 claude -p 可以將 Claude 程式化整合進你的大型任務流程。常見模式有：
1.分散式任務（fanning out）
這種方式特別適合大規模轉換或分析任務，例如分析數百筆 log、轉換上千個 CSV、或批次修改架構：
- 首先請 Claude 幫你寫一段腳本，列出所有待處理項目（如需轉換的 2000 個檔案）
- 接著撰寫迴圈腳本，依序將任務指派給 Claude，例如：
claude -p "請將 foo.py 從 React 轉為 Vue，完成後務必回傳 OK 或 FAIL" --allowedTools Edit Bash(git commit:*)- 可重複執行調整 prompt 與工具設定，直到滿意為止
2.串接資料管線（pipelining）
將 Claude 的輸出直接串給下一步工具或腳本，可作為大型資料處理流程的一部分：
claude -p "分析 sentiment 並以 JSON 回傳" --json | jq '.sentiment' | ./your_downstream_task
- 適合文字摘要、CSV 分析、模型回饋等任務
最佳化技巧
- 建議在開發階段使用
--verbose除錯 - 上線環境建議移除 verbose 以避免干擾其他程序
- 可結合 bash loop 或 job queue 系統如
xargs、GNU parallel，進一步提高併發度
