TARE-Learn/第 2 天：TRAE 上下文工程与规则体系.md

# 第 2 天：TRAE 上下文工程与规则体系

# 第 0 部分：从个人提效到团队 AI 工程治理

---

## Slide 0\-1：第 1 天到第 2 天

### PPT 页面内容

```Plain Text
第 1 天：
让 TRAE 看懂若依代码

第 2 天：
让 TRAE 按团队规则改若依代码

核心变化：
从代码理解
到研发治理
```

### 讲师逐字稿

昨天我们使用若依作为真实开源项目，学习了如何让 TRAE 理解陌生代码库。

今天我们进入第二阶段：上下文工程与规则体系。

如果说第一天是“让 AI 看懂若依”，今天就是“让 AI 按团队规则分析、修改和检查若依”。

当团队多人都使用 AI 时，必须有统一上下文、统一 rules、统一验收标准，否则 AI 会带来不一致甚至风险。

---

## Slide 0\-2：若依场景下的团队规则问题

### PPT 页面内容

```Plain Text
若依类后台项目常见风险：

绕过权限
页面直接调接口
按钮权限当安全边界
接口缺少权限注解
操作日志缺失
代码生成后直接上线
敏感信息进入日志
```

### 讲师逐字稿

若依这类后台系统，最容易出现的问题不是页面不好看，而是权限、日志、接口边界和生成代码质量。

比如 AI 可能在页面里直接新增接口调用，可能只做前端按钮隐藏，可能没有检查后端权限注解，可能新增敏感操作但没有操作日志，可能用代码生成器生成 CRUD 后直接上线。

所以今天我们要把这些隐性开发要求写成中文规则，让 TRAE 在后续协作中长期遵守。

---

## Slide 0\-3：今天三个关键词

### PPT 页面内容

```Plain Text
上下文
规则
资产化

上下文决定 AI 看什么
规则决定 AI 怎么做
资产化决定团队怎么复用
```

### 讲师逐字稿

今天仍然是三个关键词。

上下文决定 AI 看什么。比如看整个若依项目，还是只看用户管理模块，还是只看某个 Controller。

规则决定 AI 怎么做。比如不能绕过权限、不能遗漏操作日志、不能把前端权限当安全边界。

资产化决定团队怎么复用。好的 Prompt、rules、报告模板，都应该进入团队资产库。

---

# 模块 1：上下文工程原则

---

## Slide 1\-1：若依任务为什么要讲清楚？

### PPT 页面内容

```Plain Text
模糊任务：

帮我优化用户管理模块

问题：
目标不清
范围不清
约束不清
输出不清
验收不清
```

### 讲师逐字稿

在若依项目里，如果你直接问“帮我优化用户管理模块”，AI 很难给出可靠结果。

优化什么？权限？接口？页面？表单？数据权限？操作日志？代码结构？测试？

范围不清，AI 就会自由发挥。

所以若依这种后台系统，更需要上下文工程。

---

## Slide 1\-2：好任务五要素

### PPT 页面内容

```Plain Text
好任务 =
目标 + 范围 + 约束 + 输出格式 + 验收标准
```

### 讲师逐字稿

一个合格的 AI 编程任务，必须包含五要素。

目标：到底要分析或修改什么。

范围：只看哪些模块，不看哪些模块。

约束：不能做什么，必须遵守什么。

输出格式：报告、表格、代码 diff、测试用例。

验收标准：什么结果算合格。

这五项越清楚，AI 输出越稳定。

---

## Slide 1\-3：若依坏 Prompt 示例

### PPT 页面内容

```Plain Text
@workspace 帮我检查若依权限有没有问题。
```

### 讲师逐字稿

这个 Prompt 看起来合理，但其实太大。

“权限”包含页面权限、按钮权限、接口权限、数据权限。

“有没有问题”也太泛。是安全风险、实现缺陷、配置问题，还是调用链路不清？

没有范围，没有约束，没有输出格式，也没有验收标准。

---

## Slide 1\-4：若依好 Prompt 示例

### PPT 页面内容

```Plain Text
@workspace 请分析若依“用户管理页面按钮权限”的调用链路。

范围：
只分析用户管理页面的新增、修改、删除按钮权限。

约束：
不修改代码；结论标注文件和函数；区分前端权限和后端接口权限。

输出：
表格。

验收：
覆盖按钮、权限字符、前端判断、后端接口、权限注解、不确定点。
```

### 讲师逐字稿

这个 Prompt 就清楚很多。

目标是用户管理页面按钮权限，不是整个权限系统。

范围限定新增、修改、删除按钮。

约束要求不修改代码，结论标注文件和函数，区分前端权限和后端权限。

验收标准要求覆盖按钮、权限字符、前端判断、后端接口、权限注解和不确定点。

这就是合格任务。

---

## Slide 1\-5：上下文组织清单

### PPT 页面内容

```Plain Text
若依任务上下文清单：

目标
范围
输入文件
约束
输出格式
验收标准
不确定点
```

### 讲师逐字稿

以后大家在若依项目里使用 TRAE，可以先填这张清单。

比如分析角色权限保存链路，需要提供角色页面、角色 API、后端角色 Controller、Service、菜单关系表、操作日志相关代码。

同时要约束 AI：不要改代码，不要猜，不要把按钮权限当安全边界。

---

# 模块 2：@workspace、\#File、\#Code、\#Web 使用

---

## Slide 2\-1：四类上下文

### PPT 页面内容

```Plain Text
@workspace：找路
#File：看文件
#Code：抠细节
#Web：查外部依据
```

### 讲师逐字稿

若依项目比较大，所以更要正确选择上下文。

@workspace 用来找入口，比如找 getInfo、getRouters、按钮权限指令。

\#File 用来分析相关文件，比如用户管理页面和用户 Controller。

\#Code 用来分析某个方法，比如 handleLogin 或某个权限判断函数。

\#Web 用来查框架文档或最佳实践，但不能替代项目代码依据。

---

## Slide 2\-2：@workspace 找路示例

### PPT 页面内容

```Plain Text
@workspace 请找出若依中与“用户登录后菜单路由生成”相关的前端和后端文件。

要求：
标注文件路径
标注函数或类名
区分事实和推测
列出不确定点
```

### 讲师逐字稿

这个 Prompt 适合任务早期。

我们不知道具体文件在哪里，就让 @workspace 先找入口。

它应该帮我们找出前端登录、权限 store、路由守卫、getRouters API，以及后端菜单路由接口相关文件。

但所有结论都必须标注依据。

---

## Slide 2\-3：\#File 聚焦示例

### PPT 页面内容

```Plain Text
#File 请分析这些文件中登录、用户信息、菜单路由的调用关系。

重点：
谁调用 login
谁调用 getInfo
谁调用 getRouters
权限信息保存在哪里
路由在哪里动态生成
```

### 讲师逐字稿

当我们找到相关文件后，就用 \#File 聚焦。

这时目标不是全局找，而是分析这些文件之间的调用关系。

比如谁调用 login，谁调用 getInfo，谁调用 getRouters，权限信息保存在哪里，路由在哪里动态生成。

---

## Slide 2\-4：\#Code 抠细节示例

### PPT 页面内容

```Plain Text
#Code 请分析 handleLogin 函数。

重点：
参数来源
调用哪个 API
token 如何保存
失败如何处理
loading 是否恢复
登录成功后跳转哪里
```

### 讲师逐字稿

如果我们只分析登录函数，就用 \#Code。

重点看参数来源、API 调用、token 保存、失败处理、loading 恢复和登录成功后的跳转。

这类函数级分析非常适合发现细节风险。

---

## Slide 2\-5：\#Web 使用边界

### PPT 页面内容

```Plain Text
#Web 可查：
Spring Security 权限实践
Vue Router 动态路由
前端按钮权限最佳实践

但：
若依当前实现必须回到代码验证
```

### 讲师逐字稿

\#Web 可以查外部资料，比如 Spring Security 权限实践、Vue Router 动态路由、按钮权限最佳实践。

但若依当前实现如何，必须回到代码里验证。

外部资料只能提供参考，不能替代项目事实。

---

# 模块 3：幻觉死循环切断方法

---

## Slide 3\-1：若依场景中的幻觉死循环

### PPT 页面内容

```Plain Text
常见表现：

AI 说所有接口都有权限校验
但不给 Controller 依据

AI 说操作日志完整
但不给注解或 AOP 依据

AI 说按钮权限安全
但只看到前端代码
```

### 讲师逐字稿

在若依项目里，AI 很容易因为它“知道若依是权限系统”，就过度自信。

比如它说所有接口都有权限校验，但不给 Controller 依据。

它说操作日志完整，但不给注解或 AOP 依据。

它说按钮权限安全，但只看到了前端按钮隐藏。

这就是需要切断的幻觉。

---

## Slide 3\-2：幻觉控制顺序

### PPT 页面内容

```Plain Text
先找证据
再判断原因
最后给方案
```

### 讲师逐字稿

遇到这种情况，不要继续让 AI 给结论。

先让它找证据：文件、类、方法、注解、调用关系。

然后再判断问题。

最后才给方案。

---

## Slide 3\-3：若依证据收集 Prompt

### PPT 页面内容

```Plain Text
请先不要修改代码。

请围绕“用户管理删除按钮权限”收集证据：

1. 前端按钮在哪个页面
2. 使用了哪个权限字符
3. 前端如何判断按钮显示
4. 后端删除接口在哪里
5. Controller 是否有权限注解
6. 是否记录操作日志
7. 无法确认的内容
```

### 讲师逐字稿

这是若依场景下的证据收集 Prompt。

它没有直接问“有没有风险”，而是先要求 AI 找证据。

前端按钮在哪里，权限字符是什么，前端怎么判断，后端删除接口在哪里，Controller 是否有权限注解，是否记录操作日志，哪些无法确认。

这些证据收集完，才能判断风险。

---

## Slide 3\-4：原因判断 Prompt

### PPT 页面内容

```Plain Text
请基于证据判断风险：

每个风险必须对应文件、函数或注解
区分已确认事实和推测
无法确认的内容写入不确定点
不要直接下安全结论
```

### 讲师逐字稿

第二步是原因判断。

比如发现前端按钮有权限字符，但后端删除接口没有找到权限注解。

这时可以说“存在接口级权限待确认风险”，但不能直接说“系统不安全”。

如果没有看到后端文件，也要写无法确认，而不是猜测。

---

## Slide 3\-5：方案生成 Prompt

### PPT 页面内容

```Plain Text
请基于已确认风险给出方案：

修改文件
修改方法
新增或调整权限注解
是否需要操作日志
影响范围
验证方式
测试建议
```

### 讲师逐字稿

第三步才给方案。

如果确认证据显示后端接口缺少权限注解，才建议补权限注解。

如果敏感操作缺少日志，才建议补操作日志。

每个方案都要说明文件、方法、影响范围、验证方式和测试建议。

---

# 模块 4：\.gitignore 与 IDE 忽略配置

---

## Slide 4\-1：若依项目哪些文件不能提交？

### PPT 页面内容

```Plain Text
不应提交：

.env
application-dev.yml 中真实密码
数据库账号
Redis 密码
target/
node_modules/
dist/
日志文件
IDE 本地配置
```

### 讲师逐字稿

若依项目里，忽略配置同样重要。

后端可能有 application\-dev\.yml、本地数据库账号、Redis 密码。前端有 node\_modules、dist。后端有 target。还有日志文件和 IDE 配置。

这些都不应该进入仓库，更不应该进入 AI 上下文。

---

## Slide 4\-2：若依忽略配置检查 Prompt

### PPT 页面内容

```Plain Text
@workspace 请检查若依项目的 .gitignore 是否完整。

重点检查：
后端 target
前端 node_modules / dist
日志文件
本地配置
数据库密码
Redis 密码
IDE 配置
```

### 讲师逐字稿

可以让 TRAE 检查若依项目的 \.gitignore。

重点看后端 target、前端 node\_modules 和 dist、日志文件、本地配置、数据库密码、Redis 密码、IDE 配置。

同样，不要让 AI 直接改，先给审查报告。

---

# 模块 5：\.trae/rules\.md 中文安全规则

---

## Slide 5\-1：若依安全规则重点

### PPT 页面内容

```Plain Text
若依安全规则重点：

账号密码
Token
接口权限注解
菜单与按钮权限
数据权限
操作日志
敏感配置
日志脱敏
```

### 讲师逐字稿

若依安全规则和一般前端项目不完全一样。

它必须重点关注账号密码、token、接口权限注解、菜单与按钮权限、数据权限、操作日志、敏感配置、日志脱敏。

尤其是权限与日志，是后台管理系统的核心。

---

## Slide 5\-2：中文安全规则示例

### PPT 页面内容

```Plain Text
规则示例：

前端按钮权限只能作为交互控制，不能作为安全边界。

涉及用户、角色、菜单、部门、岗位等敏感接口时，必须检查后端 Controller 是否存在权限控制。

涉及新增、修改、删除、导出等操作时，必须检查是否记录操作日志。
```

### 讲师逐字稿

这些规则可以直接写进 \.trae/rules\.md。

第一，前端按钮权限只能作为交互控制，不能作为安全边界。

第二，涉及用户、角色、菜单、部门、岗位等敏感接口时，必须检查后端 Controller 是否存在权限控制。

第三，涉及新增、修改、删除、导出等操作时，必须检查是否记录操作日志。

这些规则非常适合若依。

---

## Slide 5\-3：敏感配置规则

### PPT 页面内容

```Plain Text
规则示例：

禁止在源码中硬编码数据库密码、Redis 密码、JWT 密钥、第三方密钥。

不得提交真实 application-dev.yml、.env、本地配置文件。

示例配置必须使用占位符。
```

### 讲师逐字稿

若依项目通常有后端配置文件，所以敏感配置规则也很重要。

禁止在源码中硬编码数据库密码、Redis 密码、JWT 密钥、第三方密钥。

不得提交真实 application\-dev\.yml、\.env、本地配置文件。

示例配置必须使用占位符。

---

# 模块 6：中文编码与测试规则

---

## Slide 6\-1：若依编码规则重点

### PPT 页面内容

```Plain Text
若依编码规则重点：

前端 api 分层
后端 Controller / Service / Mapper 分层
权限注解
操作日志注解
数据权限
字典使用
代码生成规范
```

### 讲师逐字稿

若依的编码规则要结合它的项目结构。

前端接口应放在 api 目录，不应该页面里直接写请求。

后端要遵守 Controller、Service、Mapper 分层。

敏感接口要关注权限注解和操作日志注解。

列表查询要关注数据权限。

固定枚举值尽量使用字典。

代码生成结果不能直接上线，要人工检查权限、日志、校验和测试。

---

## Slide 6\-2：若依测试规则重点

### PPT 页面内容

```Plain Text
测试规则重点：

登录成功 / 失败
无权限访问接口
按钮权限显示
角色授权变化
数据权限范围
操作日志记录
代码生成 CRUD
```

### 讲师逐字稿

若依测试规则应该围绕权限和后台管理流程。

登录要测成功和失败。

无权限访问接口要返回拒绝。

按钮权限显示要和权限字符匹配。

角色授权变化后，菜单和按钮权限应变化。

数据权限要验证不同角色看到的数据范围。

敏感操作要验证操作日志记录。

代码生成 CRUD 要验证增删改查、权限和日志。

---

# 模块 7：中文前端专项规则

---

## Slide 7\-1：若依前端规则重点

### PPT 页面内容

```Plain Text
前端规则重点：

api 目录调用
权限指令
动态路由
列表 loading
表单校验
删除二次确认
导出权限
字典显示
```

### 讲师逐字稿

若依前端规则应覆盖这些点。

接口调用要放 api 目录。

按钮权限要使用项目已有权限指令或权限方法。

动态路由不能随意绕过。

列表页必须有 loading、空状态、错误处理。

表单必须有校验。

删除必须二次确认。

导出按钮要有权限控制。

字典字段要使用统一字典显示。

---

## Slide 7\-2：用户管理页面规则示例

### PPT 页面内容

```Plain Text
用户管理页面规则：

新增、修改、删除、导出按钮必须使用权限控制
删除必须二次确认
提交失败后恢复 loading
修改用户后刷新列表
敏感字段不得明文展示或输出日志
```

### 讲师逐字稿

以用户管理页面为例。

新增、修改、删除、导出按钮必须使用权限控制。

删除必须二次确认。

提交失败后 loading 必须恢复。

修改用户后列表必须刷新。

密码、手机号、邮箱等敏感字段不得随意明文展示或输出日志。

---

# 模块 8：技能与规则资产化

---

## Slide 8\-1：若依资产库建议

### PPT 页面内容

```Plain Text
建议沉淀：

若依结构分析 Prompt
登录权限链路 Prompt
菜单路由分析 Prompt
按钮权限检查 Prompt
操作日志检查 Prompt
代码生成 Review 清单
若依 rules.md
```

### 讲师逐字稿

若依案例非常适合沉淀资产。

比如若依结构分析 Prompt、登录权限链路 Prompt、菜单路由分析 Prompt、按钮权限检查 Prompt、操作日志检查 Prompt、代码生成 Review 清单、若依 rules\.md。

这些资产以后可以直接用于公司内部类似后台管理系统。

---

## Slide 8\-2：若依资产库目录

### PPT 页面内容

```Plain Text
ai-dev-assets/
├── prompts/若依/
├── rules/若依/
├── templates/若依/
├── checklists/若依/
└── examples/若依/
```

### 讲师逐字稿

建议企业资产库里单独有一个若依目录。

prompts 存若依相关 Prompt。

rules 存若依 rules\.md。

templates 存若依代码理解报告、权限链路报告模板。

checklists 存权限检查、日志检查、代码生成检查清单。

examples 存优秀案例和反面案例。

---

# 模块 9：规则可执行性检查

---

## Slide 9\-1：若依坏规则示例

### PPT 页面内容

```Plain Text
坏规则：

注意权限安全
代码要规范
日志要完整
数据权限要合理
生成代码要检查
```

### 讲师逐字稿

这些话方向没错，但不可执行。

“注意权限安全”太泛。

“日志要完整”没有说明哪些操作必须记录。

“数据权限要合理”没有判断标准。

“生成代码要检查”没有检查项。

所以要改成明确规则。

---

## Slide 9\-2：若依好规则示例

### PPT 页面内容

```Plain Text
好规则：

涉及用户、角色、菜单、部门、岗位的新增、修改、删除、导出接口时，必须检查后端权限控制和操作日志记录。

涉及列表查询时，必须确认是否需要数据权限过滤。

代码生成结果上线前，必须检查权限、日志、表单校验、异常处理和测试。
```

### 讲师逐字稿

这就是更好的规则。

它有触发场景：用户、角色、菜单、部门、岗位相关接口。

它有必须动作：检查后端权限控制和操作日志。

它能被检查：看 Controller、注解、Service 和日志配置。

这类规则才适合写进 \.trae/rules\.md。

---

## Slide 9\-3：若依 rules 检查 Prompt

### PPT 页面内容

```Plain Text
@workspace 请检查当前 .trae/rules.md 是否适合若依项目。

重点检查：
权限规则
操作日志规则
数据权限规则
前端按钮权限规则
代码生成规则
敏感配置规则
```

### 讲师逐字稿

这是让 TRAE 检查若依 rules 的 Prompt。

重点检查权限规则、操作日志规则、数据权限规则、前端按钮权限规则、代码生成规则和敏感配置规则。

要求 AI 先给审查报告，不要直接改文件。

---

# 综合实战：团队 \.trae/rules\.md v0\.1

---

## Slide 10\-1：若依版 rules\.md 结构

### PPT 页面内容

```Plain Text
若依版 rules.md：

0. 基础原则
1. 安全规则
2. 权限规则
3. 操作日志规则
4. 编码规则
5. 前端规则
6. 测试规则
7. 代码生成规则
8. 不确定性处理规则
```

### 讲师逐字稿

今天最终产出是若依版 \.trae/rules\.md v0\.1。

它比通用 rules 多了几个若依特色部分：权限规则、操作日志规则、代码生成规则。

这份 rules 后续可以作为团队后台管理系统 AI 协作规范的基础。

---

## Slide 10\-2：若依版 rules 核心条款

### PPT 页面内容

```Plain Text
核心条款：

前端按钮权限不是安全边界
敏感接口必须检查后端权限
敏感操作必须检查操作日志
列表查询必须考虑数据权限
代码生成结果不得直接上线
不确定内容必须标注
```

### 讲师逐字稿

若依版 rules 的核心条款可以浓缩成六句。

前端按钮权限不是安全边界。

敏感接口必须检查后端权限。

敏感操作必须检查操作日志。

列表查询必须考虑数据权限。

代码生成结果不得直接上线。

不确定内容必须标注。

只要这六条落实，AI 在若依项目里的使用风险会明显降低。

---

## Slide 10\-3：第 2 天交付物

### PPT 页面内容

```Plain Text
第 2 天交付物：

01_上下文组织清单
02_上下文引用模板
03_幻觉控制 Prompt
04_gitignore 忽略配置样例
05_若依中文安全规则
06_若依编码测试规则
07_若依前端规则
08_若依 AI 资产库目录
09_规则验收清单
10_若依版 rules.md v0.1
```

### 讲师逐字稿

第 2 天最终交付十个产物。

它们不是零散作业，而是一套若依项目 AI 协作规范资产。

以后团队在若依或类似后台系统中使用 TRAE，就可以复用这些清单、Prompt、规则和模板。

---

## Slide 10\-4：两天课程总结

### PPT 页面内容

```Plain Text
第 1 天：
用 TRAE 看懂若依

第 2 天：
让 TRAE 按规则参与若依研发

最终能力：
读得懂
问得准
查得实
改得稳
可复用
```

### 讲师逐字稿

两天课程到这里形成闭环。

第一天，我们学习如何用 TRAE 看懂若依代码：看结构、找入口、追链路、查依据。

第二天，我们学习如何让 TRAE 按团队规则参与若依研发：组织上下文、控制幻觉、编写 rules、沉淀资产。

最终目标是五个字：读得懂，问得准，查得实，改得稳，可复用。

这就是 AI 编程在企业研发里的真正价值。