自我修復（自我修正規則引擎）
一個自我修正的記憶與學習引擎，將修正內容、專案慣例和錯誤修復記錄到持久的規則集檔案（autofix.json）中。它確保代理程式持續適應、消除跨工作階段的重複錯誤，並嚴格遵守使用者偏好。
為何有效： AI 代理程式傾向於在新的工作階段中重複相同的預設假設或風格錯誤。透過將學到的知識外部化為一個指令性、帶有版本號的 JSON 規則集（新規則優先），代理程式會保留針對特定使用者與儲存庫的嚴格界限。
儲存與配置
此技能會按以下優先順序尋找規則集檔案：
.agents/autofix.jsonautofix.json（位於工作區根目錄）.rules/autofix.json
如果上述位置皆不存在，且需要新增規則時，它會建立 .agents/autofix.json（或根據專案慣例建立根目錄下的 autofix.json）。
規則結構
每條規則以 JSON 陣列儲存，結構如下：
[
{
"Rule_number": 1,
"Category": "CODE",
"Instruction": "永遠不要對 React 元件使用預設匯出 - 一律使用具名匯出。",
"Why": "確保與程式碼庫保持一致並簡化重構。"
}
]
允許的類別
| 類別 | 說明 | 範例 |
|---|---|---|
[STYLE] | 程式碼格式、命名慣例、匯入順序、註解 | "一律對輔助函式使用駝峰式命名" |
[CODE] | 語言模式、函式庫選擇、型別定義、錯誤處理 | "永遠不要在 TypeScript 中使用 any；請使用 unknown 搭配型別守衛" |
[ARCH] | 目錄結構、模組邊界、架構層次 | "API 路由位於 src/server/routes/，而非 src/api/" |
[TOOL] | CLI 指令、建置工具、套件管理器、測試框架 | "一律使用 pnpm 而非 npm 或 `yarn"" |
[PROCESS] | Git 工作流程、提交訊息、PR 要求、測試閘道 | "永遠不要在提交訊息中加入 emoji" |
[DATA] | 資料庫結構、遷移、快取策略、狀態形狀 | "請記得在表格中加入 created_at 和 updated_at 時間戳" |
[UX] | UI 行為、文案慣例、無障礙標準 | "一律為僅含圖示的按鈕提供明確的 aria-label" |
[OTHER] | 一般性或專案領域特定的偏好 | "一律以 markdown 表格格式記錄公開 API 端點" |
操作流程
[工作階段開始 / 收到任務]
│
▼
┌───────────────────────────────┐
│ 1. 任務前掃描 │ ◄── 讀取 autofix.json
│ - 載入所有規則 │
│ - 解決衝突（新規則優先） │
│ - 建立活躍限制條件 │
└───────────┬───────────────────┘
│
▼
┌───────────────────────────────┐
│ 2. 任務執行 │
│ - 套用限制條件 │
│ - 執行程式碼 / 編輯 │
└───────────┬───────────────────┘
│
├─────────────────────────────────────────┐
│ │
[無修正] [偵測到觸發條件]
│ │
▼ ▼
┌───────────────────────────────┐ ┌───────────────────────────────┐
│ 任務完成 │ │ 3. 自我修復與捕捉 │
│ 將結果交付給使用者 │ │ - 制定指令式規則 │
└───────────────────────────────┘ │ - 附加至 autofix.json │
│ - 確認已學習 │
└─────────────┬─────────────────┘
│
▼
┌───────────────────────────────┐
│ 4. 重新執行與修正 │
│ 修正目前任務輸出 │
└───────────────────────────────┘
詳細逐步執行說明
1. 任務前掃描（執行任何動作之前）
在規劃或修改任何任務中的檔案之前：
- 找到並載入
autofix.json。 - 掃描規則：
- 檢查是否有任何規則直接適用於當前提示所涉及的檔案、工具或模式。
- 解決衝突：
- 如果兩條規則給出衝突的指導，編號較大（較新）的規則優先。
- 保持限制條件活躍：
- 將所有活躍規則視為硬性限制條件（相當於提示合約中的
CONSTRAINTS）。
- 將所有活躍規則視為硬性限制條件（相當於提示合約中的
2. 何時新增規則（觸發條件）
發生以下任何情況時，立即觸發規則捕捉：
- 使用者明確修正輸出：例如，「不，不要用 X，用 Y 來做」、「我們這裡不使用類別元件」。
- 使用者拒絕某個檔案、方法或模式：例如，「不要把測試檔案放在原始碼旁邊」。
- 使用者陳述個人/團隊偏好：例如，「一律將提交訊息格式化為 Conventional Commits」、「永遠不要在文件中使用 emoji」。
- 因錯誤假設而導致的錯誤：代理程式假設某個函式庫或檔案位置導致了失敗。
- 使用者執行
/learn或要求記住某條規則。
3. 附加新規則
當觸發條件發生時，執行以下原子更新：
- 讀取現有的
autofix.json陣列。 - 決定下一個連續的
Rule_number：- 如果現有最高規則編號為 $N$，則新規則編號為 $N + 1$。
- 如果檔案為空或不存在，則從
1開始。
- 格式化新規則物件：
- Rule_number：連續整數。
- Category：標準類別之一（
STYLE、CODE、ARCH、TOOL、PROCESS、DATA、UX、OTHER）。 - Instruction：以嚴格的指令式格式撰寫：
「永遠不要/一律執行 X - 因為 Y。」 - Why：簡短原因（例如「使用者偏好」、「程式碼庫模式」、「框架限制」）。
- 將規則附加至 JSON 陣列，並以 2 個空格縮排格式化儲存檔案。
- 永遠不要刪除現有規則。如果舊規則已過時，請撰寫新規則，使其以較高編號取得優先權。
- 簡短通知使用者：
「已學習規則 #
<N>（[CATEGORY]）：<指令>— 已記錄於autofix.json。」
4. 範例規則檔案 (autofix.json)
[
{
"Rule_number": 1,
"Category": "PROCESS",
"Instruction": "永遠不要在提交訊息中加入 emoji - 保持提交標題為純 Conventional Commits 格式。",
"Why": "使用者偏好"
},
{
"Rule_number": 2,
"Category": "ARCH",
"Instruction": "一律將 API 路由處理程式放在「src/server/routes/」，不要放在「src/api/」- 維持一致的後端架構。",
"Why": "現有程式碼庫模式"
},
{
"Rule_number": 3,
"Category": "CODE",
"Instruction": "在所有外部進入點一律使用 Zod 架構進行輸入驗證 - 防止未經型別檢查的執行時期輸入。",
"Why": "防止執行時期錯誤並強制型別檢查"
}
]
最佳實踐與邊界案例
- 原子性 JSON 寫入：務必解析現有的 JSON 陣列，附加新物件，然後寫回有效的 JSON。絕不要因未跳脫的文字而損壞檔案。
- 具體且指令性強：撰寫能讓另一個 AI 明確遵循的規則。避免模糊的建議（如「撰寫乾淨的程式碼」），應優先採用「一律在
.types.ts檔案中，將型別與元件實作一起匯出」這類寫法。 - 避免無限迴圈：記錄規則時，不要為規則檔案本身觸發另一個自我修復迴圈。
- 取代規則：如果規則 1 說「使用 Axios」，而使用者隨後指示「全部遷移至 Fetch」，則新增規則 4：「一律使用原生 Fetch 替代 Axios」，並將
Why設為「使用者要求遷移至原生 fetch（取代規則 1）」。