如果你想讓代理做你希望它做的事，你就得學會把它框進確定性的動作裡。不幸的是，這不是現有程式碼代理擅長的事。它們被設計成探索式、開放式的。它們接收一個模糊的提示，產生一個看起來合理的修補，執行測試，重複幾次，諸如此類。這對原型開發和全新專案來說很有用。但當你需要可靠性、當你希望同一個指令每次都有相同效果、希望相同的重構套用到二十個檔案、希望相同的部署流程以相同順序執行時，模糊的提示和「請閱讀文件」這種提示就會變成負擔。
所以你最後會有一堆 md 檔叫你的代理繼續讀。這是錯的停下來方式。
Markdown 文件不是約束，它們只是建議。代理可以讀取 CONTRIBUTING.md、AGENTS.md、CLAUDE.md、規則檔、風格指南、runbook，不管是什麼，然後把它們總結出來、引用其中內容，說「我已經讀過文件了，我會盡力遵循。」它們增加了越來越多需要被解析與理解的表面積：「請使用儲存庫中既有的 logging 慣例。」哪一種？在哪裡？「請使用小函式。」多小？「推送前先跑測試。」哪些測試？哪個指令？哪個環境？代理必須處理這一切、權衡彼此衝突的指示，並做出判斷。正是在這種判斷裡，代理才可能走偏。
相較之下，確定性的動作不需要判斷。「閱讀文件並遵循程式碼風格」會變成「執行 ./scripts/lint.sh、./scripts/format.sh、./scripts/test.sh 這些腳本。」代理執行它們，然後得到通過/失敗的結果。如果某個腳本失敗了，代理就會看到精確的錯誤，而且沒有任何需要解讀或猜測的地方。「我以為這個規則是……」會變成 ./scripts/lint.sh。「進行重構」會變成「執行 ast-grep、jscodeshift 或 sed 工具來套用轉換。」代理不需要決定要更新哪些檔案。腳本會依設計完成這件事。你是在把代理框進一連串確定性的動作中。
這是一種設計典範的改變：從「教代理你偏好什麼」變成「把你的偏好翻譯成確定性的動作」。你不能執行一份 Markdown 文件，但你可以執行一個腳本、一份檢查清單、一個 Makefile 目標、或一個 GitHub Actions。若你有一個 Makefile，裡面有 make setup、make lint、make test、make build 等目標，代理就不需要理解你的程式設計哲學。它只需要執行 make lint，然後根據結果回應。
重點不是把代理變笨，而是讓環境變得不含糊。代理在執行一組確定性的動作時，仍然可以很聰明。它可以讀取失敗訊息、修正問題，然後重新執行測試。只是它不能跳出這個框架。它可以在限制內很機靈，但這個框架本身必須是一系列只會通過或失敗的指令。
這就是為什麼程式碼代理在這件事上做得不好。它們想要獨立行動、想要探索儲存庫、讀取檔案、建立心智模型，然後讓事情發生。這方法有用，直到它不再有用。md 檔越多，代理就越覺得自己有裁量權。「文件說要用 snake_case，但這個既有檔案卻是 camelCase。也許文件過時了。」代理是在想幫忙，但它並不是確定性的。
大多數 AI 模型寫出來的回覆都很難閱讀。所以我把 ASD-STE100——一個為航空器維修手冊編寫的簡明英語標準——加入到我的程式碼代理的 Markdown 規則裡。其中一條規則是「句子長度不得超過 20 個字。」如果把它寫成腳本，就會變成 MAX_SENTENCE = 20。當代理把自己某次會話中 10 則回覆都拿去跑這個腳本時，發現了 9 個失敗。腳本是在回覆寫完之後才找出這些問題的，因為沒有任何機制強制更早執行。所以這個腳本應該放進 hook 裡。
我在一次送給 Forem 的修正中看過 CI 這樣做。我不寫 Ruby，而且我也沒有安裝 Ruby，所以 CI 就是我的測試機器。我的程式碼助理寫了修正和測試。第一次執行失敗了，而問題出在測試，不在程式碼。這個結果不取決於助理對自己作品的看法。但 CI 也放過了一行未使用的程式碼，只有審查者發現了它。單一檢查只會把它測試到的部分框住。
完整故事： I Don't Write Ruby. A Fix I Sent Is Now in Forem.
如果你想讓代理做你希望它做的事，不要停在 md 檔。請寫腳本。
把每一句「請記得……」都變成一個指令。把每一句「我們偏好……」都變成一個檢查。把每一句「在你推送前……」都變成一個 pre-push hook。代理可以略過本機 hook，所以要再用一個必要的 CI 工作和一個代理沒有權限變更的合併閘門來支撐它。如果某個檢查失敗了，代理可以修正後再跑一次。這就是把代理框進確定性動作序列的方法。這不是建議，而是一份契約。而代理不能交付未通過檢查的工作。
原文出處：https://dev.to/dannwaneri/dont-write-markdown-files-for-your-coding-agent-write-scripts-j00
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
