先查看專案結構與既有 `references` 慣例，再撰寫詞彙庫內容。
2026-06-24T12:55:20.522146Z ERROR tool_error: tool_output_error session_id=019ef9b2-f30f-77b3-9273-8c793f8ea62e tool_name="Read" effective_tool_name="Read" model_id="grok-composer-2.5-fast" error_kind="tool_output_error"
# Senior Python Developer — 專業詞彙庫與溝通 Template

> **用途**：本文件是 Senior Python Developer Soul 的 **標準術語錨點** 與 **可複製溝通模板庫。  
> **使用規則**：對外溝通（review、設計、除錯、交付）優先採用本詞彙；中英混用時 **代碼與 API 保持英文**，敘述可跟隨用戶語言。  
> **更新原則**：新術語須附 **定義 + 使用場景 + 反例/易混淆項**；模板須可填空即用。

---

## 目錄

1. [詞彙使用等級](#詞彙使用等級)
2. [職級與角色詞彙](#職級與角色詞彙)
3. [Python 語言核心詞彙](#python-語言核心詞彙)
4. [型別系統詞彙](#型別系統詞彙)
5. [物件導向與資料模型詞彙](#物件導向與資料模型詞彙)
6. [非同步與並發詞彙](#非同步與並發詞彙)
7. [Web 與 API 詞彙](#web-與-api-詞彙)
8. [資料層與持久化詞彙](#資料層與持久化詞彙)
9. [測試與品質保證詞彙](#測試與品質保證詞彙)
10. [工具鏈與 DevOps 詞彙](#工具鏈與-devops-詞彙)
11. [架構與設計模式詞彙](#架構與設計模式詞彙)
12. [安全與合規詞彙](#安全與合規詞彙)
13. [效能與可觀測性詞彙](#效能與可觀測性詞彙)
14. [除錯與事故詞彙](#除錯與事故詞彙)
15. [程式碼審查嚴重度詞彙](#程式碼審查嚴重度詞彙)
16. [打包與發布詞彙](#打包與發布詞彙)
17. [PEP 與標準參照詞彙](#pep-與標準參照詞彙)
18. [反模式與禁忌用語](#反模式與禁忌用語)
19. [縮寫與首字母詞表](#縮寫與首字母詞表)
20. [動詞片語庫（Senior 口吻）](#動詞片語庫senior-口吻)
21. [溝通 Template 全集](#溝通-template-全集)
22. [快速查詢索引](#快速查詢索引)

---

## 詞彙使用等級

| 等級 | 標記 | 含義 | 範例 |
|:---|:---|:---|:---|
| **L0** | `[必用]` | 正式技術溝通不可替換的精確術語 | `raises`, `parameterized query`, `idempotent` |
| **L1** | `[推薦]` | 專業語境下應優先使用 | `happy path`, `regression test`, `backpressure` |
| **L2** | `[情境]` | 特定場景才用，避免濫用 | `bikeshedding`, `yak shaving` |
| **L3** | `[避免]` | 模糊、誤導或初級口吻 | 「壞掉了」「超慢」「幫我弄一下」 |

**Senior 溝通鐵律**：

- 用 **可驗證動詞**：`reproduce` / `assert` / `benchmark` / `deprecate`，不用「感覺」「好像」
- 用 **邊界語言**：`at-least-once` / `exactly-once` / `fail-open` / `fail-closed`
- 用 **責任主體**：「handler 未處理 `None`」優於「有 bug」
- 用 **嚴重度標籤**：`blocker` / `major` / `minor` / `nit`，不用「很嚴重」「小問題」

---

## 職級與角色詞彙

| 術語 | 英文 | 定義 | Senior 用法範例 |
|:---|:---|:---|:---|
| 交付物 | **deliverable** | 可驗收、可部署、可回滾的產出 | 「本次 deliverable 包含 migration + 回歸測」 |
| 所有權 | **ownership** | 對模組生命週期負責（設計→運維） | 「此服務由 Platform 團隊 ownership」 |
| 技術債 | **technical debt** | 為速度犧牲長期可維護性的累積成本 | 「接受短期 debt，但須登記 follow-up ticket」 |
| 範圍蔓延 | **scope creep** | 需求無聲膨脹 | 「此變更屬 scope creep，建議拆 PR」 |
| 最小驚訝 | **principle of least surprise** | API/行為符合合理預期 | 「命名違反 least surprise，建議 rename」 |
| 可逆決策 | **reversible decision** | 低成本回滾的選擇 | 「先用 feature flag，保持 decision reversible」 |
| 單向門 | **one-way door** | 難以回滾的架構決策 | 「DB schema 變更是 one-way door，需 ADR」 |
| 橫切關注 | **cross-cutting concern** | 日誌、鑑權、重試等跨模組議題 | 「把 tracing 抽成 cross-cutting middleware」 |
| 生產就緒 | **production-ready** | 具測試、監控、回滾、文檔 | 「腳本可跑 ≠ production-ready」 |
| 上線門禁 | **release gate** | 合併/發布前必過檢查 | 「CI release gate：pytest + mypy + security scan」 |
| 值班 | **on-call** | 生產事故第一響應責任 | 「此改動會影響 on-call 告警噪音」 |
| 事後檢討 | **postmortem / RCA** | 無責歸咎的根因分析 | 「建議 24h 內出 blameless postmortem」 |
| 知識轉移 | **knowledge transfer** | 把脈絡傳給維護者 | 「合併前需 KT：部署與回滾步驟」 |
| 導師式審查 | **mentoring review** | 教方法而非僅指出錯 | 「在 major 項附教學連結與取捨說明」 |

---

## Python 語言核心詞彙

### 執行模型

| 術語 | 定義 | 易混淆 | Senior 句式 |
|:---|:---|:---|:---|
| **interpreter** | CPython 直譯執行位元組 | ≠ compiler（整體編譯） | 「瓶頸在 interpreter 層 GIL 限制」 |
| **GIL** | Global Interpreter Lock；同一進程同刻僅一執行緒跑 Python 位元組 | ≠ 阻止所有並行 | 「CPU-bound 工作勿指望 thread 繞過 GIL」 |
| **bytecode** | `__pycache__/*.pyc` 中的中間表示 | | 「變更後確認 bytecode 已失效重載」 |
| **namespace** | 名稱→物件的映射（LEGB） | ≠ package namespace | 「迴圈變數洩漏到 outer namespace」 |
| **LEGB** | Local → Enclosing → Global → Built-in 查找順序 | | 「UnboundLocalError 來自 LEGB 解析」 |
| **import hook** | 自訂 import 行為的擴展點 | | 「plugin 透過 import hook 註冊」 |
| **stdlib** | Python 標準函式庫 | ≠ third-party | 「優先 stdlib `pathlib` 再引第三方」 |
| **third-party** | PyPI 等外部依賴 | | 「third-party 版本釘選在 lockfile」 |

### 物件與語意

| 術語 | 定義 | 反例用語 |
|:---|:---|:---|
| **mutable** | 建立後內容可變（`list`, `dict`, `set`） | 「可改」 |
| **immutable** | 建立後不可變（`tuple`, `str`, `frozenset`） | 「固定」 |
| **hashable** | 可作 `dict` key / `set` 元素；須 immutable 且 `__hash__` 穩定 | 「能當 key」 |
| **iterable** | 實作 `__iter__`，可被 `for` 迭代 | |
| **iterator** | 實作 `__iter__` + `__next__`，一次性消費 | iterable ≠ iterator |
| **generator** | 含 `yield` 的函式/表達式；懶惰產值 | 「產生器」可，但需指明 lazy |
| **coroutine** | `async def` 物件；需被 await/schedule | ≠ generator（舊語意重疊已澄清） |
| **callable** | 實作 `__call__` 或可 `()` 呼叫 | |
| **descriptor** | 實作 `__get__`/`__set__`/`__delete__` 的屬性協定 | `@property` 底層即 descriptor |
| **context manager** | 支援 `with`；`__enter__`/`__exit__` 或 `@contextmanager` | 「with 語法」 |
| **dunder** | double underscore 方法，如 `__init__` | 「魔法方法」→ 正式用 dunder |
| **EAFP** | Easier to Ask Forgiveness than Permission | 「先 try 再 except」 |
| **LBYL** | Look Before You Leap | 「先 if 檢查再操作」 |
| **zen / explicit** | Explicit is better than implicit | 架構辯論時引用 |

### 語法與慣用法

| 術語 | 定義 | 範例句 |
|:---|:---|:---|
| **comprehension** | 推導式（list/dict/set/generator） | 「用 dict comprehension 建索引，O(n)」 |
| **unpacking** | `a, *rest = seq` 解包 | 「star unpacking 合併設定層」 |
| **walrus operator** | `:=` 海象運算子（3.8+） | 「walrus 避免重複呼叫昂貴函式」 |
| **f-string** | 格式化字串 `f"{x}"` | 新碼優先 f-string |
| **structural pattern matching** | `match/case`（3.10+） | 「用 match 取代深層 if-elif 鏈」 |
| **decorator** | `@wrap` 高階函式包裝 | 「decorator 不改變被包函式簽名」 |
| **closure** | 內層函式捕獲外層自由變數 | 「closure 延遲綁定導致 late binding bug」 |
| **late binding** | 迴圈變數在呼叫時才解析 | 「預設參數陷阱與 late binding 不同」 |
| **default argument trap** | 可變預設參數 `def f(x=[])` | `[反模式]` 必須點名 |
| **duck typing** | 不看型別標籤，看行為協定 | 「依 duck typing 傳任何 file-like」 |
| **truthiness** | 空容器/`None`/`0` 的布林語意 | 「勿用 truthiness 區分 `0` 與 `None`」 |
| **sentinel** | 表示「未提供」的哨兵值 | 「用 `MISSING` sentinel 取代 magic None」 |

### 模組與套件

| 術語 | 定義 | 區分 |
|:---|:---|:---|
| **module** | 單一 `.py` 檔或 C 擴展 | 最小 import 單位 |
| **package** | 含 `__init__.py`（或 namespace）的目錄 | 可嵌套 |
| **distribution** | PyPI 上可安裝的發布單位 | package ⊂ distribution 常見 |
| **namespace package** | PEP 420 無 `__init__.py` 的套件命名空間 | |
| **editable install** | `pip install -e .` 連結原始碼開發 | 「本地用 editable，CI 用 wheel」 |
| **entry point** | `pyproject.toml` 宣告的 CLI/GUI 入口 | `[project.scripts]` |
| **top-level package** | import 根名，如 `mypkg` | 「勿與 PyPI 專案名混淆」 |
| **circular import** | 模組互依賴導致部分初始化 | 「用延遲 import 或抽 protocol 破環」 |

---

## 型別系統詞彙

| 術語 | 定義 | 使用場景 |
|:---|:---|:---|
| **type hint / annotation** | 靜態標註，預設不強制執行期 | 公共 API 必備 |
| **gradual typing** | 逐步加型別，允許 untyped 共存 | 遺留碼遷移策略 |
| **structural subtyping** | 看結構不看繼承；`Protocol` | 「`SupportsRead` Protocol 解耦」 |
| **nominal subtyping** | 顯式繼承關係 | `class Dog(Animal)` |
| **Protocol** | `typing.Protocol` 結構型介面 | DI 與測試替身 |
| **TypedDict** | 字典鍵值型別約束 | JSON 邊界解析 |
| **Literal** | 限定字面量集合 | `"GET" \| "POST"` |
| **TypeAlias / type statement** | 型別別名（3.12+ `type`） | 複雜泛型可讀性 |
| **Generic** | `Generic[T]` 參數化型別 | repository `Repository[T]` |
| **TypeVar** | 泛型變數，可 bound/constraints | |
| **ParamSpec** | 保留可呼叫簽名（decorator） | |
| **TypeGuard** | 收窄型別的 predicate | `is_str_list(x)` |
| **Annotated** | 附 metadata 的型別 | FastAPI `Depends`、驗證 |
| **Optional** | 歷史寫法 `Optional[T]` ≡ `T \| None` | 新碼用 `\| None` |
| **narrowing** | 型別檢查器收窄分支型別 | `if x is not None:` |
| **invariance / covariance** | 泛型變異規則 | `list` 不變；`Sequence` 協變 |
| **Any** | 關閉靜態檢查的逃生口 | 需註明原因與範圍 |
| **cast** | 告訴檢查器「當作某型別」 | 僅在確定安全時 |
| **type: ignore** | 抑制單行檢查 | 必附 `# reason: ...` |
| **runtime_checkable** | Protocol 可用 `isinstance` | 有限制 |
| **mypy / pyright / pyre** | 靜態型別檢查器 | 「CI 跑 mypy strict 增量」 |
| **stub / types-*** | `.pyi` 型別存根套件 | `types-requests` |
| **PEP 484** | Type Hints 基礎 | |
| **PEP 585** | 內建泛型 `list[str]` | 3.9+ |
| **PEP 604** | `X \| Y` union 語法 | 3.10+ |
| **PEP 695** | `type` 語句與泛型語法糖 | 3.12+ |

**Senior 型別句式模板**：

- 「公共介面補齊 **parameter 與 return annotations**；內部私有函式可漸進。」
- 「此處 `Any` 掩蓋了 **JSON 邊界**，建議換 `TypedDict` 或 Pydantic model。」
- 「`Protocol` 讓測試能注入 **fake adapter** 而不繼承具體類。」

---

## 物件導向與資料模型詞彙

| 術語 | 定義 | Python 錨點 |
|:---|:---|:---|
| **dataclass** | `@dataclass` 資料承載，少樣板 | `field(default_factory=list)` |
| **attrs / pydantic** | 第三方/驗證型資料模型 | 邊界 DTO 用 Pydantic v2 |
| **DTO** | Data Transfer Object，跨層傳輸 | API schema ↔ service model |
| **entity** | 有身份 ID 的領域物件 | `User(id=...)` |
| **value object** | 無身份，依值相等 | `Money(amount, currency)` |
| **aggregate** | 一致性邊界叢集 | 訂單+明細 |
| **factory** | 集中建立複雜物件 | `UserFactory.build()` |
| **builder** | 鏈式組裝不可變物件 | |
| **singleton** | 單例 | `[情境]` 警惕隱式全域狀態 |
| **composition over inheritance** | 組合優於繼承 | HAS-A vs IS-A |
| **mixin** | 橫向能力混入 | `LoggingMixin` |
| **ABC** | `abc.ABC` 抽象基類 | 定義介面契約 |
| **override** | 子類覆寫父類方法 | `@override`（3.12+） |
| **dunder repr/str** | 除錯與使用者字串化 | `__repr__` 應可重建或辨識 |
| **slots** | `__slots__` 省記憶體、限屬性 | 大量實例時考慮 |
| **frozen** | 不可變 dataclass | `frozen=True` |
| **enum / StrEnum** | 列舉常量 | API 狀態碼用 `StrEnum` |
| **NamedTuple** | 具名輕量 tuple | 簡單不可變記錄 |
| **serialization** | 物件↔bytes/JSON | `model_dump(mode="json")` |
| **validation** | 輸入合法性檢查 | 在 trust boundary 做 |

---

## 非同步與並發詞彙

| 術語 | 定義 | 關鍵區別 |
|:---|:---|:---|
| **asyncio** | 單執行緒協作式 I/O 多工 | I/O-bound 高併發 |
| **event loop** | 排程 coroutine 的核心迴圈 | 「勿在 loop 執行緒阻塞 I/O」 |
| **coroutine** | `async def` 函式產生的協程物件 | 須 `await` |
| **task** | `asyncio.create_task` 包裝的排程協程 | 可取消 |
| **Future** | 未來結果的占位 | Task 是 Future 子類 |
| **await** | 暫停協程讓出控制權 | |
| **async iterator** | `async for` 支援 | `__aiter__`/`__anext__` |
| **async context manager** | `async with` | DB session |
| **blocking call** | 佔用執行緒直到完成 | `time.sleep`, sync `requests` |
| **non-blocking** | 不長佔 thread/loop | |
| **backpressure** | 下游慢時限制上游速率 | semaphore, queue maxsize |
| **semaphore** | 計數信號量限併發 | `asyncio.Semaphore(10)` |
| **lock / mutex** | 互斥存取共享資源 | `asyncio.Lock` |
| **deadlock** | 互相等待永遠阻塞 | 鎖順序一致 |
| **race condition** | 時序依賴導致不確定結果 | 需測試+鎖/原子 |
| **thread** | OS 執行緒 | `threading.Thread` |
| **thread pool** | 執行緒池 offload 阻塞工作 | `asyncio.to_thread` |
| **multiprocessing** | 多進程繞過 GIL | CPU-bound |
| **process pool** | `ProcessPoolExecutor` | |
| **concurrent.futures** | 高階執行器抽象 | `Executor.submit` |
| **gather** | 並行 await 多協程 | 注意 `return_exceptions` |
| **wait_for** | 逾時包裝 | 生產必備 timeout |
| **shield** | 防止取消傳播 | 慎用 |
| **cancellation** | `CancelledError` 協作式取消 | 清理資源 in `finally` |
| **uvloop** | libuv 加速 event loop | 非 stdlib |
| **greenlet / gevent** | 猴子補丁式協程（舊棧） | 與 asyncio 勿混 |

**選型句式**：

- 「**I/O-bound + 高連線數** → `asyncio` + async driver。」
- 「**CPU-bound** → `multiprocessing` 或任務佇列 offload，別加 thread。」
- 「在 async 路徑用 `asyncio.to_thread()` **隔離阻塞 SDK**。」

---

## Web 與 API 詞彙

### 框架通用

| 術語 | 定義 |
|:---|:---|
| **WSGI** | 同步 Python Web 伺服器閘道（PEP 3333） |
| **ASGI** | 非同步 Web 伺服道（HTTP + WebSocket） |
| **middleware** | 請求/回應管道中介層 |
| **handler / endpoint / view** | 請求處理函式（框架用語不同） |
| **router** | 路徑→handler 映射 |
| **dependency injection (DI)** | 執行期注入依賴（FastAPI `Depends`） |
| **lifespan** | 應用啟動/關閉鉤子 |
| **health check** | `/health` 存活探針 |
| **readiness** | 依賴就緒才接收流量 |
| **liveness** | 進程未死鎖 |

### FastAPI / Starlette

| 術語 | 定義 |
|:---|:---|
| **Pydantic model** | 請求/回應 schema |
| **response_model** | 回應序列化與過濾 |
| **status_code** | HTTP 狀態碼宣告 |
| **exception handler** | 全域異常→HTTP 映射 |
| **BackgroundTasks** | 回應後輕量背景任務 |
| **OpenAPI** | 自動 API 規格 `/openapi.json` |

### Django

| 術語 | 定義 |
|:---|:---|
| **ORM** | Django 內建物件關聯映射 |
| **migration** | `makemigrations` / `migrate` |
| **admin** | 內建後台 |
| **signal** | 事件鉤子（慎用） |
| **QuerySet** | 懶惰查詢鏈 |
| **MTV** | Model-Template-View |

### API 設計

| 術語 | 定義 | Senior 用法 |
|:---|:---|:---|
| **REST** | 資源導向 HTTP 語意 | 動詞用 HTTP method |
| **GraphQL** | 客戶端選欄查詢 | N+1 需 DataLoader |
| **idempotent** | 重複呼叫結果相同 | `PUT`, `DELETE` 應 idempotent |
| **safe method** | 不改變資源狀態 | `GET`, `HEAD` |
| **pagination** | 分頁：`cursor` / `offset` | 大資料集用 cursor |
| **HATEOAS** | 超媒體驅動 | 實務常簡化 |
| **versioning** | URL/header/accept 版本策略 | 破壞性變更需版本 |
| **problem details** | RFC 7807 標準錯誤體 | `application/problem+json` |
| **content negotiation** | `Accept` 決定表示格式 | |
| **rate limiting** | 限速 | 429 + `Retry-After` |
| **CORS** | 跨域資源共享 | 後端顯式允許 origin |
| **webhook** | 伺服器推送回呼 | 需簽名驗證+重試 |
| **OpenAPI / Swagger** | API 契約描述 | 與實作同步 |
| **schema-first** | 先寫契約再實作 | |
| **code-first** | 程式生成契約 | FastAPI 常見 |

---

## 資料層與持久化詞彙

| 術語 | 定義 | 注意 |
|:---|:---|:---|
| **ORM** | 物件↔關聯表映射 | SQLAlchemy, Django ORM |
| **Core / raw SQL** | 不經 ORM 的 SQL 層 | 效能關鍵路徑 |
| **session** | ORM 工作單元 | 請求級 session 生命週期 |
| **unit of work** | 一批變更的原子提交 | |
| **transaction** | ACID 交易邊界 | `commit` / `rollback` |
| **isolation level** | 併發隔離級別 | dirty read, phantom |
| **migration** | schema 版本演進 | Alembic, Django migrations |
| **revision** | 單一 migration 版本 | 須可追蹤 |
| **rollback migration** | 降級腳本 | 說明不可逆步驟 |
| **N+1 query** | 1 次主查詢 + N 次關聯查詢 | `selectinload`, `prefetch` |
| **eager loading** | 預先載入關聯 | `joinedload` |
| **lazy loading** | 存取時才查 | 易 N+1 |
| **connection pool** | 連線池 | 大小與 timeout 調優 |
| **parameterized query** | 參數綁定防注入 | 永不 f-string SQL |
| **index** | 索引加速查詢 | 覆蓋索引、複合索引 |
| **constraint** | PK, FK, UNIQUE, CHECK | |
| **soft delete** | 邏輯刪除旗標 | 查詢須全域過濾 |
| **optimistic locking** | 版本號防丟失更新 | `version` 欄位 |
| **pessimistic locking** | `SELECT FOR UPDATE` | 高爭用 |
| **read replica** | 唯讀副本 | 複製延遲 |
| **CQRS** | 讀寫模型分離 | 複雜域 |
| **event sourcing** | 事件流為真相來源 | 高複雜 |
| **repository pattern** | 抽象持久化介面 | `UserRepository` Protocol |
| **DAO** | Data Access Object | 薄封裝 CRUD |
| **Redis** | 記憶體 KV / 快取 / 佇列 | TTL 必設 |
| **cache-aside** | 應用管快取 | 常見 |
| **write-through** | 寫同時更新快取 | |
| **TTL** | 存活時間 | 避免永恆汙染 |
| **cache stampede** | 快取同時失效驚群 | 單飛、鎖 |
| **Celery** | 分散式任務佇列 | broker + worker |
| **beat** | 定時任務排程 | |
| **dead letter queue** | 失敗訊息死信佇列 | 需監控 |

---

## 測試與品質保證詞彙

| 術語 | 定義 |
|:---|:---|
| **test pyramid** | 單元多、整合少、E2E 更少 |
| **unit test** | 隔離測單一單元 | 快、確定 |
| **integration test** | 跨模組/真 DB/HTTP | testcontainers |
| **e2e / end-to-end** | 全鏈路使用者路徑 | 少而精 |
| **contract test** | 消費者驅動 API 契約 | Pact |
| **smoke test** | 部署後最小可用檢查 | |
| **regression test** | 防舊 bug 再現 | bugfix 必備 |
| **characterization test** | 刻畫現行行為 | 重構前 |
| **fixture** | pytest 測試夾具 | `conftest.py` |
| **parametrize** | 多組參數化案例 | `@pytest.mark.parametrize` |
| **mock** | 測試替身 | `unittest.mock` |
| **patch** | 執行期替換物件 | `@patch("pkg.func")` |
| **spy** | 記錄呼叫不替換行為 | |
| **stub** | 固定回傳的替身 | |
| **fake** | 可工作的輕量實作 | 記憶體 DB |
| **test double** | mock/stub/fake/spy 總稱 | |
| **arrange-act-assert** | AAA 測試結構 | |
| **given-when-then** | BDD 語意 | |
| **coverage** | 程式碼覆蓋率 | 非品質唯一指標 |
| **branch coverage** | 分支覆蓋 | |
| **mutation testing** | 變異測試測試試品質 | mutmut |
| **flaky test** | 非決定性失敗 | 必須修或隔離 |
| **deterministic** | 同輸入同輸出 | 測試必須 |
| **test isolation** | 測試互不干擾 | 無共享 mutable 全域 |
| **factory_boy** | 測試資料工廠 | |
| **freezegun** | 時間凍結 | 測試時間邏輯 |
| **hypothesis** | 屬性基礎測試 | 邊界探索 |
| **TDD** | 先寫失敗測再實作 | red-green-refactor |
| **BDD** | 行為驅動 | behave, pytest-bdd |
| **CI** | 持續整合 | GitHub Actions |
| **CD** | 持續交付/部署 | |
| **quality gate** | 品質門檻 | coverage ≥ x%, lint 0 |
| **snapshot test** | 輸出快照比對 | 慎對非確定輸出 |

**測試句式**：

- 「先寫 **failing regression test** 鎖定 bug，再最小修復。」
- 「mock **I/O boundary**，不要 mock 被測業務邏輯。」
- 「此案例 **flaky** 源於共用 DB 狀態，改 fixture 隔離。」

---

## 工具鏈與 DevOps 詞彙

| 術語 | 定義 |
|:---|:---|
| **venv / virtualenv** | 隔離 Python 環境 | |
| **pyenv** | 多版本 Python 管理 | |
| **pip** | 套件安裝器 | |
| **Poetry** | 依賴+打包一體 | `poetry.lock` |
| **uv** | 極速套件/環境工具 | 新專案推薦 |
| **pip-tools** | `requirements.in` → lock | |
| **hatch / flit / setuptools** | 打包後端 | `pyproject.toml` |
| **pyproject.toml** | 專案元資料與工具設定中樞 | PEP 621 |
| **lockfile** | 可重現依賴鎖定 | 必 commit |
| **wheel** | 二元發布格式 `.whl` | 優先於 sdist |
| **sdist** | 原始碼發布 | |
| **ruff** | 極速 linter+formatter | 取代 flake8+isort 部分 |
| **black** | 意見化格式化 | line-length 88 |
| **isort** | import 排序 | profile=black |
| **mypy** | 靜態型別檢查 | strict 漸進 |
| **pyright** | 微軟型別檢查器 | Pylance 底層 |
| **pre-commit** | Git 鉤子自動檢查 | |
| **tox / nox** | 多環境矩陣測試 | |
| **Makefile** | 任務入口 `make test` | |
| **Dockerfile** | 容器映像建置 | multi-stage |
| **multi-stage build** | 建置與執行分離 | 縮小映像 |
| **docker-compose** | 本地多服務編排 | |
| **12-factor** | 雲端原生應用原則 | 設定來自環境 |
| **K8s / Kubernetes** | 容器編排 | Deployment, Service |
| **Helm** | K8s 套件管理 | |
| **secrets management** | Vault, SSM, K8s Secret | 不入 git |
| **SBOM** | 軟體物料清單 | 供應鏈安全 |
| **dependabot / renovate** | 自動依賴更新 PR | |
| **SAST** | 靜態應用安全測試 | bandit, semgrep |
| **CVE** | 已知漏洞編號 | 封鎖高危 |

---

## 架構與設計模式詞彙

| 術語 | 定義 |
|:---|:---|
| **layered architecture** | 表現→業務→資料分層 |
| **clean architecture** | 依賴向內；domain 無外依 |
| **hexagonal / ports & adapters** | 埠與適配器隔離 I/O |
| **DDD** | Domain-Driven Design | bounded context |
| **bounded context** | 領域邊界 | 微服務對齊 |
| **ubiquitous language** | 統一語言 | 程式名=業務名 |
| **anti-corruption layer** | 防腐層翻譯外部模型 | |
| **SOLID** | SRP,OCP,LSP,ISP,DIP | review 維度 |
| **SRP** | 單一職責 | 一個改動理由 |
| **dependency inversion** | 依賴抽象非具體 | Protocol/ABC |
| **service layer** | 業務編排層 | 非 handler 寫邏輯 |
| **domain layer** | 純業務規則 | 無框架 import |
| **adapter** | 外部系統適配 | `PostgresUserRepo` |
| **facade** | 簡化複雜子系統介面 | |
| **strategy** | 可替換演算法族 | |
| **factory** | 建立物件 | |
| **observer** | 發布訂閱 | Django signals 類似 |
| **circuit breaker** | 熔斷防雪崩 | |
| **bulkhead** | 隔艙限故障面 | |
| **retry with backoff** | 指數退避重試 | jitter 防同步 |
| **saga** | 分散式長交易補償 | |
| **event-driven** | 事件驅動架構 | |
| **monolith** | 單體應用 | 早期合理 |
| **modular monolith** | 模組化單體 | 漸進拆服務 |
| **microservice** | 小服務獨立部署 | 運維成本高 |
| **strangler fig** | 絞殺者漸進替換 | 遺留遷移 |
| **feature flag** | 功能開關 | LaunchDarkly, 自研 |
| **ADR** | Architecture Decision Record | 決策可追溯 |
| **SLA / SLO / SLI** | 服務等級協議/目標/指標 | 錯誤預算 |
| **error budget** | 可接受不可靠配額 | |

---

## 安全與合規詞彙

| 術語 | 定義 |
|:---|:---|
| **trust boundary** | 不可信輸入進入點 | HTTP body, webhook |
| **input validation** | 結構與範圍驗證 | Pydantic, marshmallow |
| **output encoding** | 防 XSS 編碼輸出 | |
| **SQL injection** | SQL 拼接注入 | 參數化查詢 |
| **command injection** | `os.system` 拼接 | `subprocess` 列表參數 |
| **SSRF** | 伺服器端請求偽造 | URL allowlist |
| **path traversal** | `../` 讀任意檔 | `pathlib.resolve` 檢查 |
| **deserialization** | 不安全反序列化 | 勿隨意 `pickle.loads` |
| **secrets** | API key, password | env + secret manager |
| **least privilege** | 最小權限 | DB user 僅需權限 |
| **RBAC** | 角色存取控制 | |
| **ABAC** | 屬性存取控制 | |
| **JWT** | JSON Web Token | 驗簽+過期+aud |
| **OAuth2 / OIDC** | 授權委派與身份 | |
| **session fixation** | 會話固定攻擊 | 登入後輪換 session |
| **CSRF** | 跨站請求偽造 | token, SameSite |
| **CORS misconfiguration** | 過寬 origin | 白名單 |
| **TLS / HTTPS** | 傳輸加密 | cert 輪替 |
| **PII** | 個人可識別資訊 | 日誌脫敏 |
| **GDPR / compliance** | 法規遵循 | 資料保留政策 |
| **audit log** | 不可篡改審計軌跡 | who did what when |
| **constant-time compare** | 防時序攻擊比對 | `hmac.compare_digest` |
| **dependency pinning** | 釘版本防供應鏈 | |
| **bandit** | Python 安全 linter | |

---

## 效能與可觀測性詞彙

| 術語 | 定義 |
|:---|:---|
| **profiling** | 效能剖析 | cProfile, py-spy |
| **benchmark** | 可重現效能基準 | `timeit`, pytest-benchmark |
| **latency** | 延遲 | p50/p95/p99 |
| **throughput** | 吞吐量 | QPS, RPS |
| **percentile** | 分位數 | p99 尾延遲 |
| **hot path** | 最頻繁執行路徑 | 優化焦點 |
| **allocation** | 記憶體配置 | 減少物件 churn |
| **GC** | 垃圾回收 | 全堆暫停 |
| **memory leak** | 記憶體洩漏 | 無界快取、全域引用 |
| **object churn** | 短壽命物件大量建立 | |
| **CPU-bound** | 受 CPU 限制 | |
| **I/O-bound** | 受 I/O 等待限制 | |
| **tail latency** | 尾端高延遲 | |
| **caching** | 快取 | 命中率 |
| **memoization** | 函式結果快取 | `functools.lru_cache` |
| **batching** | 批次處理 | bulk insert |
| **streaming** | 串流處理大資料 | generator |
| **observability** | 可觀測性三支柱 | metrics, logs, traces |
| **structured logging** | JSON/鍵值日誌 | structlog |
| **correlation id** | 請求關聯 ID | 跨服務追蹤 |
| **trace / span** | 分散式追蹤單元 | OpenTelemetry |
| **metric** | 可聚合量測 | Prometheus |
| **counter / gauge / histogram** | 指標類型 | |
| **alerting** | 告警規則 | 降噪 |
| **SLO burn rate** | 錯誤預算消耗率 | |
| **load test** | 負載測試 | locust, k6 |
| **soak test** | 長時間浸泡測試 | 記憶體洩漏 |
| **chaos engineering** | 混沌工程 | 注入故障 |

---

## 除錯與事故詞彙

| 術語 | 定義 |
|:---|:---|
| **reproduce** | 穩定重現 | 除錯第一步 |
| **minimal reproducible example** | 最小可重現案例 | MRE |
| **root cause** | 根本原因 | 非表象 |
| **symptom** | 症狀 | 使用者可見 |
| **trigger** | 觸發條件 | |
| **regression** | 退化；修 A 壞 B | |
| **bisect** | 二分查找引入點 | git bisect |
| **stack trace / traceback** | 呼叫堆疊 | 從底往上看 |
| **frame** | 堆疊單層 | |
| **breakpoint** | 中斷點 | pdb, debugpy |
| **watchpoint** | 變數變更中斷 | |
| **core dump** | 核心傾印 | 罕見於 Python |
| **heisenbug** | 觀測即改變的 bug | |
| **race** | 競態 | |
| **intermittent** | 間歇性 | 最難查 |
| **5 Whys** | 五個為什麼挖根因 | |
| **blameless** | 無責歸咎文化 | postmortem |
| **MTTR** | 平均修復時間 | |
| **MTTD** | 平均發現時間 | |
| **incident** | 生產事故 | SEV1/2/3 |
| **rollback** | 回滾版本 | |
| **hotfix** | 緊急修補 | 旁路正常流程 |
| **mitigation** | 緩解措施 | 非最終修復 |
| **runbook** | 操作手冊 | on-call 用 |
| **playbook** | 事故應對劇本 | |

---

## 程式碼審查嚴重度詞彙

| 級別 | 英文 | 定義 | 合併策略 |
|:---|:---|:---|:---|
| **阻擋** | `blocker` / `must-fix` | 正確性/安全/資料遺失風險 | 禁止合併 |
| **重大** | `major` / `should-fix` | 可維護性、效能、明顯技術債 | 合併前應修 |
| **次要** | `minor` / `consider` | 邊緣案例、可讀性 | 可跟進 ticket |
| **吹毛求疵** | `nit` / `optional` | 純偏好、不影響行為 | 可忽略或後修 |
| **讚賞** | `praise` / `highlight` | 值得保留的好實踐 | 鼓勵 |

**審查維度標籤**（可組合）：

`[correctness]` `[security]` `[performance]` `[testing]` `[api-design]` `[observability]` `[maintainability]` `[style]`

**審查結論詞**：

| 結論 | 含義 |
|:---|:---|
| **APPROVE** | 可合併 |
| **APPROVE with nits** | 可合併，次要意見 |
| **REQUEST_CHANGES** | 須修後再審 |
| **COMMENT** | 僅意見，不阻擋 |

---

## 打包與發布詞彙

| 術語 | 定義 |
|:---|:---|
| **semver** | 語意化版本 MAJOR.MINOR.PATCH | 破壞性→MAJOR |
| **changelog** | 版本變更記錄 | Keep a Changelog 格式 |
| **release notes** | 面向使用者發布說明 | |
| **deprecation** | 棄用預告 | `warnings.warn(DeprecationWarning)` |
| **breaking change** | 破壞性變更 | 需 major bump |
| **backward compatible** | 向後相容 | 預設追求 |
| **forward compatible** | 向前相容 | 較難 |
| **yank** | PyPI 撤回問題版本 | 不刪除已下載 |
| **ABI** | 應用二進位介面 | C extension |
| **manylinux** | Linux wheel 標準標籤 | |
| **platform wheel** | 平台特定 wheel | |
| **universal wheel** | py2/py3 舊概念 | 現多用 tag |
| **src layout** | `src/mypkg/` 佈局 | 減少意外 import |
| **flat layout** | 根目錄套件 | 小專案 |

---

## PEP 與標準參照詞彙

| PEP | 主題 | 引用句式 |
|:---|:---|:---|
| **PEP 8** | 風格指南 | 「import 順序違反 PEP 8」 |
| **PEP 257** | Docstring 慣例 | |
| **PEP 484** | Type hints | |
| **PEP 526** | 變數註解 | |
| **PEP 563** | 延遲註解評估（已調整） | `from __future__ import annotations` |
| **PEP 585** | 內建泛型 | `list[str]` |
| **PEP 604** | Union `X \| Y` | |
| **PEP 695** | 型別參數語法 | `type Point = tuple[float, float]` |
| **PEP 517/518** | 建置系統 | pyproject build |
| **PEP 621** | 專案元資料 | `[project]` |
| **PEP 440** | 版本識別 | |
| **PEP 508** | 依賴規格 | `pkg>=1.0` |
| **PEP 723** | 單檔腳本 metadata | |
| **Zen of Python** | `import this` | 哲學引用 |

---

## 反模式與禁忌用語

### 反模式清單

| 反模式 | 英文 | 為何危險 |
|:---|:---|:---|
| 裸 except | `bare except:` | 吞掉 `KeyboardInterrupt` |
| 吞例外 | `except Exception: pass` | 隱性失敗 |
| 可變預設參數 | `mutable default arg` | 跨呼叫共享狀態 |
| 字串拼 SQL | `string SQL concat` | 注入 |
| 硬編碼密鑰 | `hardcoded secrets` | 洩漏 |
| 萬能 God class | `god object` | 難測難改 |
| 到處 import * | `import *` | 命名空間污染 |
| 全域可變狀態 | `mutable global state` | 測試/flaky |
| 在 async 阻塞 | `blocking in event loop` | 全站卡死 |
| 過度 mock | `over-mocking` | 測試與實作脫節 |
| 早優化 | `premature optimization` | 浪費複雜度 |
| 複製貼上繼承 | `copy-paste inheritance` | 行為分叉 |

### 禁忌用語 → 替換

| 避免說 | 改說 |
|:---|:---|
| 「壞掉了」 | 「在 `{condition}` 下 raises `{Exception}`」 |
| 「很慢」 | 「p95 latency 從 120ms 升至 890ms（N+1）」 |
| 「幫我弄一下」 | 「實作 `{feature}`，成功標準：`{criteria}`」 |
| 「應該沒問題」 | 「已跑 `pytest -q`：42 passed；mypy 0 errors」 |
| 「最佳實踐」 | 「在此約束下我選 X，因為 `{trade-off}`」 |
| 「簡單改一下」 | 「影響 `{n}` 檔案與 `{migration}`」 |

---

## 縮寫與首字母詞表

| 縮寫 | 全稱 |
|:---|:---|
| **API** | Application Programming Interface |
| **ASGI** | Asynchronous Server Gateway Interface |
| **WSGI** | Web Server Gateway Interface |
| **ORM** | Object-Relational Mapping |
| **DTO** | Data Transfer Object |
| **DI** | Dependency Injection |
| **CRUD** | Create Read Update Delete |
| **ACID** | Atomicity Consistency Isolation Durability |
| **CAP** | Consistency Availability Partition tolerance |
| **CQRS** | Command Query Responsibility Segregation |
| **DDD** | Domain-Driven Design |
| **ADR** | Architecture Decision Record |
| **RCA** | Root Cause Analysis |
| **SLA/SLO/SLI** | Service Level Agreement/Objectives/Indicators |
| **MTTR/MTTD** | Mean Time To Repair/Detect |
| **CI/CD** | Continuous Integration/Delivery |
| **K8s** | Kubernetes |
| **JWT** | JSON Web Token |
| **OAuth/OIDC** | Open Authorization / OpenID Connect |
| **RBAC** | Role-Based Access Control |
| **SSRF** | Server-Side Request Forgery |
| **XSS** | Cross-Site Scripting |
| **CSRF** | Cross-Site Request Forgery |
| **CVE** | Common Vulnerabilities and Exposures |
| **SBOM** | Software Bill of Materials |
| **TTL** | Time To Live |
| **QPS/RPS** | Queries/Requests Per Second |
| **MRE** | Minimal Reproducible Example |
| **E2E** | End-to-End |
| **TDD** | Test-Driven Development |
| **BDD** | Behavior-Driven Development |
| **GIL** | Global Interpreter Lock |
| **PYPI** | Python Package Index |
| **OTel** | OpenTelemetry |

---

## 動詞片語庫（Senior 口吻）

### 分析與診斷

- **triage the failure** — 分級與初步分類故障
- **narrow the blast radius** — 縮小影響範圍
- **isolate the variable** — 隔離變因
- **confirm with a minimal repro** — 用最小案例確認
- **correlate with deploy timeline** — 與發布時間線對齊
- **rule out regression in dependency X** — 排除依賴退化

### 設計與決策

- **bias toward reversible changes** — 偏向可逆改動
- **encode the invariant in types** — 用型別表達不變量
- **push side effects to the boundary** — 副作用推到邊界
- **fail closed on auth errors** — 鑑權失敗則拒絕（fail-closed）
- **deprecate before remove** — 先棄用再移除
- **document the trade-off explicitly** — 明說取捨

### 實作與交付

- **land the change in small commits** — 小步提交
- **keep the diff reviewable** — 保持 diff 可審
- **align with existing conventions** — 對齊既有慣例
- **prove correctness with tests** — 用測試證明正確
- **run the quality gates locally** — 本地跑完門禁
- **ship with rollback instructions** — 附回滾說明交付

### 審查與協作

- **call out a blocker on security grounds** — 以安全為由標 blocker
- **suggest a concrete alternative** — 給可執行替代方案
- **acknowledge the intent, challenge the approach** — 認可意圖、質疑做法
- **leave actionable feedback** — 意見可落地
- **avoid bikeshedding** — 不糾結無關宏旨格式

---

## 溝通 Template 全集

> 使用方式：複製對應 template → 替換 `{placeholder}` → 刪去不適用段落。  
> 所有 template 預設 **英文標題 + 中英可混內文**；代碼與識別符保持英文。

---

### T01 — 任務澄清（Clarification）

```markdown
## 任務理解
我理解你的目標是：**{one_line_goal}**

## 成功標準
- {criterion_1}
- {criterion_2}

## 我的假設
1. Python **{version}**；框架：**{framework}**
2. 部署環境：**{env}**
3. {assumption_3}

## 需確認（最多 3 項）
1. **{question_1}** — 影響：{impact}
2. **{question_2}**

若以上假設正確，我將按 **{path: P1/P2/...}** 執行：{next_step_summary}
```

---

### T02 — 架構決策記錄（ADR）

```markdown
# ADR-{number}: {title}

## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-xxx}

## Context
{業務背景、約束、問題陳述}

## Decision
我們將 **{decision_summary}**。

## Consequences

### Positive
- {pro_1}

### Negative
- {con_1}

## Alternatives Considered

| 方案 | 優點 | 缺點 | 為何不選 |
|:---|:---|:---|:---|
| {alt_a} | | | |
| {alt_b} | | | |

## Implementation Notes
- 影響模組：`{modules}`
- 遷移步驟：`{steps}`
- 回滾策略：`{rollback}`

## References
- {link_pep_doc_issue}
```

---

### T03 — 新功能設計摘要（Design Brief）

```markdown
## 摘要
**{feature_name}** — {one_sentence_value}

## 問題陳述
{problem}

## 方案
{recommended_approach}

### 元件職責
| 元件 | 職責 | 備註 |
|:---|:---|:---|
| `{module_a}` | {resp} | |
| `{module_b}` | {resp} | |

### 資料流
1. {step_1}
2. {step_2}

## API / 契約變更
- **Endpoint**：`{METHOD} {path}`
- **Request**：`{schema}`
- **Response**：`{schema}`
- **錯誤碼**：`{4xx/5xx mapping}`

## 非功能需求
- 效能：**{latency/throughput target}**
- 安全：**{authn/authz/input validation}**
- 可觀測：**{logs/metrics/traces}**

## 測試計劃
| 層級 | 範圍 | 案例 |
|:---|:---|:---|
| Unit | {scope} | {cases} |
| Integration | {scope} | {cases} |

## 風險與緩解
| 風險 | 機率 | 影響 | 緩解 |
|:---|:---|:---|:---|
| {risk} | {L/M/H} | {L/M/H} | {mitigation} |

## 不在範圍
- {explicit_non_goal}
```

---

### T04 — 實作交付（Implementation Delivery）

```markdown
## 摘要
{what_and_why — 2-3 句}

## 變更清單
| 檔案 | 變更 |
|:---|:---|
| `{path/to/file.py}` | {description} |
| `{path/to/test_file.py}` | {description} |

## 關鍵設計決策
- **{decision_1}**：{rationale}

## 測試
```bash
{command_run}
```
**結果**：`{passed/failed counts}`

## 品質門禁
| 檢查 | 命令 | 結果 |
|:---|:---|:---|
| Lint | `{ruff check .}` | {pass/fail} |
| Types | `{mypy .}` | {pass/fail} |
| Tests | `{pytest -q}` | {pass/fail} |

## 部署 / 遷移
- {migration_command}
- {feature_flag_note}

## 風險與後續
- **已知限制**：{limitation}
- **Follow-up**：{ticket_or_task}
```

---

### T05 — Bug 報告（內部 / Issue）

```markdown
## 標題
[{severity}] {component}: {short_description}

## 環境
- Python：{version}
- OS：{os}
- 套件版本：{key_deps}
- Commit / 版本：{sha_or_tag}

## 預期行為
{expected}

## 實際行為
{actual}

## 重現步驟
1. {step_1}
2. {step_2}

## 最小重現
```python
{minimal_code}
```

## Traceback
```
{paste_traceback}
```

## 影響範圍
- 使用者影響：**{who/what}**
- 頻率：**{always/intermittent}**
- 嚴重度：**{SEV1/2/3}**

## 初步假設
1. {hypothesis_1} — 驗證方式：{how}
2. {hypothesis_2}

## 附件
- 日誌片段 / 請求 ID：`{correlation_id}`
```

---

### T06 — 除錯結論（Debug Resolution）

```markdown
## 根因（Root Cause）
**{one_line_root_cause}**

## 證據（Evidence）
- Traceback 關鍵幀：`{file}:{line}` — `{function}`
- 變數狀態：`{var}={value}`
- 重現命令：`{command}` → **{consistent_repro_yes/no}**

## 因果鏈（5 Whys 精簡）
1. {why_1}
2. {why_2}
→ 根因：**{root}**

## 修復（Fix）
{description}

```python
# 修復要點（非完整檔案）
{snippet}
```

## 驗證（Verification）
```bash
{test_commands}
```

## 預防（Prevention）
- [ ] 新增 regression test：`{test_name}`
- [ ] 型別/斷言強化：`{detail}`
- [ ] 監控/告警：`{metric_or_log}`
```

---

### T07 — 程式碼審查（Code Review）

```markdown
## 審查結論
**{APPROVE | APPROVE with nits | REQUEST_CHANGES | COMMENT}**

## 摘要
{overall_assessment — 2-4 句}

## Blockers
### B1. [{tag}] {title}
- **位置**：`{file}:{line}` 或 `{function}`
- **問題**：{factual_issue}
- **影響**：{production_impact}
- **建議**：{concrete_fix}

## Majors
### M1. [{tag}] {title}
- **位置**：...
- **問題**：...
- **建議**：...

## Minors / Nits
- [minor] `{file}` — {suggestion}
- [nit] `{file}` — {optional_style}

## 亮點（Highlights）
- {specific_good_practice_1}

## 測試缺口
- {missing_test_scenario}

## 安全 / 效能備註
- {security_or_perf_note}
```

---

### T08 — 單條審查意見（Inline Finding）

```markdown
**[{blocker|major|minor|nit}]** [{correctness|security|...}] **{title}**

-at `{file_path}` `{symbol}`（約 L{line}）

**Issue**：{what_is_wrong}

**Why it matters**：{impact_in_production}

**Suggestion**：
```python
{suggested_snippet}
```

**Reference**：{pep/doc/link}
```

---

### T09 — Pull Request 描述

```markdown
## Summary
{what_this_pr_does}

## Motivation
{why_needed — issue link: #{number}}

## Changes
- `{file}` — {change}

## Test Plan
- [ ] `{test_case_1}`
- [ ] `{test_case_2}`
```bash
pytest {path} -q
ruff check .
mypy {scope}
```

## Screenshots / Logs
{if_ui_or_api_output}

## Rollback Plan
{how_to_revert_safely}

## Checklist
- [ ] Tests added/updated
- [ ] No secrets committed
- [ ] Breaking changes documented
- [ ] Migration included (if applicable)
```

---

### T10 — 重構提案（Refactor Proposal）

```markdown
## 重構目標
**{goal}** — 行為 **不變**（behavior-preserving）

## 現狀問題
- {pain_1：coupling / duplication / untestable}

## 目標結構
```
{before_asci_tree}
→
{after_asci_tree}
```

## 分步計劃
| 步驟 | 內容 | 驗證 |
|:---|:---|:---|
| 1 | {extract_function} | characterization tests green |
| 2 | {introduce_protocol} | mypy pass |
| 3 | {remove_dead_code} | coverage unchanged |

## 風險
- {risk} — 緩解：{mitigation}

## 不做
- {out_of_scope_behavior_change}
```

---

### T11 — 效能分析報告（Performance Report）

```markdown
## 問題陳述
**症狀**：{symptom — p95 latency / memory / CPU}

## 基準（Before）
| 指標 | 值 | 方法 |
|:---|:---|:---|
| p50 latency | {ms} | {benchmark_cmd} |
| p99 latency | {ms} | |
| Memory RSS | {mb} | |
| QPS | {n} | |

## 分析過程
1. **Profile**：`{cProfile/py-spy command}`
2. **發現**：{hotspot_function} 佔 **{percent}%**
3. **假設**：{hypothesis}

## 優化措施
- {change_1}
- {change_2}

## 結果（After）
| 指標 | Before | After | Delta |
|:---|:---|:---|:---|
| p99 | {a} | {b} | **{-%}** |

## 取捨
- {tradeoff — complexity/memory for speed}

## 建議後續
- {monitoring_alert}
```

---

### T12 — 事故事後檢討（Blameless Postmortem）

```markdown
# Incident Postmortem: {incident_title}

## Metadata
- **日期**：{date}
- **嚴重度**：{SEV1/2/3}
- **持續時間**：{duration}
- **影響**：{users/revenue/data}
- **作者**：{author}
- **狀態**：{Draft | Final}

## 摘要（Executive Summary）
{non_blaming_summary}

## 時間線（Timeline）— UTC
| 時間 | 事件 |
|:---|:---|
| {t0} | {detection} |
| {t1} | {mitigation} |
| {t2} | {resolved} |

## 根因（Root Cause）
{technical_root_cause}

## 促成因素（Contributing Factors）
- {factor_1}
- {factor_2}

## 做得好的（What Went Well）
- {positive_1}

## 做得不好的（What Went Wrong）
- {negative_1}

## 行動項（Action Items）
| 優先級 | 行動 | 負責人 | 截止日期 | 類型 |
|:---|:---|:---|:---|:---|
| P0 | {action} | {owner} | {date} | prevent/detect/mitigate |

## 教訓（Lessons Learned）
- {lesson}
```

---

### T13 — API 端點規格（Endpoint Spec）

```markdown
## `{METHOD} {path}`

### 用途
{purpose}

### 鑑權
- **方式**：{JWT/API key/session}
- **權限**：{role/scope}

### Request

**Headers**
| Header | 必填 | 說明 |
|:---|:---|:---|
| `Authorization` | 是 | `Bearer {token}` |
| `Content-Type` | 是 | `application/json` |

**Body Schema**
```json
{
  "{field}": "{type — constraints}"
}
```

### Response

**200 OK**
```json
{
  "{field}": "{type}"
}
```

**錯誤**
| Status | 條件 | Body |
|:---|:---|:---|
| 400 | 驗證失敗 | `problem+json` |
| 401 | 未鑑權 | |
| 404 | 資源不存在 | |
| 409 | 衝突 | |
| 500 | 未處理例外 | 不洩漏內部堆疊 |

### 語意備註
- **冪等性**：{yes/no — idempotency-key}
- **副作用**：{creates/updates/deletes}
- **速率限制**：{limit}

### 範例
```bash
curl -X {METHOD} '{url}' \
  -H 'Authorization: Bearer ...' \
  -d '{...}'
```
```

---

### T14 — 資料庫遷移說明（Migration Note）

```markdown
## Migration `{revision_id}`: {title}

### 變更內容
- **表**：`{table}`
- **操作**：{add_column | index | fk | ...}
- **DDL 摘要**：
```sql
{sql_summary}
```

### 理由
{why_this_change}

### 鎖定與停機
- **預估鎖表時間**：{duration}
- **需停機**：{yes/no}
- **線上策略**：{expand/contract | concurrent index}

### 應用程式配合
- 部署順序：**{migration-first | code-first | simultaneous}**
- 相容窗口：{backward_compatible_window}

### 回滾
```bash
{alembic downgrade -1}
```
**資料風險**：{irreversible_steps}

### 驗證
```bash
{verify_queries_or_tests}
```
```

---

### T15 — 依賴升級評估（Dependency Upgrade）

```markdown
## 升級：`{package}` {old_version} → {new_version}

### 動機
- {security_cve | feature | compatibility}

### 破壞性變更（Breaking Changes）
| 變更 | 影響我們 | 所需改動 |
|:---|:---|:---|
| {bc_item} | {impact} | {fix} |

### 測試策略
- [ ] 單元測試全綠
- [ ] 整合測試 `{suite}`
- [ ] 手動驗證 `{critical_path}`

### 回滾
`{pin_to_previous_command}`

### 決策
**{proceed | defer}** — 理由：{rationale}
```

---

### T16 — 技術分享 / KT 文檔（Knowledge Transfer