在軟體開發與 AI 協作日益緊密的今天，許多開發者常面臨 AI 產出低質量、難以維護程式碼的困境。本文是日常學習第807天的實作筆記，深入探討如何透過建立明確的「協作協定」來防止 AI 協作崩壞。藉由研究資深工程師 Matt Pocock 的 .claude 規則，我們能掌握讓 AI 精準執行任務的核心邏輯，提升開發工作流的穩定性。

本文重點快速看

  • AI 產出垃圾代碼的根本原因在於缺乏明確的「協作協定」，而非 AI 本身能力不足。
  • 借鑑資深工程師 Matt Pocock 的 .claude 技能集，建立結構化的引導規則。
  • 透過明確定義上下文與開發規範，能大幅降低 AI 瞎忙與代碼崩壞的機率。
  • 個人學習實作心得：協作協定的本質是將開發標準系統化，讓 AI 成為真正的得力助手。

為什麼你的 AI 總是寫出難以維護的垃圾代碼？

AI 寫出劣質代碼通常是因為缺乏明確的開發規範與邊界條件，導致其只能根據模糊的提示詞進行盲目通化猜測。

在日常開發實作第131天中，我發現許多人（包括我過去）常把 AI 當作萬能許願池。當我們只給出「幫我寫一個登入功能」這種模糊指令時，AI 只能拼湊網路上的常見寫法，而忽略了專案既有的架構、型別定義與程式風格。這並非 AI 的問題，而是我們沒有提供一個「防崩壞」的協作框架。

什麼是 .claude 協作協定？資深工程師的三個核心洞察

.claude 協定是資深工程師 Matt Pocock 提出的規則集，核心在於透過結構化檔案預先定義 AI 的角色、開發標準與代碼產出規範。

透過研究 Matt Pocock 分享的 .claude 技能集，我整理出以下三個關鍵的協作洞察：

  • 角色與上下文錨定：在協作開始前，必須讓 AI 清楚知道它扮演的角色、專案使用的技術棧（如 TypeScript、Next.js）以及絕對不能違反的架構原則。
  • 漸進式重構與確認：不要讓 AI 一次性修改大範圍代碼。應該要求 AI 在修改前先說明邏輯，並以小步快跑的方式提交變更。
  • 嚴格的型別與錯誤處理規範：明確限制 AI 不得使用 any 等寬鬆型別，並規定統一的錯誤處理機制，從源頭杜絕難以維護的垃圾代碼。

傳統提示詞與 .claude 協作協定的差異比較

傳統提示詞依賴單次對話的運氣，而 .claude 協定則是將規範寫入設定檔，確保每次協作都遵循統一標準。

提示詞與協作協定之比較
比較維度 傳統對話提示詞 .claude 協作協定
規範持續性 單次有效，對話拉長後容易遺忘 全域有效，作為 AI 系統提示詞底層
代碼一致性 隨機性高，風格容易前後不一 高度一致，嚴格遵守專案既定規範
溝通成本 每次都需要重複輸入背景資訊 一次設定，後續直接進入開發主題
適用場景 簡單的單一問題諮詢 複雜、長期的軟體專案開發協作

常見問題 FAQ

Q1: 什麼是 .claude 規則？它只能用在 Claude 上嗎？
A1: 雖然它源自 Claude 的 System Prompts 設定，但其核心的結構化協定邏輯同樣適用於 GPT-4 等其他主流大語言模型。

Q2: 如何在現有專案中導入這套防崩壞指南？
A2: 建議先從定義「最不希望 AI 犯的五個錯誤」開始（例如禁止使用 any、必須寫單元測試），將其寫成專案根目錄的說明文件。

Q3: 使用協作協定會不會限制了 AI 的創意產出？
A3: 會在一定程度上限制其發散思維，但在軟體工程中，我們追求的是高預測性與穩定性，限制不必要的創意正是防崩壞的關鍵。

Q4: 為什麼導入協定後，AI 還是會寫出有 Bug 的代碼？
A4: 協定能大幅降低架構性崩壞，但無法完全避免邏輯錯誤。人類工程師仍需扮演最後的代碼審查（Code Review）守門人。

結語與個人學習反思

在日常學習第807天與開發實作第131天的這個節點上，我深刻體會到，與其抱怨 AI 工具不好用，不如花時間優化自己的「協作接口」。Matt Pocock 的 .claude 實踐證明了，系統化的規則與明確的邊界，才是釋放 AI 真正潛能的鑰匙。在未來的開發工作流中，持續修正與疊代這套協作協定，將是每位工程師不可或缺的必修課。

延伸參考資料