接手没文档的老项目,我让TRAE从零补起

系列：TRAE 从入门到应用 · 第 16 篇

顺序很关键。倒着来——先让它给每个函数加注释——你会得到八百条废话，而且代码一改就过期。先出地图，再挑着写。

存量项目最容易翻车的地方在这。@Folder 依赖项目代码索引，索引没建完，AI 拿到的项目上下文是残缺的——你问“这个模块干什么”，它答得像模像样，其实漏了三分之一文件。

去 设置 > 索引与文档 > 工作区，打开“启动自动化索引”。然后先把该排除的排除掉，不然索引里会混进一堆垃圾。在“忽略文件”处点编辑，TRAE 会在 .trae/ 下自动创建 .ignore：

**/dist**/node_modules*.log**/.env***/legacy-v1

两个注意点：.gitignore 里的内容默认就忽略；改完 .ignore 必须回索引面板点一次 Build 重建，否则新规则不生效。这步我漏过一次，它把 dist 里的编译产物当源码分析，写出来的文档全是混淆后的变量名。

这一轮的关键在“禁止”上：

@Folder src读这个目录下所有代码，只输出一张 Markdown 表格，四列：目录/文件、职责一句话、被谁依赖、可疑处。规则：1. 不要写任何解释性段落，不要"概述""总结"章节2. 职责必须具体到"输入什么、输出什么、副作用是什么"，   禁止出现"处理数据""相关逻辑"3. 不确定的放"可疑处"列，标"未确认"，不要猜

四列表格比三段概述有用得多。“被谁依赖”这列是白捡的架构图；“可疑处”这列会把它自己没读懂的地方标出来——比硬编一段解释诚实。

产出存成 docs/codemap.md，然后人工抽三个模块核对。我抽的三个里错了一个（把定时任务入口当成了普通工具函数），这个错误率可以接受，比从零读八百个文件快得多。

配图由AI生成，仅作示意参考

它默认写“通用技术文档腔”，放你项目里就是不搭。设置 > 索引与文档 > 文档集 > 添加文档集 能治这个，两种加法限制不同：

- URL：以入口为起点，只抓同级路径或子路径下、最多三次跳转内的页面；不跨 Host，也不能高于入口路径（example.com/docs/api 抓不到 example.com/）

- 本地文件：只吃 .md 和 .txt，单文件 ≤10MB，整个文档集 ≤50MB，文件数 ≤1000

我把自己前几个项目的 README 和一份内部接口规范打包传进去，用 @Doc 引用，指令里补一句“参照已有写法：二级标题用动宾短语、命令块必须可直接复制、不写'本文将介绍'这类开场”。风格立刻从“通用 AI 腔”变成“我们组的腔”。

存量项目 README 的验收标准只有一条：新人照做能跑起来，不用问人。

读者：第一次接触这个项目的前端，Node 20，会 npm 但不懂业务。必须能完成：克隆→装依赖→配环境变量→起服务→看到登录页。禁止：① 任何"根据实际情况配置"这类模糊表述     ② 真实密钥、内网地址     ③ 未经验证的命令要求：命令全部用代码块可直接复制；环境变量列成表格，     写用途和示例值（假值）

“未经验证的命令”这句很关键。它会从记忆里翻出老命令写上去，比如 npm run dev:all——你项目里根本没这个 script。我这份里就有一条 cp .env.example .env 是错的，实际用的是 .env.local。

注释最容易写成噪音。规则文件可以按文件类型生效，正好治这个：.trae/rules/ 下建 comment.md，生效方式选“指定文件生效”，globs 填 src//.ts,src//.tsx。

---alwaysApply: falseglobs: src/**/*.ts,src/**/*.tsx---## 注释规范- 只写"为什么"，不写"是什么"；函数名说清的不写注释- 所有 export 的函数/类必须有 JSDoc：@param 写取值范围  和单位，@returns 写失败时返回什么- 业务魔数必须注明来源，如 // 网关限 200 QPS，见 OPS-1421- 禁止：// 定义变量  // 循环遍历  // TODO（除同步开 issue）

globs 多模式用英文逗号分隔，规则目录支持 3 层嵌套，大项目按模块拆开别全压一个文件。

一个反直觉的点：规则写好后建议新开对话。官方最佳实践里明确提过，历史上下文会和新规则打架；而且存量代码本身就是“坏样例”，模型容易照着旧风格写。

文档最容易死在“写完不管”。update-docs 这个技能的思路值得抄：它维护两份参考文件——CODE-TO-DOCS-MAPPING.md（代码文件→该更新哪个文档）和 DOC-CONVENTIONS.md（文档规范），改代码时用 git diff 找出受影响的文档，只改那几段。

说实话，这技能是 vercel 写给 Next.js 仓库自己的，直接装用不上——映射表全指向 Next.js 的 docs 结构。但结构可以照搬，自己写一份，三十行就够：

| 代码变更 | 需要更新的文档 || src/api/** | docs/api.md 对应接口小节 || src/config/** | README 环境变量表 || src/core/queue/** | docs/architecture.md 消息流 |

装的位置有讲究：跨项目复用放全局 %userprofile%/.trae-cn/skills/（macOS 是 ~/.trae-cn/skills），单项目放 .trae/skills/。若技能来自 Agent Skills 生态（.agents/skills/），要在 设置 > 技能与命令 > 导入设置 打开“启用 .agents 技能目录”，同名时优先 .trae/skills/。

配图由AI生成，仅作示意参考

以上是“补存量”。如果你在 SOLO 模式里从需求开始做，工具面板有独立的「文档」工具（Windows Ctrl+Alt+/，macOS option+command+/），它展示产品需求文档、技术架构文档的生成过程与初稿，支持 Markdown，能手动改，也能选中一段丢回对话重写。

区别是：SOLO 的文档工具“边做边写”，产出跟着任务走；补存量只能靠读代码反推。

顺带一句：内置四个技能是 security-review、generate-mini-app、debugger、code-review——没有文档生成技能，docs.trae.cn/ide/documentation 也是 404。文档这件事得自己配：规则管风格、技能管流程、文档集管语气。

快废弃的项目。三个月后下线的系统，补文档收益是负的——花两天写一份没人看、还要跟着代码一起进坟墓的东西。让它写五百字交接备忘就够。

要过合规审计的对外 API 文档。它会漏错误码全集，会自己编一个“建议重试”策略。这类文档每一行都要有责任人。

架构决策记录（ADR）。“当初为什么选这个队列而不是那个”，代码里没有答案，它只能编。这种只能问人。

1. 别让它把密钥写进文档。补 README 时它会“贴心地”从 .env 读出现有配置做示例。指令里写死“示例值一律假值”，.ignore 排除 .env*。

2. 索引没重建就 @Folder。改了 .ignore 要点 Build，漏了它分析的是编译产物。

3. 一次让它写全仓库。八百个文件塞一次任务，后半段质量断崖下跌还会重复段落。按模块切开，一个模块一次。

4. 注释写完不管。注释比文档更容易腐坏，因为它贴着代码，读的人默认它是对的。

5. 让它“润色”README。它会顺手删掉“这里有个坑”“不要用 xxx”，因为读起来不优雅——而这些恰恰最值钱。指令里明确写“保留所有以【坑】开头的段落，一个字都不许动”。

最后一句实话：补文档，AI 替你省的是读代码的时间，不是判断该写什么的时间。前者几十小时，后者半小时——但这半小时省不掉，省了就得到四十页废话。

点赞+在看，下期TRAE不迷路。

下期预告：第17篇，把 TRAE 当脚本工程师——一次性的数据清洗、批量改名、日志分析，这类“写完就扔”的脚本它比人快在哪，又会在哪埋雷。