# 第 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 编程在企业研发里的真正价值。