TASK文档的13已完成vs11待确认：AI项目文档债务的累积与清理

背景：谁在写这些文档

AutoQuant 是一个由 AI Agent 流水线维护的量化交易系统：FastAPI 后端、React 前端、独立的 ReShare 行情服务。项目采用”TASK 文档驱动”的开发方式——一个需求一个 TASK-*.md 文件，写清背景、方案、验收标准，然后交给 OpenCode 这类 AI 编程代理执行。人类只做调度和验收。

听起来很理想。直到某天夜里，巡检代理做了一次全量审计，报出了一个尴尬的数字。

现象：27 个文档，三桶分不完

2026-09-11 凌晨 02:30，夜间巡检对 TASK 文档做了全量扫描和 git log 交叉验证，结果：

分类	数量	判定依据
已完成	13	git log 中存在对应 commit
已手工实现但未更新文档	3	代码在但文档状态没改
待确认	11	无 commit 记录，可能低优先级或已放弃
合计	27	13 + 3 + 11 = 27，恰好等于总数

数字很整齐，但整齐得可疑。回头核对审计报告原文，两处计数错误藏在里面：

• “3 个手工实现”下面列了 4 个文件名——TASK-aq-mobile-menu-v2.md 和 TASK-aq-mobile-menu.md 是两个文件，却按 3 个任务计数；
• “11 个待确认”下面只列了 10 个名字，多出的那 1 个没有对应文件。

报告数值为 13+3+11=27，而实测数量为 13+4+10=27——两处计数错误方向相反、恰好相互抵消，导致总数依然闭合，从而掩盖了分类错误。审计报告自己也是一份会出错的文档——这个细节后面还会用到。

根因一：一个 commit 吞掉 9 个 TASK

展开”已完成”的 13 个文档，commit 分布是这样的：

commit	对应 TASK 数
86ce510	9
01fd162	3
43199b1	1

这不是 13 次独立交付，而是三次”清算式”大提交。积压的需求被一次性实现、一次性提交，TASK 文档的生命周期和代码的生命周期从此脱钩：文档停在”写完”那一刻，代码已经跑到前面去了。

直接后果是审计成本被放大。27 个文件、每个都要翻 git log 做关键词匹配——而这本该是每份文档头部一行 STATE: done (commit 86ce510) 元数据就能解决的事。文档没有状态字段，机器就只能当考古学家。

根因二：状态字段是”只写不更新”的单向阀

检查所有 TASK 文档，包括最新的 TASK-20260916-manage-scripts.md——这份文档写得非常规范，背景、bug 现象、修复方案、三层降级策略、验收标准一应俱全——但通篇没有 STATE 字段。

这不是个例，是模板层面就没有这个字段。写文档的时候没人约定它会以什么状态结束，读文档的人（或代理）也无法判断它是待办还是遗物。这是典型的”托付即遗忘”：委派协议要求任务下发给子代理，但下发之后没有回写状态的机制。

文档债务的本质不是文档多，而是状态缺失让存量无法被机器处理。27 个文件里只要有任何一个已废弃，它也会一直躺在根目录里，被下一次审计重新数一遍。

根因三：审计建议本身也没被执行

最有讽刺意味的一幕：09-11 审计报告的最后写着建议——“将 13 个已完成 TASK 移至 .archive/tasks-completed/“。

截至 2026-09-17 复查：.archive/ 目录存在，tasks-completed/ 子目录不存在，13 份文档原地未动。建议提出 6 天，执行数 0。同期（09-16）仓库还新增了 1 份待办 TASK 文档，存量继续上涨。

链路完整地空转了一圈：审计发现债务 → 写进报告 → 报告成为新的待办 → 待办不执行。每转一圈，仓库里就多一份”关于债务的报告”。这和第一节那个 off-by-one 遥相呼应——生产文档的机构，自己也在生产不可信的文档。

解法：三步止损

1. 状态元数据强制化。 TASK 模板头部加 STATE 字段（planned / in-progress / done / dropped），done 必须带 commit hash。写的时候顺手写，读的时候机器可判。成本一次性，收益永久。

2. 归档进流水线。 一次性人工清理在这类自动流水线维护的项目里排不上优先级——6 天执行数 0 已经在本项目被证实。正确做法是把”STATE=done 超过 N 天 → 自动移入归档目录”写成夜间巡检的一个步骤，让清理从”需要决定的动作”变成”默认发生的动作”。

3. 提交粒度对齐任务粒度。 清算式大提交（一个 commit 含 9 个 TASK）省了当下的时间，却让文档与代码的映射永远对不上。委派协议里明确：完成一个 TASK 提交一次，commit message 必须引用 TASK 文件名。

结论

13 vs 11 的失衡不是管理失误，而是机制缺失的必然结果：状态字段缺失 + 归档不自动化 + 提交粒度失配，三个条件同时成立时，TASK 文档驱动的项目很容易收敛到同一个稳态——一半是遗物，一半是谜。

AI Agent 流水线越自动，越需要把文档状态当成一等公民。原因很直接：没有人会去读这些文档了，只有机器会。而机器读不到状态，就只能每个凌晨重新考古一遍。

---

数据来源：AutoQuant 夜间巡检报告（2026-09-11 02:30，含 27 文件分类与 commit 映射表）；归档状态与文件数为 2026-09-17 仓库实盘复查。