AI Agent 寫 Code 為什麼會失控？因為你沒給它這份文件

本文是社群貼文的完整延伸版。社群版講了核心概念，本文加上四大準則的實務拆解、黃金標準檔案的建立方法、以及台灣企業實際導入 AI coding agent 時最常踩的坑。

---

重點回顧

Stack Overflow Blog 在 2026 年 3 月 26 日發了一篇文章，直接點出現在軟體工程的現實：工程師越來越少親手寫程式碼，越來越多是讓 coding agent 幫忙寫，自己做設計和 code review。

問題來了。這個 AI agent 要進你們公司的 codebase，它必須遵守你們的規範。但它沒辦法靠「感覺」學會規範。它只能靠你把規範寫清楚。

用一個口語的說法：新人是靠「vibe」理解規矩的，AI agent 不懂 vibe。

這篇文章集合了 Sourcegraph CEO Quinn Slack、Graphite CTO Greg Foster、Heroku 首席架構師 Vish Abrams、Google DeepMind 的 Logan Kilpatrick 等業界重量級人物的觀點，整理出一套完整的 AI coding guidelines 建立方法論。

對正在導入 AI 開發工具的台灣企業來說，這不是理論，這是明天上班就要用的東西。

---

為什麼 AI Agent 無法像新人一樣學習

我在帶企業培訓的時候，常常遇到一種狀況：有個主管說「我們早就給 AI 看過公司規範文件了，但它寫出來的程式碼還是不一樣」。

我問：你的規範文件是給人看的，還是給 AI 看的？

通常沉默。

人在閱讀規範文件的時候，會用背景知識、職業直覺、過去的工作經驗去補足那些文件裡沒寫的空白。AI agent 不行。它只有文字。你沒寫的，它就不管。

Graphite 的 CTO Greg Foster 說得很直接：

「工程師在寫程式碼的時候，一邊在吸收整個 codebase 的脈絡。這種隱性知識（tacit knowledge）需要被攤開來，寫成明確規則，還要給每條規則加上客觀的理由。」

這就是問題所在。過去我們的 coding guidelines 是給人看的，寫得「夠用就好」。現在 AI agent 要用這些文件工作，那些「大家心照不宣」的地方，全部要重寫。

---

【獨家】四大 AI Agent 必備編碼準則，逐一拆解

根據 Stack Overflow 的整理，加上我在 400+ 場企業培訓中的觀察，這四個區塊是 AI agent 特別需要明確指引的。每一個我都會加上台灣企業常見的踩坑案例。

1. 命名規範：AI 最容易亂來的地方

這是軟體工程裡被公認最難的事之一。如果你的 codebase 裡有些地方用 camelCase、有些地方用 underscore_style，你要在文件裡說清楚什麼時候用哪個，為什麼。

Heroku 的首席架構師 Vish Abrams 說：「DRY 原則、12-Factor 應用、設定和程式碼分離——這些對資深工程師來說是常識，但你不告訴 AI，它就隨便做。」

實際案例：我見過一個台灣金融業客戶，他們的 codebase 裡前端用 camelCase、後端 API 用 snake_case、資料庫欄位用 PascalCase。人類工程師做了三年，自然知道「在哪一層用哪個」。但 AI agent 不知道。它可能幫你生出一個 FactoryBuilderBuilderFactory，你不能怪它，你沒說不行。

怎麼修：在你的 agents.md 裡明確寫出每一層的命名規則，附上三個正確範例和三個錯誤範例。不用多，但要精確。

2. 排版與格式：小事不小

Tab 還是 space？函式的大括號換行還是不換行？這些可能在你的 IDE 裡已經有 Prettier 在管，但 AI 在生成程式碼的時候不一定會跟著走。

研究顯示，程式碼的排版方式會影響理解速度，所以這個「小事」並不小。

關鍵提醒：很多團隊以為「我們有 Prettier / ESLint，AI 生成的程式碼會自動被格式化」。但問題是，如果 AI 生成的程式碼結構就不對（例如把應該分行的邏輯全塞在一行），formatter 改完格式後，邏輯可讀性可能更差。

3. 例外處理和 Log：Production 品質的分水嶺

程式要怎麼失敗？什麼狀況下要 log？log 用什麼格式？這些是 production 品質的核心，也是 AI agent 最常不處理好的地方。

我的觀察：在培訓現場，我最常看到的問題就是這個。AI 寫了一個「能跑」的版本，功能測試全過。但沒有 error handling、沒有 log、沒有 retry logic。上線第一天就出事，而且完全看不到任何 log 來除錯。

你不說，它可能幫你寫一個沒有任何 error handling 的版本，跑得很開心，但線上一掛就什麼都看不到。

建議：在 guidelines 裡加一條「所有外部 API 呼叫必須有 try-catch + structured log」，附上你們公司標準的 log 格式。這一條就能省掉無數 production incident。

4. 註解規範：太多或太少都是災難

要加在 function 前面還是裡面？要用 JSDoc 還是普通說明？詳細程度是多少？

這對人來說可以猜，但 AI 需要你說清楚，否則你會看到兩種極端：到處是廢話註解（// 這是一個 for 迴圈），或是完全沒有註解。兩種都很痛苦。

黃金法則：告訴 AI「註解要說 why，不是 what」。這句話加進 guidelines 就能大幅改善註解品質。

---

黃金標準檔案：你的 AI 的 Integration Test

Stack Overflow 的文章建議，你的 coding guidelines 要同時提供：

• **正確範例**：這樣寫
• **錯誤範例**：不要這樣寫

AI 可以從這些 pattern 中學習。更進一步，你可以準備一個「黃金標準檔案」——一個完全符合所有規範的 code 範例，作為 AI 的 end-to-end 參考。

個別範例就像 unit test，黃金標準檔案就像 integration test。

怎麼建：挑你的 codebase 裡最乾淨、最符合規範的一個模組，把它標記為黃金標準。在 agents.md 裡指向這個檔案，告訴 AI「有任何疑問，參考這個檔案的風格」。

這個思路不難理解，但執行起來需要時間。我帶過的企業裡，那些真正把 AI 用得有效的團隊，都有一件共通點：他們花了時間在「讓 AI 真的懂我們的規矩」這件事上，而不是每次都在亡羊補牢。

---

心態轉換：錯誤是反饋，不是失敗

你的第一版 coding guidelines 不會完美，這沒關係。

當 AI agent 寫出不符合預期的程式碼，那是資訊，不是廢物。每一個「它又做錯了」的瞬間，都是一個機會：你有沒有在規範文件裡說清楚這件事？如果沒有，補進去。

Sourcegraph 的 CEO Quinn Slack 有一句話我覺得非常到位：

「有些人對著 AI 隨便打幾個字，完全不希望它成功。然後有些人花時間定義規則、寫 agents.md，出錯了就更新，讓這個過程變成正向循環。」

Google DeepMind 的 Logan Kilpatrick 也說：「大公司有清楚的風格指南和最佳實踐。這些都是理想的 context，可以直接給模型，讓它真的幫上你。沒有這些 context，你只是在賭運氣。」

這也解釋了為什麼那些已經有完整工程文化的公司，在導入 AI agent 的時候反而更有優勢——他們的知識已經被文字化了。

反過來說，那些知識全靠口耳相傳的團隊，在這個時代吃的虧會特別大。因為 AI 沒辦法聽老前輩「口傳心授」。

---

Linter 還是要用，但角色變了

這個我要特別說一句：把規範交給 AI，不等於可以拿掉 linter 和 formatter。

Linter 處理的是「基本款」，不管是人寫的還是 AI 寫的，都要過這一關。AI agent 很快，但它也很容易在細節上犯初學者的錯。靜態分析工具就是你的最後一道防線。

兩者不是替代關係，是互補關係：

• **AI agent** 負責生成符合團隊風格的程式碼
• **Linter / Formatter** 負責攔截基本格式錯誤
• **Code Review（人）** 負責審核業務邏輯和架構決策

三層防線，缺一不可。

---

台灣企業的 AI Coding Guidelines 行動清單

根據我在培訓現場的觀察，以下是大部分台灣企業可以在一週內完成的步驟：

第 1 天：盤點現有規範

• 你們現在有 coding guidelines 嗎？在哪裡？最後更新是什麼時候？
• 如果有，用 AI 讀一次，看它能不能正確理解並產出符合規範的 code

第 2-3 天：補齊四大區塊

• 命名規範（每一層各三個正確 + 三個錯誤範例）
• 排版格式（明確寫出所有 formatter 規則）
• 例外處理與 log（標準 try-catch 模板 + log 格式）
• 註解規範（「說 why 不說 what」+ JSDoc 模板）

第 4 天：建立黃金標準檔案

• 挑一個最乾淨的模組作為 reference
• 在 agents.md / CLAUDE.md 裡指向這個檔案

第 5 天：實測 + 迭代

• 讓 AI agent 根據新的 guidelines 寫一個功能
• 記錄所有不符合預期的地方
• 更新 guidelines

這不是一次做完的事，但起步不難。重點是「開始」。

---

阿峰老師的觀點

我自己在協助企業導入 AI 的過程中，最常見的問題不是「AI 不夠聰明」，而是「我們沒有給 AI 足夠清楚的工作指令」。

這篇 Stack Overflow 文章讓我想到一個比喻：你請了一個翻譯，給他一份文件，說「就照著這個的意思翻」。結果他翻完你發現不對。問題是出在翻譯不夠專業，還是那份「照著這個意思」根本沒有說清楚你要什麼？

AI agent 寫程式碼也是一樣。

如果你的 coding guidelines 只是一份給人看的、充滿「大家應該都懂的潛規則」的文件，那你導入 AI agent 之後，得到的可能是比以前更混亂的 codebase。

但如果你願意花時間把那些潛規則都攤開來，加上正確和錯誤範例，加上一個黃金標準檔案，再把這些東西放進 agents.md 跟著 repo 一起管理，你的 AI agent 就能真正變成你工程團隊的延伸，而不是一個每次都要重頭解釋的外來者。

問題不在 AI 不夠聰明。問題在你的規矩還沒準備好讓 AI 讀懂。

---

本文提到的資源

資源	說明
Stack Overflow Blog 原文	Building shared coding guidelines for AI (and people too)
Sourcegraph	Quinn Slack 領導的 AI 原生程式碼搜尋平台
Graphite	Greg Foster 的 AI 輔助 code review 工具

---

如果你的公司正在評估如何讓工程團隊更有效地使用 AI coding agent，歡迎到 autolab.cloud 聯繫阿峰老師。服務過超過 400 家企業，從製造業到金融業，都有落地的 AI 開發培訓案例。

加入 LINE 社群，跟一萬多名學員一起關注 AI 工具的最新動態：https://lin.ee/mUvPZwJC

---

---

關於作者

黃敬峰（AI峰哥），企業 AI 實戰培訓專家，400+ 企業合作、10,000+ 學員。核心心法：「會用、懂用、好用、每天用」。官網：https://www.autolab.cloud