smart
22 KiB
第 2 天：TRAE 上下文工程与规则体系
第 0 部分：从个人提效到团队 AI 工程治理
Slide 0-1：第 1 天到第 2 天
PPT 页面内容
第 1 天：
让 TRAE 看懂若依代码
第 2 天：
让 TRAE 按团队规则改若依代码
核心变化：
从代码理解
到研发治理
讲师逐字稿
昨天我们使用若依作为真实开源项目，学习了如何让 TRAE 理解陌生代码库。
今天我们进入第二阶段：上下文工程与规则体系。
如果说第一天是“让 AI 看懂若依”，今天就是“让 AI 按团队规则分析、修改和检查若依”。
当团队多人都使用 AI 时，必须有统一上下文、统一 rules、统一验收标准，否则 AI 会带来不一致甚至风险。
Slide 0-2：若依场景下的团队规则问题
PPT 页面内容
若依类后台项目常见风险：
绕过权限
页面直接调接口
按钮权限当安全边界
接口缺少权限注解
操作日志缺失
代码生成后直接上线
敏感信息进入日志
讲师逐字稿
若依这类后台系统，最容易出现的问题不是页面不好看，而是权限、日志、接口边界和生成代码质量。
比如 AI 可能在页面里直接新增接口调用，可能只做前端按钮隐藏，可能没有检查后端权限注解，可能新增敏感操作但没有操作日志，可能用代码生成器生成 CRUD 后直接上线。
所以今天我们要把这些隐性开发要求写成规则，让 TRAE 在后续协作中长期遵守。
Slide 0-3：今天三个关键词
PPT 页面内容
上下文
规则
资产化
上下文决定 AI 看什么
规则决定 AI 怎么做
资产化决定团队怎么复用
讲师逐字稿
今天仍然是三个关键词。
上下文决定 AI 看什么。比如看整个若依项目，还是只看用户管理模块，还是只看某个 Controller。
规则决定 AI 怎么做。比如不能绕过权限、不能遗漏操作日志、不能把前端权限当安全边界。
资产化决定团队怎么复用。好的 Prompt、rules、报告模板，都应该进入团队资产库。
模块 1：上下文工程原则
Slide 1-1：若依任务为什么要讲清楚？
PPT 页面内容
模糊任务：
帮我优化用户管理模块
问题：
目标不清
范围不清
约束不清
输出不清
验收不清
讲师逐字稿
在若依项目里，如果你直接问“帮我优化用户管理模块”，AI 很难给出可靠结果。
优化什么？权限？接口？页面？表单？数据权限？操作日志？代码结构？测试？
范围不清，AI 就会自由发挥。
所以若依这种后台系统，更需要上下文工程。
Slide 1-2：好任务五要素
PPT 页面内容
好任务 =
目标 + 范围 + 约束 + 输出格式 + 验收标准
讲师逐字稿
一个合格的 AI 编程任务，必须包含五要素。
目标：到底要分析或修改什么。
范围：只看哪些模块，不看哪些模块。
约束：不能做什么，必须遵守什么。
输出格式：报告、表格、代码 diff、测试用例。
验收标准：什么结果算合格。
这五项越清楚，AI 输出越稳定。
Slide 1-3：若依坏 Prompt 示例
PPT 页面内容
@workspace 帮我检查若依权限有没有问题。
讲师逐字稿
这个 Prompt 看起来合理，但其实太大。
“权限”包含页面权限、按钮权限、接口权限、数据权限。
“有没有问题”也太泛。是安全风险、实现缺陷、配置问题，还是调用链路不清？
没有范围，没有约束，没有输出格式，也没有验收标准。
Slide 1-4：若依好 Prompt 示例
PPT 页面内容
@workspace 请分析若依“用户管理页面按钮权限”的调用链路。
范围：
只分析用户管理页面的新增、修改、删除按钮权限。
约束：
不修改代码；结论标注文件和函数；区分前端权限和后端接口权限。
输出：
表格。
验收：
覆盖按钮、权限字符、前端判断、后端接口、权限注解、不确定点。
讲师逐字稿
这个 Prompt 就清楚很多。
目标是用户管理页面按钮权限，不是整个权限系统。
范围限定新增、修改、删除按钮。
约束要求不修改代码，结论标注文件和函数，区分前端权限和后端权限。
验收标准要求覆盖按钮、权限字符、前端判断、后端接口、权限注解和不确定点。
这就是合格任务。
Slide 1-5：上下文组织清单
PPT 页面内容
若依任务上下文清单：
目标
范围
输入文件
约束
输出格式
验收标准
不确定点
讲师逐字稿
以后大家在若依项目里使用 TRAE，可以先填这张清单。
比如分析角色权限保存链路，需要提供角色页面、角色 API、后端角色 Controller、Service、菜单关系表、操作日志相关代码。
同时要约束 AI：不要改代码，不要猜，不要把按钮权限当安全边界。
模块 2：@workspace、#File、#Code、#Web 使用
Slide 2-1：四类上下文
PPT 页面内容
@workspace：找路
#File：看文件
#Code：抠细节
#Web：查外部依据
讲师逐字稿
若依项目比较大，所以更要正确选择上下文。
@workspace 用来找入口，比如找 getInfo、getRouters、按钮权限指令。
#File 用来分析相关文件，比如用户管理页面和用户 Controller。
#Code 用来分析某个方法，比如 handleLogin 或某个权限判断函数。
#Web 用来查框架文档或最佳实践，但不能替代项目代码依据。
Slide 2-2：@workspace 找路示例
PPT 页面内容
@workspace 请找出若依中与“用户登录后菜单路由生成”相关的前端和后端文件。
要求：
标注文件路径
标注函数或类名
区分事实和推测
列出不确定点
讲师逐字稿
这个 Prompt 适合任务早期。
我们不知道具体文件在哪里，就让 @workspace 先找入口。
它应该帮我们找出前端登录、权限 store、路由守卫、getRouters API，以及后端菜单路由接口相关文件。
但所有结论都必须标注依据。
Slide 2-3：#File 聚焦示例
PPT 页面内容
#File 请分析这些文件中登录、用户信息、菜单路由的调用关系。
重点：
谁调用 login
谁调用 getInfo
谁调用 getRouters
权限信息保存在哪里
路由在哪里动态生成
讲师逐字稿
当我们找到相关文件后，就用 #File 聚焦。
这时目标不是全局找，而是分析这些文件之间的调用关系。
比如谁调用 login，谁调用 getInfo，谁调用 getRouters，权限信息保存在哪里，路由在哪里动态生成。
Slide 2-4：#Code 抠细节示例
PPT 页面内容
#Code 请分析 handleLogin 函数。
重点：
参数来源
调用哪个 API
token 如何保存
失败如何处理
loading 是否恢复
登录成功后跳转哪里
讲师逐字稿
如果我们只分析登录函数，就用 #Code。
重点看参数来源、API 调用、token 保存、失败处理、loading 恢复和登录成功后的跳转。
这类函数级分析非常适合发现细节风险。
Slide 2-5：#Web 使用边界
PPT 页面内容
#Web 可查：
Spring Security 权限实践
Vue Router 动态路由
前端按钮权限最佳实践
但：
若依当前实现必须回到代码验证
讲师逐字稿
#Web 可以查外部资料，比如 Spring Security 权限实践、Vue Router 动态路由、按钮权限最佳实践。
但若依当前实现如何，必须回到代码里验证。
外部资料只能提供参考，不能替代项目事实。
模块 3：幻觉死循环切断方法
Slide 3-1：若依场景中的幻觉死循环
PPT 页面内容
常见表现：
AI 说所有接口都有权限校验
但不给 Controller 依据
AI 说操作日志完整
但不给注解或 AOP 依据
AI 说按钮权限安全
但只看到前端代码
讲师逐字稿
在若依项目里，AI 很容易因为它“知道若依是权限系统”，就过度自信。
比如它说所有接口都有权限校验，但不给 Controller 依据。
它说操作日志完整，但不给注解或 AOP 依据。
它说按钮权限安全，但只看到了前端按钮隐藏。
这就是需要切断的幻觉。
Slide 3-2：幻觉控制顺序
PPT 页面内容
先找证据
再判断原因
最后给方案
讲师逐字稿
遇到这种情况，不要继续让 AI 给结论。
先让它找证据：文件、类、方法、注解、调用关系。
然后再判断问题。
最后才给方案。
Slide 3-3：若依证据收集 Prompt
PPT 页面内容
请先不要修改代码。
请围绕“用户管理删除按钮权限”收集证据：
1. 前端按钮在哪个页面
2. 使用了哪个权限字符
3. 前端如何判断按钮显示
4. 后端删除接口在哪里
5. Controller 是否有权限注解
6. 是否记录操作日志
7. 无法确认的内容
讲师逐字稿
这是若依场景下的证据收集 Prompt。
它没有直接问“有没有风险”，而是先要求 AI 找证据。
前端按钮在哪里，权限字符是什么，前端怎么判断，后端删除接口在哪里，Controller 是否有权限注解，是否记录操作日志，哪些无法确认。
这些证据收集完，才能判断风险。
Slide 3-4：原因判断 Prompt
PPT 页面内容
请基于证据判断风险：
每个风险必须对应文件、函数或注解
区分已确认事实和推测
无法确认的内容写入不确定点
不要直接下安全结论
讲师逐字稿
第二步是原因判断。
比如发现前端按钮有权限字符，但后端删除接口没有找到权限注解。
这时可以说“存在接口级权限待确认风险”，但不能直接说“系统不安全”。
如果没有看到后端文件，也要写无法确认，而不是猜测。
Slide 3-5：方案生成 Prompt
PPT 页面内容
请基于已确认风险给出方案：
修改文件
修改方法
新增或调整权限注解
是否需要操作日志
影响范围
验证方式
测试建议
讲师逐字稿
第三步才给方案。
如果确认证据显示后端接口缺少权限注解，才建议补权限注解。
如果敏感操作缺少日志，才建议补操作日志。
每个方案都要说明文件、方法、影响范围、验证方式和测试建议。
模块 4：.gitignore 与 IDE 忽略配置
Slide 4-1：若依项目哪些文件不能提交？
PPT 页面内容
不应提交：
.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 页面内容
@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 页面内容
若依安全规则重点：
账号密码
Token
接口权限注解
菜单与按钮权限
数据权限
操作日志
敏感配置
日志脱敏
讲师逐字稿
若依安全规则和一般前端项目不完全一样。
它必须重点关注账号密码、token、接口权限注解、菜单与按钮权限、数据权限、操作日志、敏感配置、日志脱敏。
尤其是权限与日志，是后台管理系统的核心。
Slide 5-2：安全规则示例
PPT 页面内容
规则示例：
前端按钮权限只能作为交互控制，不能作为安全边界。
涉及用户、角色、菜单、部门、岗位等敏感接口时，必须检查后端 Controller 是否存在权限控制。
涉及新增、修改、删除、导出等操作时，必须检查是否记录操作日志。
讲师逐字稿
这些规则可以直接写进 .trae/rules.md。
第一，前端按钮权限只能作为交互控制，不能作为安全边界。
第二，涉及用户、角色、菜单、部门、岗位等敏感接口时，必须检查后端 Controller 是否存在权限控制。
第三，涉及新增、修改、删除、导出等操作时，必须检查是否记录操作日志。
这些规则非常适合若依。
Slide 5-3：敏感配置规则
PPT 页面内容
规则示例：
禁止在源码中硬编码数据库密码、Redis 密码、JWT 密钥、第三方密钥。
不得提交真实 application-dev.yml、.env、本地配置文件。
示例配置必须使用占位符。
讲师逐字稿
若依项目通常有后端配置文件，所以敏感配置规则也很重要。
禁止在源码中硬编码数据库密码、Redis 密码、JWT 密钥、第三方密钥。
不得提交真实 application-dev.yml、.env、本地配置文件。
示例配置必须使用占位符。
模块 6：编码与测试规则
Slide 6-1：若依编码规则重点
PPT 页面内容
若依编码规则重点：
前端 api 分层
后端 Controller / Service / Mapper 分层
权限注解
操作日志注解
数据权限
字典使用
代码生成规范
讲师逐字稿
若依的编码规则要结合它的项目结构。
前端接口应放在 api 目录，不应该页面里直接写请求。
后端要遵守 Controller、Service、Mapper 分层。
敏感接口要关注权限注解和操作日志注解。
列表查询要关注数据权限。
固定枚举值尽量使用字典。
代码生成结果不能直接上线，要人工检查权限、日志、校验和测试。
Slide 6-2：若依测试规则重点
PPT 页面内容
测试规则重点：
登录成功 / 失败
无权限访问接口
按钮权限显示
角色授权变化
数据权限范围
操作日志记录
代码生成 CRUD
讲师逐字稿
若依测试规则应该围绕权限和后台管理流程。
登录要测成功和失败。
无权限访问接口要返回拒绝。
按钮权限显示要和权限字符匹配。
角色授权变化后，菜单和按钮权限应变化。
数据权限要验证不同角色看到的数据范围。
敏感操作要验证操作日志记录。
代码生成 CRUD 要验证增删改查、权限和日志。
模块 7：前端专项规则
Slide 7-1：若依前端规则重点
PPT 页面内容
前端规则重点：
api 目录调用
权限指令
动态路由
列表 loading
表单校验
删除二次确认
导出权限
字典显示
讲师逐字稿
若依前端规则应覆盖这些点。
接口调用要放 api 目录。
按钮权限要使用项目已有权限指令或权限方法。
动态路由不能随意绕过。
列表页必须有 loading、空状态、错误处理。
表单必须有校验。
删除必须二次确认。
导出按钮要有权限控制。
字典字段要使用统一字典显示。
Slide 7-2：用户管理页面规则示例
PPT 页面内容
用户管理页面规则：
新增、修改、删除、导出按钮必须使用权限控制
删除必须二次确认
提交失败后恢复 loading
修改用户后刷新列表
敏感字段不得明文展示或输出日志
讲师逐字稿
以用户管理页面为例。
新增、修改、删除、导出按钮必须使用权限控制。
删除必须二次确认。
提交失败后 loading 必须恢复。
修改用户后列表必须刷新。
密码、手机号、邮箱等敏感字段不得随意明文展示或输出日志。
模块 8：技能与规则资产化
Slide 8-1：若依资产库建议
PPT 页面内容
建议沉淀：
若依结构分析 Prompt
登录权限链路 Prompt
菜单路由分析 Prompt
按钮权限检查 Prompt
操作日志检查 Prompt
代码生成 Review 清单
若依 rules.md
讲师逐字稿
若依案例非常适合沉淀资产。
比如若依结构分析 Prompt、登录权限链路 Prompt、菜单路由分析 Prompt、按钮权限检查 Prompt、操作日志检查 Prompt、代码生成 Review 清单、若依 rules.md。
这些资产以后可以直接用于公司内部类似后台管理系统。
Slide 8-2：若依资产库目录
PPT 页面内容
ai-dev-assets/
├── prompts/若依/
├── rules/若依/
├── templates/若依/
├── checklists/若依/
└── examples/若依/
讲师逐字稿
建议企业资产库里单独有一个若依目录。
prompts 存若依相关 Prompt。
rules 存若依 rules.md。
templates 存若依代码理解报告、权限链路报告模板。
checklists 存权限检查、日志检查、代码生成检查清单。
examples 存优秀案例和反面案例。
模块 9：规则可执行性检查
Slide 9-1：若依坏规则示例
PPT 页面内容
坏规则：
注意权限安全
代码要规范
日志要完整
数据权限要合理
生成代码要检查
讲师逐字稿
这些话方向没错，但不可执行。
“注意权限安全”太泛。
“日志要完整”没有说明哪些操作必须记录。
“数据权限要合理”没有判断标准。
“生成代码要检查”没有检查项。
所以要改成明确规则。
Slide 9-2：若依好规则示例
PPT 页面内容
好规则：
涉及用户、角色、菜单、部门、岗位的新增、修改、删除、导出接口时，必须检查后端权限控制和操作日志记录。
涉及列表查询时，必须确认是否需要数据权限过滤。
代码生成结果上线前，必须检查权限、日志、表单校验、异常处理和测试。
讲师逐字稿
这就是更好的规则。
它有触发场景：用户、角色、菜单、部门、岗位相关接口。
它有必须动作：检查后端权限控制和操作日志。
它能被检查：看 Controller、注解、Service 和日志配置。
这类规则才适合写进 .trae/rules.md。
Slide 9-3：若依 rules 检查 Prompt
PPT 页面内容
@workspace 请检查当前 .trae/rules.md 是否适合若依项目。
重点检查：
权限规则
操作日志规则
数据权限规则
前端按钮权限规则
代码生成规则
敏感配置规则
讲师逐字稿
这是让 TRAE 检查若依 rules 的 Prompt。
重点检查权限规则、操作日志规则、数据权限规则、前端按钮权限规则、代码生成规则和敏感配置规则。
要求 AI 先给审查报告，不要直接改文件。
综合实战：团队 .trae/rules.md v0.1
Slide 10-1：若依版 rules.md 结构
PPT 页面内容
若依版 rules.md：
0. 基础原则
1. 安全规则
2. 权限规则
3. 操作日志规则
4. 编码规则
5. 前端规则
6. 测试规则
7. 代码生成规则
8. 不确定性处理规则
讲师逐字稿
今天最终产出是若依版 .trae/rules.md v0.1。
它比通用 rules 多了几个若依特色部分：权限规则、操作日志规则、代码生成规则。
这份 rules 后续可以作为团队后台管理系统 AI 协作规范的基础。
Slide 10-2：若依版 rules 核心条款
PPT 页面内容
核心条款：
前端按钮权限不是安全边界
敏感接口必须检查后端权限
敏感操作必须检查操作日志
列表查询必须考虑数据权限
代码生成结果不得直接上线
不确定内容必须标注
讲师逐字稿
若依版 rules 的核心条款可以浓缩成六句。
前端按钮权限不是安全边界。
敏感接口必须检查后端权限。
敏感操作必须检查操作日志。
列表查询必须考虑数据权限。
代码生成结果不得直接上线。
不确定内容必须标注。
只要这六条落实，AI 在若依项目里的使用风险会明显降低。
Slide 10-3：第 2 天交付物
PPT 页面内容
第 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 页面内容
第 1 天：
用 TRAE 看懂若依
第 2 天：
让 TRAE 按规则参与若依研发
最终能力：
读得懂
问得准
查得实
改得稳
可复用
讲师逐字稿
两天课程到这里形成闭环。
第一天，我们学习如何用 TRAE 看懂若依代码：看结构、找入口、追链路、查依据。
第二天，我们学习如何让 TRAE 按团队规则参与若依研发：组织上下文、控制幻觉、编写 rules、沉淀资产。
最终目标是五个字：读得懂，问得准，查得实，改得稳，可复用。
这就是 AI 编程在企业研发里的真正价值。