B.8 Claude Code 終端命令列 Agent 實戰手冊:從初階 Prompt 到擴充機制與 Agent Teams

學完本節,你能夠:

  1. 安裝 Claude Code,並依任務風險選擇合適的權限模式(規劃、手動核准、自動)。
  2. 用 CLAUDE.md、Skills、Subagents、Hooks、MCP、Plugins 等機制,把公司規則與常用流程「裝進」AI,並說出哪些是建議、哪些是強制。
  3. 以「探索 → 規劃 → 實作 → 提交」的節奏,完成一個附自動測試的小工具。

💡 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. 探索 → 規劃 → 實作 → 提交

flowchart LR E["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 節;人工審核測試案例

本節小結

  1. 權限模式就是授權層級:不熟的專案先 Plan,再 Manual,熟悉後才考慮 Auto。
  2. CLAUDE.md 是建議,Hooks 是強制;機密保護一定要用強制機制。
  3. Skills 封裝流程、Subagents 分工、MCP 連外部系統、Plugins 打包分享。
  4. 探索 → 規劃 → 實作 → 提交:讓 AI 先交出你看得懂的計畫,再讓它動手。

拾壹、練習

  1. 改規則(5 分鐘):公司決定也接受歐元報價,EUR 最多 2 位小數。你要改 CLAUDE.md 的哪一行?要在步驟 1 的需求加什麼?應該新增哪一個測試案例?
  2. 加功能(20 分鐘):寫一個 PreToolUse Hook,在 Claude 執行 git push 前要求停下(提示:matcher 設為 Bash,腳本從 .tool_input.command 讀出指令內容,含 git push 就以結束碼 2 結束)。說明為什麼這比在 CLAUDE.md 寫「不要 push」可靠。
  3. 管理反思(討論):海運併櫃(LCL)通常以「1 立方公尺(CBM)折算 1,000 公斤」比較體積與重量計費,但 AI 常套用空運或快遞的折算標準而算錯。這條規則應該寫在 CLAUDE.md、做成 Skill,還是寫成測試?請從出錯成本、維護者、適用範圍三個角度討論,並說明誰有權修改它。

國立臺中科技大學 國際貿易系 / 企業管理系 專用教材

《現代軟體工程:商學院的 AI 系統思維與 Agent 實踐》

作者:陳俊智 博士 Dr. Chun-Chih Chen

本書章節架構改編自陳鍾誠教授(金門大學)開源課程《現代軟體工程》(github.com/ccc115a/se,MIT 授權),內容針對商學院全面改寫與擴充。