这是让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 分钟
- 拿齐 5 样东西:仓库权限、业务文档、测试环境地址、数据库只读账号、接口文档地址。缺什么记下来,不要让 AI 猜。只读账号够识栈和读链路;完整链路若含写操作,单独申请测试库写账号并登记,不用生产库。
- TRAE CN 首次启动时导入 VS Code 配置,语言选中文。
- 前后端代码放同一项目根打开,从一个项目根拿到完整上下文;目录仍按
frontend//backend/分开,通过项目规则落实按端隔离和显式声明。 - 从干净分支起步,
git status必须干净。 - 配置全局规则和项目规则:以本机已有全局规则为准,只补缺项;项目级
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 Apply | alwaysApply: true | 00-collab.md:协作契约,项目内所有对话生效 |
| Apply to Specific Files | globs + alwaysApply: false | 前后端规则:收窄到各自目录的文件类型;子目录规则本身按目录自动携带 |
| Apply Intelligently | description | 按场景由 AI 判断 |
| Apply Manually | @Rule 引用 | 手动触发,引用方式中优先级最高 |
| commit 场景 | scene: git_message | 90-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 用三问决定放不放行
用大白话回答,按改动涉及的端选择一套;一次任务涉及两端就两套都答,且分两次提交。三问都设计成是非问,直接用"有 / 没有"判定。
后端三问:
- 有没有影响已有功能?
- 有没有改数据库数据或表结构?
- 有没有动权限、登录、事务?
前端三问:
- 有没有影响现有页面和路由?
- 有没有改公共组件、request 封装或 Pinia store?
- 有没有改接口字段映射或入参结构?
三个都答"没有"、测试跑通、且 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 |