專欄 › 八、安全與 AI 協作 › 第 32 篇
用 Claude Code 開發 Go 微服務:規則、權限與安全審查
Building Go Microservices with Claude Code: Rules, Permissions and Security Review
把 Claude Code 接進訂單系統的開發:用 CLAUDE.md 寫下指令與規則、用 settings.json 的 allow/deny 限制它能做的事、用 hooks 自動 gofmt 與擋下受保護路徑,再搭配子代理、skills、plan 模式與先寫測試的流程,最後談提示注入與審查責任。
這篇的步驟
上一篇〈微服務的安全性:認證、授權、密鑰與供應鏈〉把訂單系統從威脅模型一路檢查到供應鏈。這篇把一個新角色加進開發流程:會讀程式碼、會改檔案、會執行指令的 AI 代理。它能幫上很多忙,但它本身也是一個需要被放進威脅模型的對象。
這篇要解決什麼
Claude Code 是 Anthropic 推出的代理式(agentic)程式開發工具,可以在終端機、IDE 擴充套件或桌面應用程式裡使用。和「在聊天視窗貼程式碼、再把回答複製回來」不同,它直接在你的專案目錄裡工作:讀檔案、搜尋程式碼、修改檔案、執行 go test 之類的指令,看結果之後再決定下一步。這種工作方式效率高,也代表它做錯事時影響更直接——它可以刪檔案、可以執行 git push,也可能讀到 .env。
這篇以訂單系統(example.com/shop)的 repo 為例,一步一步建立一套讓 AI 代理「有用但受控」的設定:
- 用
CLAUDE.md(或AGENTS.md)告訴它這個專案怎麼建置、怎麼測試、架構長什麼樣子、有哪些規則。 - 用
.claude/settings.json的權限規則,明確允許測試指令、禁止讀取密鑰與推送程式碼。 - 用 hooks 在它每次改完 Go 檔案後自動跑
gofmt與go vet,並擋下對受保護路徑的修改。 - 用子代理(subagent)處理專門的工作,例如安全審查;用 skills 把重複的流程變成一個指令。
- 用 plan 模式處理較大的變更、先寫表格驅動測試再寫實作、在獨立分支或 worktree 上工作。
- 最後談風險:提示注入、密鑰外洩、以及「AI 寫的程式誰負責」。
這篇提到的設定檔位置、欄位與指令,都以 Claude Code 官方文件(code.claude.com/docs)為準。工具更新很快,實際使用前請對照你安裝的版本與當時的文件;文中沒有把握的細節,會寫成一般原則而不是具體旗標。
第 1 步:先理解它怎麼工作——代理迴圈與控制的層次
Claude Code 的基本運作是一個迴圈:讀取你的需求與專案說明 → 決定要用哪個工具(讀檔、搜尋、編輯、執行 Bash 指令、抓網頁)→ 執行 → 看結果 → 決定下一步,直到它認為完成或需要問你。每一次工具呼叫,都會先經過權限檢查:有的動作預設不用問(在工作目錄裡讀檔),有的要你同意(修改檔案、執行大部分 shell 指令)。
圖:規劃、修改、跑測試、審查形成一個迴圈;每一次工具呼叫都會經過權限規則與 hooks。
控制它的方式可以分成四層,越往下越「硬」:
圖:CLAUDE.md 是指引,權限規則與 hooks 由工具強制執行,沙箱與作業系統權限是最後一道防線。
這個分層是整篇最重要的觀念。官方文件明確說明,CLAUDE.md 的內容是當作上下文提供給模型,不是強制設定;如果某件事「絕對不能發生」(例如修改正式環境的設定),就要用權限規則或 hooks 來擋,而不是只在 CLAUDE.md 裡寫「請不要這樣做」。反過來,權限規則擋得住動作,卻沒辦法告訴它「這個專案的錯誤要用 %w 包裝」,這種知識就屬於 CLAUDE.md。
| 想達成的事 | 放在哪裡 |
|---|---|
| 建置、測試指令、架構說明、程式風格 | CLAUDE.md |
不准讀 .env、不准 git push | settings.json 的 permissions.deny |
| 測試指令不用每次問 | settings.json 的 permissions.allow |
| 改完 Go 檔自動格式化、擋下受保護路徑 | hooks |
| 安全審查、寫測試這類專門工作 | 子代理(.claude/agents/) |
| 「新增一個 API 端點」這類重複流程 | skills(.claude/skills/) |
| 即使設定被繞過也碰不到正式環境 | 開發機上根本沒有正式環境的憑證 |
第 2 步:寫一份 CLAUDE.md——專案的工作說明書
每次開新的工作階段,Claude Code 都是從空白的上下文開始。CLAUDE.md 就是讓它每次都能讀到的專案說明:專案層級的放在 repo 根目錄的 ./CLAUDE.md 或 ./.claude/CLAUDE.md,提交進版本控制讓團隊共用;個人偏好放在 ~/.claude/CLAUDE.md(所有專案)或 ./CLAUDE.local.md(這個專案、不提交)。在專案裡執行 /init 可以讓它分析程式碼後產生一份初稿,再由你補上它自己看不出來的規則。
如果團隊同時使用其他會讀 AGENTS.md 的 AI 工具,可以只維護一份。依官方文件,較新版本的 Claude Code 在目錄裡沒有 CLAUDE.md 時會直接讀 AGENTS.md;兩者都有時只讀 CLAUDE.md。最穩定的做法是讓 CLAUDE.md 用 @AGENTS.md 這種 import 語法把它引進來,再補上 Claude Code 專屬的說明。
寫的原則是:具體、簡短、可以驗證。「寫好的程式碼」沒有用;「錯誤用 fmt.Errorf("...: %w", err) 包裝,不要只回傳 err」才有用。下面是訂單系統的範例:
# example.com/shop
線上商店的訂單系統:api-gateway、order、payment、inventory 四個 Go 服務。
## 指令
- 建置:`go build ./...`
- 單元測試:`go test -race ./...`(宣稱完成之前一定要跑,並貼出結果)
- 靜態檢查:`go vet ./...`、`gofmt -l .` 必須沒有輸出
- 漏洞:`govulncheck ./...`
- 整合測試:`go test -tags=integration ./internal/...`(需要 `docker compose up -d postgres nats`)
## 架構
- `cmd/<service>/main.go`:組裝依賴、啟動與優雅關閉,不放業務邏輯
- `internal/<domain>/`:handler.go(HTTP/gRPC)→ service.go(業務規則、授權)→ repository.go(SQL)
- `api/proto/`:gRPC 定義;改了要重新產生程式碼,不要手改產生的檔案
- `deploy/`:Dockerfile、Compose 與 Kubernetes 設定(命名空間 `shop`)
- Order 的金額 `Total` 是 int64「分」,不准用 float64
- 訂單狀態只有 pending、paid、cancelled,狀態轉換集中在 `internal/order/service.go`
## 規則
- 不得捏造:不確定的 API、套件版本、設定欄位,先查程式碼或文件,查不到就說不知道。
- 每個讀寫訂單的服務方法都要檢查擁有者(防 BOLA),並有「別人的訂單」測試案例。
- SQL 一律用佔位符參數;不准用 fmt.Sprintf 拼 SQL。
- 日誌不准出現 token、密碼、完整 Email。
- 新功能先寫表格驅動測試,確認測試失敗,再寫實作。
- 只用標準函式庫能解決的,不新增相依;要新增相依先問。
- 不准修改 `deploy/k8s/overlays/prod/` 與 `.github/workflows/`,需要改時說明原因由人處理。
- 完成時回報:改了哪些檔案、跑了哪些指令與結果、有哪些沒驗證到。幾個值得注意的地方。「宣稱完成之前一定要跑,並貼出結果」這條規則很實用:AI 代理有時會在沒有實際執行測試的情況下說「已完成」,要求它貼出結果,你就能一眼看出它有沒有跑。「不得捏造」則是針對它可能編出不存在的函式或套件 API。「不准修改某些目錄」寫在這裡是讓它知道規則與原因,真正的阻擋在第 4 步用 hook 做——這就是上一步說的分層。
CLAUDE.md 不要寫太長。它每次工作階段都會被載入,佔用上下文;內容越長,每一條被認真遵守的機率越低。大型專案可以把細節拆到 .claude/rules/ 底下依路徑套用的規則檔,或用 @docs/architecture.md 引入其他文件。
第 3 步:權限規則——明確允許什麼、禁止什麼
權限設定寫在 JSON 設定檔裡。團隊共用的放 .claude/settings.json 並提交;個人的放 .claude/settings.local.json(Claude Code 會把它排除在 git 之外);使用者層級的放 ~/.claude/settings.json;組織還可以發布管理員設定(managed settings),優先權最高、個人無法覆蓋。
permissions 底下有三個清單:allow(不用問就執行)、ask(每次都問)、deny(一律拒絕)。評估順序固定是 deny → ask → allow,第一個符合的規則決定結果,所以寬的 deny 規則不會被比較窄的 allow 規則開例外。規則的寫法是「工具名稱(範圍)」:
Bash(go test *):以go test開頭的指令。注意*前面的空格,Bash(go test*)也會符合go testx這種指令。Read(./.env)、Read(./secrets/**):路徑規則,語法類似 gitignore。Edit(...):適用於所有會修改檔案的內建工具。WebFetch(domain:pkg.go.dev):限定抓取的網域。
訂單系統的團隊設定如下,同時也包含第 4 步要用的 hooks:
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(go build *)",
"Bash(go test *)",
"Bash(go vet *)",
"Bash(gofmt *)",
"Bash(govulncheck *)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(git log *)",
"WebFetch(domain:pkg.go.dev)",
"WebFetch(domain:go.dev)"
],
"ask": ["Bash(git commit *)", "Bash(go get *)", "Bash(go mod tidy)", "Bash(docker compose *)"],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Read(./deploy/secrets/**)",
"Read(~/.kube/**)",
"Read(~/.aws/**)",
"Bash(git push *)",
"Bash(kubectl *)",
"Bash(curl *)",
"Bash(wget *)"
]
},
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-paths.sh"
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/go-fmt-vet.sh"
}
]
}
]
}
}設計思路是:會讀不會寫、在本機可逆的動作放 allow;會改變外部狀態或相依的放 ask;碰到密鑰、正式環境或對外網路的放 deny。 測試、建置、vet 每次都問只會讓人養成「無腦按同意」的習慣,反而更危險;而 git commit 放 ask 是讓你在每次提交前看一眼 diff。go get 與 go mod tidy 放 ask,是因為新增相依屬於供應鏈決策(上一篇第 8 步)。
這些規則有它的極限,官方文件也寫得很清楚,必須知道:
- Bash 規則是比對指令文字。
Bash(git push *)擋得住git push origin main,但擋不住git -C . push、sh -c 'git push'這類寫法。所以真正的保證不能只靠這條規則,而是要讓開發機上的 git 憑證本來就推不到受保護分支(分支保護,見下一篇)。 - Read 的 deny 規則會套用到內建的讀檔工具,以及它認得的
cat、head這類指令與重新導向;但如果執行的是一支自己去開檔案的 Python 或 Go 程式,規則就攔不到。需要作業系統層級的保證時,要啟用沙箱(sandbox)功能,或乾脆讓密鑰檔不存在於這台機器上。 - 專案的 allow 規則要在每個人信任這個資料夾之後才生效;deny 與 ask 規則則立刻生效。這是為了避免你 clone 一個陌生 repo 時,它的設定自動放行一堆指令。
權限模式(permission mode)是另一個維度。預設模式(介面上稱為 Manual)會依上面的規則詢問;acceptEdits 自動接受檔案修改;plan 只讀不改(第 6 步);bypassPermissions 幾乎跳過所有檢查。終端機裡可以用 Shift+Tab 在幾個模式之間切換,啟動時也能用 --permission-mode 指定。bypassPermissions 只適合在完全隔離、可以丟掉的環境(例如沒有任何憑證的容器)裡使用,不要在日常開發機上開。
第 4 步:用 hooks 把規則變成自動執行的檢查
hooks 是在特定事件發生時,由 Claude Code 執行你寫的指令。和 CLAUDE.md 不同,hooks 一定會跑,不靠模型「記得」。常用的事件有:
| 事件 | 時機 | 典型用途 |
|---|---|---|
PreToolUse | 工具執行之前 | 擋下危險指令、保護特定路徑 |
PostToolUse | 工具成功執行之後 | 格式化、lint、跑相關測試 |
UserPromptSubmit | 你送出訊息時 | 補充上下文、檢查訊息裡有沒有貼上密鑰 |
Stop | 它準備結束回合時 | 檢查是否真的跑過測試 |
SessionStart | 工作階段開始 | 載入當前分支、待辦等資訊 |
hook 透過標準輸入收到一份 JSON,裡面有 tool_name 與 tool_input;對 Edit、Write 這些檔案工具,tool_input.file_path 一定是絕對路徑。hook 的結束碼決定結果:0 代表沒有意見、照一般的權限流程走;2 代表阻擋,標準錯誤輸出的內容會回饋給 Claude,讓它知道為什麼被擋;其他非零結束碼只算非阻擋性的錯誤。要強制執行政策就要用 exit 2。上一步設定裡用到的兩支腳本如下:
#!/usr/bin/env bash
# .claude/hooks/protect-paths.sh(PreToolUse,matcher: Edit|Write)
# 擋下對正式環境設定、CI 與 Claude 設定本身的修改。
set -uo pipefail
file=$(jq -r '.tool_input.file_path // empty')
rel=${file#"$CLAUDE_PROJECT_DIR"/}
case "$rel" in
deploy/k8s/overlays/prod/* | .github/workflows/* | .claude/settings.json | .claude/hooks/*)
echo "受保護路徑:${rel}。請說明要改什麼與原因,由人來修改。" >&2
exit 2
;;
esac
exit 0
#!/usr/bin/env bash
# .claude/hooks/go-fmt-vet.sh(PostToolUse,matcher: Edit|Write)
# 改完 Go 檔就格式化並 vet 所在套件;vet 失敗時把訊息回饋給 Claude。
set -uo pipefail
file=$(jq -r '.tool_input.file_path // empty')
[[ "$file" == *.go ]] || exit 0
gofmt -w "$file"
pkg="./$(dirname "${file#"$CLAUDE_PROJECT_DIR"/}")"
if ! out=$(cd "$CLAUDE_PROJECT_DIR" && go vet "$pkg" 2>&1); then
echo "go vet ${pkg} 失敗:" >&2
echo "$out" >&2
exit 2
fi
exit 0這兩支是分開的檔案,記得 chmod +x。第一支保護的路徑裡包含 .claude/settings.json 與 .claude/hooks/ 本身——如果代理可以修改自己的權限設定與 hooks,前面所有限制都能被它(或被注入的指令)拿掉。第二支在 PostToolUse 跑,此時檔案已經寫入,exit 2 不會撤銷修改,但會把 go vet 的錯誤訊息交給 Claude,讓它在同一個回合裡修正,不必等你發現。
hook 會以你的使用者權限執行任意指令,所以 hook 腳本本身要像正式程式碼一樣審查。另外要注意,從陌生 repo 開啟 Claude Code 時,那個 repo 的 .claude/settings.json 也可能帶著 hooks;在非互動模式(claude -p)下尤其要小心,官方文件提到這種模式不會跳出信任資料夾的對話框,CI 等腳本環境可以用 --bare 讓它不自動載入專案的 hooks 與設定。
第 5 步:子代理與 skills——把專門工作與重複流程固定下來
子代理是有自己系統提示、自己工具清單的專門代理。主對話把工作交給它,它在獨立的上下文裡完成,只把結論交回來。好處有兩個:主對話的上下文不會被大量搜尋結果塞滿;以及可以給它比主代理更少的權限。子代理是放在 .claude/agents/(專案)或 ~/.claude/agents/(個人)的 Markdown 檔,前面用 YAML frontmatter 描述,name 與 description 必填,tools 與 model 可選:
---
name: security-reviewer
description: 審查 Go 微服務的變更是否有安全問題。修改 handler、service、repository、SQL 或身分驗證相關程式碼之後,或開 PR 之前使用。
tools: Read, Grep, Glob, Bash
model: inherit
---
你是這個訂單系統的安全審查者。只審查,不修改任何檔案。
1. 用 `git diff main...HEAD` 取得變更範圍,只看有改到的部分與它們的呼叫者。
2. 逐項檢查:
- 每個讀寫 Order 的服務方法是否比對 `UserID` 與呼叫者身分(BOLA);不屬於時是否回 404。
- 管理功能(退款、後台)是否檢查角色。
- SQL 是否全部使用佔位符;排序欄位是否走白名單。
- JSON 解碼是否有大小上限與 `DisallowUnknownFields`。
- 日誌或錯誤訊息是否可能帶出 token、密碼、完整 Email。
- 是否新增相依;是否出現 `InsecureSkipVerify`。
3. 每個發現都要寫出:檔案與行號、從輸入到問題點的路徑、可以怎麼利用、建議修法。
沒辦法指出具體路徑的,標成「待確認」,不要當成確定的漏洞。
4. 沒有發現時直接說沒有,不要為了湊數而列出風格問題。使用時直接說「用 security-reviewer 子代理審查這個分支」即可。第 3 點的要求很重要:AI 審查常見的問題是列出一堆「可能」的漏洞,其中不少經不起追查。要求它寫出從輸入到問題點的路徑,你驗證時就有具體的東西可以對照,也能過濾掉臆測。另一個常見的子代理是「測試撰寫者」:只負責依規格寫出表格驅動測試,不碰實作。
skills 則是把一段可重複的工作流程存成一個指令。專案的 skill 放在 .claude/skills/<名稱>/SKILL.md,可以用 /名稱 直接呼叫,$ARGUMENTS 會被替換成呼叫時給的參數。早期的「自訂斜線指令」(.claude/commands/*.md)已經併入 skills,舊檔案仍然可以用。下面是「新增一個 API 端點」的流程:
---
name: new-endpoint
description: 依照專案慣例在指定服務新增一個 HTTP 端點(測試先行)
disable-model-invocation: true
argument-hint: '<service> <METHOD> <path> <說明>'
---
在訂單系統新增端點:$ARGUMENTS
1. 讀 CLAUDE.md 與 `internal/<service>/` 現有的 handler.go、service.go、repository.go,沿用相同結構。
2. 先在 service_test.go 寫表格驅動測試,至少包含:正常情況、輸入不合法、別人的資源(應回 ErrNotFound)。
執行 `go test -race ./internal/<service>/...`,確認新測試失敗。
3. 實作 service 方法(含擁有者檢查)→ repository(參數化 SQL)→ handler(MaxBytesReader、DisallowUnknownFields)。
4. 在 handler_test.go 用 httptest 補上 HTTP 層的測試。
5. 執行 `go vet ./...` 與 `go test -race ./...`,貼出結果。
6. 用 security-reviewer 子代理審查這次變更,列出它的發現,並說明你如何確認或排除每一項。disable-model-invocation: true 讓這個 skill 只在你主動輸入 /new-endpoint 時執行,模型不會自己決定要不要用它——會改動很多檔案的流程,最好由人觸發。把流程寫成 skill 的價值不只是省打字:它是一份可以審查、可以版本控制的流程說明,團隊每個人用的是同一套步驟,下一篇會把同樣的想法延伸到 CI。
第 6 步:plan 模式、測試先行與在分支上工作
對於較大的變更(例如「取消訂單時要釋放庫存並發出事件」),不要一開始就讓它動手。plan 模式讓它只讀檔案、執行唯讀的探索指令,然後寫出計畫,不修改原始碼;你核准計畫之後才離開 plan 模式開始修改。在終端機裡可以用 Shift+Tab 切換,或用 claude --permission-mode plan 啟動。看計畫時重點檢查三件事:它找到的修改位置對不對(有沒有漏掉 gRPC handler、事件消費者);它打算新增的東西是不是真的需要;它怎麼驗證完成。
計畫確定後,用測試先行的迴圈。先要求它只寫測試,跑一次確認測試失敗,再寫實作讓測試通過。這個順序對 AI 代理特別重要:如果先寫實作再寫測試,測試很容易只是「描述程式現在的行為」,包括它的錯誤。下面是取消訂單的測試,它是在實作之前就寫好的:
package order
import (
"errors"
"testing"
)
func TestCancel(t *testing.T) {
tests := []struct {
name string
status Status
caller string
wantErr error
wantStatus Status
}{
{"擁有者取消 pending", StatusPending, "alice", nil, StatusCancelled},
{"重複取消是冪等的", StatusCancelled, "alice", nil, StatusCancelled},
{"已付款不能直接取消", StatusPaid, "alice", ErrNotCancelable, StatusPaid},
{"別人的訂單", StatusPending, "bob", ErrNotOwner, StatusPending},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
o := &Order{ID: "o-1", UserID: "alice", Total: 4500, Status: tt.status}
err := Cancel(o, tt.caller)
if !errors.Is(err, tt.wantErr) {
t.Fatalf("Cancel() error = %v, want %v", err, tt.wantErr)
}
if o.Status != tt.wantStatus {
t.Errorf("status = %q, want %q", o.Status, tt.wantStatus)
}
})
}
}你審查的重點應該放在測試上,而不是實作:這四列是不是涵蓋了真正的業務規則?「已付款不能直接取消」是對的嗎(也許應該走退款流程)?「重複取消是冪等的」符合〈冪等與分散式鎖〉的設計嗎?測試對了,實作錯了會被測試抓到;測試錯了,實作再漂亮也是錯的。實作(Cancel 函式、ErrNotOwner、ErrNotCancelable)由它接著寫,並以 go test -race ./internal/order/... 確認通過。
最後,所有修改都在分支上進行,不要讓它直接在 main 上改。git worktree 讓同一個 repo 有多個獨立的工作目錄,各自在不同分支上;Claude Code 的 --worktree(或 -w)旗標可以建立一個 worktree 並在裡面啟動,預設放在 .claude/worktrees/<名稱>/。這樣你可以讓一個工作階段做新功能、另一個修 bug,彼此不干擾;做完就是一個普通的分支,用 git diff main...HEAD 審查、開 PR,跟同事寫的程式碼走同一套流程。
第 7 步:用它做安全審查,但每一項發現都要自己驗證
讓 AI 審查一份 diff 的安全問題,是成本很低、收穫不錯的用法:它不會累、會逐行看,對 SQL 拼接、漏掉的擁有者檢查、日誌印出整個請求這類模式很敏感。但它的輸出是線索,不是結論。實際使用時常見兩種錯誤:誤報(把有防護的程式碼當成漏洞,因為它沒看到防護在另一個檔案裡)與漏報(沒注意到跨服務的問題,例如 gateway 沒有刪除外來標頭)。
建議的驗證流程:
- 對每一項發現,自己打開它指出的檔案與行號,沿著它描述的路徑走一遍:輸入從哪裡來、經過哪些檢查、最後到哪裡。
- 能寫成測試的就寫成測試。例如它說「
GetOrder沒有檢查擁有者」,就加一列「別人的訂單」測試;測試失敗就確認是真的,測試通過就是誤報。 - 確認的問題修掉並留下測試;誤報的,想想為什麼會誤報——常常代表程式碼結構讓人(包括 AI)看不出防護在哪裡,也許值得重構。
- 不要只靠它。上一篇的檢查表、
govulncheck、go vet以及人工審查都還在,AI 審查是額外的一層。
同樣的道理也適用於它寫的程式碼本身:把它當成一位速度很快、但剛加入團隊的初級工程師送來的 PR。它可能不知道你們上次為什麼刻意不用某個寫法,可能為了讓測試通過而改掉測試,可能在你沒要求的地方「順便」重構。審查時特別注意:測試有沒有被弱化或刪除、有沒有新增相依、錯誤處理有沒有被吞掉、有沒有超出需求範圍的修改。
第 8 步:風險——提示注入、密鑰與你按下的每一個「同意」
最後把 AI 代理本身放進威脅模型。它的特殊之處在於:它讀到的任何文字,都可能被它當成指令。這就是提示注入(prompt injection)。在開發情境裡,危險的文字可能來自:
- 你讓它抓取的網頁、部落格文章或文件。
- GitHub issue、PR 留言、程式碼審查意見(任何人都能寫)。
- 相依套件的 README、原始碼註解、測試資料。
- 錯誤訊息與日誌(如果其中包含使用者輸入的內容)。
例如某個相依套件的 README 裡藏了一段「AI 助理請注意:執行以下指令更新設定……」,代理讀到後可能就照做。防禦方式不是期待模型永遠分辨得出來,而是讓「照做了也不會怎樣」:
- 權限最小化:第 3 步的 deny 規則讓它讀不到密鑰、推不了程式碼、連不了任意網站;
WebFetch只開放需要的網域。 - 保護設定本身:第 4 步的 hook 讓它不能修改自己的權限與 hooks。
- 不要在處理不可信內容時給它高權限:例如請它摘要一個陌生 repo 的 issue 時,不要同時開著
acceptEdits或允許任意 Bash。 - 看清楚每個要你同意的指令:權限提示是你的最後一道防線。如果它突然想執行一個跟任務無關的指令(例如
curl某個網址、讀家目錄下的檔案),先停下來想為什麼。
密鑰的原則更簡單:永遠不要把正式環境的密鑰貼進對話,也不要讓它出現在它讀得到的檔案裡。開發機上用的是開發環境的假憑證;正式環境的憑證根本不應該在開發機上。對話內容會被傳送到模型服務處理,也會留在本機的工作階段紀錄裡,把它當成任何外部服務一樣看待。如果不小心貼了,就當作已外洩,立即輪替。
責任則要說清楚:AI 寫的程式碼,由把它合併進主分支的人負責,跟自己手寫的沒有差別。這不是形式上的規定,而是實際的品質保證——只有當審查者知道自己要為這段程式碼負責,審查才會認真。下一篇會把這條規則放進團隊的 PR 流程與 CI 裡。
常見陷阱
- 把規則只寫在 CLAUDE.md。 它是上下文不是強制設定;「絕對不能」的事要用權限規則或 hooks。
- 測試、建置也要每次按同意。 結果養成無腦按同意的習慣,真正危險的指令出現時也順手按下去。
- 以為
Bash(git push *)就擋住了推送。 指令有很多種寫法;真正的保證來自分支保護與憑證權限。 - 代理可以修改自己的設定檔與 hooks。 等於所有限制都可以被拿掉。
- 讓它先寫實作再補測試。 測試變成描述現有行為,連錯誤一起鎖死。
- 它說「完成」就相信。 要求它貼出實際執行的指令與結果,並自己再跑一次。
- 把 AI 安全審查的結果直接當結論。 每一項都要沿著路徑驗證,能寫成測試就寫成測試。
- 在
main上直接讓它改。 改壞了很難乾淨地還原,也不容易審查。 - 把正式環境的密鑰貼進對話。 貼了就要輪替。
- 對陌生 repo 直接執行
claude -p。 它的專案設定與 hooks 可能會被載入;CI 與腳本考慮用--bare。
重點整理
- Claude Code 是在你的專案裡讀檔、改檔、執行指令的代理;控制它分四層:CLAUDE.md(指引)、權限規則與 hooks(強制)、沙箱與憑證隔離(最後防線)。
CLAUDE.md寫建置與測試指令、架構地圖與具體規則,例如「宣稱完成前要跑go test -race並貼出結果」「不得捏造」;與其他工具共用時可以 importAGENTS.md。.claude/settings.json:測試、建置放 allow,提交與新增相依放 ask,密鑰、推送、正式環境與任意網路放 deny;順序是 deny → ask → allow。- hooks 一定會執行:
PreToolUse用exit 2擋下受保護路徑,PostToolUse自動gofmt與go vet;保護好設定檔與 hooks 本身。 - 子代理處理專門工作(安全審查、寫測試)並可以給更少的工具;skills 把重複流程變成可以審查的
/指令。 - 大變更用 plan 模式先看計畫;先寫表格驅動測試再寫實作;在分支或 worktree 上工作。
- AI 的審查與程式碼都是線索與草稿:逐項驗證,把它當初級工程師的 PR 來審。
- 提示注入的防禦是讓「照做了也不會怎樣」;不貼密鑰;合併的人對程式碼負責。
下一篇
一個人用好 AI 代理,靠的是本機的規則與權限;整個團隊要用好,就需要把它接進 PR、CI 與審查流程。下一篇〈AI 工作流接進團隊流程:PR 審查、CI 與人工把關〉談 AI 在開發生命週期裡的位置、CI 裡的 AI 審查,以及哪些關卡必須由人與機器規則把守。