用踩坑记录减少 AI 编程重复试错

AI 编程最让人头疼的一种浪费，是同一个坑要填好几遍。作者在 ParkEase 项目里给 Claude Code 配了一份 learnings.md，把费时间才找到的修复办法留给下一次会话。项目结束时，这份文件积累了 246 条记录、1,550 行内容。

这套方法的价值不在于让模型真的拥有记忆，而是让它开工前能查到项目踩过的坑。对于经常遇到依赖冲突、开发环境异常和工具副作用的程序员，它提供了一种成本很低的经验复用办法。不过，作者对节省时间的描述，还需要和实测数据分开看。

什么经验值得写进 learnings.md

作者描述的循环很熟悉：周一，Agent 为一个异常尝试六种办法，终于修好；周四换个会话，又按相同顺序试一遍。先前的排查过程没有进入新会话，它就得重新探索。

ParkEase 是作者独自用 Claude Code 构建的印度点对点停车交易平台。他在项目指令文件的第一条要求里写明：每次任务开始前，先读 learnings.md。

但这份文件不负责介绍系统架构。它只收录一种内容：那些不容易猜到、确实花过时间才找到的修复经验。

每条记录用标题直接给出教训，再写症状、原因和修复办法。原文里的几个例子很有代表性：

• workspace 包必须对齐 React 版本。版本不同时，pnpm 会把较新的版本提升到根目录，依赖旧版本的包又在自己的 node_modules 中保留副本，最终可能因两个 React 实例导致运行时崩溃。
• Metro 开发服务器在反复 reload 后可能退化。作者遇到的表现是：导航几次之后，所有路由都只渲染空根节点，控制台没有任何错误。
• 用 pip install --user 安装开发工具，把 47 个包放进共享的用户 site-packages，遮蔽了三个库的系统副本，连带弄坏了三个无关工具。
• 工具安装器可能修改 Agent 的上下文文件。有一次安装器改写了根目录 CLAUDE.md，创建了第二份上下文文件，注册两个 hooks，还修改了 .gitattributes。

Metro 那条尤其有用：看到白屏时，Agent 很容易开始修改业务代码；记录下这种环境故障，至少能让它先检查开发服务器。

文件长到 1,550 行，怎样避免变成噪声

作者给了四个维护习惯，核心都是让经验在排查现场更容易被找到。

第一，标题写教训，不写分类。只写「Metro」，读者仍不知道要防什么；写清「反复 reload 后开发服务器会退化，看起来像应用坏了」，标题本身就能指导排查。

第二，记录使用者实际看到的症状。「空根节点、控制台零错误」比原因更适合搜索，因为排查开始时，人通常还不知道原因。

第三，按涉及的技术范围分组，包括 pnpm、TypeScript、NestJS、Expo、测试、迁移，以及 Agent 执行环境。Agent 可以读取与当前任务有关的章节。

第四，当场写。作者还通过 hook 强制执行：复杂任务如果完全没有更新 learnings 文件，就不允许结束。具体 hook 实现在系列第 12 篇，当前原文没有展开。

作者还建议，只要某个问题耗时超过 15 分钟，就补一条记录。这样收集的是已经付过排查成本的经验，维护动作也有了明确触发点。

我的判断

我认可它对经验类型的限制。README 负责上手，架构记录负责解释设计，learnings.md 负责保存「这个项目里容易误判的地方」。职责清楚，文件才有机会长期保持可用。

它也比不断扩充全局提示词更适合存放具体故障：经验留在项目里，按技术范围组织，需要时读取。但「每次任务前读文件」和「只读相关章节」如何衔接，原文没有交代；246 条记录以后如何检索、清理和失效，也没有说明。

作者称，一条记录能把 40 分钟排查变成 4 秒阅读，在五周开发里累计省下数天。**这些数字是作者的经验描述，原文没有提供计时记录或对照实验。**可以据此理解收益方向，不能拿来预测自己团队的提效比例。

强制复杂任务更新文件，也有前提。不是每个复杂任务都会产生新经验，机械执行可能催生重复条目。一般团队还需要审核过时记录，尤其是 React、pnpm、Metro 等工具升级之后。

原文提到的另一条经验很有价值：调用关系图能说明谁调用谁，却不能说明哪些操作被允许。外部记录既能帮助修 bug，也能提醒 Agent 别把技术关系误当成操作权限。

能拿来做什么

• 在项目里建立 learnings.md，并在 Agent 指令文件中要求任务开始前读取；先按依赖、开发服务器、测试和迁移等范围分组。
• 下次排查 React 多实例或 Metro 无报错白屏时，把实际症状、确认过的原因和有效修复一起记下，标题直接写结论。
• 安装会接入 Agent 的开发工具后，检查 CLAUDE.md、hooks 和 .gitattributes 的 diff，把确认过的副作用留档。
• 用「排查超过 15 分钟」作为记录起点，先检查条目能否帮助下一次定位，再决定是否增加强制 hook。