# Handoff Protocol

> 三方協作(決策者 / 把關者 / 實作者)的交接紀律。用於任何「有人拍板、有人把關、有人動手」的同構協作:怎麼回報進度而不燒光對話空間、怎麼不悶頭長跑、怎麼分辨「假卡」與「真失敗」、交給把關者的結果要長什麼樣、哪些界線實作者不可越。

- Skill: `poloplay0114/handoff-protocol-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add poloplay0114/handoff-protocol-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/poloplay0114/handoff-protocol-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: poloplay0114 (https://skillmd.com/u/poloplay0114)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/poloplay0114/handoff-protocol-2

---


# 交接紀律(Handoff Protocol)

## 什麼時候用

任何工作分成三個角色的時候:**決策者**(定方向、拍板)、**把關者**(審查、驗收)、**實作者**(動手做)。
三者可能是三個人,也可能是「人 + 審查者 + 自動代理」。這技能講三者之間**交接的格式與紀律**,
讓協作不靠猜、不燒溝通成本、不出無聲的錯。

---

## 通用法則

### 法則 1:回報結果用「一行結論」,不貼原始輸出

把關者要的是**結論**,不是你螢幕上的一切。跑完一件事,回報一行:做了什麼、結果是綠是紅、關鍵數字。
- ✓「全量測試 1372 passed / 0 fail(baseline 1341 + 31 新測)」
- ✗ 貼三百行測試輸出讓對方自己找。
原始輸出留在檔案/日誌,需要時再指路。**溝通空間有限,別用它搬運噪音。**

### 法則 2:進度段要「省空間」

長時間任務中途回報進度時,同樣一行:目前到哪、有沒有異常。不要每一步都貼完整細節——
對話/上下文空間是稀缺資源,塞滿了反而看不到重點。

### 法則 3:不悶頭長跑(先估時、按時回報、超時喊停)

- **動手前先估**:這件事大概多久?
- **按節奏回報**:長任務每隔一小段(如 2–3 分鐘)報一次「還在跑、到哪了」,別消失。
- **超時即停**:實際明顯超過預估(如 1.5 倍)就**停下來診斷**,別無限等——通常是卡住了,不是慢。
- **別重試已知無辜的**:已經驗過綠的東西別反覆重跑燒時間;針對可疑的查。

### 法則 4:分辨「假卡」與「真失敗」,別把假卡當真 bug 改

長任務停住或報錯時,先問:**是我的產物錯了(真失敗),還是環境噪音(假卡)?**
- **假卡**的典型來源:殘留的舊進程搶資源/檔鎖、上一輪沒清乾淨的狀態、外部相依暫時不穩、
  同名資源多份實例互搶。
- **處置**:先**隔離**(把干擾源精準清掉——按進程 ID 精準結束,別誤殺無辜;**精準結束干擾的那個
  程式,別全殺**)→ **乾淨重跑一次** →
  若重跑就綠 = 假卡,不是 bug,別去改產物;若穩定重現 = 真失敗,才進入除錯。
- **鐵律**:假卡絕不當真 bug 改——「憑推測就改」會把一個好產物改壞。先重現、再定性、才動手。

### 法則 5:交給把關者的東西要「可直接把關」

把關者要能**一眼複核**,不用重建你的上下文:
- 結論(綠/紅)+ 證據(關鍵數字/對帳)+ 邊界(驗到哪、沒驗到哪,誠實標)。
- 若把關者要貼給更上層,給一段**可複製的定稿段落**(標題 + 結論 + 證據 + 邊界),別讓對方自己拼。
- 對帳要精確:「原 N + 新增 M = N+M」——數字對得上,把關才信得過。

### 法則 6:實作者不代改決策者/把關者的文件

角色邊界是安全機制,不是形式:
- **實作者不擅自改「決策者管理的文件」**(規格、需求、拍板紀錄)。要補內容 → 用**自己的**設計/計畫
  文件引用它,或提案請決策者改。看見它被別人動過(工作樹有改動)→ **不碰、不提交**,回報即可。
- 同理,把關的判準由把關者定,實作者不自行放寬。
- 越界的代價:決策者失去對「真相來源」的掌控,後面所有人跟著錯。

### 法則 7:誠實回報,壞消息不修飾

測試紅了就說紅、貼輸出;跳過了就說跳過;做完並驗過了就直說,不加沒必要的保留。
把關的前提是「回報可信」——一次粉飾,之後所有回報都要被重新驗證,協作成本暴增。

---

## 本專案案發現場(佐證,非通用必需)

- **一行自驗 + 對帳(法則 1/5)**:某財務報表自動化專案每個 Task 收尾回報「pytest X passed / 0 fail」,
  合併關口報「baseline 1341 + 31 新測 = 1372」——把關者靠這行 + 對帳數字複核,不看原始輸出。
- **假卡實例(法則 4)**:某次全量測試「假卡」——中途留下的舊測試進程(真在跑全掃)與正式 run 搶 Windows
  檔鎖,造成假卡。處置:**按 PID 精準清**掉殘留進程 + 隔離重跑取乾淨綠,判定「假卡 ≠ 真 fail」,
  未去改任何產物。另有一次 webapp「flaky」誤判,教訓正是「flaky 別憑推測就改」,查出真根因(檔案原子
  寫競態)才修。
- **不代改決策者文件(法則 6)**:主規格 `主規格檔` 由 決策者 工作樹管理;實作發現它被改動 →
  不碰不 commit,只在獨立的 spec/plan 文件引用。呼應姊妹技能 spec-citation 的「非本人管理只讀不改」。
- **不悶跑(法則 3)**:專案有明文「不悶跑工作守則」——長指令先估時、每 2–3 分回報、超時停、
  別重跑已驗證無辜的。
- **雙向對帳(法則 4/5/7 完整活案例)**:同一件事,兩個方向都被「對著真相核實」擋下:
  - **實作者端(自報被抓)**:把一份**只被口頭指示過內容、實際從未送審**的交付物標成「已審過」。
    把關者一句「內容指示 ≠ 成品已審」的**對帳**當場抓出(四份審過、標了五份)。教訓:「已完成」只認
    **走過驗收關**的,不認「我覺得該過」(呼應 verification-discipline「不信自報結果」)。
  - **審查者端(意見被核實擋回)**:把關者依**渲染過的貼文副本**下了「刪重複段、補截斷句」的意見;實作者
    **對真實檔案核實**——那段沒重複、也沒截斷,是貼文渲染假影 → **不盲從、不去刪一個不存在的重複**,
    回報請對方對真檔再確認(呼應法則 4「假影 vs 真問題」的精神:先核實再動手)。
  - 合起來的鐵則:**實作者不誤標「已審」,審查者的意見執行前先對真實成品核實**——兩端都不靠「印象/
    副本」,靠對帳真相。雙方誠實更正、無硬拗。
- **主動揭露自己的假綠(法則 7 正面實例)**:實作者在真檔重測時發現,自己先前交過的一條等值測試是
  靠「兩次寫出恰落同一時間戳 bucket」矇綠的——**不等把關者抓,自己先講**:「先前那條 test 只是同秒
  僥倖」,並附逐 part 比對證明內容其實一致、差異純為時間戳,連同修法(固定時間戳)一次交。把關者因此
  只需覆核、不需偵查——一次主動揭露,買回的是之後所有回報的免驗成本。