Claude Code AI Agent 實作教學：讓它幫你跑任務而不只是回答問題
這篇要帶你做到什麼
Claude Code 跟你在瀏覽器開 Claude 聊天是完全不同的東西。前者是 Anthropic 在 2026 年初推出的 CLI 工具，設計上就是讓 Claude 在你的本機環境裡當一個 agent——讀你的程式碼、跑指令、改檔案、串工具，不只是輸出文字然後讓你自己複製貼上。
這篇教學的目標很明確：你跑完之後，會有一個可以執行多步驟任務的 Claude Code Agent 環境，知道怎麼設計 task prompt、怎麼讓它用工具、怎麼控制它能碰什麼不能碰什麼。
如果你之前看過用 Claude AI Agent 跑自動任務：從零開始的實作教學，那篇是概念+瀏覽器端操作；這篇是 Claude Code CLI 版本，場景更偏開發工作流。
事前準備：你需要這些東西
- Node.js 18+（
node -v確認一下） - Anthropic API Key（去 console.anthropic.com 拿，有免費額度可以測）
- 終端機（macOS/Linux 原生，Windows 用 WSL2 最省事）
- 基本的 CLI 操作能力，不需要精通 Bash
安裝指令很簡單：
npm install -g @anthropic-ai/claude-code
裝完之後設定 API Key：
export ANTHROPIC_API_KEY="sk-ant-..."
建議直接寫進 ~/.zshrc 或 ~/.bashrc，不然每次開新 terminal 都要重設。
步驟一：跑第一個 Hello World，確認環境沒問題
claude "列出這個目錄下的所有 .py 檔，並說明每個檔案大概在做什麼"
如果你看到 Claude 真的去讀了你的目錄然後回傳說明，恭喜，基本環境 OK。
白話講就是：Claude Code 預設會拿到幾個工具——讀檔、寫檔、執行 shell 指令、搜尋程式碼。你下的那句話是 prompt，它自己決定要用哪個工具、用幾次、結果怎麼組合。這就是 agent 跟一般問答的根本差別。
步驟二：設計一個真正有用的 Agent 任務
Agent 發揮效果的場景，通常是「多步驟、需要讀寫檔案、或需要跑指令確認結果」的任務。幾個實際例子：
- 「掃描這個 repo 裡所有 TODO 註解，整理成一份 markdown 清單存到 TODO.md」
- 「讀 requirements.txt，找出有安全漏洞的套件（對照 pip audit 輸出），把受影響的版本號更新到最新穩定版」
- 「跑測試，如果有失敗的，定位到對應的函式，嘗試修它，然後再跑一次確認通過」
這些任務共同點：有明確的起點、中間有判斷、有可以驗證的終點。你可以把它想成給一個新人工程師的工作說明書——越清楚、越有邊界，結果越可預期。
步驟三：用 --allowedTools 控制 Agent 能用的工具
Claude Code 預設工具組很廣，包含寫檔和跑 shell。在 production 環境或你想縮小風險的情境下，可以限制它：
claude --allowedTools "Read,Grep,Bash" "分析 src/ 裡的函式命名是否符合 PEP8"
這樣它就只能讀、搜尋、跑 Bash，沒辦法直接改你的檔案。適合「只要分析、不要動到我的 code」的場景。
工具清單可以到官方文件查完整名稱，常用的有：Read、Write、Edit、Bash、Grep、WebSearch。
步驟四：用 CLAUDE.md 給 Agent 長期指令
這是很多人剛開始用 Claude Code 不知道的功能。在你的專案根目錄放一個 CLAUDE.md，裡面寫你對這個 repo 的規範和背景，Claude Code 每次啟動都會讀它。
範例內容：
# 這個 Repo 的規則
- 語言：Python 3.11+
- 測試框架：pytest，跑測試指令是 `pytest tests/`
- 不要修改 `config/prod.yaml`
- commit message 格式：`feat:` / `fix:` / `chore:` 開頭
- 所有新函式要有 type hint
這樣你每次下任務都不用重複說明背景，agent 自己會遵守這些規則。白話講就是給它一份「入職說明文件」。
步驟五：串接多輪任務（Non-interactive 模式）
如果你要把 Claude Code 跑進 CI 或腳本裡，用 --print 旗標讓它只輸出結果、不進互動模式：
claude --print "檢查 src/ 底下有沒有未被 import 的模組，列出檔名" > unused_modules.txt
這樣的輸出可以直接 pipe 給其他工具，或存進檔案給下一個步驟用。Claude AI Agent 怎麼用？從聊天模式到自動執行任務的實作教學這篇有更詳細講到 agent 模式的架構設計思路，可以一起看。
常見錯誤與怎麼避開
1. Prompt 太模糊導致 agent 跑偏
「幫我優化這個 repo」這種 prompt 對 agent 來說等於沒說。要明確：「找出 api/ 裡面 response time 超過 200ms 的函式，並加上 caching decorator」。
2. 沒設 CLAUDE.md 然後怪它不懂你的 convention Agent 不會通靈，你的 code style 規範要明文寫出來。
3. 在有 production 資料的目錄直接跑
先在測試環境或 git 分支上跑，確認行為符合預期再移到正式環境。Claude Code 的 Edit 和 Write 工具是真的會改你的檔案，沒有 undo 按鈕。
4. API 費用沒注意
Agent 模式一個任務可能跑很多輪，token 消耗比單次問答高很多。建議先用 Haiku 模型測試流程（--model claude-haiku-4-5），確認邏輯對再換 Sonnet/Opus。
進階技巧：自訂工具（Custom Tools）
Claude Code 支援你自己定義工具，讓 agent 能呼叫你的內部 API 或腳本。在 CLAUDE.md 裡描述工具的行為，然後在你的腳本裡 handle 對應的 tool call。
這部分進入 MCP（Model Context Protocol）的領域——白話講就是讓 Claude 知道「我可以呼叫這個函式，它會回傳 XX 格式的資料」。Anthropic 在 2026 年已經把 MCP 標準化了，市面上有不少現成的 MCP server 可以直接接（GitHub、Notion、Slack 都有），不用全部自己寫。
跑完之後：確認你真的跑起來了
做個快速 checklist：
-
claude --version輸出版本號 - 跑一個讀取任務（Read only）確認 agent 會使用工具
- 專案根目錄有
CLAUDE.md - 試過
--allowedTools限制工具範圍 - 跑過一個有多步驟的真實任務
下一步可以試試把 Claude Code 接進你的 CI pipeline，或是開始玩 MCP server 擴充它能操作的資料來源。agent 這個概念真正有趣的地方，不是它能做多複雜的事，而是你設計任務邊界的能力——那才是決定結果好不好的關鍵。
常見問題
Claude Code 跟直接在網頁用 Claude 有什麼差別？
Claude Code 是跑在你本機的 CLI 工具，可以直接讀寫你的檔案、執行 shell 指令，是真正的 agent 模式。網頁版 Claude 只能對話輸出文字，你還是要自己複製貼上去執行。兩者的使用場景完全不同。
用 Claude Code 會花很多 API 費用嗎？
Agent 模式確實比單次問答消耗更多 token，因為它可能跑很多輪工具呼叫。建議先用 claude-haiku 模型測試任務流程，確認邏輯正確後再切換到 Sonnet 或 Opus 處理正式工作，可以有效控制成本。
CLAUDE.md 一定要放嗎？
不強制，但強烈建議。沒有 CLAUDE.md 的話，你每次下任務都要重複說明 code style、禁止碰的檔案、測試指令等背景，效率很低。有了它，Claude Code 每次啟動就會自動讀取，相當於給 agent 一份持久的「專案說明書」。
Claude Code 可以用在 Windows 上嗎？
可以，但建議透過 WSL2（Windows Subsystem for Linux）來跑，這樣 Bash 工具和路徑處理都會比較順。原生 Windows CMD 或 PowerShell 理論上也能跑，但踩到奇怪問題的機率高一些。
怎麼讓 Claude Code 不要動到某些重要檔案？
有兩個方法：一是在 CLAUDE.md 裡明確寫「不要修改 config/prod.yaml 等重要檔案」；二是用 --allowedTools 把 Write 和 Edit 工具排除掉，讓 agent 只能讀取而無法寫入。兩種可以同時用，保障更完整。
分享這篇
