用 TRAE Work 把项目踩坑经验沉淀成「团队可复用工程规范」，新人再也不重复掉坑
一、痛点：经验都在脑子里，文档永远滞后
我负责一个 CMS 项目（NestJS + Vue3 + TS + Pinia + Handlebars 模板引擎），迭代半年下来，踩过的坑能拉一车：
- 图片上传后压缩水印顺序搞错，水印位置跟着原图尺寸跑偏；
- 拖拽区块时浏览器默认幽灵和自定义幽灵同时出现，画面"双影"；
- 主题模板改了
.hbs文件，浏览器刷爆也不生效，因为模板引擎有内存缓存； - 前端直接读
user.roleIds拿不到角色，后端实际存在userRoles里； - API 路径拼接重复，
/api/public/api/public/...这种事故出现过两次......
这些经验原本散落在三处：聊天记录里一段段、代码注释里一句句、还有更多只存在我脑子里。结果是：
- 新人接手必踩同款坑，我反复口头提醒，效率极低；
- 自己隔一个月也忘，回头修类似功能又重新踩一遍；
- 规范文档永远滞后，写一次就过时，没人维护。
尝试过手写规范，但"从脑子里掏经验"这件事本身就很反人性------你很难凭空回想"这个模块到底有哪些坑"，写着写着就变成流水账。
二、实操过程：让 TRAE Work 帮我把经验"榨"出来
第一步：让 TRAE Work 先读懂项目上下文
我没有一上来就让它"写规范"，而是先让它建立项目认知。指令大致是：
bash
这是一个 CMS 项目，技术栈 NestJS + Vue3 + TS + Pinia + Handlebars。
请先浏览项目结构，重点看 apps/admin（后台前端）、server（NestJS后端）、
themes（主题模板）三个目录，理解整体架构后告诉我你的理解。
这一步很关键。直接问"有哪些坑"，AI 只能瞎猜；先让它读懂项目，后续提取的经验才贴合真实代码。
第二步：从「记忆 + 代码」双向提取经验
我让 TRAE Work 同时看两个信息源：一是项目的 memory 文件（里面记着历次会话沉淀的 lessons learned），二是真实代码实现。指令：
diff
请读取项目的 memory 文件（project_memory.md），同时检索代码中带
TODO/FIXME/注释的"避坑提示"，把所有"曾经踩过的坑 + 最终解法"
提取出来，按模块分类，每条格式：
- 问题现象
- 根因
- 正确做法
- 模块归属（HTTP/路由/模板/拖拽/图片/用户/状态...）
这一步让我意外的是，它从代码注释里挖出了几条我自己都忘了的坑------比如 cleanUndefined 工具函数旁边的注释，提醒"更新用户时不能带 username 字段"。
第三步：去重 + 补"为什么"
原始经验列表有重复（比如"模板缓存"和"服务端重启"其实是同一件事），也有只写"怎么做"没写"为什么"的。我让 TRAE Work 做二次加工：
markdown
请对上面列表做三件事：
1. 合并重复项（同一根因的合并为一条）
2. 每条补一句"为什么"，解释根因背后的机制
3. 标注"影响范围"（仅前端/仅后端/全栈）
补"为什么"这步特别重要。规范如果只写"必须用 buildUrl() 拼接 URL"，新人会记不住；但补一句"因为后端存的 API 地址可能已含完整路径，直接拼接会导致路径重复"，新人就理解了，以后遇到类似场景还能举一反三。
第四步：生成可维护的规范文档
最后一步，让 TRAE Work 按模块输出结构化文档，并加上"如何更新本文档"的说明：
diff
把最终规范整理成 Markdown，结构：
- 按模块分章（HTTP请求/路由注册/模板渲染/拖拽交互/图片处理/用户管理/状态管理）
- 每条规范编号，方便引用
- 文末加一节"如何维护本文档"，说明下次踩坑后如何追加条目
三、落地成果
最终产出一份 7 个模块、40+ 条规范 的工程文档，每条都带「现象 + 根因 + 做法 + 为什么 + 影响范围」。举两条例子：
HTTP-03 GET 请求必须加
cache: 'no-cache'
现象：列表页数据更新后前端不刷新
根因：浏览器对 GET 默认走强缓存
为什么：CMS 后台频繁改动数据，缓存会导致脏数据
影响范围：全栈
IMG-01 图片处理顺序固定为 resize → watermark → quality现象：水印尺寸跟着原图跑偏
根因：水印字号按图片宽度计算，若先压缩再算字号才一致
为什么：保证水印相对最终成图的比例稳定
影响范围：后端
效率提升很直观：以前新人接手我得口头讲 2 小时，还经常漏；现在丢一份文档，配合代码 review，半小时就能上手。我自己回头改老功能，也习惯先 Cmd+F 搜规范编号，避免重蹈覆辙。
四、复用经验（重点）
这套方法最大的价值不是文档本身，而是**「经验沉淀的流程」可照搬到任何项目**。总结成 4 步 SOP：
① 先建立上下文，再提取经验
不要一上来就让 AI"写规范"。先让它读懂项目结构、技术栈、目录职责，提取出的经验才会贴合真实代码，而不是通用废话。
② 双源提取：记忆 + 代码
经验不要只从一个地方挖。让 AI 同时看：会话记忆（踩坑时的上下文最完整）+ 代码注释（最接近真相的一手记录）。两个源交叉验证，能发现单看一边会漏的坑。
③ 补"为什么"比补"怎么做"更重要
规范最常见的失败是"只规定动作，不解释原因"。新人记不住规则，但能记住原理。让 AI 给每条规范补一句根因说明，规范的"可复用性"会大幅提升。
④ 文档要带"自我维护"说明
静态文档一定会过时。在文末加一节"如何维护本文档"，约定每次踩坑后用固定格式追加条目，让文档能跟着项目一起长。
通用指令模板
把上面的流程浓缩成一条可复用指令，换项目时改下技术栈就能用：
markdown
你是项目经验沉淀助手。请按以下步骤帮我生成工程规范：
1. 浏览项目结构，理解技术栈与目录职责
2. 读取 memory 文件 + 检索代码中的 TODO/FIXME/避坑注释
3. 按「现象/根因/做法/为什么/影响范围」提取并分类
4. 合并重复项，补全缺失的"为什么"
5. 输出按模块分章的 Markdown，文末附"如何维护本文档"五、总结
开发过程中最值钱的不是代码，是踩坑后沉淀的经验。但经验一旦只存在脑子里，就等于没有------会忘、会漏、没法传承。
用 TRAE Work 把"从脑子里掏经验"这件反人类的事，变成"AI 帮你从记忆和代码里榨经验"，半小时就能产出一份团队可复用的规范文档。这套方法不挑项目、不挑技术栈，任何团队都能照搬。
经验的终点不是"我踩过"，而是"大家都不用再踩"。