# 从项目理解到研发治理

<div class="grid grid-cols-2 gap-8 mt-8">
<div class="p-4 rounded-xl bg-white/5 border border-white/10">

**项目理解：** 让 TRAE 看懂若依代码
</div>
<div class="p-4 rounded-xl bg-emerald-500/10 border border-emerald-500/30">

**研发治理：** 让 TRAE 按团队规则改若依代码

从项目事实到可执行规则
</div>
</div>

<!--
昨天我们使用若依作为真实开源项目，学习了如何让 TRAE 理解陌生代码库。
今天我们进入第二阶段：上下文工程与规则体系。
如果说第一天是“让 AI 看懂若依”，今天就是“让 AI 按团队规则分析、修改和检查若依”。
当团队多人都使用 AI 时，必须有统一上下文、统一 rules、统一验收标准，否则 AI 会带来不一致甚至风险。
-->

---

# 若依场景下的团队规则问题

<div class="mt-6 text-sm">

**若依类后台项目常见风险：**
- 绕过权限，页面直接调接口
- 按钮权限当安全边界
- 接口缺少权限注解
- 操作日志缺失
- 代码生成后直接上线
- 敏感信息进入日志
</div>

<!--
若依这类后台系统，最容易出现的问题不是页面不好看，而是权限、日志、接口边界和生成代码质量。
AI 可能在页面里直接新增接口调用；只做前端按钮隐藏；没有检查后端权限注解；新增敏感操作但没有操作日志；用代码生成器生成 CRUD 后直接上线。
今天要把这些隐性开发要求写规则，让 TRAE 在后续协作中长期遵守。
-->

---

# 上下文、规则与资产

<div class="grid grid-cols-3 gap-6 mt-10">
<div class="text-center p-4 rounded-xl bg-blue-500/10 border border-blue-500/30">
<div class="text-2xl mb-2">🎯</div>
<div class="font-bold">上下文</div>
<div class="text-xs text-gray-400">决定 AI 看什么</div>
</div>
<div class="text-center p-4 rounded-xl bg-emerald-500/10 border border-emerald-500/30">
<div class="text-2xl mb-2">📏</div>
<div class="font-bold">规则</div>
<div class="text-xs text-gray-400">决定 AI 怎么做</div>
</div>
<div class="text-center p-4 rounded-xl bg-amber-500/10 border border-amber-500/30">
<div class="text-2xl mb-2">📦</div>
<div class="font-bold">资产化</div>
<div class="text-xs text-gray-400">决定团队怎么复用</div>
</div>
</div>

<!--
今天仍然是三个关键词。
上下文决定 AI 看什么：看整个若依项目，还是只看用户管理模块，还是只看某个 Controller。
规则决定 AI 怎么做：不能绕过权限、不能遗漏操作日志、不能把前端权限当安全边界。
资产化决定团队怎么复用：好的 Prompt、rules、报告模板都应该进入团队资产库。
-->

---

# 上下文工程流程

<div class="grid grid-cols-4 gap-3 mt-6 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">
<div class="font-bold mb-1">1. 组织上下文</div>
<div class="text-xs text-gray-400">把任务、范围、文件和验收讲清楚</div>
</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">
<div class="font-bold mb-1">2. 收集证据</div>
<div class="text-xs text-gray-400">让 TRAE 先找文件、函数、注解和调用链</div>
</div>
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">
<div class="font-bold mb-1">3. 写成 rules</div>
<div class="text-xs text-gray-400">把隐性要求变成可执行约束</div>
</div>
<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">
<div class="font-bold mb-1">4. 资产化复用</div>
<div class="text-xs text-gray-400">沉淀 Prompt、清单、模板和验收标准</div>
</div>
</div>

<div class="mt-6 p-4 rounded-xl bg-white/5 border border-white/10 text-sm">
<strong>任务产物：</strong>围绕若依“用户管理删除权限”完成证据审查，并形成可落地的 <code>.trae/rules.md v0.1</code>。
</div>

<!--
第二天的训练不是单独讲规则，而是按真实工作流推进。
先把任务上下文讲清楚，再让 TRAE 收集证据，然后把证据转成规则，最后沉淀成团队资产。
今天我们用一个贯穿案例：用户管理删除权限。
学员最后要拿走的不只是 Prompt，而是一套能复用的 rules、检查清单和验收模板。
-->

---

# 模块 1：任务上下文为什么必须明确？

<div class="mt-6 p-4 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">

**模糊任务：** 帮我优化用户管理模块

**问题：** 目标不清 · 范围不清 · 约束不清 · 输出不清 · 验收不清
</div>

<!--
在若依项目里，如果你直接问“帮我优化用户管理模块”，AI 很难给出可靠结果。
优化什么？权限？接口？页面？表单？数据权限？操作日志？代码结构？测试？
范围不清，AI 就会自由发挥。
所以若依这种后台系统，更需要上下文工程。
-->

---

# 好任务五要素

<div class="mt-8 text-center">
<div class="inline-block p-4 rounded-xl bg-blue-500/10 border border-blue-500/30 px-8 text-lg font-bold">
好任务 = 目标 + 范围 + 约束 + 输出格式 + 验收标准
</div>
</div>

<!--
一个合格的 AI 编程任务，必须包含五要素。
目标：到底要分析或修改什么。
范围：只看哪些模块，不看哪些模块。
约束：不能做什么，必须遵守什么。
输出格式：报告、表格、代码 diff、测试用例。
验收标准：什么结果算合格。
这五项越清楚，AI 输出越稳定。
-->

---

# 贯穿案例：用户管理删除权限审查

<div class="grid grid-cols-2 gap-5 mt-6 text-sm">
<div class="p-4 rounded-xl bg-blue-500/10 border border-blue-500/30">
<div class="font-bold mb-2">业务动作</div>
<div>管理员在用户管理页面删除用户。</div>
<div class="text-xs text-gray-400 mt-2">前端按钮、接口调用、后端权限、操作日志都会被牵连。</div>
</div>
<div class="p-4 rounded-xl bg-emerald-500/10 border border-emerald-500/30">
<div class="font-bold mb-2">训练目标</div>
<div>让 TRAE 不凭印象判断，而是按证据给出风险、修改建议和验证方式。</div>
</div>
</div>

<div class="mt-5 text-sm">

| 审查点 | 必须找到的证据 |
|---|---|
| 前端按钮 | 页面路径、权限字符、按钮显示判断 |
| 后端接口 | Controller 方法、权限注解、请求路径 |
| 操作审计 | 日志注解、操作类型、异常路径 |
| 验证方式 | 无权限账号、正常账号、日志查询 |

</div>

<!--
后面所有 Prompt 和 rules 都围绕同一个案例展开。
用户管理删除权限很适合教学，因为它同时涉及前端按钮权限、后端接口权限、操作日志和验证方式。
我们不是让 AI 泛泛讲安全，而是让它在这个动作上找证据。
-->

---

# 若依坏 Prompt 示例

<div class="mt-6 p-4 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">

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

问题：权限包含页面权限、按钮权限、接口权限、数据权限。"有没有问题"太泛。
</div>

<!--
这个 Prompt 看起来合理，但其实太大。
“权限”包含页面权限、按钮权限、接口权限、数据权限。
“有没有问题”也太泛：是安全风险、实现缺陷、配置问题，还是调用链路不清？
没有范围，没有约束，没有输出格式，也没有验收标准。
-->

---

# 若依好 Prompt 示例

<div class="mt-4 p-4 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">

```
@workspace 请分析若依"用户管理页面按钮权限"的调用链路。
范围：只分析用户管理页面的新增、修改、删除按钮权限。
约束：不修改代码；结论标注文件和函数；区分前端权限和后端接口权限。
输出：表格。
验收：覆盖按钮、权限字符、前端判断、后端接口、权限注解、不确定点。
```

</div>

<!--
这个 Prompt 就清楚很多。
目标是用户管理页面按钮权限，不是整个权限系统。
范围限定新增、修改、删除按钮。
约束要求不修改代码，结论标注文件和函数，区分前端权限和后端权限。
验收标准要求覆盖按钮、权限字符、前端判断、后端接口、权限注解和不确定点。
这就是合格任务。
-->

---

# 上下文包模板

<div class="mt-4 p-4 rounded-xl bg-blue-500/10 border border-blue-500/30 text-sm">

```md
任务：审查若依用户管理删除权限是否完整
范围：用户管理页面、用户 API、后端用户 Controller/Service、操作日志相关代码
不做：不要修改代码；不要输出泛泛安全建议；不要猜测未看到的实现
必须标注：文件路径、函数/方法名、权限字符、注解、无法确认项
输出：证据表 + 风险判断 + 修改建议 + 验证步骤
验收：至少覆盖前端按钮、后端接口、权限注解、操作日志、无权限访问验证
```

</div>

<!--
这是今天反复使用的上下文包模板。
真实工作里，不要只把一句话丢给 AI。
先把任务、范围、不做什么、必须标注什么、输出格式和验收标准写清楚。
这能显著减少 AI 自由发挥。
-->

---

# 上下文组织清单

<div class="mt-6 text-sm">

| 要素 | 说明 |
|------|------|
| 目标 | 到底要分析或修改什么 |
| 范围 | 只看哪些模块 |
| 输入文件 | 提供哪些文件 |
| 约束 | 不能做什么 |
| 输出格式 | 报告/表格/diff |
| 验收标准 | 什么结果算合格 |
| 不确定点 | 需要人工判断的 |

</div>

<!--
以后大家在若依项目里使用 TRAE，可以先填这张清单。
比如分析角色权限保存链路，需要提供角色页面、角色 API、后端角色 Controller、Service、菜单关系表、操作日志相关代码。
同时要约束 AI：不要改代码，不要猜，不要把按钮权限当安全边界。
-->