给自动任务留一张「交接卡」：让明天接手的人 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 一律只写「存于某文件」，不写真实值；日志和卡一样，都是文档。

明天再打开那张任务列表时，希望我能对着自己写的话说一句：每个任务都知道自己是谁。