B.8 Claude Code 終端命令列 Agent 實戰手冊:從初階 Prompt 到擴充機制與 Agent Teams
學完本節,你能夠:
- 安裝 Claude Code,並依任務風險選擇合適的權限模式(規劃、手動核准、自動)。
- 用
CLAUDE.md、Skills、Subagents、Hooks、MCP、Plugins 等機制,把公司規則與常用流程「裝進」AI,並說出哪些是建議、哪些是強制。 - 以「探索 → 規劃 → 實作 → 提交」的節奏,完成一個附自動測試的小工具。
💡 Claude Code 更新頻繁,本節指令以撰寫時的 Anthropic 官方文件(code.claude.com/docs)為準。若畫面與本節不同,在 Claude Code 裡輸入
/help,或直接問它「這個功能現在怎麼用?」
壹、開場情境:同一件事,每次都要交代一遍
📌 以下為教學情境(依實務改編)。
外貿公司的實習生小林用網頁版 AI 寫了一支報關資料檢查程式。兩週下來他發現三個問題:
| 問題 | 發生的事 |
|---|---|
| 每次都要重講規則 | 每開一次新對話,就要重新說「台幣金額不能有小數」「HS Code 是 10 碼」 |
| 程式碼來回複製貼上 | AI 看不到他電腦上的檔案,改一行就要整段貼過去 |
| 差點外洩機密 | 有一次把含 API 金鑰的 .env 內容整個貼進對話框 |
本節要解決的問題: 用一個能直接讀寫專案資料夾、又能被「裝上公司規矩」的 AI 工具,讓規則只需寫一次,機密檔案碰都碰不到。
貳、Claude Code 是什麼
Claude Code 是 Anthropic 推出的 AI 程式開發代理(Agent)。它能讀取你專案資料夾裡的檔案、修改程式碼、執行終端機指令(例如跑測試、操作 Git),並在每個步驟依你設定的權限決定要不要先問你。
除了終端機,它也提供 VS Code 與 JetBrains 擴充套件、桌面應用程式與網頁版。本節以終端機版為主(終端機基礎見附錄 E)。
| Google Antigravity | Claude Code(終端機版) | |
|---|---|---|
| 介面 | 圖形化的開發環境,有編輯器與代理管理畫面 | 文字指令介面,也可裝進既有編輯器 |
| 強項 | 視覺化操作、看畫面迭代原型 | 可在任何有終端機的地方執行(含遠端伺服器)、可寫成腳本自動化 |
| 擴充方式 | Skills(第 B.4 節)、MCP(第 B.5 節)等 | CLAUDE.md、Skills、Subagents、Hooks、MCP、Plugins 等(本節第陸段) |
兩者不是互斥。B.5 寫的 MCP 伺服器,兩邊都能接。
參、安裝與第一次對話
1. 安裝
Claude Code 需要 Claude 付費方案(Pro、Max、Team、Enterprise)或 Claude Console(API 預付額度)帳號;免費方案不包含 Claude Code。
# macOS/Linux/WSL(官方建議的原生安裝)
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# 或使用套件管理工具:macOS 的 Homebrew、Windows 的 WinGet
brew install --cask claude-code
winget install Anthropic.ClaudeCode
安裝後開新的終端機視窗,輸入 claude --version,看到版本號即成功。
⚠️ 也可以用 npm 安裝(
npm install -g @anthropic-ai/claude-code,需 Node.js 22 以上),但不要加sudo。官方文件明確警告這會造成權限與資安問題。
2. 登入與啟動
cd ~/trade-project
claude
第一次執行會開啟瀏覽器完成登入。之後在專案資料夾輸入 claude 就能開始對話。可以先問:
請閱讀這個專案,用繁體中文說明它在做什麼、資料怎麼流動、主要的程式進入點在哪裡。
3. 最常用的指令
| 在終端機輸入 | 作用 |
|---|---|
claude |
開始互動對話 |
claude "修好建置錯誤" |
帶著第一個任務開始對話 |
claude -p "說明這個函式" |
只問一次、印出答案就結束(適合寫進腳本) |
claude -c |
接續這個資料夾最近一次的對話 |
claude -r |
從清單挑一個過去的對話接續 |
| 在對話中輸入 | 作用 |
|---|---|
/help |
列出可用指令 |
/init |
分析專案,產生 CLAUDE.md 初稿 |
/memory |
編輯 CLAUDE.md 等記憶檔 |
/clear |
清空對話,開始新主題 |
/compact |
把目前對話濃縮成摘要,騰出上下文空間 |
/context |
檢視上下文用量 |
/usage |
查看本次費用與方案用量(/cost 是別名) |
/rewind |
把對話和程式碼回復到之前的某個時間點 |
/model |
切換模型 |
/effort |
調整思考深度(見第伍段) |
/permissions |
管理允許、詢問、拒絕的規則 |
肆、權限模式:AI 能自己做多少事
這是商管人最該先懂的設定,本質就是授權層級。在對話中按 Shift+Tab 可以切換;狀態列會顯示目前模式。
| 模式 | 不用問你就能做的事 | 適合情境 |
|---|---|---|
Manual(設定值 default) |
只能讀檔 | 敏感作業、第一次接觸的專案 |
Accept edits(acceptEdits) |
讀檔、改檔、常見檔案操作 | 你邊看邊改的時候 |
Plan(plan) |
讀檔、執行探索用指令;在你核准計畫前不會修改原始碼 | 動手前先研究、先出計畫 |
Auto(auto) |
大部分動作,由另一個模型(分類器)在背景把關 | 長時間任務、減少反覆按核准 |
dontAsk |
只做事先允許的工具,其餘一律拒絕 | 自動化腳本、CI |
bypassPermissions |
全部 | 僅限隔離的容器或虛擬機 |
⚠️ 注意預設值:在較新的版本中,終端機互動對話預設以 auto 模式啟動。初學者處理公司專案時,建議用
claude --permission-mode plan啟動,先看計畫再放行;或按Shift+Tab切到 Manual。
也可以只對單一訊息進入規劃模式:在提示前加 /plan,例如 /plan 幫報價模組加上匯率檢查。
伍、工作節奏與思考深度
1. 探索 → 規劃 → 實作 → 提交
讀檔、理解現況
不改任何東西"] --> P["2. 規劃
Plan 模式產出步驟
人審核後核准"] P --> C["3. 實作
改程式、跑測試
失敗就修到通過"] C --> CM["4. 提交
檢視 diff
寫 commit 訊息"]
這和第 2.6 節「先寫規格再寫程式」是同一個道理:計畫是你能審核的規格,比事後讀一大堆修改容易得多。
另外兩種常用節奏:
| 節奏 | 做法 | 對應章節 |
|---|---|---|
| 測試先行(TDD) | 先請它寫測試、確認測試失敗,再寫程式直到測試通過 | 第 5.2 節 |
| 看畫面迭代 | 給它設計截圖,產生介面後再截圖回饋差異 | 第 2.7 節 |
2. 調整思考深度與模型
| 方式 | 說明 |
|---|---|
/effort low~/effort max |
設定思考深度。較新的模型提供 low、medium、high、xhigh、max;預設值依模型而異。越深越慢、越耗用量 |
提示中加入 ultrathink |
只對這一次提問要求更深入的推理,不改變整體設定 |
/model opus、/model sonnet、/model haiku |
切換模型家族:Opus 適合複雜推理,Sonnet 適合日常開發,Haiku 快速便宜 |
/model opusplan |
規劃模式用 Opus、執行時改用 Sonnet,兼顧規劃品質與成本 |
💡 成本思維:規劃錯了,後面全部重做;執行步驟清楚時,用較便宜的模型就夠。這與第 6.2 節 FinOps 的精神一致。
陸、把公司規矩裝進 AI:擴充機制總覽
| 機制 | 放在哪裡 | 用途 | 性質 |
|---|---|---|---|
| CLAUDE.md | 專案根目錄 CLAUDE.md(個人全域:~/.claude/CLAUDE.md) |
每次對話自動載入的專案規則 | 建議:AI 會參考,但不保證遵守 |
| Skills | .claude/skills/<名稱>/SKILL.md |
打包常用流程,可用 /名稱 呼叫,或讓 AI 依描述自動使用 |
建議 |
| Subagents | .claude/agents/<名稱>.md |
定義專責子代理,擁有獨立上下文與工具範圍 | 工具範圍是強制的 |
| Hooks | .claude/settings.json 的 hooks 區塊 |
在特定時間點一定會執行的指令(例如改檔前檢查) | 強制 |
| MCP | claude mcp add 或專案的 .mcp.json |
連接外部系統(見第 B.5 節) | 依伺服器設計 |
| Plugins | 以 /plugin 安裝 |
把上述多種元件打包,一次安裝、跨專案共用 | 依內含元件 |
| Dynamic workflows | 存檔於 .claude/workflows/ |
由腳本同時調度大量子代理的大型任務 | 進階,本節不展開 |
最重要的一欄是「性質」:CLAUDE.md 是員工手冊,Hooks 是門禁系統。 「不准碰 .env」寫在 CLAUDE.md 裡,AI 多半會遵守;寫成 Hook,就是一定擋得住。
1. CLAUDE.md:專案的員工手冊
輸入 /init 產生初稿,再補上 AI 自己看不出來的公司規則。官方建議每個檔案控制在 200 行以內,太長反而降低遵守程度。
# 報關與報價工具專案規則
## 商業規則
- 金額:USD 最多 2 位小數;TWD 一律整數。
- HS Code:本公司報關資料使用 10 位數字(不含檢查碼)。
- 涉及多筆金額加總或匯率換算,一律寫程式計算,不要心算。
## 程式規範
- Python 3.10 以上,函式加型別註記與繁體中文說明。
- 新功能必須附 pytest 測試,測試全數通過才能提交。
- Commit 訊息使用 Conventional Commits 格式(feat:、fix:、docs:)。
## 資安
- API 金鑰只從環境變數讀取,不寫進程式碼。
- 不讀取、不修改 .env 與 secrets/ 目錄(另有 Hook 強制執行)。
2. Skills:把常用流程變成指令
當某段提示你每週要打好幾次,就做成 Skill。建立 .claude/skills/vat-check/SKILL.md:
---
name: vat-check
description: 檢查進口報價單的營業稅與關稅計算是否正確。使用者提到進口稅費、營業稅試算時使用。
---
1. 讀取使用者指定的報價檔。
2. 依公司規則重算關稅與營業稅,寫成 Python 腳本執行,不要心算。
3. 用表格列出:項目、原檔數字、重算數字、差異。差異不為 0 的列標示 ⚠️。
之後輸入 /vat-check 就能執行;description 寫得清楚,AI 也會在相關對話中自動使用。若不希望 AI 自動觸發(例如會寄信、會部署的流程),在開頭區塊加上 disable-model-invocation: true。舊版放在 .claude/commands/ 的自訂指令仍可使用,但新作品建議用 Skills。
3. Subagents:專責助手
建立 .claude/agents/tariff-reviewer.md:
---
name: tariff-reviewer
description: 審查報關與關稅相關程式碼的商業規則是否正確。修改報關模組後主動使用。
tools: Read, Grep, Glob
model: sonnet
---
你是熟悉台灣出口報關實務的審查員。只讀取程式碼,不修改任何檔案。
逐條比對 CLAUDE.md 的商業規則,列出違反之處、所在檔案與行號、建議修正方式。
tools 只給了讀取類工具,所以這個子代理無法改檔。它在獨立的上下文中工作,完成後只把審查結果交回主對話(多代理的概念見第 B.6 節)。
4. Hooks:真正擋得住的門禁
以下設定讓 Claude 每次要編輯或寫入檔案前,先執行檢查腳本;腳本以結束碼 2 結束時,該動作會被阻擋,錯誤訊息會回饋給 Claude。
.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
]
}
]
}
}
.claude/hooks/protect-files.sh(需要 jq 工具;存檔後執行 chmod +x 使其可執行):
#!/bin/bash
# 讀取 Claude 準備修改的檔案路徑
FILE_PATH=$(jq -r '.tool_input.file_path // empty')
for pattern in ".env" "secrets/"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "已阻擋:$FILE_PATH 屬於受保護檔案" >&2
exit 2
fi
done
exit 0
常用的 Hook 時間點:
| 事件 | 觸發時機 | 商業用途 |
|---|---|---|
PreToolUse |
工具執行前,可阻擋 | 保護機密檔、禁止特定指令 |
PostToolUse |
工具成功執行後 | 改完檔自動格式化、寫稽核紀錄 |
UserPromptSubmit |
你送出訊息、Claude 處理前 | 偵測是否貼了個資或金鑰 |
Stop |
Claude 回應結束時 | 自動跑測試、發通知 |
SessionStart |
對話開始或接續時 | 載入當日匯率等背景資訊 |
輸入 /hooks 可以檢視目前生效的設定。注意:這個 Hook 只攔截編輯與寫入工具;若也要防止透過終端機指令讀取,需另外為 Bash 或 Read 工具設定規則(/permissions 的拒絕規則也能做到)。
5. MCP 與 Plugins
把第 B.5 節的 ERP 伺服器接進 Claude Code:
claude mcp add --env ERP_WEBAPP_URL=https://script.google.com/macros/s/你的ID/exec --env ERP_API_TOKEN=你的密鑰 erp -- node /完整路徑/erp-mcp/erp-mcp-server.mjs
-- 之後是啟動伺服器的指令。加上 --scope project 會寫進專案的 .mcp.json,團隊成員共用;遠端伺服器則用 claude mcp add --transport http 名稱 網址。在對話中輸入 /mcp 檢查連線狀態。
當你的 Skills、Subagents、Hooks、MCP 設定成熟到想給其他部門使用,就可以打包成 Plugin。輸入 /plugin 可瀏覽並安裝官方市集中的外掛。安裝外掛等於讓它以你的身分執行程式,安裝前務必確認來源可信。
柒、平行工作:Worktrees 與 Agent Teams
| 方式 | 怎麼做 | 適合 |
|---|---|---|
| Git worktree | claude --worktree feature-tariff:在 .claude/worktrees/ 下建立獨立工作目錄與分支,再開另一個終端機用不同名稱啟動第二個工作 |
兩件互不相干的開發同時進行(Git 分支概念見附錄 A.3) |
| Subagents | 在同一個對話中派出子代理,結果交回主對話 | 短小、只需要結果的子任務 |
| Agent Teams(實驗功能) | 需先設定環境變數 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1;由一個主導者指派任務,隊友各自獨立工作,可以互相傳訊、共用任務清單 |
需要彼此討論、互相挑錯的研究或審查 |
⚠️ Agent Teams 每位隊友都是獨立的 Claude 工作階段,Token 用量隨人數線性增加。官方建議從 3~5 位隊友開始,例行任務用單一對話或子代理即可。
捌、手把手實戰:出口報關資料防呆檢驗器
步驟 1:規劃
claude --permission-mode plan
輸入需求:
請規劃 Python 模組 customs_checker.py 與 pytest 測試:
1. 檢查報關資料 dict,必須包含 hs_code、fob_price、currency、destination。
2. hs_code 必須是 10 位數字(依 CLAUDE.md)。
3. currency 只接受 TWD 與 USD:TWD 不得有小數;USD 最多 2 位小數。fob_price 必須大於 0。
4. 回傳錯誤訊息清單,空清單代表通過。金額用 Decimal 判斷小數位數,避免浮點誤差。
請列出測試案例,先不要寫檔。
步驟 2:審核計畫
逐條核對:需求中的每條規則是否都有對應的測試?有沒有考慮「欄位缺漏」「不支援的幣別(例如 JPY)」?沒問題就選擇核准,Claude 會離開規劃模式開始實作。
步驟 3:實作與自動測試
Claude 建立 customs_checker.py 與 tests/test_customs.py,執行 pytest。測試失敗時它會讀錯誤訊息、修正、再跑一次。依上述規格實作的版本,測試結果如下:
tests/test_customs.py ...... [100%]
============================== 6 passed in 0.02s ===============================
步驟 4:提交
請檢視變更並提交,commit 訊息使用 Conventional Commits 格式。
Claude 會先執行 git status 與 git diff 確認內容,再提交,例如:feat(customs): validate HS code length and currency decimals。提交前,你仍應自己看一次 diff。
玖、判斷看看:常見誤解
| 說法 | 正確嗎? | 說明 |
|---|---|---|
| 「CLAUDE.md 寫了不准改 .env,所以絕對安全」 | ❌ | CLAUDE.md 是參考資訊,要強制必須用 Hook 或權限拒絕規則 |
| 「Plan 模式下 Claude 什麼指令都不會執行」 | ❌ | 它會讀檔、執行探索用指令;限制的是核准前不修改原始碼 |
| 「思考深度開到最大,結果一定最好」 | ❌ | 簡單任務開高深度只會更慢、更耗用量 |
| 「Subagent 越多越好」 | ❌ | 每個子代理都要讀資料,成本上升;子題彼此相依時反而容易矛盾 |
| 「Agent Teams 是正式功能,直接用」 | ❌ | 目前為實驗功能,預設關閉,有已知限制 |
| 「網路上教學寫的指令一定能用」 | ⚠️ | 工具更新快,以官方文件與 /help 為準 |
拾、回到情境與小結
小林的三個問題都有了對應:規則寫進 CLAUDE.md 只講一次;Claude Code 直接讀寫專案檔案,不必複製貼上;.env 由 Hook 擋住,不靠自律。
| 仍要注意的限制 | 後果 | 在哪一節處理 |
|---|---|---|
| Auto/bypass 模式授權範圍大 | AI 可能執行你沒預期的指令 | 第 9.2 節權限隔離;第 13.2 節最小授權 |
| 讀到的檔案或網頁可能夾帶惡意指令 | 被誘導做出危險動作 | 第 13.1 節提示注入防禦 |
| Agent 能寫測試,也可能寫出「為了通過而通過」的測試 | 測試全綠但規則錯 | 第 5.2 節;人工審核測試案例 |
本節小結
- 權限模式就是授權層級:不熟的專案先 Plan,再 Manual,熟悉後才考慮 Auto。
- CLAUDE.md 是建議,Hooks 是強制;機密保護一定要用強制機制。
- Skills 封裝流程、Subagents 分工、MCP 連外部系統、Plugins 打包分享。
- 探索 → 規劃 → 實作 → 提交:讓 AI 先交出你看得懂的計畫,再讓它動手。
拾壹、練習
- 改規則(5 分鐘):公司決定也接受歐元報價,EUR 最多 2 位小數。你要改
CLAUDE.md的哪一行?要在步驟 1 的需求加什麼?應該新增哪一個測試案例? - 加功能(20 分鐘):寫一個
PreToolUseHook,在 Claude 執行git push前要求停下(提示:matcher設為Bash,腳本從.tool_input.command讀出指令內容,含git push就以結束碼 2 結束)。說明為什麼這比在 CLAUDE.md 寫「不要 push」可靠。 - 管理反思(討論):海運併櫃(LCL)通常以「1 立方公尺(CBM)折算 1,000 公斤」比較體積與重量計費,但 AI 常套用空運或快遞的折算標準而算錯。這條規則應該寫在 CLAUDE.md、做成 Skill,還是寫成測試?請從出錯成本、維護者、適用範圍三個角度討論,並說明誰有權修改它。