先查看專案結構與既有 references 格式，再撰寫 `references/core-methodology.md`。
# Python 工程核心方法論 — Senior Python Developer

> **模組代號**：`REF-METHODOLOGY`  
> **檔案路徑**：`references/core-methodology.md`  
> **適用場景**：設計（P1/P7）、程式碼審查（P4）、重構（P3）、探索理解（P0）、函式庫/SDK 設計（P9）、根因涉及設計缺陷的除錯（P2）  
> **與其他模組關係**：本檔定義 **怎麼思考、怎麼判斷、怎麼驗收**；具體架構模式見 `references/architecture-patterns.md`；測試細節見 `references/testing-strategy.md`；效能見 `references/performance-debugging.md`；安全見 `references/security-sop.md`；工具鏈見 `references/toolchain-sop.md`。

---

## 0. 方法論定位與使用紀律

### 0.1 本檔解決什麼問題

資深 Python 工程師的價值不在於「寫出更多行程式碼」，而在於：

1. **在約束下做出可逆、可驗證、可維護的決策**
2. **把隱性知識變成顯性檢查項**（checklist、ADR、測試契約）
3. **在正確性、安全性、可維護性、效能、交付速度之間做透明權衡**
4. **讓六個月後的 on-call 工程師能在 30 分鐘內定位問題**

本檔是上述能力的 **操作系統**——不是風格指南的複製品，而是可重複執行的工程方法論。

### 0.2 載入後必守紀律

| 紀律 | 說明 |
|:---|:---|
| **先方法論、後實作** | 在動手改碼前，內化本章對應路徑的方法論章節 |
| **Checklist 不可跳過** | 文末各 checklist 是交付門禁，不是建議清單 |
| **證據優於直覺** | 宣稱「更好」「更快」「更安全」必附可驗證依據 |
| **對齊倉庫慣例** | 方法論是底線；專案既有慣例優先於個人偏好 |
| **最小驚訝** | API、錯誤語意、命名應符合使用者（含未來的自己）的合理預期 |
| **可逆優先** | 在不確定時，選擇易於回滾、易於量化的方案 |

### 0.3 方法論優先級階梯（衝突時的決策順序）

當目標衝突時，依序取捨——**不可為了速度犧牲上位原則**：

```
1. 正確性（Correctness）     — 資料不丟、不壞、不靜默失敗
2. 安全性（Security）         — 輸入、權限、秘密、供應鏈
3. 可維護性（Maintainability）— 六個月後仍能安全修改
4. 可觀測性（Observability）  — 出事能定位、能關聯、能告警
5. 效能（Performance）        — 在已量化的瓶頸上優化
6. 交付速度（Velocity）       — 在 1–5 約束下的最短路徑
```

**鐵律**：*Make it work → make it right → make it fast*。順序顛倒即為技術債加速器。

---

## 1. 核心工程哲學（First Principles）

### 1.1 The Zen of Python 的工程化詮釋

| 原則 | 資深工程實踐 | 常見誤用 |
|:---|:---|:---|
| **Explicit is better than implicit** | 顯式型別、顯式依賴注入、顯式錯誤層次 | 魔術 decorator、全域單例藏狀態 |
| **Simple is better than complex** | 扁平模組、直白控制流 | 過早引入 DDD 全套戰術模式於 500 行專案 |
| **Readability counts** | 命名即文件；函式短小 | 炫技 one-liner、巢狀 comprehension 地獄 |
| **Errors should never pass silently** | 結構化日誌 + 可行動錯誤訊息 | 裸 `except:`、`except Exception: pass` |
| **There should be one obvious way** | 跟隨專案與生態慣例（pytest、Pydantic、pathlib） | 自創框架、自創 DI 容器 |
| **If the implementation is hard to explain, it's a bad idea** | 複雜度需 ADR 辯護 | 「你不懂是因為你不夠資深」 |

### 1.2 資深工程師的思維模型

```
觀察（Observe）→ 假設（Hypothesize）→ 實驗（Experiment）→ 結論（Conclude）→ 固化（Encode）
```

- **觀察**：讀碼、讀測試、讀配置、讀生產指標；拒絕盲改
- **假設**：把問題寫成可反證陳述：「若 X 則 Y；實際為 Z」
- **實驗**：最小復現、基準測試、特性開關、金絲雀
- **結論**：根因一句話；修復可對應測試
- **固化**：測試、型別、文件、runbook、ADR

### 1.3 「Pythonic」的務實定義

**Pythonic ≠ 最短程式碼**。Pythonic 是：

1. **符合語言慣例與生態最佳實踐**（EAFP vs LBYL 的場景判斷）
2. **在團隊可讀性預算內表達意圖**
3. **正確使用標準庫抽象**（`pathlib`、`dataclasses`、`contextlib`、`typing`）
4. **不為 Pythonic 犧牲正確性、安全性或可測試性**

| 場景 | 更 Pythonic | 較差 |
|:---|:---|:---|
| 鍵不存在 | `try: val = d[k]` / `d.get(k, default)` | 多層 `if k in d` 巢狀 |
| 路徑操作 | `Path("a") / "b"` | `"a" + "/" + "b"` |
| 資源管理 | `with open(...) as f:` | 手動 `close()` 無 finally |
| 結構化資料 | `@dataclass` / Pydantic `BaseModel` | 無約束 `dict[str, Any]` 層間傳遞 |
| 可擴展分派 | `match` / `singledispatch` | 長 `if/elif` 鏈 |

### 1.4 SOLID 在 Python 中的落地

| 原則 | Python 落地要點 | 檢查問句 |
|:---|:---|:---|
| **S — 單一職責** | 模組/類/函式只做一類變更理由 | 「改訂單規則會動到這個檔案嗎？」 |
| **O — 開放封閉** | 用 `Protocol`、策略物件、plugin 註冊擴展 | 「加新支付方式要改核心 `if` 嗎？」 |
| **L — 里氏替換** | 子類不削弱契約；慎用深繼承 | 「替換實作會破壞呼叫方假設嗎？」 |
| **I — 介面隔離** | 小 `Protocol`；避免胖基類 | 「實作者被迫實作用不到的方法嗎？」 |
| **D — 依賴倒置** | domain 依賴抽象；基礎設施實作抽象 | 「業務邏輯 import 了 ORM 具體類嗎？」 |

**Python 特別注意**：組合 + `Protocol` 往往優於深層繼承；`abc.ABC` 用於需要強制實作的框架邊界。

### 1.5 邊界思維（Boundary Thinking）

所有可靠系統的核心是把世界切成 **純淨核心** 與 **有副作用的邊界**：

```
[外部世界] → [Inbound Adapter] → [Application Service] → [Domain] ← [Outbound Port]
                                      ↓
                              [Outbound Adapter: DB/HTTP/Queue]
```

**紀律**：

- **Domain 層**：無 I/O、無框架 import、確定性邏輯
- **Application 層**：用例編排、事務邊界、授權檢查
- **Infrastructure 層**：ORM、HTTP client、快取、訊息佇列
- **Interface 層**：FastAPI route、CLI、Celery task 入口

**副作用集中爆發在邊界**，便於測試與替換。

---

## 2. 需求澄清與問題定義方法論

### 2.1 問題陳述模板（Problem Statement）

任何 P1/P7 任務開始前，內化以下結構：

```markdown
## 問題陳述
- **角色**：[誰需要這個能力]
- **情境**：[在什麼流程/觸發條件下]
- **痛點**：[現狀缺什麼、成本是什麼]
- **成功標準**：[可驗證的完成定義，含負向案例]
- **非目標**：[明確不做什麼]
- **約束**：[時間、相容性、效能、合規、團隊技能]
```

### 2.2 澄清問題優先級（最多問 1–3 個高價值問題）

| 優先級 | 問題類型 | 範例 |
|:---|:---|:---|
| P0 | 成功標準模糊 | 「完成後怎樣算驗收通過？」 |
| P0 | 破壞性變更 | 「能否破壞既有 API？誰是下游消費者？」 |
| P1 | 資料與一致性 | 「允許最終一致嗎？冪等要求？」 |
| P1 | 規模與 SLA | 「QPS、延遲 P99、資料量級？」 |
| P2 | 審美偏好 | 「命名風格」——通常從倉庫推斷 |

### 2.3 假設明示協議

資訊不足時 **禁止用自信語氣填補空白**。必須輸出：

```
## 假設
1. [假設內容] — 若不成立則 [替代方案]
2. ...

## 待確認
- [ ] [需使用者/產品/運維確認的項目]
```

---

## 3. 設計方法論（Design Methodology）

### 3.1 設計產出物層級

| 複雜度 | 必要產出 | 可選產出 |
|:---|:---|:---|
| 單檔小改 | 內化設計（成功標準 + 測試計畫） | — |
| 跨模組功能 | 方案摘要 + 影響面 + 測試計畫 | 序列圖 |
| 新服務/重大變更 | ADR + 組件圖 + 遷移計畫 | 威脅模型草圖 |
| 函式庫公開 API | API 面清單 + semver 策略 + changelog 草案 | 效能預算 |

### 3.2 ADR（Architecture Decision Record）精簡模板

```markdown
# ADR-NNN: [決策標題]
- **狀態**：提議 | 已接受 | 已棄用 | 已取代
- **日期**：YYYY-MM-DD
- **上下文**：[為何需要做決策]
- **決策**：[選定了什麼]
- **理由**：[關鍵論據]
- **後果**：[正面 + 負面 + 緩解措施]
- **替代方案**：[為何不選]
```

### 3.3 方案評估矩陣

對每個可行方案填寫：

| 維度 | 權重 | 方案 A | 方案 B |
|:---|:---|:---|:---|
| 正確性/資料風險 | 高 | | |
| 實作複雜度 | 中 | | |
| 運維複雜度 | 中 | | |
| 團隊熟悉度 | 中 | | |
| 效能餘量 | 依場景 | | |
| 可逆性/回滾 | 高 | | |
| 測試可行性 | 高 | | |

**選擇規則**：非分數最高者必勝——需文字說明 **為何犧牲某維度**。

### 3.4 API 與模組契約設計原則

1. **窄接口、寬實作**：公開面最小化
2. **契約優先**：輸入輸出型別 + 錯誤語意 + 不變量文件化
3. **破壞性變更顯式化**：deprecation cycle、`warnings.warn(..., DeprecationWarning)`
4. **冪等與重試語意**：HTTP method、task handler、consumer 需文件化
5. **版本策略**：服務用 URL/header；函式庫用 semver

### 3.5 資料與狀態設計檢查問句

- 這段狀態是 **源頭真相（source of truth）** 還是衍生快取？
- 併發寫入時用 **樂觀鎖、悲觀鎖、唯一約束、還是冪等鍵**？
- 刪除是 **硬刪、軟刪、還是事件溯源**？
- 時區與精度：**UTC 儲存、local 展示**？`Decimal` vs `float`？
- 遷移是否 **可回滾**？不可逆時有無備份與演練？

---

## 4. 實作方法論（Implementation Methodology）

### 4.1 實作前「三讀」協議

| 讀取對象 | 目的 |
|:---|:---|
| **目標檔案與呼叫鏈** | 理解插入點與影響面 |
| **鄰近模組** | 對齊命名、錯誤處理、日誌、型別風格 |
| **測試與 CI 配置** | 知道如何證明正確 |

### 4.2 增量交付切片（Vertical Slicing）

優先交付 **端到端可驗證的最薄切片**，再迭代加厚：

```
Slice 1: 快樂路徑 + 單測 + 日誌 → 可 demo
Slice 2: 主要錯誤路徑 + 授權 → 可上 staging
Slice 3: 邊界效能 + 監控 + 文件 → 可上 production
```

**禁止**：一次 PR 混入無關重構、格式化全庫、依賴大升級。

### 4.3 型別策略（Typing Strategy）

| 層級 | 要求 |
|:---|:---|
| 公開 API | 完整參數、返回值、泛型約束 |
| 內部函式 | 複雜邏輯必註解；瑣碎可推斷 |
| 邊界 | Pydantic / `TypedDict` / `NewType` 區分 ID 與裸 `str` |
| 協定 | `Protocol` 定義結構化子類型；避免過度 `cast` |
| 漸進遷移 | 新碼嚴格；舊碼不擴大 `# type: ignore` 面積 |

**標準開頭**（專案無禁止時）：

```python
from __future__ import annotations
```

### 4.4 錯誤處理方法論

#### 4.4.1 異常層次設計

```python
class AppError(Exception):
    """應用程式錯誤基類。"""

class DomainError(AppError):
    """業務規則違反。"""

class UserNotFoundError(DomainError):
    """指定使用者不存在。"""
```

**規則**：

- 業務錯誤 **可預期、可映射** 為 HTTP 4xx / 明確 CLI exit code
- 程式錯誤 / 基礎設施故障 → 5xx / 非零退出；附 correlation id
- **禁止** 用異常控制正常流程（except 作 branch 要極克制）

#### 4.4.2 錯誤訊息品質標準

好的錯誤訊息必含：

1. **發生什麼**（事實）
2. **上下文**（user_id、request_id、操作名）
3. **可行動建議**（若面向工程師/運維）

壞範例：`"Something went wrong"`  
好範例：`"Failed to enqueue export job: user_id=42 queue=exports reason=ConnectionTimeout retry_after=30s"`

### 4.5 日誌與可觀測性嵌入

| 事件類型 | 級別 | 必含欄位 |
|:---|:---|:---|
| 請求進入/離開 | INFO | `method`, `path`, `status`, `duration_ms`, `trace_id` |
| 業務關鍵動作 | INFO | `action`, `entity_id`, `actor_id` |
| 可恢復異常 | WARNING | `error_type`, `retry_count` |
| 不可恢復/資料風險 | ERROR | 堆疊 + 上下文（**無 secrets/PII 明文**） |
| 除錯細節 | DEBUG | 僅開發環境或動態採樣 |

**結構化優先**：`structlog` / JSON formatter；欄位名穩定以利查詢。

### 4.6 並發選型決策樹

```
CPU-bound?
├─ 是 → multiprocessing / ProcessPoolExecutor / 任務佇列 offload
└─ 否 → I/O-bound?
    ├─ 高併發連線 → asyncio + async driver
    ├─ 簡單阻塞 I/O、低 QPS → 同步 + 連線池
    └─ 混合 → async 邊界 + asyncio.to_thread() 包阻塞調用
```

**陷阱清單**：

- 在 event loop 執行 `time.sleep`、同步 `requests.get`
- 未限制併發導致連線/記憶體耗盡
- 共享可變全域狀態無鎖
- 誤以為 `async` 會加速 CPU 工作

---

## 5. 程式碼審查方法論（Code Review Methodology）

### 5.1 審查者心態

- **對事不對人**：指出風險與取捨，非品味審判
- **證據導向**：「可能有问题」要說明觸發條件
- **可執行建議**：給出具體改法或 patch 思路
- **區分必改與建議**：blocker vs nit 不混用

### 5.2 嚴重度分級

| 級別 | 定義 | 範例 | 處置 |
|:---|:---|:---|:---|
| **Blocker** | 資料錯誤、安全漏洞、必現崩潰、破壞契約 | SQL 拼接、裸 secret、無測試的核心邏輯變更 | 必須修復才可合併 |
| **Major** | 高機率生產問題、嚴重可維護性傷害 | N+1、無超時、錯誤被吞 | 應修復；可協商 follow-up issue |
| **Minor** | 邊緣案例、可測試性不足、缺文件 | 缺少空列表處理 | 建議本 PR 或後續 |
| **Nit** | 純風格（且 linter 未覆蓋） | 變數名略含糊 | 可選 |

### 5.3 七大審查維度（必須全掃）

#### 維度 1：正確性與邊界條件（Correctness & Boundaries）

**審查問句**：

- 快樂路徑是否正確？主要錯誤路徑是否處理？
- `None`、空集合、零、負數、超大輸入、重複提交是否考慮？
- 浮點與金額、時區與 DST、編碼與 Unicode 是否正確？
- 競態條件：check-then-act 是否原子？是否需要鎖/唯一約束？
- 冪等：重試會否重複扣款、重複建立資源？

**常見缺陷信號**：

- 無守衛的 `obj.attr` 鏈
- `if user:` 把空字串與 None 混為一談
- 用 `float` 做貨幣
- 樂觀更新無衝突處理

#### 維度 2：安全性（Security）

**審查問句**：

- 所有外部輸入是否在校驗後進入 trust zone？
- SQL/命令/路徑/模板是否參數化與規範化？
- 秘密是否可能進 log、exception message、git？
- 授權檢查是否在正確層級（不可只藏在前端）？
- 依賴是否引入已知 CVE？反序列化是否安全？

**常見缺陷信號**：

- f-string 拼 SQL
- `pickle.loads` on 不可信資料
- `eval` / `exec` on 使用者輸入
- JWT `alg=none` 或未驗簽

#### 維度 3：效能與可擴展性（Performance & Scalability）

**審查問句**：

- 是否存在 N+1、無索引查詢、全表掃描？
- 是否有無界快取、無界佇列、一次載入過大結果集？
- 同步阻塞是否卡在 async 路徑？
- 演算法複雜度是否與資料規模匹配？
- 是否有超時、限流、背壓？

**常見缺陷信號**：

- 迴圈內 `session.query` 懶加載
- `list(rows)` 對百萬行表
- 重複編譯正則於熱路徑

#### 維度 4：可測試性與耦合（Testability & Coupling）

**審查問句**：

- 邏輯能否在不啟動完整基礎設施下單測？
- 依賴是否可替換（Protocol / 注入）？
- 是否過度 mock 導致測試與生產脫節？
- 模組依賴方向是否正確（domain 不依賴 framework）？
- 全域狀態是否污染測試？

**常見缺陷信號**：

- 業務邏輯直接 `import requests` 並呼叫
- 硬編碼 `datetime.now()` 無時鐘注入
- 測試 assert 私有實作細節

#### 維度 5：API 設計與破壞性變更（API Design & Compatibility）

**審查問句**：

- 公開函式簽名是否清晰、狹窄、穩定？
- 錯誤語意是否與文件一致？
- 是否破壞下游（欄位刪除、語意反轉、預設行為變更）？
- HTTP status、錯誤 body 是否機器可解析？
- 是否有 deprecation 路徑與遷移說明？

**常見缺陷信號**：

- `*args, **kwargs` 透傳進資料層
- 回傳型別隨分支變化（有時 `dict` 有時 `None`）
- 靜默改預設值

#### 維度 6：可觀測性與運維（Observability & Operations）

**審查問句**：

- 關鍵路徑是否有結構化日誌與 trace 關聯？
- 失敗時 on-call 能否 30 分鐘內定位？
- 設定是否可從環境調整（超時、開關）？
- 健康檢查是否反映真實依賴狀態？
- 部署/遷移是否冪等、可回滾？

**常見缺陷信號**：

- 只有 `print`
- 無 correlation id 串聯
- migration 不可逆卻無說明

#### 維度 7：風格與專案一致性（Style & Consistency）

**審查問句**：

- 是否遵循專案 import 順序、命名、目錄慣例？
- 是否引入與周邊矛盾的抽象？
- linter/formatter 能否通過？
- 註解是否解釋 **為什麼** 而非 **做什麼**（程式已表達的）？

**注意**：純格式問題應交給工具；人審聚焦語意與結構。

### 5.4 審查輸出格式（每個問題）

```markdown
### [嚴重度] 標題
- **位置**：`path/to/file.py:42` 或 `startLine:endLine:filepath`
- **問題**：[事實描述 + 觸發條件]
- **影響**：[資料/安全/效能/維護]
- **建議**：[具體改法或替代設計]
```

### 5.5 審查結論判定

| 結論 | 條件 |
|:---|:---|
| **APPROVE** | 無 blocker；major 已修或已達成 follow-up 共識 |
| **REQUEST_CHANGES** | 存在未解 blocker 或重大風險 major |
| **COMMENT** | 僅 nit/minor；作者可自主合併 |

---

## 6. 重構方法論（Refactoring Methodology）

### 6.1 重構前提（不可跳過）

1. **行為不變**（除非明確標註 breaking change）
2. **測試護航**：characterization tests 或現有綠燈測試
3. **小步提交**：每步可 review、可回滾
4. **度量驅動**：為何要重構？痛點是否可量化？

### 6.2 重構決策樹

```
測試是否存在且可信？
├─ 否 → 先補 characterization tests
└─ 是 → 痛點類型？
    ├─ 理解困難 → 重命名、抽函式、拆模組
    ├─ 重複邏輯 → 提取共用（注意二/三次法則）
    ├─ 耦合過緊 → 引入 Port/Adapter、DI
    ├─ 效能 → 先 profile 再動結構
    └─ 架構失衡 → 分階段遷移（見 strangler fig）
```

### 6.3 安全重構手法目錄

| 手法 | 適用 | 風險 |
|:---|:---|:---|
| **Extract Function** | 長函式、重複區塊 | 低 |
| **Rename** | 誤導命名 | 低（需全專案替換） |
| **Introduce Protocol** | 替換具體依賴 | 中 |
| **Move Module** | 邊界不清 | 中（注意循環 import） |
| **Replace Conditional with Strategy** | 膨脹 `if/elif` | 中 |
| **Strangler Fig** | 遺留子系統替換 | 高（需遷移計畫） |

### 6.4 重構反模式（禁止）

- **Big Bang Rewrite** 無遷移計畫
- **重構 + 新功能** 同一 PR 難以審查
- **抽象过早**：只出現一次的邏輯抽「通用框架」
- **無測試改核心狀態機**

---

## 7. 技術債管理方法論（Technical Debt Management）

### 7.1 技術債分類

| 類型 | 描述 | 策略 |
|:---|:---|:---|
| **刻意債** | 為交付速度明知故犯 | ADR 記錄 + 還債 ticket + 到期日 |
| **疏忽債** | 缺乏測試/文件漸漸腐蝕 | 童子軍規則 + 20% 容量 |
| **環境債** | 工具鏈、CI、依賴老化 | 定期升級視窗 |
| **模型債** | 領域理解錯誤導致結構扭曲 | 需產品對齊後再重構 |

### 7.2 技術債評估四象限

```
        高影響
          │
  優先還債 │ 規劃還債
──────────┼──────────
  順手清理 │ 接受/忽略
          │
        低影響
    低 effort    高 effort
```

### 7.3 童子軍規則（Boy Scout Rule）操作化

每次觸碰檔案時 **至少選一項**：

- [ ] 補一個缺失的邊界測試
- [ ] 改善一個誤導命名
- [ ] 移除一塊死碼
- [ ] 為魔術數字命名常數
- [ ] 為複雜分支加一行為什麼註解

**禁止**：借童子軍之名做大範圍無關重構（drive-by refactor）。

### 7.4 Legacy 程式碼接手指南

1. **閱讀不修改** 建立 mental model
2. **畫依賴與資料流**（入口 → 核心 → 出口）
3. **補 characterization tests** 鎖定現行行為
4. **最小修補** 解當前 ticket
5. **邊界絞殺** 逐步替換核心（若需）

---

## 8. Python 慣用法與反模式百科

### 8.1 推薦慣用法

| 主題 | 推薦 | 備註 |
|:---|:---|:---|
| 路徑 | `pathlib.Path` | 跨平台、語意清晰 |
| 設定 | `pydantic-settings` / 顯式 config 物件 | 12-factor |
| 結構化資料 | `@dataclass(frozen=True, slots=True)` | 值物件 |
| 驗證邊界 | Pydantic v2 `BaseModel` | API 入出參 |
| 日誌 | `logging` + `LoggerAdapter` 或 structlog | 不用 print 做運維日誌 |
| 測試 | pytest + fixtures | 描述行為的測試名 |
| 並發 I/O | `asyncio` + `TaskGroup`（3.11+） | 注意取消語意 |
| 重試 | `tenacity` 或自寫限定異常重試 | 指數退避 + jitter |
| 時間 | `datetime.now(tz=UTC)` | 禁止 naive datetime 比較 |

### 8.2 反模式紅線（見到即標 Major/Blocker）

| 反模式 | 風險 | 替代 |
|:---|:---|:---|
| 裸 `except:` | 吞掉 `KeyboardInterrupt`、SystemExit | 捕獲具體異常 |
| `except Exception: pass` | 靜默失敗 | 記錄 + 重新拋出或轉換 |
| 可變預設參數 `def f(x=[])` | 跨呼叫共享狀態 | `None` + 內部分配 |
| 裸 `pickle` 不可信來源 | RCE | JSON / 明確 schema |
| 字串拼 SQL | 注入 | 參數化查詢 / ORM |
| `type: ignore` 氾濫 | 型別系統失效 | 修類型或窄化 ignore |
| 在模組 import 時做 I/O | 啟動慢、測試難 | lazy init / factory |
| `from module import *` | 命名空間污染 | 顯式 import |

### 8.3 EAFP vs LBYL 選擇指南

| 情境 | 偏好 | 理由 |
|:---|:---|:---|
| 字典鍵存取（預期常不存在） | EAFP (`try/except KeyError`) | 熱路徑更清晰 |
| 權限/存在檢查（預期常成功） | LBYL | 避免異常開銷 |
| 併發環境 | LBYL + 鎖 | 競態下 EAFP 可能誤導 |
| 驗證使用者輸入 | 顯式驗證（LBYL 風格） | 錯誤訊息可控 |

---

## 9. 決策速查表（Decision Tables）

### 9.1 同步 vs 異步

| 場景 | 選擇 |
|:---|:---|
| CPU 密集計算 | `multiprocessing` / worker queue |
| 高併發 I/O（>500 閒置連線） | `asyncio` |
| 內部 CRUD、低 QPS | 同步 |
| 既有 sync 程式碼為主 | 不為 async 而 async |
| 需同時呼叫多個 I/O | `asyncio.gather` / `TaskGroup` |

### 9.2 資料驗證邊界

| 場景 | 選擇 |
|:---|:---|
| HTTP API 入參 | Pydantic `BaseModel` |
| 內部不可變值物件 | `dataclass(frozen=True)` |
| 可選欄位多 | `TypedDict` + `NotRequired` |
| 動態鍵 | `dict[str, V]` + 運行時校驗 |
| 跨服務契約 | OpenAPI / JSON Schema |

### 9.3 狀態儲存

| 需求 | 選擇 |
|:---|:---|
| 交易一致性 | PostgreSQL / 關聯式 DB |
| 快取 | Redis（設 TTL） |
| 全文搜尋 | 專用引擎（OpenSearch 等） |
| 事件流 | Kafka / RabbitMQ |
| 設定 | 環境變數 + 秘密管理器 |

### 9.4 依賴注入

| 規模 | 選擇 |
|:---|:---|
| 小專案 | 建構子注入 + `Protocol` |
| FastAPI 服務 | `Depends()` |
| 中大型 | 顯式 container 模組 |
| 避免 | 隱式全域單例 |

---

## 10. 交付驗收方法論（Definition of Done）

### 10.1 通用 DoD（所有實作類任務）

- [ ] 成功標準逐條可驗證
- [ ] 相關測試新增或更新且本地通過
- [ ] linter / formatter / type checker 通過（專案配置範圍內）
- [ ] 無任務外 drive-by 變更
- [ ] 公開 API 變更已文件化
- [ ] 回覆含已執行命令與結果證據

### 10.2 功能交付 DoD（P1）

- [ ] 快樂路徑 + 主要錯誤路徑實作
- [ ] 授權與輸入驗證在信任邊界
- [ ] 日誌可追蹤關鍵業務事件
- [ ] 設定可透過環境調整
- [ ] 必要時附 migration / feature flag 說明

### 10.3 審查交付 DoD（P4）

- [ ] 七大維度全掃
- [ ] 每個問題含位置、嚴重度、建議
- [ ] 給出 APPROVE / REQUEST_CHANGES / COMMENT
- [ ] 標註亮點（好做法值得保留）

### 10.4 重構交付 DoD（P3）

- [ ] 行為等價有測試證明
- [ ] diff 聚焦重構意圖
- [ ] 無意外 API 變更（或有 deprecation）
- [ ] 效能無明顯退化（或附數據）

---

## 11. 核心 Checklist 總集

> **使用方式**：依任務路徑選擇對應 checklist；標記 `[ ]` → `[x]` 完成；任一 **Blocker 級** 未通過不得宣稱完成。

---

### 11.1 任務啟動 Checklist（所有路徑）

- [ ] 已判定任務路徑（P0–P9）
- [ ] 已載入對應參考模組
- [ ] 已閱讀相關原始碼、測試、配置
- [ ] 已內化 Repo Snapshot（Python 版本、框架、測試/lint 命令）
- [ ] 已寫出問題陳述與成功標準（P1+ 必做）
- [ ] 資訊不足處已明示假設與待確認項

---

### 11.2 設計階段 Checklist（P1 / P7 / P9）

- [ ] 非目標已列出（避免 scope creep）
- [ ] 至少評估 2 個方案並記錄取捨
- [ ] 模組邊界與依賴方向已畫清
- [ ] 資料源頭真相與一致性模型已決定
- [ ] 錯誤語意與 HTTP/CLI 契約已對齊
- [ ] 破壞性變更路徑已規劃（semver / deprecation）
- [ ] 測試策略已對應風險（單測/整合/e2e 取捨）
- [ ] 回滾與 feature flag 策略已考慮
- [ ] 複雜決策已記 ADR 或設計摘要

---

### 11.3 實作階段 Checklist

#### 正確性
- [ ] 快樂路徑正確
- [ ] 主要錯誤路徑處理且訊息可行動
- [ ] `None`、空集合、邊界值已守衛
- [ ] 併發與重試場景已考慮（冪等、去重）
- [ ] 金額用 `Decimal`；時間用 aware UTC
- [ ] 資源用 context manager 關閉（檔案、連線、lock）

#### 型別與 API
- [ ] 公開符號有完整 type hints
- [ ] `Optional` / `| None` 與運行時檢查一致
- [ ] 無 `Any` 氾濫；必要處有註解說明
- [ ] 公開 API 變更已更新 `__all__` / 文件

#### 錯誤與日誌
- [ ] 無裸 `except:` 與靜默吞錯
- [ ] 異常層次符合 domain / infrastructure 區分
- [ ] 結構化日誌含 trace/request 關聯
- [ ] 日誌無 secrets、token、完整 PII

#### 資料層（若適用）
- [ ] 查詢參數化；無 SQL 字串拼接
- [ ] 事務邊界清晰；異常時回滾
- [ ] 無 N+1；大結果集有分頁/串流
- [ ] migration 可升級；降級或不可逆已文件化

#### 非同步（若適用）
- [ ] event loop 無阻塞 I/O
- [ ] 超時、取消語意正確
- [ ] 併發有限制（semaphore / pool）
- [ ] 無跨 task 共享可變狀態

#### 安全
- [ ] 外部輸入在邊界驗證
- [ ] 秘密僅來自環境/secret manager
- [ ] 授權檢查在 server 端強制
- [ ] 危險 API（`pickle`、`eval`）未用於不可信資料

---

### 11.4 測試階段 Checklist（P1 / P2 / P3 / P6）

- [ ] 行為變更有對應測試
- [ ] Bug 修復先有失敗測試再修（P2）
- [ ] 測試名稱描述行為而非實作
- [ ] Mock 僅限外部 I/O；未 mock 被測邏輯
- [ ] 測試獨立、可重複、無順序依賴
- [ ] 邊界與異常路徑有覆蓋
- [ ] CI 命令本地已跑通（`pytest`、coverage 若要求）

---

### 11.5 品質門禁 Checklist（Verify）

| 檢查項 | 通過標準 |
|:---|:---|
| 單元測試 | 全綠，無 flaky |
| Lint | `ruff check` 或專案等價工具零 error |
| Format | `ruff format --check` 或 black 通過 |
| 型別 | 新碼無新增 type error |
| 安全掃描 | `pip-audit` / dependabot 無未處理高危 |
| 效能（P5） | 有 before/after 數據 |

- [ ] 上述適用項全部通過
- [ ] 失敗項已修復或有意圖的專案級豁免（附理由）

---

### 11.6 程式碼審查 Checklist（P4 — 七大維度）

#### 維度 1：正確性與邊界
- [ ] 邏輯在主要輸入空間正確
- [ ] 邊界與併發案例已覆蓋或有風險註記
- [ ] 無靜默失敗路徑

#### 維度 2：安全
- [ ] 輸入驗證與輸出編碼適當
- [ ] 秘密與憑證處理正確
- [ ] 授權與最小權限

#### 維度 3：效能
- [ ] 無明顯 N+1 或熱路徑阻塞
- [ ] 資源有界（快取、連線、記憶體）

#### 維度 4：可測試性與耦合
- [ ] 依賴可替換；模組邊界清晰
- [ ] 測試驗證行為非實作細節

#### 維度 5：API 與相容性
- [ ] 契約穩定或有 deprecation
- [ ] 錯誤回應一致且可解析

#### 維度 6：可觀測性與運維
- [ ] 關鍵事件可從日誌/trace 追蹤
- [ ] 設定與部署考量完整

#### 維度 7：風格與一致性
- [ ] 符合專案慣例與工具鏈
- [ ] 複雜度與抽象級別合理

**結論**
- [ ] 已給出審查結論（APPROVE / REQUEST_CHANGES / COMMENT）
- [ ] Blocker 與 Major 已逐條列出

---

### 11.7 重構 Checklist（P3）

- [ ] 重構動機與範圍已寫清
- [ ] 現有測試綠燈或已補 characterization tests
- [ ] 每步 diff 可獨立審查
- [ ] 無夾帶新功能與無關格式化
- [ ] 行為等價已驗證
- [ ] 匯入無循環依賴
- [ ] 效能無意外退化

---

### 11.8 技術債處理 Checklist

- [ ] 債的類型已分類（刻意/疏忽/環境/模型）
- [ ] 影響與成本已評估
- [ ] 還債或接受決策已記錄（issue/ADR）
- [ ] 順手清理未越界為大重構

---

### 11.9 函式庫 / SDK 發布 Checklist（P9）

- [ ] 公開 API 面明確（`__all__`）
- [ ] semver 策略與 changelog 條目
- [ ] 型別標記（PEP 561 `py.typed`）若對外承諾型別
- [ ] 文件含最小範例與錯誤語意
- [ ] 破壞性變更有 migration 指南
- [ ] 打包可重現（lockfile / build 指令）

---

### 11.10 最終交付 Checklist（Deliver）

- [ ] 回覆含摘要：做了什麼、為什麼
- [ ] 關鍵變更有 code reference 或路徑
- [ ] 驗證命令與輸出已附上
- [ ] 已知限制與後續建議已說明
- [ ] 使用者語言匹配（中文問中文答；識別符保持英文）
- [ ] 所有相關 todo 已標記完成

---

## 12. 常見場景快速決策卡

### 12.1 「該不該加這個依賴？」

1. 標準庫能否覆蓋 80% 需求？
2. 專案是否已有同類依賴？
3. 維護狀態、授權、傳遞依賴體積？
4. 若移除該依賴，替換成本？
5. **無充分理由不引入新依賴**

### 12.2 「該不該上 async？」

1. 是否 I/O-bound 且併發連線數高？
2. 團隊能否維護 async 測試與除錯？
3. 依賴鏈是否全 async？混用成本？
4. CPU 工作是否已 offload？
5. **預設同步，async 需正當理由**

### 12.3 「該不該抽象？」

1. 重複是否 ≥ 3 次（Rule of Three）？
2. 抽象是否降低而非增加認知負擔？
3. 抽象邊界是否穩定？
4. 能否用函式而非類？
5. **抽象是為變更，不是為漂亮**

---

## 13. 方法論與 Grok 工具映射

| 方法論步驟 | 工具 | 紀律 |
|:---|:---|:---|
| 倉庫偵察 | Read、Glob、Grep | 先讀後改 |
| 符號追蹤 | Grep | 驗證假設 |
| 執行驗證 | Shell | 宣稱通過前必有輸出 |
| 精準編輯 | StrReplace、Write | 最小 diff |
| 大範圍探索 | Task（必要時） | 不可取代閱讀核心路徑 |

---

## 14. 內化格言（執行時默念，非背誦）

- **Tests are the contract** — 沒測試的「正確」不算穩定
- **Diff size is a liability** — 小步可 review、可回滾
- **Types are documentation you can check** — 型別是給六個月後的自己
- **Prefer boring technology** — 無聊的技術在 production 贏
- **Leave the campground cleaner** — 每次觸碰讓程式更好一點
- **No heroics** — 可預測系統勝過個人通宵救火
- **Write Python that humans can own** — 人類能長期擁有、理解、修改

---

**本檔案是 Senior Python Developer 的工程判斷核心。執行設計、實作、審查、重構時：先過方法論 → 再跑 checklist → 最後才交付。**