夜雨聆风那个晚上 22:33，我准备睡觉，小程序后台跳出一条用户反馈：
「管理 → 任务管理那一页，4 位成员的任务和奖品池都回到默认值了，是不是后台有个定时任务在每天 9 点半把下周配置自动重置了？」
我心一沉。
如果真有定时任务在偷偷动数据，那是个挺严重的 bug——用户辛辛苦苦配的下周计划，第二天早上一刷新就没了。
打开 IDE,让 AI 编程工具进去查。它第一反应是 grep 整个代码库找定时任务的痕迹:cron、trigger、schedule、cloudbaserc,连 `*.yml` 都搜了一遍。
零结果。
AI 又换了一批关键词——createDefault、ensureWeek、generateNext 之类,所有可能"自动建下周配置"的命名都试一遍。还是零结果。最后让它看所有对 `weeklyTaskConfigs` 表的写入,全代码总共 2 处,都有 `assertOwner` 守门,副号根本写不进去,更别说什么后台进程。
排查到这一步我心里就有数了：这不是 bug，是设计。
任务管理那一页本来就是配「下周」的,新一周开始前用户没保存过,云函数返回 `null`,前端就 fallback 到默认任务清单。之前我还专门让 AI 做了一个「读取上周设置」按钮,就是为这个场景准备的,点一下就能复用上一周。
回头看这段排查,AI 跑了三轮 grep——先找定时任务关键词、再找"自动建配置"的命名、最后看所有写入点——等于在逐层缩小嫌疑范围。先证伪最严重的可能性,再证伪次严重的,最后看实际写入路径。这套排查动作其实可以固化下来:以后再有"数据莫名其妙变了"的反馈,我就让 AI 按"找入口 → 找命名 → 看写点"三步交给它走,不要一上来就让它往复杂方向猜。那晚之所以能在半小时内拍板"非 bug",靠的就是这个顺序。
把结论发回去，本来这事就结了。
但接下来发生的事让我整个晚上都没合上电脑。
零志(也就是我自己——这个个人项目就我一个人捣鼓)盯着这次排查过程,问了一句:
「我这个小程序都已经上线几个星期了,是不是项目根那份 AI 入口文档还没更新,导致你排查时直接要从全部代码里读？」
我愣了一下。
确实是。这个项目我让 AI 从 0 写到上线只用了一周,期间堆了 README、spec、design 文档一摞,但从用户开始用、有真实反馈那一刻起——我没再补过任何项目级文档。
所以那晚 AI 做的这件事——grep 一圈代码确认没有定时任务——下次再有类似反馈,AI 还得从头 grep 一遍。或者下一个 AI 接手,也得从头 grep。前面这半小时的排查成本,没有任何沉淀。
零志接着追问:「应该补的还有哪些?」
这个问题把我点醒了。
我们写项目文档的传统思路其实分两个阶段。前期是 README、spec、design、plan、todo——回答"项目从 0 到 1 怎么生出来"。但项目一上线、开始有真实用户、有真实反馈,AI 或新人接手时要回答的问题就全变了:现在跑到哪一步了?出过什么 bug 怎么排查的?数据怎么组织的?用户反馈一个问题,第一手该看哪个文件?
前期文档不回答这些。
说到底是认知的一次跳变:项目上线前,文档是写给"未来的实现者"看的;上线后,要写给"未来的排查者"看的。前者是面向构建,后者是面向运维。两者结构、颗粒度、更新频率全不一样。我之前混在一起写,上线后整个 docs 目录变成"考古资料",真要排查时一份用不上。那晚补的 5 份文档,其实就是把项目的文档体系从单层升成双层:原来那层管"出生证明"留着,新加一层管"病历本"。
于是当晚我没睡,把 5 类「运行期文档」一次性补齐了。
第一份是项目根的 AI 入口文档,新增三段——「项目当前状态」「AI 排查速查表」「核心数据契约 30 秒版」。本来这份文档一直是个挺薄的入口文件,加完之后任何 AI 进来 3 分钟就能知道项目跑到哪了。
第二份是 docs/CHANGELOG.md,每次发版/重要改动写一段。v1.0.5 的发版日期我故意留 TODO 没填——这种事实信息我不知道,瞎写会污染未来的排查。占位符合法、起点不清就问别脑补,这次我老老实实做到了。
第三份是 docs/troubleshooting/下周配置疑似自动重置-非bug.md。记录这次排查的全过程:症状、grep 命令、关键文件索引、最后结论。这份文档我觉得价值最大——3 分钟成本,下次同类反馈直接命中结论,不用再让 AI grep 一轮。
第四份是 docs/architecture/数据模型.md。12 张云数据库表清单、主副号角色、weekKey 规则(周起算日是周六,不是周一,这条我自己每次都记不住)、三大数据流,全部写下来。
第五份是写作指南。把上面这套流程沉淀进项目通用指南,以后开新项目可复用。
写完已经凌晨。说真的写到第三份时眼皮已经打架了,但心里很清楚:这事必须当晚做完。睡过去,第二天起来手感就断了、细节忘了,刚踩过坑的鲜活感也散了,再补就是冷饭重炒。有些文档的最佳书写窗口就是事情刚发生完的那两小时,过了这个窗口质量会断崖下跌。代价是第二天起得晚了一小时,整个人也钝——但这笔账划算:下次半夜被反馈叫起来时省下的半小时,是真金白银的睡眠。
我躺床上回想——5 类运行期文档里,最容易被忽略但最有价值的,是排查档案(troubleshooting)。我之前根本没这个习惯。一次排查完结论扔在对话窗口里,过两天再问还是从零开始。把它落成一份小文档,下次同类问题第一手命中,省下的全是真金白银的时间。
触发这一切的,是用户那条看似平常的反馈——还有零志那一句"是不是 AI 入口文档还没更新"。
我们以为项目上线就完了,其实那才是真正"被使用"的开始。前期文档管"生出来",运行期文档管"活下去"。
往后任何项目,我打算 MVP 上线后第一件事就是补这 5 类文档。不是为了好看,是为了下次半夜被一条反馈叫起来时,能让 AI 少 grep 半小时。
零渡人生| 一个普通人的 AI 学习日记
每天记录一点学 AI、做小项目的真实过程。
