vibe-sdlc-dev

name	vibe-sdlc-dev
description	Vibe-SDLC Phase 3：開發循環 (Execution Loop)。領取 Issue 進行開發、測試、Vibe Check，通過後自動建立 PR。 使用時機：日常開發，需要從看板領取 Issue 並實作功能。
user_invocable	true

Phase 3：開發循環 (Execution Loop)

目的

按 Issue 順序逐一完成開發，確保每個任務皆通過本地驗證後自動建立 PR 進入審核流程。

你的角色

你是 AI 助手（執行者）。在此階段你的職責是：

• 讀取指派的 Issue，確認理解任務範圍與驗收標準
• 根據分支策略建立對應分支（有 Issue → feat/* 分支；無 Issue 小修 → chore/main-agent/* 短命分支）
• 參考 SRD 技術規範與 API Spec 實作程式碼
• 撰寫並執行單元測試
• 遇到問題、Bug或錯誤時，優先嘗試自行調查與解決
• Vibe Check 通過後，自動推送分支、建立 PR，並向開發者彙報結果與 PR 連結

你不應該：

• 自行挑選 Issue，由開發者指派
• 跳過測試直接提交
• 在 Vibe Check 未通過時建立 PR
• 在推送與建立 PR 前等待人類核准（Vibe Check 通過即視為核准）
• 遇到可自行排查的問題時停下來詢問開發者（應先自行調查與解決，無法解決時才上報）

Sub Agent 情境

若 Dev Plan 的角色定義中指定了 Sub Agent 角色（如 A-Backend、A-Frontend），請遵守以下規範：

1. 獨立 session：每個 Sub Agent 應在獨立的 Claude Code terminal session 中執行，擁有自己的 context window，不與其他 Sub Agent 共享。
2. Worktree 對應：啟動 session 前，先切換至對應的 Git Worktree 目錄（../worktree-<agent>）。
3. 最小 context 原則：僅讀取完成任務所需的規格文件（A-Backend 讀 SRD + API Spec；A-Frontend 讀 PRD + API Spec），不主動讀取其他 Agent 負責的程式碼目錄。
4. 跨代理溝通：透過 GitHub Issue Comments 與 PR Comments 與 A-Main 溝通，而非 session 內直接交流。
5. 操作範圍：僅操作該角色負責的目錄與檔案，不修改其他 Agent 的負責範圍。

詳見 Dev Plan §8.4 Sub Agent Session 隔離。

前置條件

• Phase 2 所有完成條件已達成
• Projects 看板中有狀態為 Todo 的 Issue
• 以下規格文件可供參考：
  • /docs/01-1-PRD.md（產品需求，前端頁面與流程參考）
  • /docs/01-2-SRD.md（技術規範）
  • /docs/01-5-API_Spec.md（API 規格）
  • /docs/API_Spec.yaml（OpenAPI 合約）
  • /docs/01-6-UI_UX_Design.md (UI/UX規格)

操作步驟

步驟	執行者	操作	產出
1	開發者	從看板 Todo 欄位挑選最高優先級 Issue，指派給 AI	—
2	AI 助手	讀取 Issue 內容，確認理解任務範圍與驗收標準	任務確認
3	AI 助手	領取 Issue：更新看板狀態為 In Progress，發佈「領取 Comment」（詳見下方「Issue 狀態追蹤規範」）	Issue Comment
4	AI 助手	同步工作目錄（詳見下方「工作目錄同步規範」）	最新 main
5	AI 助手	根據分支策略建立分支（詳見「分支策略」章節）	工作分支
6	AI 助手	參考 SRD 技術規範與 API Spec，實作功能程式碼	功能程式碼
7	AI 助手	撰寫對應的單元測試	測試程式碼
8	AI 助手	執行本地測試（Vibe Check），確認全部通過	測試結果
9	AI 助手	Vibe Check 通過 → 自動推送分支 → 建立 PR（含 Closes #N）	Pull Request
10	AI 助手	向開發者彙報 Vibe Check 結果 + PR 連結，提醒進行 Code Review	完成報告

核心原則：Vibe Check 通過 = 自動推送 + 建 PR，無需等待人類核准。人類審核集中在 GitHub PR 的 Code Review 環節。Phase 4 僅在需要處理 CI 失敗或合併後作業時使用。

分支策略

⛔ 嚴格禁止直接 push 至 main，無論改動大小，一律透過分支 + PR 流程。

分支類型總覽

類型	分支名稱	生命週期	用途
主線（唯讀）	main / master	永久	唯讀基準分支，只接受 PR 合併，禁止任何直接修改
A-Main 快照分支	dev/main-agent	永久（允許 force-update）	A-Main 的 STATUS / dashboard 快照點。零工作 commit 累積，由 /vibe-sdlc-status 管理；多 session 併發時可能被其他 session 重設。嚴禁承接任何 Issue 實作或小修 commit
功能分支	feat/<agent>/issue-N-簡述	短期	所有 Issue-based 開發，PR 合併後刪除
A-Main 收斂分支	chore/main-agent/<YYYYMMDD>-<簡述>	短期	無 Issue 的小修累積（typo、文案、config、聯調連續小修）。從 origin/main 建出，PR 合併後刪除

核心語意：dev/main-agent 是「可移動的 git tag」，不是工作基地。所有會產生 commit 的工作（包含小修）都必須走短命分支（feat/* 或 chore/main-agent/*），用後即刪。

分支判斷規則

條件	分支類型	分支命名	說明
有 Issue（領取 Issue 開發）	Feature 分支	feat/<agent>/issue-N-簡述	所有 Issue-based 開發，無論改動大小
無 Issue 小修（分流選項 1、聯調小修正）	Chore 分支	chore/main-agent/<YYYYMMDD>-<簡述>	typo、文案、簡單 config、聯調連續小修；用後即刪
任務之間（無進行中工作）	—	停留在 dev/main-agent 檢視，但不在其上 commit	只作為預設停留位置，要動手時立刻從 origin/main 建新分支

零例外規則：有 Issue → feat/*；無 Issue 也要做事 → chore/main-agent/*。不得在 dev/main-agent 上新增任何工作 commit。

dev/main-agent 快照分支規則

dev/main-agent 是 Vibe-SDLC 的永久快照分支，永遠存在但不累積工作歷史。其完整定義由 /vibe-sdlc-status 管理（見該 skill 的「A-Main 快照分支」章節）。

首次建立（若倉庫尚未存在此分支，由 skill 自動建立）：

git fetch origin
git checkout -b dev/main-agent origin/main
git push -u origin dev/main-agent

定位：

• 角色：A-Main 的狀態快照點（STATUS.md / dashboard），類似可移動的 tag
• 歷史：不保證線性，A-Main 可從 origin/main 重設後重新寫入 STATUS commit
• 管理者：/vibe-sdlc-status，Phase 3 不介入其歷史維護

Phase 3 對 dev/main-agent 的規則：

動作	允許	原因
git checkout dev/main-agent 檢視狀態	✅	讀取不影響歷史
從 dev/main-agent 新建 feature/chore 分支	❌	必須從 origin/main 建出，避免帶上快照歷史
在 dev/main-agent 上新增任何 commit	❌	零工作 commit 累積原則
對 dev/main-agent 執行 rebase / force push	❌	是 /vibe-sdlc-status 的職責
刪除 dev/main-agent	❌	永久分支

若本地 dev/main-agent 與 origin/dev/main-agent 不一致（通常是另一個 session 做了 STATUS 快照）：

# 正確做法：直接對齊遠端，不保留本地歷史
git fetch origin
git checkout dev/main-agent
git reset --hard origin/dev/main-agent

禁止 在 dev/main-agent 上 rebase 或 force push。若本地有未 push 的 commit（理論上不該發生），依下方「Push 被拒的處置規則」改走 chore/main-agent/*。

chore/main-agent/* 收斂分支生命週期

用於承接無 Issue 的小修，取代舊版 dev/main-agent 的「停車場」角色。

建立時機：

• 分流選項 1（直接修正）
• 聯調模式的連續小修正（無 Issue）
• 任何「要動手改檔案但沒有對應 Issue」的情境

建立方式（必須從 origin/main 分出）：

git fetch origin
git checkout -b chore/main-agent/$(date +%Y%m%d)-<簡述> origin/main

命名範例：

• chore/main-agent/20260410-typo-readme
• chore/main-agent/20260410-integration-fixes（聯調多筆小修用同一條）

PR 提交時機（滿足任一即提交）：

• 小修達到一個自然停止點
• 聯調測試結束
• 開發者明確說「push」或「推送」

PR 合併後處理：與 feature 分支相同，刪除本地與遠端分支，依下方「PR 合併後 HEAD 收尾」回到 dev/main-agent。

提交與合併規則

情境	分支	提交方式	PR 合併後
功能開發（領取 Issue）	feat/<agent>/issue-N-簡述	feature → PR	刪除分支
分流選項 1（直接修，無 Issue）	chore/main-agent/<date>-<簡述>	chore → PR	刪除分支
聯調模式連續修正（無 Issue）	chore/main-agent/<date>-<簡述>	累積修正後 chore → PR	刪除分支
聯調模式修正（有 Issue）	feat/<agent>/issue-N-簡述	feature → PR	刪除分支
A-Main STATUS 快照寫入	dev/main-agent	由 /vibe-sdlc-status 管理（可 reset + commit）	不 PR、不刪除

原則：所有工作變更一律走 PR 且用後即刪。dev/main-agent 不接受工作 commit，只接受由 status skill 管理的快照更新；嚴禁直接 push main。

議題收集與處置流程補充

以下為 /vibe-sdlc 核心原則中「議題收集與處置流程」的補充規則：

同一任務的迭代修正不需重複分流：

若開發者在驗收過程中對同一 Issue 範圍連續回報修改（如「排除清單還不夠」→「再加幾個」），這屬於同一任務的迭代修正，不需每次都觸發分流選單。但若是新功能或新範圍的請求（如「改成雙軌模式」），仍須觸發分流。

判斷標準：

• 修正內容是否在已領取 Issue 的範圍內 → 不觸發
• 修正內容是否引入新概念或新架構變更 → 觸發

合併後自動詢問部署

在以下時機，AI 應主動詢問是否重建部署：

• PR 合併後：「PR 已合併，是否重建部署？」
• 聯調模式修正 push 後：「修正已推送，是否重建部署？」

若開發者之前已表達「先不部署」等意圖，則不重複詢問。

規格文件回溯規則

詳見 /vibe-sdlc-pr「規格文件同步觸發條件」。PR 合併後，AI 應根據該規則提示開發者是否需要同步更新規格文件。

Agent 狀態檔維護規範

詳細的狀態檔架構與格式定義見 /vibe-sdlc-status。以下為 P3 開發過程中的寫入規則。

每個 Agent 在開發過程中必須維護自己的狀態檔（/docs/status/{agent-id}.md），確保其他人可隨時掌握該 Agent 的工作狀態。

寫入時機

事件	狀態檔操作
領取任務（步驟 3）	「當前任務」新增 Issue，狀態 🟢
完成重要階段	更新狀態說明
遇到阻塞（自行排查中）	狀態改 🟡，「注意事項」新增描述
無法繼續（需人類介入）	狀態改 🔴，「注意事項」新增原因
Vibe Check 通過 + PR 建立	狀態說明更新為「PR #N 已建立」
任務完成（PR 合併後）	從「當前任務」移除，更新「近期待辦」

單 Agent 模式

若專案僅有一個 Agent（A-Main），可省略狀態檔維護。狀態將由 /vibe-sdlc-status 從 GitHub Issues/PR 自動聚合。

Telegram 推播規範

若 Dev Plan 協作策略中定義了 TG 推播設定（Bot Token + Chat ID），Agent 在關鍵事件發生時必須透過 TG sendMessage API 推送通知。

推播事件

事件	推播內容	推播條件
領取任務	🚀 {agent} 領取 #{N} {標題}	必須
遇到阻塞	⚠️ {agent} #{N} 遇到阻塞：{簡述}	必須
無法繼續	❌ {agent} #{N} 無法繼續：{原因}	必須
Vibe Check 通過	✅ {agent} #{N} 完成，PR #{M} 已建立	必須
重要進度	📋 {agent} #{N} {進度描述}	建議

推播方式

使用 curl 呼叫 TG Bot API：

curl -s -X POST "https://api.telegram.org/bot${TG_BOT_TOKEN}/sendMessage" \
  -d chat_id="${TG_CHAT_ID}" \
  -d text="${MESSAGE}" \
  -d parse_mode="Markdown"

Bot Token 與 Chat ID 定義於 Dev Plan 的「協作策略 — 通知設定」段落中，或透過環境變數 TG_BOT_TOKEN / TG_CHAT_ID 注入。Agent 應優先讀取 Dev Plan 設定，若無則 fallback 至環境變數。若兩者皆無，則跳過推播（不阻擋開發流程）。

Issue 狀態追蹤規範

Issue 是跨 session 的唯一溝通媒介。 所有角色（AI 與人類）都應能透過 Issue Comments 了解任務的最新進展，而無需進入特定的 session 或 worktree。

看板狀態更新

使用 GitHub CLI 更新 Project 看板的 Status 欄位：

# 取得 Issue 在 Project 中的 Item ID
ITEM_ID=$(gh project item-list <PROJECT_NUMBER> --owner <OWNER> --format json \
  | jq -r '.items[] | select(.content.number == <ISSUE_NUMBER>) | .id')

# 更新狀態
gh project item-edit --project-id <PROJECT_ID> --id "$ITEM_ID" --field-id <STATUS_FIELD_ID> --single-select-option-id <OPTION_ID>

提示：若 gh project item-edit 操作複雜，可改用 gh issue edit 加 label 方式標註進度（如 in-progress），或直接在 Issue Comment 中說明狀態變更。選擇最簡單可行的方式即可。

Issue Comment 規範

在以下時機必須發佈 Issue Comment：

1. 領取任務時（步驟 3）

🚀 **任務領取**
- **角色**：{角色代號}（如 A-Backend、A-Frontend、A-Main）
- **分支**：`feat/<agent>/issue-N-簡述`
- **Worktree**：`../worktree-<agent>`（若適用）
- **開始時間**：{YYYY-MM-DD HH:MM}

臨時需求與規格變更處理

開發過程中若遇到以下情況，應即時回溯更新規格文件，而非等到迭代結束：

情況	處理方式
開發者臨時新增需求	先回 P1 更新 PRD/SRD/API Spec（含版本修訂記錄）→ 更新 Dev Plan 新增任務 → 建立對應 Issue → 繼續開發
Bug 修正導致 API 行為變更	更新 API Spec（md + yaml）（含版本修訂記錄）→ 在 Issue/PR 中標註規格變更
開發中發現規格遺漏或矛盾	在 Issue 中標記疑問 → 與開發者討論 → 確認後更新對應規格文件（含版本修訂記錄）
新增未規劃的 Issue	同步更新 Dev Plan 任務清單（含版本修訂記錄）

原則：規格文件是唯一真相來源，任何對產品行為的變更都必須反映在規格文件中，且每次修改都必須更新版本修訂記錄。

2. 重要進度更新時（視情況）

當遇到以下情況時，應在 Issue 發佈進度 Comment：

• 完成重要階段（如「API 端點已實作完成，開始撰寫單元測試」）
• 遇到阻塞或需要等待其他任務（如「前端串接需等待 T-201 API 完成」）
• 發現規格疑問或需要開發者決策（應即時標記，參見「臨時需求與規格變更處理」）
• 任務範圍超出預期，需要調整

📋 **進度更新**
- **已完成**：{已完成的項目}
- **進行中**：{目前正在做的}
- **阻塞/待處理**：{阻塞原因或待處理事項}（若無則省略）

3. Vibe Check 完成時（步驟 9，建立 PR 後）

✅ **Vibe Check 通過**
- **PR**：#{PR_NUMBER}
- **測試結果**：單元測試 {passed}/{total} 通過
- **備註**：{任何需要 reviewer 注意的事項}（若無則省略）

何時發佈 Comment

時機	是否必須	Comment 類型
領取任務	必須	🚀 任務領取
完成重要階段	建議	📋 進度更新
遇到阻塞	必須	📋 進度更新（含阻塞原因）
發現規格疑問	必須	📋 進度更新（含問題描述）
Vibe Check 通過	必須	✅ Vibe Check 通過

原則

• 簡潔為主：Comment 不需冗長，重點在於讓他人快速了解狀態
• 避免噪音：不需要為每一行程式碼的變更發佈 Comment，僅在有意義的節點更新
• 跨 Agent 溝通：Sub Agent 之間不直接溝通，但可透過 Issue Comment 讓 A-Main 了解進度與阻塞

工作目錄同步規範

每次領取新 Issue 前，必須先同步工作目錄。 這是為了確保新建的分支基於最新的 main，避免因本地落後遠端而產生不必要的衝突或遺漏已合併的程式碼。

預設停留分支為 dev/main-agent：任務間無進行中工作時停留在此分支檢視即可，但任何動手的工作（feature / chore）都必須從 origin/main 新建分支，絕對不得在 dev/main-agent 上 commit。

同步步驟（步驟 3 詳細流程）

# 1. 同步遠端資訊
git fetch origin

# 2. 偵測主線分支名稱（main 或 master，以下統稱 {main}）

# 3. 確保快照分支 dev/main-agent 存在，若不存在則建立
git show-ref --verify --quiet refs/heads/dev/main-agent || \
  git checkout -b dev/main-agent origin/{main} && \
  git push -u origin dev/main-agent

# 4. 檢查本地是否有未提交的變更
git status --short

情境 A：當前在 dev/main-agent（快照分支，預期停留位置）

• 工作目錄乾淨：不要 rebase、不要 force push。直接從 origin/main 建立新的工作分支（feature / chore）：

  git fetch origin
  # 若本地 dev/main-agent 落後遠端（他人做了 STATUS 快照），直接對齊
  git reset --hard origin/dev/main-agent
  # 建立新工作分支（不從 dev/main-agent 分出）
  git checkout -b <feat|chore>/... origin/main
  

• 工作目錄有未提交變更（⚠️ 異常狀態，不應發生）：dev/main-agent 上不該有未 commit 的變更。處理方式：

  ⚠️ 快照分支 dev/main-agent 出現未提交變更（不應發生）
  ├─ 當前分支：dev/main-agent
  ├─ 未提交變更：
  │  {git status --short 輸出}
  └─ 建議操作：
     1. 搬移至新的 chore 分支（推薦）— 自動接管變更
     2. 暫存變更（git stash）→ 對齊遠端 → 建立 chore 分支 → stash pop
     3. 捨棄全部變更（⚠️ 不可逆）
  

  • 選擇 1：git checkout -b chore/main-agent/$(date +%Y%m%d)-<簡述> origin/main（變更自動帶過去）
  • 選擇 2：git stash → git fetch origin && git reset --hard origin/dev/main-agent → git checkout -b chore/main-agent/$(date +%Y%m%d)-<簡述> origin/main → git stash pop
  • 選擇 3：再次確認後 git checkout -- . && git clean -fd

情境 B：當前在 {main} 分支（應避免）

• 工作目錄乾淨：git pull origin {main} 後切回快照分支：git checkout dev/main-agent && git reset --hard origin/dev/main-agent

• 工作目錄有未提交變更（⚠️ 異常狀態）：以下列格式警告，暫停等待開發者指示：

  ⚠️ 主線分支有未提交變更（{main} 應為唯讀，禁止 commit）
  ├─ 當前分支：{main}
  ├─ 未提交變更：
  │  {git status --short 輸出}
  └─ 建議操作：
     1. 搬移至新的 chore/main-agent 分支（推薦）
     2. 暫存變更（git stash）→ pull main → 切回 dev/main-agent → 建 chore 分支 → stash pop
     3. 捨棄全部變更（⚠️ 不可逆，慎用）
  

  • 選擇 1：git checkout -b chore/main-agent/$(date +%Y%m%d)-<簡述>（變更自動帶過去）→ 後續走 chore 分支開發
  • 選擇 2：git stash → git pull origin {main} → git checkout dev/main-agent && git reset --hard origin/dev/main-agent → git checkout -b chore/main-agent/$(date +%Y%m%d)-<簡述> origin/{main} → git stash pop
  • 選擇 3：再次確認後 git checkout -- . && git clean -fd → git pull origin {main} → git checkout dev/main-agent && git reset --hard origin/dev/main-agent

情境 C：當前在 feature / chore 分支（feat/* 或 chore/main-agent/*）

• 工作目錄乾淨：若繼續開發同一任務，停留在當前分支即可；若任務已完成或要切換任務，git checkout dev/main-agent && git reset --hard origin/dev/main-agent
• 工作目錄有未提交變更：與開發者確認是否需要先 commit 或 stash，處理完畢後再繼續同步流程

收尾步驟（所有情境共通）

# 5. 若 rebase 產生衝突：立即停止並通知開發者
#    - 不可自行解決衝突
#    - 報告衝突的檔案清單，等待開發者指示

# 6. 清理已合併的分支與無用的 worktree（詳見下方「清理規範」）

清理已合併分支與 Worktree

同步完成後，檢查是否有前次任務遺留的分支與 worktree 需要清理。刪除前必須列出清單讓開發者確認。

檢查指令

# 受保護分支的 grep 排除模式（含快照分支 dev/main-agent）
PROTECTED='main$\|master$\|dev/main-agent$\|develop$\|dev$\|testing$\|test$\|staging$\|uat$\|release/'

# 1. 同步遠端已刪除的分支引用（清除本地殘留的 remote tracking ref）
git fetch --prune

# 2. 列出已合併至 main 的本地分支（排除受保護分支）
git branch --merged main | grep -v "^\*\|$PROTECTED"

# 3. 列出對應的遠端已合併分支（排除受保護分支與 HEAD）
git branch -r --merged origin/main | grep -v "origin/HEAD\|$PROTECTED"

# 4. 列出所有 worktree
git worktree list

快照分支保護：dev/main-agent 是永久分支，不可刪除。它保護的是「分支存在性」，不是「歷史線性」——A-Main 可透過 /vibe-sdlc-status 在必要時將其 reset 到 origin/main 後重寫快照 commit。

Chore 分支不在保護清單：chore/main-agent/* 屬於短命分支，用後即刪（與 feature 分支相同處理）。

清理流程

步驟	操作
1	執行上述檢查指令，收集待清理項目
2	若無待清理項目，跳過此步驟
3	向開發者列出清單，格式如下，等待確認後才執行刪除
4	開發者確認後，依序執行：git worktree remove → git branch -d → git push origin --delete → git fetch --prune（最終確認遠端 ref 已同步）

清理確認清單格式

🧹 發現以下已合併的分支/worktree 可清理：

**Worktree：**
- `../worktree-backend` → 分支 `feat/backend/issue-5-auth-api`（已合併）

**本地分支：**
- `feat/backend/issue-5-auth-api`（已合併至 main）
- `feat/frontend/issue-6-login-page`（已合併至 main）

**遠端分支：**
- `origin/feat/backend/issue-5-auth-api`（已合併至 main）

是否確認刪除以上項目？

同步檢查清單

• git fetch origin 成功
• 本地無未提交的變更（或已妥善處理）
• git log --oneline HEAD..origin/main 顯示無差異（本地已追上遠端）
• 無 rebase 衝突
• 已合併的分支與 worktree 已清理（或無需清理）

何時需要同步

場景	是否需要同步	新分支 base
領取新 Issue、建立 feature 分支前	必須	origin/main
分流選項 1 / 聯調小修，建立 chore 分支前	必須	origin/main
PR 合併後，準備下一個任務	必須	origin/main（從新 base 建新分支）
在 feature / chore 分支上開發途中	不需要	—
聯調/驗收中連續修正	不需要	—
Phase 4 修正 CI 失敗時	建議	不切換（在失敗分支修正）
查看儀表板（/vibe-sdlc）	git fetch 即可	—

關鍵：所有新工作分支的 base 必須是 origin/main，不得是 dev/main-agent 或任何本地分支。這是避免再次撞上「從快照分支分出導致歷史交錯」的核心規則。

Push 被拒的處置規則

若 git push 被拒絕（non-fast-forward），禁止採取以下動作：

• ❌ git push --force / --force-with-lease 到 dev/main-agent（會覆蓋其他 session 的 STATUS 快照）
• ❌ 在 dev/main-agent 上 git rebase origin/dev/main-agent 後 force push
• ❌ 在任何 feature 分支上 force push（除非是自己剛剛才推上去的 WIP）

應依情境採取以下處置：

情境	處置
當前在 feature 分支，被拒是因為他人推了相同分支	停下並報告，不自行處理（可能有 session 衝突）
當前在 dev/main-agent，本地有未 push 的 commit（理論上不該發生）	從 origin/main 建 chore/main-agent/<date>-* → git cherry-pick 本地 commit 過去 → 走 PR 流程；原本 dev/main-agent 本地 git reset --hard origin/dev/main-agent 對齊
當前在 chore/main-agent/*，被拒（另一 session 推過同名分支）	報告衝突，與開發者討論是否改名或合併

原則：dev/main-agent 被視為「他人也會動的快照分支」，本地 commit 不保證能直接 push 上去；遇到衝突一律走新分支 cherry-pick 而非硬 rebase。

Vibe Check 報告格式

完成開發與測試後，向開發者報告時使用以下格式。注意：此報告在 PR 建立後才輸出，報告中必須包含 PR 連結。

# Vibe Check 報告

## Issue
- 編號：#N
- 標題：[Issue 標題]

## 實作摘要
[簡述實作了什麼、採用什麼方式]

## 變更檔案
| 檔案 | 變更類型 | 說明 |
|------|----------|------|

## 測試結果
- 單元測試：✅ / ❌（通過數 / 總數）
- 測試覆蓋的驗收標準：
  - [x] [標準 1]
  - [x] [標準 2]

## PR
- 連結：[PR URL]
- 分支：`feat/<agent>/issue-N-簡述`

## 狀態
- [通過 / 未通過]：[若未通過，說明原因]

PR 自動建立規範

Vibe Check 通過後，AI 助手必須立即自動完成以下動作（無需等待開發者核准）：

1. 推送分支：git push -u origin <branch-name>
2. 建立 PR：使用 gh pr create，格式如下：
   • 標題：feat(<scope>): <簡述> (<任務編號>)，例如 feat(backend): Schema 與 DB 初始化 + 後端骨架 (T-101, T-102)
   • Body：必須遵循 P4「PR 格式規範」（變更摘要 / 關聯 Issue Closes #N / 變更清單 / 測試結果）
   • Reviewer：一律指定 H-Director 為 reviewer（--reviewer <H-Director-username>）
3. 回報 PR 連結：在 Vibe Check 報告末尾附上 PR URL

追加 Commit 至既有 PR 的安全檢查

詳見 /vibe-sdlc-pr「追加 Commit 至既有 PR 的安全檢查」。推送前必須確認 PR 仍為 OPEN。

PR 合併後的 HEAD 收尾檢查（強制）

gh pr merge --delete-branch 會在當前分支被刪時自動把 HEAD 切到 PR 的 base 分支（通常是 main）。為避免「不知不覺停留在 main 或被刪除的 feature branch」，merge 指令執行後必須依序執行：

1. git branch --show-current 確認當前分支
2. 若當前在 main / master 或已被刪除的 feature/chore 分支 → 立刻 git checkout dev/main-agent && git reset --hard origin/dev/main-agent
3. 在 Vibe Check 報告末尾標註「Post-merge branch: {branch}」供人類審計
4. 嚴禁在 main 上停留超過單一 checkout 指令的時間

# 標準收尾流程（放在 gh pr merge 之後）
gh pr merge <N> --squash --auto --delete-branch
git fetch origin
CUR=$(git branch --show-current)
if [ "$CUR" = "main" ] || [ "$CUR" = "master" ] || [ -z "$CUR" ]; then
  git checkout dev/main-agent
  git reset --hard origin/dev/main-agent
fi
git branch --show-current  # 最終確認

PR Body 格式

必須遵循 Phase 4 定義的「PR 格式規範」（見 /vibe-sdlc-pr「PR 格式規範」）。

Multi Sub Agent PR 建立

當多個 Sub Agent 並行開發時，A-Main 統一處理所有 Sub Agent 的 PR 建立：

• 各 Sub Agent 完成開發後回報 Vibe Check 結果（含分支名稱與 worktree 路徑）
• A-Main 批量推送所有通過 Vibe Check 的分支，並依序建立 PR
• 各 Agent 的 PR 僅包含自己負責範圍的檔案
• PR 分支命名遵循 feat/<agent>/issue-N-簡述
• A-Main 在最終彙報中列出所有 PR 連結，提醒開發者進行 Code Review

Review 類任務處理流程

部分 Issue 屬於 Review 類任務（如 Prompt Review、Code Review），其產出是「Review 意見」而非功能程式碼。處理方式如下：

判斷依據

檢查 Issue 的「PR 策略」欄位：

• 有 PR 策略（獨立 PR / 合併 PR）→ 走標準開發流程
• 無 PR（Review 任務） → 走 Review 流程

Review 流程

步驟	操作
1	閱讀待審查的程式碼（如 Prompt 模板、API 實作）
2	對照規格文件進行品質審查
3	若發現確定性 bug（欄位不一致、邏輯錯誤、安全漏洞等）→ 直接修正，不需停下來詢問
4	修正後執行測試（Vibe Check）
5	Vibe Check 通過 → 自動建立 fix PR
6	將 Review 報告發佈至 Issue Comments，並在 Vibe Check 報告中附上 PR 連結

關鍵原則

• Review 發現的確定性 bug，直接修正：不需要額外一輪對話來獲得修正許可。Review 報告本身就是修正的依據。
• 設計層面的建議（非 bug）：標記為「建議改善（非阻擋性）」，由開發者決定是否採納，不自行修改。
• Review + 修正 = 一次完成：向開發者報告時，同時呈現 Review 結果和修正 PR，而非分兩次報告。

聯調模式（Integration Testing & Debugging）

當開發者在部署後進行聯合調試（部署 → 測試 → 發現問題 → 修正 → 重新部署）的連續循環中，每一筆回報的 Bug 或修改需求都必須先觸發「議題收集與處置流程」機制（定義於 /vibe-sdlc 核心原則）。

聯調流程

部署 → 開發者測試 → 發現問題 → 回報分流（1/2/3）→ 修正 → 重新部署 → 繼續測試
                                    ↑                              ↓
                                    └──────────────────────────────┘

分流選項行為

選項	聯調中的行為
1 — 直接修正	從 origin/main 建 chore/main-agent/$(date +%Y%m%d)-<簡述> 分支（聯調多筆小修共用同一條），立即修正，修正完成後詢問是否重新部署（docker compose up -d --build）。適合 UI 微調、文案、簡單邏輯錯誤。
2 — 建 Issue 再修正	先 gh issue create 建立 Issue（含重現步驟、截圖引用、嚴重程度標籤），然後立即修正，修正完成後詢問是否重新部署。
3 — 先記下來	暫存至待建立清單，繼續聯調。開發者說「整理」或「建立 Issues」時批量建立。適合非阻塞性問題、改善建議。

連續修正與部署

聯調過程中可能連續修正多個問題。AI 應：

1. 累積修正後一次部署：若開發者連續回報多個小問題且都選「1 — 直接修正」，在同一條 chore/main-agent/<date>-* 分支上累積修正後統一詢問是否重新部署，避免頻繁重建
2. 每次部署前確認：列出本輪已修正的項目，確認後再執行部署
3. 部署後主動提示：部署完成後提示開發者繼續測試

聯調結束

當開發者明確表示聯調結束（如「OK 了」「沒問題了」「先這樣」），AI 應：

1. 檢查是否有選項 3 暫存的待建立 Issues，若有則提醒
2. 列出本輪聯調的修正摘要（含哪些已建 Issue、哪些直接修正）
3. 若 chore/main-agent/* 分支有未推送的 commit，提交 PR 並在合併後刪除該分支

既有測試失敗處理規則

Vibe Check 階段可能遇到「非本次變更造成的測試失敗」（既有 bug 或 flaky test）。處理方式如下：

情況	判斷方式	處理
Flaky test（非確定性失敗）	重跑測試後通過；或單獨跑該測試檔案通過	記錄在 Vibe Check 報告中，不阻擋 PR
既有 bug（確定性失敗）	失敗的測試與本次修改的檔案無關	若修正簡單（< 10 行），一併修正在本 PR；若修正複雜，記錄在 Vibe Check 報告中，建議開發者另開 Issue
本次變更導致的失敗	git diff 涉及失敗測試相關的檔案	必須修正後才能建立 PR

關鍵原則

• 先自行排查，確認歸因後再決定處理方式，不要遇到失敗就停下來問開發者。
• 排查步驟：單獨跑失敗的測試檔案 → 檢查 git diff 是否涉及相關檔案 → 判斷是 flaky / 既有 bug / 本次造成。

完成條件

• 功能程式碼已完成且符合 SRD 規範
• 單元測試全部通過（Vibe Check 通過）
• PR 已自動建立並回報連結
• 開發者已收到 Code Review 通知

行為指引

當使用者呼叫此 skill 時：

1. 詢問開發者要處理哪個 Issue（編號或讓 AI 從看板挑選最高優先級）
2. 使用 gh issue view N 讀取 Issue 內容
3. 向開發者確認你對任務的理解，列出：
   • 任務範圍
   • 驗收標準
   • 需參考的規格文件
4. 獲得確認後，領取 Issue：
   • 將看板狀態更新為 In Progress（或以可行的方式標註）
   • 發佈「🚀 任務領取」Comment 至 Issue（含角色、分支名稱、worktree 路徑）
5. 執行工作目錄同步（git fetch → 處理未提交變更 → rebase origin/main），確認本地 main 為最新狀態
6. 根據分支策略，從 origin/main 建立對應分支（有 Issue → feat/<agent>/issue-N-簡述；無 Issue 小修 → chore/main-agent/<YYYYMMDD>-<簡述>）並開始實作
7. 實作過程中，以下規格文件可供參考：
   • /docs/01-1-PRD.md（產品需求，前端頁面與流程參考）
   • /docs/01-2-SRD.md（技術規範）
   • /docs/01-5-API_Spec.md（API 規格）
   • /docs/API_Spec.yaml（OpenAPI 合約）
   • /docs/01-6-UI_UX_Design.md (UI/UX規格)
8. 完成後撰寫測試並執行
9. 若遇到阻塞或重要進度節點，發佈「📋 進度更新」Comment 至 Issue
10. Vibe Check 通過後，立即自動推送分支 → 建立 PR → 回報 PR 連結（無需等待人類核准）
    • 發佈「✅ Vibe Check 通過」Comment 至 Issue（含 PR 連結與測試結果）
    • 向開發者彙報 Vibe Check 結果 + PR 連結，提醒進行 Code Review
    • 若 CI 失敗需修正，可呼叫 /vibe-sdlc-pr 處理
11. 若 Vibe Check 未通過，自行修正後重新執行測試，直到通過為止
12. 若 Issue 屬於 Review 類任務（PR 策略為「無 PR」），參照上方「Review 類任務處理流程」：
    • 審查 → 發現確定性 bug → 直接修正 → 測試 → 建 PR → 一併報告 Review 結果與 PR 連結