給自動化任務留一張「交接卡」：讓明天接手的人 10 秒上手

上週深夜排查一個半夜跑的排程任務，我把「最近一次成功是什麼時候、失敗時該看哪個日誌」問了三個 AI 和兩份文件，誰都沒給我答案。任務本身沒死，但沒人說得清它現在怎麼樣了——這種「活著但不透明」的狀態，比任務直接掛掉更危險。

從這裡長出一張「交接卡」：任何我寫的自動化任務，上線時必須附帶一段固定格式的說明。卡不複雜，四段：

任務：sfd-daily-skill-1400
用途：每天 14:00（SGT）發布一篇 skill 短文
依賴：本地路由 / CMS API / sfd-article-publish.py
最近運行：PASS（報告在 reports/daily-pipeline/sfd-daily-skill-20260910.md）

沒寫「最近運行」的那張卡，不算合格。一個任務死了多久沒人記得，才是真丟。

什麼時候該用

- 任務會長期跑（cron、CI、watcher），存活期超過你「幾天就忘」的記憶長度

- 涉及外部依賴的腳本：路由、資料庫、第三方 API

- 發生過的「繼承人摸黑修腳本」插手事件——不管這次修沒修好，都值得記

- 交付給他人或其他 agent 的任何工作流程；業務邏輯另算，這張卡也要有

什麼時候不用

- 一次性腳本：查個資料、跑個報表，跑完就刪，別浪費卡

- 五分鐘內能重現的活：口頭講清楚就夠了

- 文件庫裡已經有完整 runbook 的任務——別再寫一份不一樣的

寫卡 checklist

□ 一句話說清「它解決什麼問題」，不堆形容詞

□ 列出依賴：服務、憑證檔案位置（只寫檔名，不寫真值）、腳本路徑

□ 記錄最近一次成功運行的日期和報告位置

□ 寫明失敗時的查看入口：日誌在哪、報告在哪

□ 會修改線上狀態的任務（發布、刪資料），在「用途」一行裡明確標註

踩過的坑

- **只寫用途，不寫失敗入口**：卡上有「用途」沒有「出事了去哪看」，凌晨出故障就是痛苦的根源。兩欄都填，缺一不可。

- **寫得太長**：卡超過一段——大概率是想塞進去一個沒結論的概念。砍到四行。

- **寫完不更新**：「最近運行」過期了這張卡就該扔了。每次 PASS/HOLD/BLOCKED 之後做一次例行更新，是最便宜的保險。

- **真值漏進卡裡**：密碼、token 一律只寫「存於某檔案」，不寫真實值；日誌和卡一樣，都是文件。

明天再打開那張任務列表時，希望我能對著自己寫的話說一句：每個任務都知道自己是誰。