把AI开发中的纠错与遗留问题变成项目资产

AI 编程里最容易丢掉的，往往是任务之外的发现：顺手撞见的 bug、临时绕过的限制，以及反复纠正过的工作习惯。作者独自用 Claude Code 开发印度点对点停车交易平台 ParkEase，给这些信息安排了五种去处，再用 hook 拦住没有完成记录的任务。

他的结论是：开发后半程更顺，不一定靠换模型，也可以靠项目持续积累经验。这套做法值得看，但记录数量能证明执行过，不能直接证明效率提升了多少。

哪些东西该留下，为什么不能全塞进一个文件

作者按信息用途分了五类。

learnings.md 收的是花过时间才解决的问题，共 246 条，每次任务开始前读取。它要解决的是重复踩坑：上次查清的原因，下次不必重新排查。

suggestedtask.md 收的是发现了、但有意不在当前任务处理的问题。每条写清发现位置、推迟原因，以及怎样才算完成，最终积累了 162 条。后续哪个任务自然涉及对应代码，就顺便批量关闭相关记录。

控制当前改动的范围，不等于可以丢掉范围之外的发现。

代码里的 ponytail: 注释负责标记主动做出的妥协，同时写清当前方案的能力上限和升级路径。作者的思路很直接：能搜索出来的技术债，至少不会藏在实现里等人重新发现。

结构性选择则进入决策记录，共 34 份。工具或 skill 的建议与已有决策冲突时，以决策为准，agent 还必须说明冲突；如果要改变决策，就书面修订，不能悄悄换方向。

最后一类是 Claude Code 的项目记忆，记录对 AI 工作方式的纠正，并附上原因。它和问题清单的区别是：前者告诉 agent 应该怎么做，后者告诉后来的人还有什么没做。

hook 真正检查的，是有没有写下来

作者列出的行为纠正很有代表性。

一次，agent 使用地图库时连续猜错四个 prop 名称，却没有先读类型定义，于是留下「先研究再动手」的规则。另一次，它把 Security: raw-body HMAC, amount re-fetched 写进检查清单，就声称完成了审查。但描述代码里存在什么，并不能证明审查实际执行过。

还有一次，单个任务调度了约 40 个 reviewer agents，吃掉一周用量限额的大部分，作者因此补上「Token 预算优先于仪式」的约束。项目中共有 12 条这类行为纠正。作者称，每种错误都只发生了一次。

光有记录约定还不够。他设置了一个在 agent 尝试结束任务时运行的 hook，也就是自动执行的检查脚本：

• 如果任务涉及三个或更多文件编辑，而经验、测试用例或决策文件都没有更新，就不允许结束。
• 检查依据是文件修改时间，口头表示「会记录」不算完成。
• 最终回复若出现 this is a pre-existing issue、skipping tests for now、tests are failing but I'll fix them later 这类表述，也会触发阻断。

这里有个边界：原文明确列出的文件检查对象，并没有覆盖前面全部五类信息。脚本源码、路径匹配和例外处理也没给出，不能据此认定整个知识沉淀流程都已自动闭环。

我的判断

我认同这套分类，尤其是把「当前不处理」变成一条有位置、有原因、有完成标准的记录。相较于把发现埋进聊天记录，它更容易被后续任务接住。正式团队也可以用现有 issue 系统承接，不必照搬 Markdown 文件名。

但作者说，第一周需要一小时才能解决的坑，到第四周只需读四秒；项目后半程也明显更顺。这些都是作者的经验描述，原文没有对照数据，也没有排除开发者熟悉代码后自然提速的影响。「每种行为错误只犯一次」同样缺少独立验证。

hook 的检查方式也有局限。修改时间能证明文件动过，不能证明记录有用；三个文件的阈值可能漏掉单文件里的复杂改动。按措辞阻断还能误伤合理说明，例如如实报告已有测试故障。

强制留下记录有价值，记录质量仍需要判断。

246 条经验每次都读，也会占用上下文与用量预算。一般团队借鉴时，除了收集，还要考虑去重、淘汰过期规则，以及怎样找到当前任务真正相关的内容。

能拿来做什么

• 在日常 AI 编程任务里，为范围之外的发现固定记录位置，要求写明文件位置、延期原因和完成标准，避免只在最终回复中提一句。
• 使用陌生前端组件或地图库时，让 agent 先检查类型定义；如果出现反复猜 API 的行为，把纠正原因写进项目规则。
• 给临时方案加上可搜索的 ponytail: 标记，并写清能力上限与替换条件，让后续维护者知道什么时候必须升级。
• 引入结束任务的 hook 时，可以先借鉴作者的三个文件阈值，再根据实际误报调整；检查记录是否存在之外，也要抽查内容是否足以帮助下一次任务。