使用 agent.md 提升 LLM 輔助程式碼品質

使用 agent.md 檔案可以讓開發者直接將持久的風格偏好與架構約束注入到 LLM 的提示詞（prompt）中，將人類的角色從修正基礎程式碼風格轉向關注高層次設計。這種方法減少了在 AI 輔助編碼過程中重複進行繁瑣手動回饋的需求。

agent.md 框架

agent.md 檔案是一個專案根目錄的配置檔案，會由代理式 IDE（agentic IDEs）和編碼工具自動載入，用以微調 LLM 的行為。開發者不再需要在每個新對話中重複相同的風格修正，而是可以將這些要求編碼為單一的事實來源（source of truth）。

核心編碼標準

為了確保生產等級的程式碼品質，建議在 agent.md 檔案中加入以下規則：

• 簡潔性： 在註解、提交訊息（commit messages）和提示詞回覆中，盡可能使用最少的字數。避免使用最高級與讚美。
• 整潔程式碼實踐：
  • 將重複出現或具備意義的值提取到描述性的常數（constants）或列舉（enums）中，以避免「魔術數字（magic numbers）」。
  • 利用提早返回（early returns）和 continue 語句來減少縮排，以避免「箭頭反模式（Arrow Anti-Pattern）」。
  • 可見性： 預設將所有欄位與函式設為私有（private）；在更改存取修飾符為內部（internal）或公開（public）之前，需請求明確許可。
• 架構與抽象：
  • 將低階機制（例如：原始硬體 I/O、socket streams）封裝在專用的驅動層中。
  • 遵循嚴格的分層邊界層級，每一層僅能與其下方的直接鄰近層進行通訊。
• 文件化： 加入簡短的註解來解釋程式碼區塊在做「什麼」以及「為什麼」，對於複雜系統，請使用範例或 ASCII 圖形。
• 測試： 在修復錯誤時，LLM 必須先撰寫一個失敗的測試，觀察失敗情況，然後撰寫修復程式碼並驗證其通過。

提交訊息標準

為了維持整潔的 Git 歷史紀錄，agent.md 檔案可以強制執行提交訊息的 7 條規則：

1. 使用空行將主旨行與內文區隔開。
2. 將主旨行限制在 50 個字元以內（硬性限制為 72 個字元）。
3. 主旨行的第一個字母大寫。
4. 主旨行結尾不要使用句點。
5. 使用祈使句（例如：「Fix bug」而非「Fixed bug」）。
6. 手動將內文在 72 個字元處換行。
7. 使用內文來解釋「做什麼」與「為什麼」，而非「如何做」。

管理上下文與稀釋問題

隨著上下文視窗（context window）增長，LLM 會遭遇「上下文稀釋（context dilution）」（或稱「注意力稀釋（attention dilution）」），即模型對位於提示詞中間的指令關注度降低。此現象在「Lost in the Middle」研究論文中有記載。

為了減輕此問題，開發者應該：

1. 限制對話長度： 為每個獨立的功能開啟新對話，以保持上下文簡短。
2. 強制重新載入： 當程式碼品質開始下降時，明確命令代理（agent）「Reload agent.md」。
3. 自動化更新： 當在對話過程中發現新規則時，要求 AI 代理本身更新 agent.md 檔案。

社群觀點與評論

雖然 agent.md 方法對某些人有效，但開發者社群針對其執行方式提出了幾點反對意見：

"A bunch of these should be enforce with linting... The what is the code."

批評者認為，許多規則（例如：在單行 if 語句中使用大括號，或限制函式名稱長度）透過自動化 Linter 處理會比透過提示詞指令更好。其他開發者則建議，過於臃腫的 agent.md 檔案實際上會增加上下文消耗並降低效能。

社群的其他建議包括：

• 關注點分離： 將編碼標準移至 CODING_STANDARDS.md 檔案，並將 agent.md 用於互動偏好。
• 收斂規則： 有些開發者實施了「收斂規則（Convergence rule）」，要求每個任務必須結束於以下三種狀態之一：成功（Success）、有意義的進展（Meaningful Progression）或誠實的停止（Honest Stop），以防止 AI 產生無止盡且脆弱的補丁。
• 簡化技術英語： 使用指令要求遵循「ASD-STE100 Simplified Technical English」，以進一步減少 AI 的冗贅感。