AI 編程 PR 模板

Vibe Coding 團隊規範 的核心交付物之一。把以下內容存為 .github/pull_request_template.md，所有 PR 必須填寫。

完整模板

## 摘要
 
<!-- 這個 PR 在做什麼？解決什麼問題？ -->
 
## AI 產出聲明
 
- [ ] 本 PR **未** 使用 AI 產出
- [ ] 本 PR 使用 AI 產出，範圍如下：
  - AI 產出檔案：
  - 人類逐行 review 的檔案：
  - AI 工具與模型版本：
 
## 變更類型
 
- [ ] Leaf node（局部影響）
- [ ] Core code（影響面廣，需逐行 review）
 
## 計畫文件
 
<!-- 連結到 plan.md 或貼上計畫摘要 -->
 
## 驗證方式
 
- [ ] Unit tests
- [ ] Integration tests
- [ ] 至少 3 條 e2e 測試（happy path + 2 errors）
- [ ] Stress / soak test（如適用）：
- [ ] 手動驗證步驟：
 
## 可驗證性檢查
 
- [ ] 介面（輸入／輸出）已文件化
- [ ] Reviewer 可在不讀完整實作的情況下判斷正確性
- [ ] 失敗時可被監控察覺
 
## 資安檢查（如觸及外部介面）
 
- [ ] 沒有把 secrets / API keys 寫進原始碼或 prompt
- [ ] 所有外部輸入有驗證
- [ ] 權限檢查通過 admin / user 測試
- [ ] Rate limit / quota 已套用
- [ ] 失敗時不洩漏內部資訊（stack trace、SQL、檔案路徑）
 
## 風險與回滾
 
- 風險：
- 回滾方式：
 
## Reviewer 指引
 
- 重點請看：
- 可略讀：

各 section 對應的法則 / 概念

Section	對應
AI 產出聲明	核心由人嚴格 Review 法則 — 沒標示 reviewer 不知道哪要嚴看
變更類型（Leaf / Core）	Leaf Node vs Core Code / 聚焦 Leaf Nodes 法則
計畫文件	Plan-then-Execute SOP Step 3 產出
驗證方式	建立可驗證檢查點 法則 / Vibe Coding TDD 三條 e2e 測試
可驗證性檢查	可驗證性設計三支柱
資安檢查	規範底線（譬如不能 vibe code 處理 secrets / payment）
風險與回滾	Leaf 場景必備（失敗能快速回滾是 leaf 的前提）
Reviewer 指引	讓 reviewer 知道時間花在哪

重點：「AI 產出範圍」必須具體

❌ 不夠（含糊）：

- [x] 本 PR 使用 AI 產出
  - AI 產出檔案：很多

✅ 夠具體：

- [x] 本 PR 使用 AI 產出，範圍如下：
  - AI 產出檔案：
    - src/reports/activity.ts (整檔 AI 寫，未 review 邏輯細節)
    - src/reports/activity.test.ts (整檔 AI 寫，已 review 介面)
    - src/routes/admin.ts (僅新增 1 條 route，AI 寫，已逐行 review)
  - 人類逐行 review 的檔案：
    - src/routes/admin.ts (新增段落)
  - AI 工具與模型版本：Claude Code (Sonnet 4.5)

具體到「哪檔哪段、誰 review 過、review 多深」，reviewer 才知道時間花哪。

為什麼資安檢查是分開 section

Vibe Coding Anti-Patterns 第 11 條明確：「對處理 secrets / payment / auth 的程式做 vibe coding」是禁止事項。

但實務上仍有 觸及外部介面（譬如新 endpoint 不一定是核心 auth，但仍會接受 user input）的場景——這些場景降一級用 AI 是 OK 的，但資安檢查必須額外明確列出。

套用到 GitHub repo

1. 在 repo root 建 .github/pull_request_template.md
2. 內容用上面完整模板
3. 之後每個 PR 自動 prefilled

跟 Code Review 準則 (AI 編程) 的關係

PR 模板是輸入端（PR author 填寫），Code Review 準則是檢查端（reviewer 用什麼標準看 PR）。兩者配對使用。

跟既有 PR 模板的整合

如果團隊已有 PR 模板（譬如 ticket link / changelog），把這份疊加上去，不取代。順序：

1. 既有 sections（譬如 ticket / changelog）
2. AI 產出聲明 ← 新增
3. 變更類型 ← 新增
4. 計畫文件 ← 新增
5. 驗證方式（如有原本 testing checklist 可整合）
6. 可驗證性檢查 ← 新增
7. 資安檢查 ← 新增
8. 風險與回滾（可整合既有）
9. Reviewer 指引 ← 新增

違反時的常見症狀

• ❌ 模板缺「AI 產出聲明」→ reviewer 不知道哪些該嚴看
• ❌ 「驗證方式」全跳過 → 沒按 建立可驗證檢查點 法則
• ❌ 「資安檢查」勾完但沒實際做 → 形式化
• ❌ 不填「Reviewer 指引」→ reviewer 浪費時間找重點

相關

• Vibe Coding 團隊規範
• 四大黃金法則 (Vibe Coding)
• Code Review 準則 (AI 編程)
• Vibe Coding Anti-Patterns
• AI 編程角色責任矩陣 — Author / Reviewer 責任
• Vibe Coding TDD 三條 e2e 測試 — 「驗證方式」必含