使用TRAE CN 接手前后端项目

0 阅读25分钟

这是让WorkBuddy生成的,按照它说的操作可行吗?有没有大神帮忙看看~~~

适用:Vue 3 前端 + Java 后端(新老栈混合)的存量项目接手。

一、先看结论:接手存量项目的三条原则

1. 前后端同一个项目根,但流程隔离、显式声明

前后端放在同一个项目根打开,AI 能拿到完整上下文,跨端读代码和定位问题的成本大幅下降,端到端调用链一次能跟完。代价是边界消失后,AI 容易"顺手跨端改"。

因此采用同一项目根 + 流程隔离 + 显式声明:目录合在一起,改动流程按端分开。改后端前必须单独告知并确认,前后端改动分开提交。TRAE 规则是自然语言软约束,没有文件级权限控制能力,隔离靠规则约束 + 人工确认,不靠工具强制。

2. 主力是 Chat 只读分析和 Rules 沉淀,不是 SOLO 一把梭

SOLO 适合从零原型;存量业务喂给它,容易写出"看着对、跑起来炸"的代码,且 debug 时会越改越乱。

接手期以 Chat 读码、定位、review 为主,把项目约定沉淀到 Rules,再按改动风险选择一轮、两轮或四轮流程。

3. 把"读 diff 当验收"换成"跑行为"

看不懂的 diff 等于没看,硬着头皮扫一遍更危险——会产生"我检查过了"的错觉。这里说的是把 diff 当正确性依据;动手后看 diff 用于核对"改了哪些文件、哪些行",这一步仍然不能省。

验收应以"输入 → 预期输出"清单、自动化测试和改前改后行为对比为主。人工只重点盯权限、事务、SQL、公共组件等高风险改动。

整体顺序是:

开工准备 → 配置 AI 规则 → 只读识栈 → 本地跑通 → 按风险改代码 → 行为验收 → 逐步接完整需求。

本地跑通一条完整业务链路之前,不改任何业务代码(写规则文件、文档、本地启动配置属于开工准备,不在此列)。

二、开工前 30 分钟

  1. 拿齐 5 样东西:仓库权限、业务文档、测试环境地址、数据库只读账号、接口文档地址。缺什么记下来,不要让 AI 猜。只读账号够识栈和读链路;完整链路若含写操作,单独申请测试库写账号并登记,不用生产库。
  2. TRAE CN 首次启动时导入 VS Code 配置,语言选中文。
  3. 前后端代码放同一项目根打开,从一个项目根拿到完整上下文;目录仍按 frontend/ / backend/ 分开,通过项目规则落实按端隔离和显式声明。
  4. 从干净分支起步,git status 必须干净。
  5. 配置全局规则和项目规则:以本机已有全局规则为准,只补缺项;项目级 00-collab.md 只放需要随 Git 共享的边界和流程,不重复全局已有条款(唯一例外见 3.2)。

三、配置 AI 助手:全局管通用,项目管边界

目标是让规则随项目走、可随 Git 共享。全局规则只在本机生效、不随 Git 走,项目级规则才可共享。前后端同一项目根时,规则按端分开,这是"流程隔离"的具体落点。

3.1 项目文件结构

官方有两类能力,别混为一谈:

  • 子目录规则:项目任意子目录下的 .trae/rules/ 都会被读取,当对话提及该目录下的文件、或 AI 读取该目录下文件时,自动携带该目录专属规则。前后端各放一份,正好用于按端隔离。
  • 规则多层嵌套:.trae/rules/ 目录内可建子文件夹归类,系统递归读取,目前最多支持 3 层嵌套。这 3 层说的是 .trae/rules/ 内部的目录深度,不是子目录规则的层级限制。
 project-root/
 ├── AGENTS.md                       # 项目入口,跨工具约定
 ├── doc/
 │   ├── ONBOARDING.md               # 识栈产出,前后端各一节 + 端到端一节
 │   └── LOCAL_SETUP.md              # 本地启动记录
 ├── frontend/
 │   └── .trae/rules/vue3.md         # 子目录规则,按目录自动携带
 ├── backend/
 │   └── .trae/rules/java.md         # 子目录规则,按目录自动携带
 └── .trae/
     ├── rules/
     │   ├── 00-collab.md            # 协作契约,alwaysApply
     │   └── 90-commit.md            # commit 规范,scene: git_message
     └── mcp.json                    # 项目级 MCP,按需加

规则内容要短、具体、互相不冲突。同一条规则不要在全局和项目里重复写:规则是全量注入上下文的,冲突时模型会混乱,官方明确要求"各条规则之间不得彼此冲突或相互覆盖"。官方给出的优先级是 用户输入 > 自定义 Agent 提示词 > 全局规则(user_rules)> 项目规则(.trae/rules)≈ AGENTS.md——全局优先于项目,别指望项目级规则能覆盖全局规则。改完规则开新对话,旧上下文会和新规则打架。

另:所有规则(含 AGENTS.md、CLAUDE.md、CLAUDE.local.md)总大小不得超过 32K 字节;TRAE 只加载可信目录中的项目规则,规则没生效先检查目录信任。

3.2 全局规则与项目规则的分工

全局规则放:

 ~/.trae-cn/user_rules/rule-*.md

这是目录,里面按时间戳存多个 Markdown 文件;国际版路径为 ~/.trae/user_rules。本机实有 rule-1794273043224.md。

先检查已有规则,别重复写,更不要用下面的示例整体覆盖本机文件。 "改动前出计划等确认""不确定就标注不要猜""全程中文"若全局已有,项目级就不要再写一遍。

全局规则只放跨项目通用的内容,例如:

 全程中文回复。

以下是一份参考示例(不是待覆盖的目标;本机已有条款以本机为准,只补缺项):

 # 通用开发范式(全局生效)
 1. 界面文案:避免多余二级标签与描述,依靠布局表达含义。
 2. Bug修复:从根源定位问题,在现有项目规范内修复,禁止只修补表象、禁止顺手重构。
 3. 代码:后端业务逻辑,正常业务空结果(查询无数据)做正常返回;业务校验失败、不可预期异常直接抛出,交由全局异常处理器转错误码。后端业务代码不写冗余判空兜底,但前端展示层对接口返回的 null/undefined 必须做必要保护,不在此列。
 4. 交互流程:涉及流程改动、多文件改动、需求变更,先输出改造计划确认;单行简单 bug 修复可直接实现(以本机全局规则为准,本机若要求所有改动先出计划,按全局执行)。
 5. 问答输出:常规问题简短精炼;复杂代码、多步骤改造,保留必要注释和说明。
 ​
 # 业务约束
 严格遵循项目规范,禁止自行新增字段、自创逻辑、脑补业务规则;
 不允许发散、不做额外优化;
 只输出符合规范的代码;
 遇到不确定字段直接标注,不要猜测。

示例里不写任何"最高优先级"字样。优先级由官方层级决定,正文里自称"最高优先级"不改变实际生效顺序,只会制造冲突。

以下内容若全局已有就别重复写,全局没有的放项目级 00-collab.md:

  • 禁止 git push、部署、删改数据,禁止连接生产库。
  • 不粘贴密钥、真实用户数据和生产库连接信息到代码、日志或对话。
  • 改后端代码前必须单独告知并获得确认。
  • 前端遇到接口问题,默认只读后端代码核对接口契约。
  • 前后端改动分开 commit,一个提交里不许同时出现前端文件和后端文件。

唯一允许的有意重复:安全红线和前后端隔离这类必须随 Git 共享给全员的条款,项目级保留一份兜底,免得别人 clone 项目后只依赖自己本机的全局规则。但重复内容必须逐字一致——不能全局写"禁止"、项目里写"例外可合并",那正是模型最容易被搞乱的情况。本机全局规则已包含上面 5 条且没有例外,项目级逐字照抄(含上面这句原文),不要自行加例外或放宽。

原因是全局规则对所有项目生效,纯前端或纯后端项目用不到前后端隔离;但已存在于全局的条款不必也不该搬到项目级重复一遍(除上述共享兜底外)。

3.3 规则文件的生效方式

方式配置本项目落点
Always ApplyalwaysApply: true00-collab.md:协作契约,项目内所有对话生效
Apply to Specific Filesglobs + alwaysApply: false前后端规则:收窄到各自目录的文件类型;子目录规则本身按目录自动携带
Apply Intelligentlydescription按场景由 AI 判断
Apply Manually@Rule 引用手动触发,引用方式中优先级最高
commit 场景scene: git_message90-commit.md:AI 生成提交信息文本时遵守

scene: git_message 只约束生成的提交信息文本,管不到哪些文件被暂存、也管不到提交动作。涉及"提交什么"的约束必须放 00-collab.md,放这里等于没写。

3.4 四个规则文件的完整内容

1. .trae/rules/00-collab.md
 ---
 description: 项目协作契约,项目内所有对话生效
 alwaysApply: true
 ---
 ​
 # 协作契约(遵循全局规则,只写项目特有约束)
 ​
 ## 沟通与改动流程
 1. 遵循全局规则的改动审批流程;全局已有「先出计划等确认」的,这里不重复。
 2. 项目补充:仅当全局规则允许「单行简单 bug 可直接改」时,本项目的单行简单 bug 沿用该豁免;全局要求所有改动先出计划的,一律先出「文件清单 + 每处改法 + 风险点」等我确认。
 3. 不熟的代码先只读一轮:说明这段逻辑做什么、谁调用,再动手。
 4. 一个任务一个对话、一个分支,不塞多个需求。
 5. 语言、输出格式遵循全局规则,本项目不另设。
 ​
 ## 安全红线
 1. 禁止 git push、部署、删改数据;禁止连接生产库。
 2. 不把密钥、真实用户数据、生产库连接信息写进代码、日志或对话。
 3. 看不懂 / 没测试 / 动了数据,任一命中就不许提交。
 ​
 ## 前后端隔离(同一项目根 ≠ 可跨端改)
 1. 改后端文件(Controller / Service / Mapper / SQL / 配置)前,必须单独告知我并获得确认;不许在"修前端接口问题"时顺手改后端。
 2. 前端遇到接口问题,默认只读后端代码核对契约;只读不算改动。
 3. 前后端改动分开 commit,一个提交里不许同时出现前端文件和后端文件。
 4. 一次任务涉及两端时,分两次提交,两端各走一遍各自的验收流程。
 ​
 ## 验收
 1. 验收靠行为,不靠 AI 自评;按「输入 → 预期输出」清单跑一遍,不靠肉眼扫 diff 判断正确性。
 2. 方案阶段必须输出验收清单;本地跑通一条完整业务链路之前不改业务代码。
 3. 存量代码风格不代表规范,本任务按本套规则执行。

最后一条必须保留,否则 AI 会照着老代码的坏习惯写。第 3 节与本机全局规则逐字一致、没有例外;90-commit.md 和第九章红线也按同一口径写,别只改一处。

2. .trae/rules/90-commit.md
 ---
 description: 生成 git commit message 时遵守
 scene: git_message
 ---
 ​
 # Commit 规范
 1. 格式:`类型(范围): 简短描述`,例:`fix(订单): 修正退款金额计算`。
 2. 类型限 feat / fix / docs / refactor / test / chore。
 3. 描述用中文,不超过 50 字;范围写模块名,不写文件名。
 4. 提交内容是否合规(前后端分开)由 `00-collab.md` 约束,本规则只管 message 文本。
 5. 只生成 message 文本,git commit / push 命令由人执行。
3. frontend/.trae/rules/vue3.md
 ---
 description: Vue 3 前端代码规范,读取 frontend 目录文件时携带
 alwaysApply: false
 globs: "frontend/**/*.vue, frontend/**/*.ts, frontend/**/*.tsx, frontend/**/*.js, frontend/**/*.jsx"
 ---
 ​
 # Vue 3 前端规则
 1. Composition API + <script setup>,不写 Options API 新代码。
 2. 请求统一走 request 封装,不直接调 axios。
 3. 状态用 Pinia,不引入其他状态库。
 4. 字段默认直接用后端返回的字段名,不再映射一遍;确需转换集中在一处,不许散在组件里各转各的(例外见第八章)。
 5. 对接口返回的 null / undefined 必须做必要保护——这是展示层兜底,不是冗余兜底,不许删。
 6. 审查重点:
    - props / reactive 解构后响应式是否丢失
    - v-for 有没有 key,v-if 与 v-for 是否混用
    - 事件监听、定时器、watch 有没有清理
    - 字段使用是否符合第 4、5 条,null/undefined 是否兜底
    - 样式作用域是否污染(scoped 漏了、deep 滥用)
    - 路由参数变了但组件没重新拉数据
 7. 验收:按 `package.json` 实际脚本执行 build、lint;项目启用 TS 时再跑 tsc。全绿后在页面点一遍真实请求;改前截图留存,改后对比。

第 5 条不能漏。本机全局规则已写明「后端业务代码不写冗余判空兜底,前端展示层对接口返回的 null/undefined 必须做必要保护,不在此列」,这条例外已经存在,不要用 3.2 的示例整体覆盖掉它;若全局没有,则由本文件第 5 条兜底。

globs 按官方写法用逗号分隔(官方示例 *.js、src/**/*.ts),不用花括号展开——官方未承诺支持 brace expansion。子目录 .trae/rules/ 本身按目录自动携带规则,globs 只用于收窄文件类型;两套机制叠加时,以"提及/读取该目录文件"为触发前提。手写 md 文件必须显式写 alwaysApply: false,界面创建时系统才会自动设。

4. backend/.trae/rules/java.md
 ---
 description: Java 后端代码规范,读取 backend 目录文件时携带
 alwaysApply: false
 globs: "backend/**/*.java, backend/**/*.xml, backend/**/*.yml, backend/**/*.yaml, backend/**/*.properties, backend/**/*.sql"
 ---
 ​
 # Java 后端规则
 1. Controller 不写业务逻辑,只做参数校验和转发。
 2. Service 事务边界明确;统一返回体;不吞异常——业务校验失败、不可预期异常直接抛给全局异常处理器。
 3. 新老栈混合(Spring MVC/SSM + XML + Oracle / Spring Boot + MyBatis-Plus + MySQL)按所在模块原有风格做最小改动,不顺手重构、不自行新增字段、不脑补业务规则。
 4. 后端三问(用大白话回答):这次改动有没有影响已有功能?有没有改数据库数据或表结构?有没有动权限、登录、事务?
 5. 验收:按 `pom.xml` / 构建文件确认测试命令(Maven 项目通常是 `mvn test`,Gradle 项目用 `gradle test`,老项目可能没有可跑的测试,如实标注),再做改前改后请求响应对比;重点人工盯权限 / 事务 / SQL。

3.5 AGENTS.md 与其他可选配置

根目录 AGENTS.md 是跨工具 AI 入口。生效方式不是"导入文件",而是:手动把 AGENTS.md 放到项目根目录 → 设置 > 规则 > 导入设置 → 打开「将 AGENTS.md 包含在上下文中」开关(国际版界面为 Import Settings)。另外项目目录必须已设为可信,否则 TRAE 不加载其中的规则。写五块:

块内容
项目简介一句话说清做什么、给谁用
技术栈前后端框架、构建工具、JDK / Node 版本,以 pom.xml、package.json 为准
目录结构按项目实际结构画出,标清各目录职责
编码规范只列红线,细则放规则文件,避免两处冲突
常用命令启动 / 构建 / 测试命令,由 AI 读配置文件核对,不凭印象写;git diff 是人工核对改动范围的固定动作,不属于这一类

不确定的字段标 【待填】 留空,不要让 AI 猜。

其他可选项:

  • 项目级 MCP 放 .trae/mcp.json,可随 Git 共享。必要前提:先在 设置 > MCP 打开「项目级 MCP」开关并在弹窗中确认,只对可信工作区启用;只装当前用的,工具越多 token 越费。官方同时警告:工作区内项目文件必须来自可信来源。
  • 重复工作流沉淀为 .trae/skills/xxx/SKILL.md,项目级可随 Git 共享;SKILL.md 必须带 name / description 两个字段,AI 靠 description 判断是否加载。

四、识栈:只读分析,产出代码地图

使用 Chat 模式(Cmd+U,Windows 为 Ctrl+U),一次问一个主题,不要把十个问题塞进一条消息。

只读分析,不要修改任何文件。列出技术栈、构建工具、入口文件、
目录职责、配置文件含义,表格输出。
画出一次请求从页面按钮 → Controller → Service → Mapper → 表的完整调用链,
带文件路径和行号。
列出所有环境变量和配置项,标注本地启动必需项。
列出 TODO / FIXME / 硬编码 / 无注释的怪逻辑,按风险排序。

产出 doc/ONBOARDING.md,内容包括技术栈、目录地图、调用链和环境清单;一份文档写三节:前端一节、后端一节、端到端串联一节。接手前后端项目,端到端那一节不能省。

此阶段禁止改业务代码。

五、跑通:先后端,后前端

  • 让 AI 读 pom.xml / package.json / README,给出准确的 JDK、Node 版本、构建和测试命令,不要自己猜,也不要把 mvn test 之类写死进规则。
  • 启动顺序:后端起 → swagger/health 通 → 前端配代理 → 前端起 → 页面点一次真实请求。
  • 数据库只用只读账号连测试库,生产库连接信息不进对话。只读账号够识栈和读链路;完整业务链路若含写操作,单独申请测试库写账号并登记。
  • 所有踩坑写进 doc/LOCAL_SETUP.md:版本、镜像源、端口、代理、配置中心、跨域。
  • 本地跑通一条完整业务链路之前,不要改任何业务代码。 规则文件、文档、本地启动配置属于开工准备,不受此限。跑不通先解决环境。

六、改代码:按风险选择流程

四步法是最大安全档,不是默认档。真正不能省的只有两件事:动手前知道改哪些文件并拿到确认,动手后核对 diff 的改动范围。看 diff 只回答"改了哪些文件、哪些行";正确性靠第七章的行为验收,别把扫 diff 当验收。

改动类型例子轮数做法
小改单行简单 bug、纯文案(且全局规则允许直接改)1 轮直接说"把 #Xxx.java 的 xxx 改成 yyy",改完核对 diff 范围
中改一个功能点,2–3 个文件;加字段、调校验2 轮① 分析+方案,先别动;② 按方案改,核对 diff
大改跨模块、不熟的代码、动表结构4 轮完整四步法

1 轮法只在全局规则的豁免范围内可用。 本机全局规则要求「改动代码前先输出改造计划,等待用户确认后再执行修改」,没有单行豁免,那就一律走 2 轮法。规则文件(alwaysApply: true)优先于流程文档,别用 SOP 给规则开后门。

6.1 日常默认:两轮法

第一轮,只读分析并确认方案:

只读分析 #Xxx.java 的 xxx 问题,给出改动方案:
文件清单 + 每处改法 + 风险点。先不要动手。

花 30 秒扫一眼方案,跑偏就当场纠正。AI 说"我要改 3 个文件",扫一眼就知道有没有跑偏,比读完它写的全部代码快得多。

第二轮,按方案执行:

按方案执行,只改清单内文件。

改完花 1 分钟看 git diff 核对改动范围,再亲自本地跑一遍。日常两轮法不必单设一轮让 AI 自评;大改和命中放行三问的改动,仍按 7.5 走交叉审查。

6.2 大改专用:完整四步法

1 定位:只读分析 #XxxController.java,说明它做什么、谁调用、依赖哪些表。不要改代码。
2 方案:问题是 xxx。给出修改方案:文件清单、每个文件改什么、风险点、验证方式。先不要动手。
3 执行:按上面方案执行,只改清单内文件,不要顺手重构其他代码。
4 验证:review 刚才的 diff,检查遗漏和副作用,给出本地验证步骤。

一个任务一个对话、一个分支。人工看 git diff 核对范围后自己提交。AI 生成的 commit message 可以用,命令自己执行。

硬规则:不熟的代码先只读一轮。 接手期碰到没见过的模块,哪怕只改一行,也先问"这段逻辑做什么、谁调用"。摸熟了再降级到一轮。

七、验收:改动越多,越不能靠肉眼扫 diff

7.1 改之前先定"怎么算对"

这比看 diff 重要十倍。方案阶段强制输出验收清单:

这次改动完成后,我需要验证哪几件事?
按「输入 → 预期输出」列成清单,每条给出可执行的验证命令或页面路径。

你只负责照着清单点、跑;实现细节不用全懂,但高风险改动必须能听懂解释(见 7.6)。

7.2 拆到能看懂的粒度

  • 后端:一次改动 ≤ 3 个文件、≤ 150 行。
  • 前端:一次改动 ≤ 2 个组件 / 1 个页面。
把这个改动拆成 N 个可独立提交的步骤,每步完成后项目都能启动、都能验证。
列出每步的验证方式。

按"能独立跑通"拆,不是按文件拆。每步单独走两轮法。看 20 行 diff 和看 800 行 diff 完全是两回事。

7.3 让 AI 写测试,你看红变绿

给这次改动写测试,覆盖正常情况和边界情况。
先证明改动前会失败,再证明改动后通过。

只要会看 PASS / FAIL。测试通过不等于一定对,但比肉眼扫代码靠谱得多。

7.4 做改前改后的行为对比

改前抓一份响应、截图或查询结果,改后再抓一份,对比差异。

重点看原来能用的功能是否还正常,不是只盯着新功能。回归出问题往往在这里。

7.5 开新对话,让 AI 查 AI

开新对话,只贴 diff,不要让它改:

这是另一个 AI 写的改动。你是 reviewer,只审查不改代码:
1. 哪里会出错?按严重性排序
2. 哪些边界情况没处理?
3. 有没有改到不该改的文件?
4. 每条问题给出具体复现步骤

新对话很关键,别让它带着"这是我写的"的上下文。让第二个模型先给一轮独立判断,最终结论仍由人确认——它同样会漏,不能把"AI 查 AI"当免检。

7.6 人工只重点盯高风险改动

其余放过,别追求全看懂:

  • 后端:权限 / 事务 / SQL。
  • 前端:路由权限 / request 层 / Pinia / 公共组件。

这几类看不懂,就让 AI 用人话解释:

这段改动在业务上做了什么?说人话,不要术语。

解释不清楚就不要提交。

7.7 用三问决定放不放行

用大白话回答,按改动涉及的端选择一套;一次任务涉及两端就两套都答,且分两次提交。三问都设计成是非问,直接用"有 / 没有"判定。

后端三问:

  1. 有没有影响已有功能?
  2. 有没有改数据库数据或表结构?
  3. 有没有动权限、登录、事务?

前端三问:

  1. 有没有影响现有页面和路由?
  2. 有没有改公共组件、request 封装或 Pinia store?
  3. 有没有改接口字段映射或入参结构?

三个都答"没有"、测试跑通、且 7.6 的高风险改动已人工确认,才提交;任何一个答"有",必须走交叉审查和手动回归。

底线是:看不懂 / 没测试 / 动了数据,任一命中就不许提交(三者都没有才放行)。这种情况下把任务拆小重来,别赌。

7.8 前后端验收方式的差异

后端靠"请求 → 响应"验收,前端靠"页面 → 交互"验收。浏览器就是前端的验收工具。

环节后端前端
验收清单入参 → 预期响应页面路径 → 操作动作 → 预期界面变化
拆分粒度≤3 文件 / 150 行≤2 组件 / 1 页面
自动验证按构建文件确认的测试命令(如 mvn test)按 package.json 脚本跑 build + lint,启用 TS 时加 tsc;再补 Vitest / Playwright
行为对比curl 响应对比改前截图 vs 改后截图 + console 对比
AI 查 AI审查 diff审查 diff,重点看响应式和边界
人工盯权限 / 事务 / SQL路由权限 / request 层 / Pinia / 公共组件
放行三问有没有影响已有功能?动数据?动权限?有没有影响页面路由?动公共组件?改字段映射?

7.9 前端专属:让 AI 自己点一遍

TRAE 内置 Webview 预览,这是前端才有的便利:

启动项目,打开 #目标页面,在 Webview 里依次点击 xxx、输入 yyy,
读 console 有没有报错,把结果页面截图给我。

配了浏览器 MCP 效果更好——它真在浏览器里操作,不是靠想象。

土办法但极其有效:改前先截一张图丢进对话,改完让它对着原图自查"哪些地方不该变但变了"。

前端审查直接使用这份清单:

重点检查:
1. props/reactive 解构后响应式是否丢失
2. v-for 有没有 key,v-if 和 v-for 是否混用
3. 事件监听、定时器、watch 有没有清理
4. 字段使用是否遵守统一约定:直接用后端字段;确有转换是否集中在一处;有没有散落在组件里各转各的。对接口返回的 null/undefined 是否有必要保护——这是展示层兜底,不是全局规则禁止的"冗余兜底"
5. 样式作用域有没有污染(scoped 漏了、deep 滥用)
6. 路由参数变了但组件没重新拉数据

八、字段约定:默认不映射,确需转换就集中处理

默认直接用后端字段,不要再映射一遍。 后端返回 num,前端就用 num,不要转成 number。多一层映射,就是多一层能出错的地方。

8.1 什么时候必须留映射

以下情况需要保留映射:

  • 后端字段本身烂,例如 flag1、status2、a。
  • 一个页面聚合多个接口的同名字段。
  • 后端改字段名不通知前端。

这时候映射是隔离层:后端变了只改一处,不用全站翻组件。

判断标准是:后端字段能不能直接看懂、会不会随便改。 能,就别映射;不能,就集中在一处映射。

8.2 真正要拦的是"散着映射"

问题不是"映不映射",而是组件 A 里把 .num 转成 .number,组件 B 里又转一遍,组件 C 忘了转,直接读到 undefined。

因此审查时不要只问"接口字段映射错了没",而要问:

字段使用是否遵守统一约定:直接用后端字段;确有转换是否集中在一处;有没有散落在组件里各转各的。

8.3 验收靠类型 + 真实请求,不靠肉眼

interface XxxResp {
  num: number
  name: string
}

后端返回什么就定义什么。前端写了 res.number,编译期会报错——但这只能校验"声明与用法一致",校验不了"声明与后端实际返回一致" 。类型定义写错了,编译期照样全绿,所以必须再跑一次真实接口、把页面点一遍。

没上 TS 的项目,只把本次改动涉及到的字段按 8.1 判断是否需要映射,不做全站统一改造;跑一次真实接口并把页面点一遍,看有没有 undefined 渲染出来。

九、模式选择与红线

模式接手期用法
Chat Cmd+U主力,读码、定位、review 都走它
Builder只生成小工具、脚本、测试骨架,不改存量模块
SOLO只在隔离分支或新项目试,存量业务禁止自主跑全流程
CUE Tab接受前看一眼,它按上下文续写,容易照抄老代码的写法
MCP只装当前用的,项目级放 .trae/mcp.json 并开启项目级 MCP 开关,可随 Git 共享;工具越多 token 越费

红线:

  • 不贴生产库连接、密钥、真实用户数据进对话。
  • 不让 AI 执行 git push、部署、删改数据。
  • 大改动拆小步,一个对话不要塞多个需求。
  • 上下文变长,先让它输出"交接摘要",再开新对话。
  • 前后端同一项目根 ≠ 可以顺手跨端改:改后端必须先显式声明并单独确认,前后端改动分开 commit,无例外(若全局规则口径不同,以全局为准)。
  • 不信任它的自测结论,自己跑一遍。
  • 看不懂 / 没测试 / 动了数据,任一命中就不许提交。

十、30 天接手节奏

时间目标
第 1–2 天识栈 + 跑通,产出 doc/ONBOARDING.md 和 doc/LOCAL_SETUP.md
第 3–5 天跟读小 bug,练调用链;不熟的模块一律先只读一轮
第 2 周独立改小需求,前端或后端各练一轮、分开提交,用两轮法
第 3–4 周接完整需求;把"新增接口""新增页面"沉淀成 Skill