每一條規則背後都是一次教訓
你有沒有想過，你交給 AI 的每一句指令，就像把一把裝了子彈的槍，交給一個動作飛快卻沒有常識的新手實習生？因為它的執行力有 100 分，判斷力卻是 0 分，所以半年內我的 AI Agent 幫我刪過關鍵檔案、外洩過 API Key，還把三天的架構討論忘得一乾二淨，7 項致命翻車，每一次都讓我想砸爛螢幕。而最諷刺的是，我現在系統裡那份安全規則清單，沒有任何一條是我事先想到的，全是用血淚換來的補丁，100% 都是。
我把這套規則叫做 AI Agent 踩坑防線：一組從真實失敗裡歸納出來的系統化護欄，涵蓋安全攔截、記憶持久化、SOP 路由與跨平台同步，目的只有一個，就是擋住 AI 自動化過程中那些會出人命的破壞性錯誤。
過去半年，我用 Claude Code 建了一套 Agent 工作流，每天處理文獻管理、程式開發與文件撰寫。因為用得愈深，犯的錯就愈痛，下面這七個代價最大，每一個都是真金白銀的時間燒掉之後，才換回來的一條紅線。
錯誤 1：被 AI 寫的 rm -rf 燒過
發生了什麼
有一次我請 AI 幫忙清理暫存檔案，它很「積極」地寫了一個包含 rm -rf 的清理腳本。這正是那個新手實習生的毛病：你叫他打掃，他不只掃地，還順手把桌上的合約書一起丟了。因為當時我在趕工，掃了一眼覺得沒問題就直接讓它跑，結果一個重要的設定目錄被連帶刪掉了。
由於沒有備份的部分就再也撈不回來，我整整燒了 2 小時 從 Time Machine 備份撈檔案。rm -rf 這種指令按下去的瞬間很安靜，後果要等你回頭才發現，而 AI 並不會在動手前多看你一眼、問一句「你確定嗎」，它就是會直接按下去。
於是我加了一條死規則：rm 全面禁止，改用 mv 檔案 _DELETE_檔案。因為檔案只是換個名字，退路就留住了，等我確認確實不要，再手動清掉。那一次 rm -rf 讓我白白燒掉 2 小時 撈備份，軟刪除規則就是這樣被逼出來的。
這就是 Hook 守門系統 裡第一條被加入的攔截規則。
錯誤 2：沒有守門員，AI 改了不該改的設定檔
發生了什麼
有一次我請 AI 修改一個功能模組，它自作主張「順便」調了環境設定檔。麻煩的是那個設定檔管著整個系統的路徑設定，牽一髮動全身，所以被它一改，系統就全壞了。
我搞了一個多小時的 debug 才抓到根源。最陰險的是，AI 改的那幾行看起來完全合理，又混在一堆正常修改裡面，因此第一眼根本看不出來是它動的手。這不是粗心，而是「看起來對、實際上要命」的那種錯。
於是我建了 PreToolUse Hook，也就是守門員機制：AI 在寫入任何檔案之前，守門員腳本會先檢查目標是否落在「不准碰清單」裡，只要在清單上就亮紅燈，直接警告或封鎖。也正因為擋在寫入這一關，AI 再怎麼積極也得先過這一道。
我現在的敏感檔案清單包含：
| 檔案類型 | 範例 | 實際保護 |
|---|---|---|
| 環境變數 | .env、.env.local |
封鎖，要改只能人工來 |
| 情節記憶 | episodic.jsonl |
schema 閘：必填欄位缺一個就擋 |
| 所有 JSONL | *.jsonl |
寫入時驗證最後一行是不是合法 JSON |
| 生成產物 | repo 根目錄的 pdf/png/csv | 封鎖，強制指定輸出路徑 |
| 系統核心 | CLAUDE.md、AGENTS.md |
只在第二台機器封鎖，改規則一律回主機 |
這份表是「已經接上守門員的」，不是「應該被保護的」。差別很重要。我的 memory/fact.yml 存著所有核心偏好，現在還沒接上任何 hook，AI 想寫就寫得進去，擋它的只有我自己記得盯著。.gitignore 那類 git 設定檔我也一直想加，加到今天還沒加。守門員只擋得住你真的寫進腳本裡的東西。清單上沒有的，就是沒在守。
完整的 Hook 設計請看 Hook 守門系統：AI 寫的每一行 code 都過品管。
錯誤 3：跨 session 上下文全失
某天我跟 AI 花了兩小時討論架構決策，敲定了技術方向和實作細節，隔天開新 session 想接著做，它卻什麼都不記得，前一天的東西全部要重講，到了第三天情況一模一樣。這就像那個新手實習生每天早上都帶著一顆全新的腦袋走進辦公室，昨天講過的全部蒸發。
因為每次重新解釋背景就燒掉 20 分鐘，一週累積下來超過正常耗時的 3 倍。更糟的是，由於 AI 根本不知道前一天決定了什麼，它偶爾會做出跟昨天自相矛盾的決策：你說往東，它昨天同意了，今天卻自己往西走，還振振有詞。這種失憶式翻車累積起來，一週浪費的時間比寫新功能還多。
於是我建了 三層記憶架構，替 AI 分別裝上短期、中期、長期三種記憶：
- fact.yml：存長期不變的事實和偏好，永遠都在。
- episodic.jsonl：存每一次重要的決策和教訓，翻開就能回顧當初為什麼這樣決定。
- scratchpad.md：存當前任務的進度和暫存筆記，用完就換。
現在每次開新 session，AI 都會自動讀取這三層記憶，接續之前的工作，因此架構決策不會再遺失，光是省下的重複說明，每週大約就有 3 小時。
錯誤 4：同一指令重複輸入 N 次
寫科普有固定流程：定大綱、分段寫、去 AI 感、格式化。因為每開一篇新文章就得把流程重講一遍，幾個月下來，「幫我用這個格式寫科普文章，先列大綱，然後……」這段話我大概貼了超過 50 次。
這純粹是在燒時間，而且每次手動下指令，細節都會有微妙差異，文章品質也跟著飄。由於那個新手實習生永遠記不住你的偏好，每次都要你從頭交代一遍。
後來我建了 Skill 路由引擎，把每個重複性工作流打包成一個 SOP，綁上觸發詞。現在只要打「寫科普」三個字，系統就自動載入整套流程，格式、步驟、品質檢查清單全包，於是原本每次要花 10 分鐘 講的流程，壓縮成 3 秒 觸發。
詳細的 Skill 路由設計請看 Skill 路由引擎：讓 AI 自動選擇正確工作流。
錯誤 5：多平台記憶不同步
我同時用 Claude Code、Copilot CLI、Gemini CLI。Claude Code 裡我設好了「台灣繁體中文」「rm 禁止」「統計用 R」，但在 Copilot CLI 裡，這些規則通通不存在。某次用 Copilot 做事，AI 直接噴簡體中文回我，還差點跑一個 rm 指令。
這就翻車了。同一套安全習慣，在 A 工具養成，換到 B 工具卻直接歸零。因為多平台環境最危險的地方，不是某個平台的漏洞，而是你以為「另一邊也有護欄」，實際上根本沒有，規則一旦逃出某個平台的管轄，出事就只是時間問題。
補一句現在的做法，免得你照著當年的我踩同一個坑。這件事之後，我把 Copilot 從「拿來做事的工具」降級成「唯讀的 code review 關卡」。它現在只能看、只能給意見，不能改檔、不能跑指令。要它動手的那條路，我直接封掉了。工具本身沒有錯，錯在我當時把一個沒讀到我規則的工具，放到了會動手的位置上。
後來我建了 AGENTS.md 單一真相源機制，把共用規則集中在一份 AGENTS.md，其他後端的設定檔用 symlink 指過去，而不是各自複製一份副本。因此只要改一次，Claude Code、Copilot、Gemini 這 3 套 讀得到那份檔案的工具就同時生效。
完整的多平台同步攻略請看 多平台同步：一套記憶跑遍 Claude/Copilot/Gemini。
錯誤 6：API Key 一度被 commit 到 git
我請 AI 寫一個串接外部服務的腳本，它直接把 API Key 寫死在程式碼裡，而我沒看仔細就 commit 了。就算是 private repo 也沒差，因為安全原則就是安全原則，不會因為倉庫是私有的就可以把金鑰攤在原始碼裡。
發現後我馬上 revoke 舊 key、重新產生，再用 git filter-branch 清掉整段 history，前後搞了 40 分鐘，中間還得一直盯著 API 用量儀表板，深怕有人已經拿我的 key 去跑了幾萬次請求。那種冷汗，比 debug 難受十倍。
於是現在的防線是：API Key 嚴禁 hardcode，一律走環境變數。.gitignore 裡加入 .env、*.key、credentials.json，再上一層 pre-commit hook 掃描疑似 key 的字串，而這條規則同時寫在 CLAUDE.md 和 AGENTS.md 裡，所有平台都讀得到。因此三道關卡疊起來，漏了一道還有兩道。
錯誤 7：進程命名裸用 python3，找不到是哪個腳本在跑
我讓 AI 跑了幾個背景任務，全部用 python3 啟動。某天系統明顯變慢，ps aux 一查，四個 python3 進程並排在那裡，我卻分不出哪個是哪個。就像那個新手實習生，做了一堆事卻沒留下任何名牌。
因為分不出來，我只好逐一用 lsof 查每個進程開了什麼檔案，搞半天才勉強判斷出來，最後乾脆全部 kill 掉重來。這種偵探式 debug 每次都要 15 到 30 分鐘，而且隨著自動化任務愈跑愈多，這種無名進程只會愈來愈多，場面也愈來愈亂。
於是我立了新規範：背景任務禁止裸用 python3、node、bash，必須帶完整腳本路徑。python3 script.py 不行，要寫成 python3 scripts/lit_pipeline.py，背景任務還得再加一個描述性標籤。這樣一來，原本要花 30 分鐘 的偵探式辨識，就變成一眼就能判斷是哪個腳本在跑。
你可能覺得這是小事，但等你系統裡同時跑著十幾個自動化任務時，就不會這麼想了。
七個教訓，一句話總結
| # | 錯誤 | 防線 | 對應系統模組 |
|---|---|---|---|
| 1 | rm -rf 刪錯檔 | 軟刪除規則 | Hook 守門 |
| 2 | 改到不該改的檔案 | 敏感檔案攔截 | Hook 守門 |
| 3 | 跨 session 失憶 | 三層記憶寫入 | 記憶架構 |
| 4 | 重複下同一指令 | SOP 觸發路由 | Skill 路由 |
| 5 | 多平台規則不同步 | AGENTS.md 注入 | 跨平台同步 |
| 6 | API Key 外洩 | 環境變數 + gitignore | 安全政策 |
| 7 | 進程裸用泛稱 | 完整路徑命名規範 | 安全政策 |
這 7 條 防線，覆蓋了 AI Agent 自動化裡最常見的破壞性風險。每一條都簡單到你會懷疑這種小事有沒有必要寫成規則，但答案是有必要。
因為出事的時候，你一定在趕工，一定同時想著另外三件事，一定覺得「這次不會出問題」，然後就真的出問題了。不過防線也有它的侷限：它防得住已知的錯，卻防不住你從沒想過的新花樣。所以這些規則不是給清醒的你用的，而是給那個凌晨兩點、腦袋半打瞌睡的你準備的。
如果你想看這些防線在完整系統裡怎麼串接，可以看 從零建一個完整 Agent 工作流（下）：實作部署，那裡有從頭到尾的七步驟建置流程。
想更深入？
我整理了一份《Claude Code 快速上手速查表》，涵蓋安裝、CLAUDE.md 配置、記憶系統基礎、常用指令一頁搞定。裡面也包含了這七條安全規則的速查版。
常見問題
AI Agent 最容易犯什麼類型的錯？
「過度積極」。你叫它改 A，它自己判斷 B 也該順便調。你沒要求，它動手了。守門員機制（Hook）就是防這個：不管 AI 多有幹勁，出手前都得先過檢查哨。
這些錯誤只有 Claude Code 會犯嗎？
不是。任何有檔案操作能力的 AI 工具都可能犯。差別在於有沒有內建守門員機制來防。Claude Code 有原生 Hook，其他工具要自己用 git hook 加外部腳本拼湊，能做但體驗差很遠。
軟刪除規則用久了不會佔很多空間嗎？
不會。半年下來 _DELETE_ 前綴的檔案加起來大約 40 MB。每月手動清一次，或設排程自動清超過 30 天的舊檔。40 MB，你的硬碟不會有感覺。
Hook 守門員會拖慢 AI 回應速度嗎？
幾乎感覺不到。守門員腳本只做簡單字串比對，執行時間在毫秒等級。跟 AI 模型本身的回應時間比完全可以忽略，像感應式門鎖，走過去就開了。
這七條防線能擋住所有風險嗎？
擋不住。規則是被動的，只能攔截你預先想到的風險。AI 如果用你沒寫進攔截清單的方式搞破壞，防線擋不住。所以規則要持續更新，每次出事就加一條。沒有一勞永逸這回事。
API Key 被 commit 到 git 了怎麼辦？
馬上 revoke 舊 key、重新產生，用 git filter-branch 清 history。然後補三道防線：環境變數取代 hardcode、.gitignore 加入 .env 和 credentials 檔案、pre-commit hook 掃描疑似 key 字串。三關一起上。