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

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