自用 AGENTS.md 全域規則

這是我個人沉澱的一套 Claude Code 和 Codex 全域規則，放在專案根目錄的 AGENTS.md或者 CLAUDE.md 中，對初學者來說是一個非常省事的規則。

設計思想：漸進式 Spec

這套規則的核心是漸進式 Spec（Progressive Specification）——不同複雜度的需求走不同深度的流程，避免對簡單任務過度設計，同時對複雜任務建立足夠的約束。

簡單來說：偶然複雜度應該盡可能壓縮，本質複雜度才值得花精力管理。

編碼流程概覽

核心鐵律：

• No Spec, No Code — 中等及以上複雜度，沒有 Spec 不準動程式碼
• HARD-GATE — Spec 寫完必須等使用者顯式確認才能開始編碼
• Reverse Sync — 執行中發現偏差，先修 Spec，再修程式碼

每個階段的自由度是明確的：調研可以自由探索，方案設計可以充分發揮，但執行階段自由度為零，嚴格按計劃來，有偏差立即停下來問。

關於各 AI 的執行表現

這套規則在 Codex 上執行效果非常好，基本能嚴格遵循流程，約束清晰時表現穩定。

Claude 則有一些自己的"想法"——有時會在沒有明確指令的情況下主動做額外的事，或者對規則做自己的解讀，執行的靈活性比預期的高。整體上不如 Codex 那麼"聽話"，但在創造性任務和方案設計上反而更有發揮。

兩者各有優劣，根據任務類型搭配使用效果更好。

規則全文（可一鍵複製）

# 語言

- 和我對話的語言預設中文

# 注意

預設情況下，不要建立任何新的說明文件或文件檔案。
不要自動生成 README.md、設計文件、使用說明、架構說明等。
只有在我明確要求"編寫文件 / 生成 README / 寫說明文件"時，才允許建立或修改檔案。

# 程式碼規範

- 程式碼要寫清楚中文註釋，所有函式和關鍵邏輯都必須有註釋

---

# Workflow Orchestration

## 1. 漸進式 Spec：按需複雜度

不同複雜度的需求，走不同深度的流程——偶然複雜度應該盡可能壓縮：

| 需求規模 | 流程 |
|---------|------|
| 簡單（改欄位、修 bug） | 直接執行，無需 Spec |
| 中等（3+ 步驟，有架構決策） | 寫輕量 Spec，HARD-GATE 後再編碼 |
| 複雜（跨模組、多系統） | 完整 Propose → Apply → Review |

**Spec 三鐵律**（僅中等及以上複雜度觸發）：
1. **No Spec, No Code** — 沒有 Spec，不準寫程式碼
2. **Spec is Truth** — Spec 和程式碼衝突時，錯的一定是程式碼
3. **Reverse Sync** — 執行中發現偏差，先修 Spec，再修程式碼

**HARD-GATE**：Spec 完整生成後，必須等使用者顯式確認才能開始編碼。確認前禁止任何程式碼修改動作。

**Research 必須有出處**：描述程式碼現狀時，每個結論必須標註檔案路徑 + 函式名，不接受"通常來說"或無依據的推斷。

**Spec 分段確認**：不一口氣生成完整 Spec。按段輸出（現狀分析 → 功能點 → 風險與決策），每段等使用者確認後再繼續。越早發現方向偏差，修正成本越低。

## 2. Plan Node Default

- 對任何中等及以上複雜度的任務，進入 plan mode
- 出問題立刻停下重新規劃，不要強行推進
- Plan mode 同樣適用於驗證步驟，不只是構建階段

## 3. Subagent Strategy

- 大量使用 subagent 保持主 context 視窗乾淨
- Research、探索、並行分析交給 subagent
- 複雜問題通過 subagent 投入更多計算
- 每個 subagent 只做一件事，專註執行

## 4. 執行自由度曲線

| 階段 | 自由度 | 原則 |
|------|--------|------|
| 調研 | 中 | 自由探索，但結論必須有程式碼出處 |
| 方案設計 | 高 | 充分想像，提選項 + 給推薦 |
| 規劃 | 低 | 精確到檔案路徑和函式籤名 |
| 執行 | 零 | 嚴格按計劃，有偏差立即停下問 |
| 驗收 | 中 | 自由檢查，結論要有依據 |

## 5. Self-Improvement Loop

- 使用者每次糾正後：將模式寫入 `tasks/lessons.md`
- 寫規則防止同類錯誤重現
- 每次會話開始時 review lessons 裡的相關規則
- 有價值的踩坑和領域發現，主動建議沉澱到專案知識庫

## 6. Verification 鐵律

- 任務未經驗證，不得標記為完成
- 必須展示可驗證的證據（編譯輸出 / 測試結果 / 執行日誌）
- 禁止"應該沒問題"等無證據聲明
- 必要時對比修改前後的行為差異

## 7. Demand Elegance（適度）

- 非簡單修改時，停下來問一句："有沒有更優雅的方式？"
- 如果方案感覺 hacky："知道了這些之後，實現優雅方案"
- 簡單顯而易見的修復直接做，不要過度設計

## 8. Autonomous Bug Fixing

- 給 bug 報告就去修，不要等手把手指導
- 指向日誌、報錯、失敗測試，然後解決它
- 不需要使用者切換上下文
- CI 測試失敗，主動去修

---

# Task Management

1. **先寫計劃**：將計劃寫入 `tasks/todo.md`，使用可勾選的任務項
2. **確認後執行**：中等及以上複雜度任務，HARD-GATE 後才開始實現
3. **追蹤進度**：完成一項立刻標記
4. **解釋變更**：每步給出高層次說明
5. **記錄結果**：在 `tasks/todo.md` 末尾新增 review 小節
6. **沉澱教訓**：使用者糾正後更新 `tasks/lessons.md`

---

# Core Principles

- **Simplicity First**：每次改動盡量簡單。最小化影響範圍。
- **No Laziness**：找根因，不打補丁，用 senior developer 標準。
- **Minimal Impact**：只改必要的程式碼，避免引入新問題。
- **意圖分離**：一次只處理一種意圖——探索、決策、執行、審查不要混著來。