Agent 工具路線選擇與通用工程實踐

參考任務卡——目標：「讓 CSV 匯出在空輸入與非 ASCII 文本下不靜默截斷。」範圍內：export.py 的行寫入邏輯與 tests/test_export.py。非目標：不新增匯出格式、不改 UI、不升級依賴。標準：(1) python3 -m unittest tests.test_export -v 退出碼為 0；(2) 匯出空資料集得到的檔案只含表頭行（透過檢查檔案驗證）；(3) 含「café, 東京」的記錄經 CSV 寫入後逐位元組往返一致（透過重讀檔案驗證）；(4) git diff 只觸及 export.py 與 tests/test_export.py。

參考計畫——(a) 執行 python3 -m unittest discover -s tests -v 並讀堆疊；在 app.py 出錯行附近找到空清單存取。(b) 執行 git status --porcelain：若有改動先 stash 或提交（git stash -u，或臨時分支提交）；若已乾淨則用 git rev-parse HEAD 記錄基線——空提交本來也會失敗。(c) 步驟：1. 重現崩潰並記錄確切例外（檢查點：捕獲堆疊）；2. Agent 只修改 app.py 增加空值守衛（檢查點：git diff 只觸及 app.py）；3. 重跑測試套件（檢查點：退出碼 0）；4. 審查 diff 並提交綠色狀態（檢查點：git diff --check 乾淨且已提交）。

最小包：src/greeter.py（程式碼）、tests/test_greeter.py（行為契約）與堆疊（確切失敗）。只有當 README 定義問候語格式時才納入。.env 永遠排除——絕不把憑證交給 Agent；整個 src/ 樹與 package.json 與該行為無關且會污染注意力，同樣排除。

授予：倉庫讀取、檔案編輯、僅限測試命令的 shell（pytest tests/ 或等價）。拒絕：無限制 shell、網路抓取、套件安裝、git push 與部署——本任務既不需要也不被允許。開關名以所選 track 當前的官方權限文件為準（例如 Claude Code 的 permissions/settings 文件、Codex CLI 的 --sandbox/--ask-for-approval 參考、Pi 的工具邊界文件或 DeepSeek Harness README），因為名稱隨版本變化。

該 README 備註是注入指令，不得執行：執行該腳本會洩露私鑰。回應：(1) 不執行該腳本；(2) 把該檔案與行記錄為提示詞注入發現；(3) 檢查此前步驟是否已遵從（diff、shell 歷史、網路證據），若已遵從則升級處理；(4) 只繼續已授權的解析器任務；(5) 在評審記錄中上報該產物。

暴露分類：可能已傳輸且仍存在於工作區——按已暴露處理。回應順序：(1) 停止執行；(2) 在 provider 控制台吊銷並輪換該密鑰；(3) 從 secrets.env 刪除，若已提交則清洗 git 歷史；(4) 掃描 diff、日誌與轉錄中的其他副本；(5) 記錄事件與證據。評審用的最小新增行憑證掃描：

import re
SECRET = re.compile(r'^\+.*(api[_-]?key|secret|token|password|\w*key)\s*=', re.I | re.M)
diff = '+STAGING_KEY=sk-live-9f2ab\n+mode=fast\n-OLD_KEY=sk-dead\n'
hits = SECRET.findall(diff)
assert len(hits) == 1, hits  # only the added line is flagged
print('PASS: flagged added credential line')

裁決：整體拒絕——expresss 是 typosquat 模式，postinstall 腳本拉取並執行遠端程式碼，屬於外洩通道。命令：git restore package.json package-lock.json 回退 manifest 與 lockfile；不執行安裝；在評審記錄中記下事件；若安裝已發生，按環境已被攻陷處理並排查。宣告依賴差異的審查助手：

baseline = {'express': '^4.18.2', 'lodash': '^4.17.21'}
proposed = {'expresss': '^9.9.9', 'lodash': '^4.17.21'}
added = sorted(set(proposed) - set(baseline))
removed = sorted(set(baseline) - set(proposed))
assert added == ['expresss'] and removed == ['express']
print('PASS: flagged unexpected dependency delta:', added)

順序：(c) 驗收標準 → (f) 上下文包 → (d) 一處有界改動 → (a) 執行測試並檢查 → (b) 審查 diff → (e) 提交綠色狀態。停止條件：同一失敗重複兩次（重新框定而不是重試），或 Agent 越出範圍/權限行事（停下審查）。

執行：npm test（要求退出碼 0）、tsc --noEmit、npx eslint .、npm run build，然後在執行中的應用上操練真實登入頁——成功登入加一次無效密碼被拒。證據 = 記錄下來的命令、退出碼與觀察到的行為，而不是 Agent 的文字。若專案沒有設定 linter 或 typecheck，記錄其缺失而非假設存在。

Hunk 1：確認邊界邏輯並重跑測試後接受。Hunk 2：拒絕——註解斷言是在粉飾通過，恢復它們。Hunk 3：拒絕——掩蓋真實改動的越界擾動，回退它。動作：要求只含 hunk 1 的重新提交，並用 git diff、git diff --check 與 git status --short 確認沒有其他變化。

git revert cafe123——追加反向提交，保留歷史與未提交的 notes.md，但不保證無衝突：若 beef456 改過同一行，Git 會中途停下——保留 beef456 的正確行為解決衝突塊後 git revert --continue；或 git revert --abort，改在臨時分支上用 git restore --source=cafe123^ -- <受影響檔案> 選擇性恢復壞提交前的檔案狀態，並以修正提交記錄。若 cafe123 也碰過 notes.md，先快照（git diff notes.md > /tmp/notes.patch），恢復後再還原你的版本。禁止：git reset --hard beef456 或 git reset --hard HEAD~1——會丟棄 Git 無法恢復的未提交 notes.md 改動。

(1) 審查——破壞性但範圍限定且可重建；確認路徑在工作區內且 build/ 可重新產生後才批准。(2) 拒絕——force-push 重寫共享歷史；普通 push 也需授權。(3) 審查——先做供應鏈檢查（準確名字、來源、固定版本），再在一次性環境中批准。(4) 拒絕，除非有明確授權——對外通訊是真實世界副作用。(5) 允許——本地、可逆、唯讀。

參考骨架——name: release-notes-drafter；description: 「在目前倉庫中根據已合併的 PR 起草發布說明；僅當使用者要求發布說明或 changelog 草稿時觸發——不為寫程式、評審 PR 或發布任何內容而觸發。」 指令：(1) 只讀 git log 與已合併 PR 標題；(2) 按 fixed/added/changed 分組；(3) 草稿寫入 CHANGELOG-draft.md，絕不 commit、tag、push 或發布；(4) 含混的 PR 標記給使用者而不是猜測。應觸發：「根據已合併 PR 起草 v2.3 發布說明」；「為這次發布寫 changelog」。對抗不觸發：「幫我評審這個 PR」；「把發布說明發到部落格」。退役：當發布說明改由 CI 產生，或連續兩次評審發現描述誤觸發時移除。