如何沉淀 Agent 每次的踩坑经验

Agent 编程最大的浪费，是同一个坑反复踩。我把经验沉淀做成了一套三层漏斗体系，核心思路是：把"记住教训"从 agent 的自觉，变成基础设施。

阶段一：规则驱动，强制捕获（源头）

我在 TRAE 规则里定了两条硬约束：

说"结束"触发总结：每次项目收尾，agent 必须把踩坑和解决方案写成 md 文档，不允许凭记忆聊天
usercontext 持久化：对话中的用户消息落盘，保住原始语境

效果：经验不再是聊天记录里的一次性文字，而是项目内的文件资产。

CharacterSeed 沉淀出 15 篇 dev_lessons，命名规范 日期_主题.md（如 2026-07-07_complex_event_enrich_timeout.md），每篇固定结构：

核心问题 → 根因 → 解决方案 → 踩坑清单 → 可泛化经验 → 适用场景

关键点：捕获是强制的、不靠自觉。 这解决了"事后想总结却忘了细节"的最大痛点。

阶段二：蒸馏整合，跨项目复用

原始文档的问题：散在各项目里、带业务细节、agent 换项目就看不到了。于是我们把 22 篇原始文档蒸馏成全局技能 dev-lessons：

~\.agents\skills\dev-lessons\     ← TRAE 每次会话自动加载，跨项目生效
├── SKILL.md          场景路由表 + 十条元原则 + 进化协议
└── references\       6 个领域文档（LLM/前后端异步/DB/上游复用/部署/协作测试），25 张经验卡

蒸馏时做了三件事：

去业务化：剥掉 CharacterSeed 具体情节，只留通用规律和代码骨架
场景标注：每条经验带 #LLM #异步 #DB迁移 标签，SKILL.md 有"你正在做什么 → 先读哪篇"路由表
保留溯源：每条带 溯源 字段指回原始文档，需要完整上下文随时可回查

阶段三：进化协议，防止腐烂

资产最大的敌人是过时。所以在 SKILL.md 里内置了维护规则：

项目"结束"时按 lesson card 模板（场景/问题/根因/方案/反模式/溯源）追加新卡
同一问题出现第三次 → 自动提升为元原则
元原则上限 15 条，超了强制合并，防止膨胀
新经验若推翻旧原则，直接修订并注明日期

资产结构

dev-lessons\
├── SKILL.md                    主索引：场景路由表 + 十条元原则 + 进化协议
└── references\
    ├── llm-app.md              LLM 应用（7条）：锚点结构化、多样性双层修复、超时预算、救援通道…
    ├── frontend-backend.md     前后端异步（6条）：占位建模、override写回DB、乐观更新、stale保护…
    ├── data-db.md              数据库迁移（3条）：SQLite WAL、幂等、半截路检查…
    ├── upstream-reuse.md       上游复用（2条）：importlib shim 四步标准法…
    ├── deploy-env.md           部署环境（4条）：Vite缓存、MOCK残留、优雅降级、SSH转义…
    └── collab-testing.md       协作测试（3条）：PR四步法、CI变量劫持、断言坑…

这套体系的本质

三层漏斗：规则强制捕获（项目级原始档）→ 定期蒸馏（全局技能）→ 协议化进化（活性维护）。

最妙的设计是把"记住教训"从 agent 的自觉变成了基础设施——规则管捕获、技能管复用、协议管更新。

你不需要记得"上次踩过什么坑"，因为下次遇到 LLM 超时静默降级、乐观更新吞占位符这类问题时，dev-lessons 会自动出现在技能列表里提醒我先查旧账。

原始文档仍在各项目内作为详细档案。今后在任何一个项目里说"结束"做总结时，新踩坑会按模板追加进对应领域文档。