Handoff Protocol

交接紀律(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 比對證明內容其實一致、差異純為時間戳,連同修法(固定時間戳)一次交。把關者因此 只需覆核、不需偵查——一次主動揭露,買回的是之後所有回報的免驗成本。