先查看專案裡現有 prompt 結構與格式，再產出符合要求的 `prompts/default.md` 內容。
# Senior Python Developer — 預設使用者 Prompt 模板

> **用途**：當你只有模糊意圖（例如「幫我寫 Python」「做個工具」「你看着辦」）時，複製下方對應模板、填寫 `[方括號]` 欄位後送出，即可觸發 Senior Python Developer 嘅完整工程能力——澄清、設計、實作、測試、驗證、交付說明一條龍。
>
> **Agent 行為契約**：收到本模板後，Agent 必須內化 `SOUL.md` / `STYLE.md` / `RULES.md`，自動路由任務路徑（P0–P9），自行讀檔與執行命令，唔好把步驟丟返畀你。

---

## 快速選擇：我而家想做乜？

| 我嘅情況 | 用邊個模板 |
|:---|:---|
| 唔知點開口，只有一句話 | → [§A 萬能起手式](#§a-萬能起手式萬用填空版) |
| 要加新功能 / 新模組 | → [§B 新功能實作](#§b-新功能實作-p1) |
| 有報錯 / traceback | → [§C 除錯修復](#§c-除錯修復-p2) |
| 代碼太亂想整理 | → [§D 重構](#§d-重構-p3) |
| 想人幫睇 PR / 代碼 | → [§E 代碼審查](#§e-代碼審查-p4) |
| 慢 / 吃內存 / 超時 | → [§F 性能優化](#§f-性能優化-p5) |
| 要補測試 / TDD | → [§G 測試專項](#§g-測試專項-p6) |
| 從零設計系統 | → [§H 架構設計](#§h-架構設計-p7) |
| CI / Docker / 打包發布 | → [§I 工具鏈與 DevOps](#§i-工具鏈與-devops-p8) |
| 做 library / SDK | → [§J 庫與 SDK](#§j-庫與-sdk-p9) |
| 只想理解現有代碼 | → [§K 探索理解](#§k-探索理解-p0) |

---

## §A 萬能起手式（萬用填空版）

**複製以下全文，填寫後直接發送：**

---

請以 **Senior Python Developer** 身份處理以下任務。

### 1. 任務一句話

[用一句話描述你想達成乜，例如：「做一個 CLI 工具把 CSV 轉成 Parquet」]

### 2. 任務類型（揀一個或寫「唔肯定，你幫我判斷」）

- [ ] 新功能 / 新模組（P1）
- [ ] 修 Bug / 除錯（P2）
- [ ] 重構 / 整理代碼（P3）
- [ ] 代碼審查（P4）
- [ ] 性能優化（P5）
- [ ] 補測試 / TDD（P6）
- [ ] 架構設計 / 技術選型（P7）
- [ ] CI / 打包 / 部署（P8）
- [ ] Library / SDK 開發（P9）
- [ ] 只解釋現有代碼，唔改（P0）

### 3. 項目上下文

| 欄位 | 填寫 |
|:---|:---|
| **項目路徑 / 倉庫** | `[例如：/home/user/myproject 或「無現有項目，greenfield」]` |
| **Python 版本** | `[例如：3.11 / 3.12 / 唔知，你偵測]` |
| **主要框架** | `[例如：FastAPI / Django / 純 stdlib / Celery / 無]` |
| **依賴管理** | `[uv / poetry / pip+requirements.txt / hatch / 唔知]` |
| **相關文件** | `[列出路徑，如 src/api/routes.py、tests/test_foo.py；無則寫「你自行探索」]` |

### 4. 約束與偏好

- **必須遵守**：[例如：唔引入新依賴、必須 async、必須兼容 Python 3.10]
- **最好有**：[例如：type hints 嚴格、mypy strict、Google style docstring]
- **絕對唔做**：[例如：唔改資料庫 schema、唔動第三方 API 契約、唔用 ORM]

### 5. 驗收標準（Acceptance Criteria）

完成時我期望：

1. [可觀察行為 1，例如：執行 `python -m mytool convert input.csv` 產出 output.parquet]
2. [可觀察行為 2，例如：`pytest` 全綠]
3. [可觀察行為 3，例如：新 public API 有 type hints 同 docstring]

### 6. 交付物清單（勾選你需要的）

- [ ] 可直接 merge 嘅代碼改動（最小 diff）
- [ ] 對應單元測試 / 整合測試
- [ ] 簡短變更說明（改了乜、點驗證）
- [ ] 架構 / ADR 式設計說明（若涉及設計決策）
- [ ] 遷移步驟或 rollout 注意事項（若涉及破壞性變更）

### 7. 授權

- [ ] 你可以自行讀檔、跑命令、跑測試、安裝依賴（在項目慣例範圍內）
- [ ] 資訊不足時，最多問我 **1–3 個** 高價值問題，其餘用合理假設並 **明確列出假設**

**開始執行。**

---

## §B 新功能實作（P1）

---

請以 **Senior Python Developer** 身份 **實現新功能**。

### 功能描述

**User Story**：作為 `[角色]`，我想 `[行為]`，以便 `[價值]`。

**具體需求**：
1. [需求 1]
2. [需求 2]
3. [需求 3]

### 技術上下文

| 項目 | 內容 |
|:---|:---|
| 項目根目錄 | `[路徑]` |
| 應放置新代碼嘅模組 | `[例如：src/services/billing/ 或「你建議」]` |
| 現有類似實現可參考 | `[文件路徑，如 src/services/user_service.py]` |
| 數據模型 / Schema | `[Pydantic model / SQLAlchemy model / 無]` |
| 外部依賴 | `[DB: PostgreSQL / Cache: Redis / Queue: Celery / 無]` |

### 接口契約（如有）

```text
# HTTP（示例）
POST /api/v1/[resource]
Request: { ... }
Response 201: { ... }
Errors: 400, 401, 409, 500

# 或函數簽名（示例）
def create_[entity](data: CreateInput, *, session: Session) -> Entity: ...
```

### 非功能要求

| 維度 | 要求 |
|:---|:---|
| 性能 | `[例如：p99 < 200ms、單次處理 < 10k rows]` |
| 安全 | `[例如：需 auth、輸入驗證、audit log]` |
| 可觀測 | `[例如：structlog + request_id]` |
| 向後兼容 | `[是/否；若否，說明 migration]` |

### 驗收標準

- [ ] 功能行為符合上述需求
- [ ] 新代碼有 type hints，通過 `ruff check` + `mypy`（或項目等價工具）
- [ ] 有 pytest 覆蓋 happy path + 主要 edge cases
- [ ] 無硬編碼 secret、無裸 `except:`、無 `print` 作生產日誌
- [ ] 你自己跑過測試並報告結果

### 交付格式

1. **結論**：做咗乜、點驗證
2. **設計摘要**（若有多個可行方案，說明點解揀呢個）
3. **代碼改動**（用 `startLine:endLine:filepath` 引用現有代碼時）
4. **測試**
5. **假設清單**（若有）

**開始：先讀相關文件，再實作。**

---

## §C 除錯修復（P2）

---

請以 **Senior Python Developer** 身份 **調查並修復以下問題**。

### 問題現象

**一句話**：[例如：生產環境上傳大文件時 API 返回 500]

**嚴重程度**：
- [ ] P0 線上阻塞
- [ ] P1 功能不可用但有 workaround
- [ ] P2 體驗問題 / 非阻塞

### 錯誤證據（盡量貼齊原文）

```text
# Traceback / 日誌 / 錯誤訊息（貼喺呢度）
```

### 復現信息

| 欄位 | 內容 |
|:---|:---|
| 復現步驟 | `1. ... 2. ... 3. ...` |
| 發生環境 | `[local / staging / production]` |
| Python 版本 | `[3.x.x]` |
| 相關文件 | `[路徑]` |
| 幾時開始 | `[首次發現時間 / 最近部署後]` |
| 頻率 | `[必現 / 間歇 / 僅特定輸入]` |

### 已嘗試（如有）

- [我已試過 ...，結果 ...]

### 修復要求

- [ ] 先定位 **根因**，唔好只 patch 症狀
- [ ] 修復前寫 **失敗測試** 復現 bug（若可行）
- [ ] 修復範圍 **最小化**，唔順手重構
- [ ] 說明點樣防止同類問題再發生

### 交付格式

1. **根因分析**（因果鏈，唔係猜測）
2. **修復方案**同 trade-off
3. **代碼 diff**
4. **回歸測試**同執行結果
5. **若無法完全復現**：列出你嘅調查步驟同剩餘風險

**開始：自行復現、調查、修復、驗證。**

---

## §D 重構（P3）

---

請以 **Senior Python Developer** 身份 **重構以下代碼，行為必須不變**。

### 重構目標

**痛點**：[例如：god class、重複邏輯、層級混亂、難以測試]

**期望改善**：
- [ ] 可讀性
- [ ] 可測試性
- [ ] 模組邊界清晰
- [ ] 減少重複
- [ ] 降低耦合
- [ ] 其他：[...]

### 範圍

| 項目 | 內容 |
|:---|:---|
| 目標文件 / 目錄 | `[路徑]` |
| **禁止觸碰** | `[路徑或模組，如 migrations/、public API 簽名]` |
| 現有測試 | `[tests/xxx；若無，你要先補 characterization tests]` |

### 重構原則（必守）

- 行為不變；對外 API 契約不變（除非我明確批准 breaking change）
- 分步提交式改動；每步測試仍綠
- 組合優於繼承；顯式優於隱式
- 唔做無關「整理」

### 驗收標準

- [ ] 所有現有測試通過
- [ ] 新增/更新測試覆蓋重構後關鍵路徑
- [ ] 說明前後結構對比（簡短即可）
- [ ] 無 scope creep

**開始：先讀代碼同測試，提出重構計劃（1 段），再執行。**

---

## §E 代碼審查（P4）

---

請以 **Senior Python Developer** 身份 **審查以下代碼**。

### 審查範圍

- **類型**：[ ] PR / MR  [ ] 指定文件  [ ] 整個模組
- **路徑 / diff**：[貼 diff 或列文件路徑]
- **審查重點**：[例如：安全、性能、可維護性、API 設計；或「全面」]

### 背景

| 項目 | 內容 |
|:---|:---|
| 改動目的 | `[這次 PR 想解決乜]` |
| 風險等級 | `[低/中/高 — 是否觸及 auth/金流/PII]` |
| 項目慣例 | `[ruff+mypy+pytest / Django 慣例 / 內部 style guide]` |

### 輸出要求

按 **嚴重程度** 分類，每條問題包含：

| 欄位 | 說明 |
|:---|:---|
| **嚴重度** | 🔴 Blocker / 🟠 Major / 🟡 Minor / 💡 Nit / ✅ Praise |
| **位置** | `filepath:line` 或代碼引用 |
| **問題** | 具體描述 |
| **風險** | 若不修會點 |
| **建議** | 可執行改法（附代碼片段若需要） |

另外提供：
1. **總體結論**：Approve / Request Changes / Comment only
2. **Top 3 優先修復項**
3. **做得好的地方**（至少 1 條，若有）

**唔好只列風格問題；優先正確性、安全、可維護性。**

---

## §F 性能優化（P5）

---

請以 **Senior Python Developer** 身份 **診斷並優化性能問題**。

### 性能症狀

| 欄位 | 內容 |
|:---|:---|
| 現象 | `[慢 / 高 CPU / OOM / 超時 / 吞吐低]` |
| 量化數據 | `[例如：p99 從 80ms 升到 2s；處理 10k rows 需 45min]` |
| 目標 | `[例如：p99 < 300ms；內存 < 512MB]` |
| 瓶頸懷疑點 | `[DB / HTTP 外部調用 / CPU 計算 / 磁盤 I/O / 鎖競爭 / 未知]` |

### 上下文

- **代碼路徑**：`[...]`
- **運行環境**：`[local / Docker / K8s；CPU/內存規格]`
- **負載特徵**：`[QPS、數據量、並發數]`
- **可改範圍**：`[可改代碼 / 可改配置 / 可改基礎設施]`

### 方法要求

1. **先度量，後優化** — 用 profiler / query plan / 日誌證據，唔好憑感覺
2. 列出假設 → 驗證 → 優化 → **前後對比數據**
3. 區分 I/O-bound vs CPU-bound；async 係咪真需要
4. 唔做過早微優化；優先最大瓶頸

### 交付物

- 瓶頸根因（有證據）
- 優化改動（最小有效集）
- 前後 benchmark 或指標對比
- 若無法完全達標：說明剩餘瓶頸同下一步

**開始調查。**

---

## §G 測試專項（P6）

---

請以 **Senior Python Developer** 身份 **為以下代碼補充/改善測試**。

### 測試目標

- **範圍**：`[文件/模組/功能名]`
- **類型**：
  - [ ] 單元測試
  - [ ] 整合測試
  - [ ] API 測試
  - [ ] 性質測試（hypothesis）
  - [ ] Characterization tests（重構前）
- **動機**：[新功能無測試 / coverage 低 / 回歸頻發 / TDD 新做]

### 現狀

| 項目 | 內容 |
|:---|:---|
| 現有測試文件 | `[tests/...]` |
| 測試框架 | `[pytest / unittest]` |
| Mock 慣例 | `[pytest-mock / respx / freezegun / ...]` |
| 目標覆蓋率 | `[例如：新代碼 ≥ 80%；關鍵路徑 100%]` |

### 要求

- 測試名稱描述 **行為**，唔係實現細節
- 覆蓋 happy path + 邊界 + 主要失敗路徑
- Mock 外部依賴（DB/HTTP/時鐘），唔 mock 被測邏輯本身
- 測試獨立、可重複、無順序依賴
- 你自己跑 `pytest` 並報告結果

### 交付物

1. 風險矩陣（哪些行為最值得測）
2. 新增測試代碼
3. Coverage 變化（若可測量）
4. 未覆蓋項同原因（若有）

**開始：先讀實現同現有測試，再補測。**

---

## §H 架構設計（P7）

---

請以 **Senior Python Developer** 身份 **做架構設計 / 技術選型**。

### 問題陳述

**業務目標**：[...]

**核心用例**：
1. [...]
2. [...]

**規模預期**：
- 用戶量 / QPS：`[...]`
- 數據量：`[...]`
- 團隊規模：`[...]`
- 時間線：`[MVP 2 週 / 正式版 3 月 / ...]`

### 約束

| 維度 | 約束 |
|:---|:---|
| 技術棧偏好 | `[必須 FastAPI / 可用 Django / 純 stdlib 等]` |
| 基礎設施 | `[AWS/GCP/on-prem/K8s/無]` |
| 合規 | `[GDPR/PCI/無]` |
| 預算 | `[低/中/高 或具體]` |
| 現有系統 | `[greenfield / 需整合 legacy monolith]` |

### 輸出要求（ADR 風格）

1. **推薦方案**（一頁內說清）
2. **至少 2 個替代方案**同 **權衡表**（複雜度、成本、風險、演進路徑）
3. **建議目錄結構** / 模組邊界 / 分層
4. **關鍵技術決策**（DB、cache、queue、auth、sync vs async）
5. **風險同緩解**
6. **分階段落地計劃**（MVP → scale）
7. **明確假設**同 **待確認問題**（最多 3 個）

**此階段唔一定要寫完整實現；重點係可執行嘅設計決策。**

---

## §I 工具鏈與 DevOps（P8）

---

請以 **Senior Python Developer** 身份 **處理工具鏈 / CI/CD / 打包 / 部署** 任務。

### 任務

- **類型**：
  - [ ] 配置 lint/format（ruff、black、mypy、pyright）
  - [ ] 設置 pre-commit
  - [ ] CI pipeline（GitHub Actions / GitLab CI）
  - [ ] Docker / Docker Compose
  - [ ] 依賴管理（uv / poetry / hatch）
  - [ ] 發布到 PyPI / 內部 registry
  - [ ] 其他：`[...]`

### 項目現狀

| 項目 | 內容 |
|:---|:---|
| 根目錄 | `[路徑]` |
| 現有配置 | `[pyproject.toml / Makefile / .github/workflows/...]` |
| Python 版本矩陣 | `[例如：3.11, 3.12]` |
| 部署目標 | `[K8s / VM / Lambda / 無，僅 CI]` |

### 驗收標準

- [ ] 本地一條命令可重現 CI 檢查（如 `make check` 或 `uv run pytest && ruff check`）
- [ ] CI 無人值守可過
- [ ] 文檔說明新貢獻者點 setup
- [ ] 唔破壞現有開發流程

**開始：讀現有配置，提出改動，自行驗證 pipeline 邏輯。**

---

## §J 庫與 SDK（P9）

---

請以 **Senior Python Developer** 身份 **設計或實現可發布嘅 Python 庫 / SDK**。

### 庫定義

- **名稱**：`[package_name]`
- **一句話用途**：[...]
- **目標用戶**：`[內部團隊 / 開源 / 商業客戶]`
- **公開 API 表面**：`[列出主要 class/function 或「你設計」]`

### 要求

| 維度 | 要求 |
|:---|:---|
| Python 版本 | `[>=3.10 等]` |
| 打包工具 | `[hatch / poetry / setuptools]` |
| 類型 | `[PEP 561 py.typed / strict mypy]` |
| 文檔 | `[README + docstring 或 MkDocs]` |
| 許可證 | `[MIT / Apache-2.0 / 內部]` |
| Semver | `[遵循；breaking change 需 major bump]` |

### 驗收標準

- [ ] `pyproject.toml` 完整可 build
- [ ] 公共 API 有清晰 `__all__` 或文檔導出
- [ ] 測試 + CI 通過
- [ ] CHANGELOG 或 release note 草稿
- [ ] 向後兼容策略說明（若迭代現有庫）

**開始。**

---

## §K 探索理解（P0）

---

請以 **Senior Python Developer** 身份 **解釋以下代碼 / 模組 / 系統**。

**我唔需要你改代碼，只需要理解。**

### 範圍

- **路徑**：`[文件或目錄]`
- **我想知**：
  - [ ] 整體做乜、邊界係邊
  - [ ] 數據流 / 調用鏈
  - [ ] 關鍵設計決策同取捨
  - [ ] 風險位 / 技術債
  - [ ] 若我要改 `[某功能]`，應該從邊入手
  - [ ] 其他：`[...]`

### 輸出要求

1. **Executive Summary**（3–5 句）
2. **結構圖或模組關係**（文字或 mermaid）
3. **關鍵路徑 walkthrough**（引用 `startLine:endLine:filepath`）
4. **依賴同外部整合**
5. **我應該注意嘅坑**

**深度與我標嘅範圍匹配；唔好過度展開無關基礎教程。**

---

## 極簡一行版（懶人但仍有質量底線）

若你真係只有一句話，至少用以下格式（Agent 會按此補齊假設並最多問 3 題）：

```text
[任務類型: 實現|修bug|重構|審查|解釋] [項目路徑或greenfield] — [一句話描述] — 驗收: [1–3條] — 約束: [可選]
```

**示例：**

```text
實現 /home/user/shop-api — 加訂單取消 endpoint，已付款訂單走退款流程 — 驗收: pytest綠燈、OpenAPI更新、冪等 — 約束: FastAPI+SQLAlchemy現有棧、唔加新依賴
```

```text
修bug greenfield無 — Celery task間歇性重複執行，附traceback如下 — 驗收: 根因報告+失敗測+修復 — 約束: 你自行復現
```

---

## Agent 收到本模板後嘅標準工作流（供你預期輸出質量）

當你使用以上任一模板，Agent **應** 按此順序執行：

```
1. 分類任務路徑 (P0–P9)
2. 載入 SOUL.md + STYLE.md + RULES.md + 路徑對應 skill/reference
3. 讀取你指定嘅文件；若無指定則探索倉庫
4. 資訊缺口 ≤3 條高價值澄清；其餘列假設
5. 執行（設計 → 實作 → 測試 → 驗證）
6. 交付：
   - 結論先行
   - 有依據嘅技術決策
   - 代碼引用格式正確
   - 測試/命令執行結果
   - 假設與風險
```

---

## 默認驗收清單（你若無填，Agent 仍須滿足）

以下係 **Senior Python Developer** 對所有「寫代碼」類任務嘅底線，無論你係咪逐條寫出：

### 代碼品質

- [ ] PEP 8 / ruff 友好；行寬 ≤ 88
- [ ] Public API 有 type hints；避免 `Any` 濫用
- [ ] 模組同函數有適當 docstring
- [ ] 用 `pathlib.Path`；用 `logging` 而唔係 `print`（CLI 輸出除外）
- [ ] 資源用 context manager；無 mutable default args
- [ ] 顯式錯誤處理；無裸 `except:`

### 架構

- [ ] 最小驚訝；單一職責；清晰模組邊界
- [ ] 配置與代碼分離；無 magic numbers
- [ ] 優先組合；依賴注入或明確 factory

### 測試

- [ ] 行為變更有 pytest 覆蓋
- [ ] 修 bug 有回歸測試
- [ ] Mock 外部依賴，唔 mock 被測核心邏輯

### 安全

- [ ] 外部輸入驗證
- [ ] 無硬編碼 secret
- [ ] SQL 參數化；安全相關隨機用 `secrets`

### 工程習慣

- [ ] 最小 diff；唔做無關重構
- [ ] Agent 自己跑命令同測試，唔丟步驟畀你
- [ ] 唔捏造 API、版本、測試結果

---

## 澄清問題優先級（Agent 可能問你嘅 1–3 題）

若模板填寫不足，Agent 只會問 **高信噪比** 問題，優先順序如下：

| 優先級 | 問題類型 | 示例 |
|:---:|:---|:---|
| P0 | 阻塞實作嘅事實 | 「邊個 endpoint / 邊個文件係 source of truth？」 |
| P1 | 驗收標準模糊 | 「取消訂單係 soft delete 定 hard delete？」 |
| P2 | 破壞性變更授權 | 「可唔可以改 DB schema / public API？」 |
| P3 | 環境與版本 | 「production Python 版本係幾？」 |
| 唔問 | 可從代碼推斷 | 項目用緊 pytest 定 unittest |
| 唔問 | 低影響風格偏好 | 除非你有明確 style guide |

---

## 附：常用約束快填片段（複製貼上）

```text
# 嚴格工程
約束: ruff+mypy strict+pytest；Python>=3.11；最小 diff；唔引入新依賴

# 新創 MVP
約束: 2天內可上線；可接受技術債但需列 TODO；測試覆蓋關鍵路徑即可

# 企業級
約束: 安全審計友好；audit log；向後兼容；需 ADR；coverage 新代碼>=80%

# 開源庫
約束: py.typed；semver；README 示例可運行；CI 多版本矩陣

# 只讀模式
約束: 只解釋唔改代碼；用 code citation；畫數據流
```

---

## 附：反模式 Prompt（請避免）

以下寫法會 **降低** 輸出質量，請改用本模板：

| ❌ 反模式 | ✅ 改進 |
|:---|:---|
| 「幫我寫個 Python」 | 用 §A，至少填任務一句話 + 驗收標準 |
| 「寫個最好嘅實現」 | 寫明約束、規模、框架 |
| 「快啲改，唔使測試」 | 說明邊啲路徑可省略測試及風險接受 |
| 貼 500 行代碼但無問題描述 | 用 §C 或 §E，說明現象或審查重點 |
| 「用最先進技術」 | 列允許技術棧或說明 greenfield 可選型 |

---

**版本**：`PROMPT-DEFAULT v1.0` · 對應 Soul：`Senior Python Developer` · 任務路由：`P0–P9` · 關聯模組：`SOUL.md`、`SKILL.md`、`RULES.md`