前言

這篇官方文件的核心其實是在教你：

不要把 Claude Code 當聊天機器人，而是把它當成「可以自主工作的 AI 工程師」。

Anthropic 強調，Claude Code 的強項不是「回答問題」，而是：

• 讀整個 codebase
• 自己探索架構
• 執行 terminal 指令
• 修改多個檔案
• 跑測試
• 自主完成任務

但要發揮效果，關鍵在於「上下文管理（context management）」與「工作流程設計」。

📌 排序說明：以下九點是依教學重點重排，並非官方章節順序。我把 context 與 verify 放最前面，是因為這兩件事是官方在文章開頭就強調的核心，先抓到這兩點，後面的工具與工作流才能站得住。

1. Context window 很珍貴（最重要）

🎬 動畫教學 → Context 越滿越容易失準

這是全文最核心概念。

Claude Code 的所有能力都建立在：

• 對話歷史
• 讀過的檔案
• command output
• 修改紀錄

這些都會塞進 context window。

問題是：

context 越接近滿載、噪音越多，表現越容易下降。

注意這不是絕對 — 官方也提到：「如果你正在深入處理同一個複雜問題，累積的對話歷史本身就有價值。」重點在「無意義或不相關」的累積要避免。

所以官方一直強調：

• 避免無意義長對話
• 適時 /clear
• 使用 /compact
• 把長期知識寫進 CLAUDE.md

而不是一直聊天。

2. 「證據」比 AI 自信重要

🎬 動畫教學 → 證據 > AI 自信

官方在最佳實踐文件裡，把這條獨立列為「the single highest-leverage thing you can do」 — 直譯：你能做的單一最高槓桿動作。

不要相信：

"This should work"

而是要求：

• build result
• test output
• screenshot
• actual logs

因為 AI 很容易「看起來有信心」但實際沒驗證過。

官方建議：

• 給 Claude 明確的驗證標準（test cases、expected output）
• 對 UI 改動要求截圖比對
• 處理錯誤要 fix root cause，不要 suppress

3. CLAUDE.md 是核心武器

🎬 動畫教學 → CLAUDE.md 核心武器

官方非常推這個。執行 /init 可以自動產生初版。

應該寫進去的（官方表格）：

• 非顯而易見的架構決策（為什麼選 X 不選 Y、特殊取捨）
• Claude 猜不到的 bash 指令
• 跟預設不同的 coding style
• 測試框架與測試指令偏好
• Repo 規範（branch naming、PR convention）
• 開發環境 quirks（必要 env vars）
• 常見的 gotchas 或非顯而易見的行為

不應該寫進去：

• Claude 讀 code 就能推出來的事
• 逐檔說明 codebase（官方明確點名禁忌）
• 標準語言慣例
• 詳細 API 文件（改放連結）
• 經常變動的資訊
• 長篇 tutorial 或解釋

關鍵詞是「非顯而易見」— 寫的是 Claude 從程式碼推不出來的事情，而不是把整個專案結構抄一遍。

這樣 Claude 每次啟動都能知道專案規則 — 等於：

把團隊知識「永久灌進 AI」。

而不是每次重講一次。

4. 先規劃，再動手（Explore → Plan → Implement → Commit）

🎬 動畫教學 → Plan → Review → Execute

官方建議的四階段 workflow：

1. Explore — 進 plan mode，讓 Claude 讀檔、回答問題，但不動手
2. Plan — 請它列出實作計畫
3. Implement — 切回正常模式，照計畫實作 + 驗證
4. Commit — 寫 descriptive commit + 開 PR

❌ 不好的方式

「幫我直接改」 — AI 可能改一堆你沒同意的地方。

✅ 好的方式

先請它：

• 先調查、列出影響範圍
• 提出 plan
• 你 review / 修正
• 確認後再實作

📌 例外：小到一句話能描述 diff 的改動（typo、加 log、改變數名），直接做就好，不必 plan。

5. 小步驟 + 持續測試

🎬 動畫教學 → 小步驟 + 持續測試

⚠️ 本節為延伸實作習慣，非官方獨立章節。它是從官方兩個核心概念推導出來的：「Verify its work」（每步都能驗證）與「Explore → Plan → Implement → Commit」（不要一步到位）。社群（Morph、Cash Wu 等）也把這個習慣寫成獨立準則。

實務上會落地成：

• 小修改
• 立即測試
• 頻繁 commit

因為 agent 很容易：

• 一次改太多
• 造成 hidden regression
• 自信但錯誤

所以推薦：

• TDD
• lint immediately
• run tests often

不要讓 AI 一口氣改整個專案。

6. 把 Claude 當資深工程師問（Ask Codebase Questions）

🎬 動畫教學 → 把 Claude 當資深工程師問

官方明確提到：在不熟的 codebase 裡，Claude Code 是最佳 onboarding 工具。你可以問同事的問題都可以問它，不需要特別 prompt 技巧：

• How does logging work?
• How do I make a new API endpoint?
• What does async move { ... } do on line 134 of foo.rs?
• What edge cases does CustomerOnboardingFlowImpl handle?
• Why does this code call foo() instead of bar() on line 333?

它會：

• 自主掃描 repo
• 建立 mental model
• 跨檔案推理

→ 縮短新人 ramp-up 時間，減少同事被打擾的負擔。

7. 要把它當「Agent」不是 Copilot

🎬 動畫教學 → Agent ≠ Copilot

這是觀念差異。

Copilot：

你寫 code，它補 code。

Claude Code：

你描述目標，它自己想辦法完成。

例如：

「找出為什麼 staging API timeout，修掉並補測試」

Claude 會：

• trace request flow
• 看 logs
• 搜 config
• 改 code
• run tests

這是 agentic workflow。

8. Parallel Sessions

🎬 動畫教學 → Parallel Sessions

官方提到的並行方式：

• Worktrees — 不同 git checkout 隔離
• Desktop app — 視覺化管理多 session
• Claude Code on the web — 雲端 VM
• Agent teams — 自動協調多 session

進階用法：

• Writer / Reviewer 模式 — 一個 session 寫，另一個 fresh context review
• Fan-out — 用 claude -p 對 N 個檔案批次跑

9. Configure Your Environment（配置你的環境）

🎬 動畫教學 → Configure Your Environment

官方建議花一次時間配置好環境，所有後續 session 都自動受惠。八個官方推薦的擴充點：

1. CLAUDE.md — 專案規則永久灌入（見第 3 點）
2. Permissions / Auto mode / Sandboxing — 減少彈窗、限制風險
3. CLI tools — gh、aws、gcloud、sentry-cli
4. MCP Servers — Notion / Figma / DB / 監控數據
5. Hooks — 確定性自動化（PreToolUse / PostToolUse）
6. Skills — 領域知識按需載入
7. Subagents — 獨立 context 不污染主對話
8. Plugins — 社群打包好的整套擴充

💡 Claude Code 的威力不只在 prompt engineering，也在環境配置與驗證閉環。官方文件有完整一節在教 prompt 寫法（見補充 #10），環境配置是並列的另一支柱，不是取代關係。

10. ✍️ 寫出精準 Prompt

🎬 動畫教學 → 寫出精準 Prompt

官方提供四種改寫技巧 + 五種餵資料方式：

四種改寫：

• 劃範圍（指定檔案 / 情境 / 偏好）
• 指向來源（git history、特定檔案）
• 引用既有 pattern（「照 HotDogWidget.php 的樣式做」）
• 描述症狀（症狀 + 可能位置 + 修好的樣子）

五種餵資料：

• @檔名 引用
• 直接貼圖
• 給 URL（用 /permissions allowlist）
• pipe data（cat error.log | claude）
• 讓 Claude 自己抓（Bash / MCP）

11. 🚨 五大常見失敗模式

🎬 動畫教學 → 五大常見失敗模式

官方獨立列出的反模式（Avoid Common Failure Patterns）：

1. Kitchen Sink Session — 一個 session 多任務混雜 → /clear
2. Correcting Over and Over — 反覆糾正污染 context → 兩次失敗就重來
3. Over-Specified CLAUDE.md — 寫太長重要規則被淹沒 → 殘酷剪裁
4. Trust-Then-Verify Gap — 看起來對就 ship → 永遠給驗證路徑
5. Infinite Exploration — 無範圍研究讀爆檔案 → 限縮 or 用 subagent

12. 📝 其他官方技巧速覽

🎬 動畫教學 → 其他官方技巧

五個小技巧合併一頁：

• Session 控制 — 即時修正（Esc / Esc Esc / /rewind / Undo that / /btw）+ 跨次延續（/rename 取名 + claude --continue / claude --resume，把 session 當 workstream / branch 管理）
• 讓 Claude 反問你 — 大功能前用 AskUserQuestion interview 模式
• Non-interactive mode — claude -p 接 CI / pre-commit / pipeline
• Subagent 兩種用法：
  • 調查 Investigation（主流用法）— 把需要讀大量檔案的研究丟給 subagent，主對話 context 保持乾淨
  • 對抗性 Review（Adversarial）— fresh subagent 對 diff 找碴。⚠️ 官方警告：reviewer 一定會回報問題，只追究影響 correctness 或 stated requirements 的 gaps，其他發現當 optional，否則會 over-engineer（多餘抽象層、防禦性 code、不可能的 test case）
• Permission modes — Shift+Tab 預設循環 3 檔：Ask before edits（default）→ Edit automatically（acceptEdits）→ Plan mode（plan）；Auto mode 要帳號符合條件（方案 / 模型 / Admin 啟用 / Provider / 使用者 opt-in，具體名單會變動，請以官方文件為準）才會插入循環。另有 dontAsk（不進循環）、bypassPermissions（需啟用後才可能進循環）兩個進階模式。/permissions 規則與 /sandbox 隔離疊在這些模式之上

總結

這篇最佳實踐其實是在說：

「如何把 Claude Code 從聊天 AI，變成真正能協作開發的大型 agent 系統。」

12 個重點貫穿三條主軸 — 管理 context、建立工作流、配置環境：

🧠 管理 Context（資訊輸入的品質與密度）

1. Context 越滿越容易失準 — /clear、/compact、/btw、auto compaction、Esc Esc 部分摘要
2. 要證據，不要 AI 自信 — 官方標註最高槓桿，永遠要 test / build / screenshot
3. CLAUDE.md 是核心武器 — 把每次都要講的事永久寫進去
4. 寫出精準 Prompt — 劃範圍、指來源、引 pattern、描述症狀；用 @file、貼圖、URL、pipe 餵資料

🛠️ 建立工作流（從探索到 commit 的節奏）

4. Plan → Review → Execute — 官方 4 階段：Explore → Plan → Implement → Commit
5. 小步驟 + 持續測試 — 從「Verify its work」推導的實作習慣
6. 把 Claude 當資深工程師問 — onboarding 與 codebase 探索的最佳用法
7. Agent 思維，不是 Copilot — 描述目標、讓它自己想辦法
8. Parallel Sessions — worktree / 多 terminal 擴大產出
9. 避開五大失敗模式 — Kitchen Sink / Over-correct / Over-spec CLAUDE.md / Trust-then-verify gap / Infinite Exploration

⚙️ 配置環境（讓上面所有事情變容易）

9. 完整環境配置 — CLAUDE.md / Permissions / CLI tools / MCP / Hooks / Skills / Subagents / Plugins
10. 其他官方技巧 — Session 控制（/rewind / --continue / --resume）、Interview 模式、claude -p、Subagent 兩種用法、Permission modes

🧭 收尾：Develop Your Intuition（培養你的直覺）

官方文件最後一節，提醒讀者：這份指南的所有規則都是起點，不是終點。

前面 12 點是一般情況下管用的「預設模式」，但官方明確告訴你 — 經驗累積後，你會找到打破規則更有用的時機：

培養直覺的方法

官方建議：

• Claude 答得好時：注意你做對了什麼 — prompt 結構？提供的 context？所在的 mode？
• Claude 卡住時：問自己為什麼 — context 太雜？prompt 太模糊？任務一次切太大？
• 隨時間累積，你會發展出沒有任何指南能寫出來的判斷力：何時該精準、何時該開放；何時 plan、何時直接探索；何時 clear context、何時讓它累積。

💡 一句話：規則是地圖，不是地形本身。

參考資料

• Best practices for Claude Code — Claude Code Docs
• Claude Code Best Practices：Anthropic 官方最佳實踐指南 — Cash Wu Geek
• Claude Code Best Practices: The 2026 Guide to 10x Productivity — Morph
• Claude Code Best Practices the Official Docs Don't Cover (2026) — Chudi Nnorukam