smart
67837df8d0
- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
113 lines
5.5 KiB
Markdown
113 lines
5.5 KiB
Markdown
# 模块 3：Rule 的设计契约
|
||
|
||
<div class="mt-6 text-sm">
|
||
|
||
Rule 不是“代码要规范”这类口号。
|
||
|
||
一条可执行 Rule 必须说明：它基于什么证据、在哪些场景生效、必须做什么、不能做什么，以及如何验收。
|
||
|
||
</div>
|
||
|
||
<div class="grid grid-cols-3 gap-4 mt-8 text-sm">
|
||
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">来源可信</div>
|
||
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">边界明确</div>
|
||
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">结果可验</div>
|
||
</div>
|
||
|
||
<!--
|
||
逐字稿：Rule 的价值不在于写得严厉，而在于能够被执行和验收。它必须说清来源、适用范围、必须动作、禁止动作和验证方法。否则“代码要规范”这种表述只能表达态度，不能约束 Agent 或开发行为。
|
||
|
||
这里讲的是高级 Rule 编写：从项目事实提取约束，而不是用个人偏好覆盖项目结构。现有 generate-project-constraints Skill 使用了同样的证据分级方法。
|
||
-->
|
||
|
||
---
|
||
|
||
# 先给 Rule 标注证据等级
|
||
|
||
<div class="mt-5 text-xs">
|
||
|
||
| 等级 | 什么时候使用 | 典型写法 |
|
||
|---|---|---|
|
||
| 硬约束 | 配置、构建、CI 或显式规范直接证明 | 必须 / 禁止 |
|
||
| 观察性约束 | 多处源码反复出现，但没有书面规范 | 默认采用 / 优先复用 |
|
||
| 待确认约束 | 对交付很重要，但当前项目无法证明 | 需确认 / 不下结论 |
|
||
|
||
</div>
|
||
|
||
<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
|
||
不要把“一个代码样例”或“通用最佳实践”直接升级成项目硬规则。
|
||
</div>
|
||
|
||
<!--
|
||
逐字稿：Rule 首先要标注证据等级。配置、构建和明确规范能够支持“必须”或“禁止”；多处实现形成的惯例只能写成“优先”或“默认”；当前无法证明但又重要的内容必须保留为待确认。这样可以避免把一段样例代码误写成项目硬规则。
|
||
|
||
证据等级来自现有的项目约束生成 Skill。它能防止一个常见错误：看到一次实现就写成“本项目必须如此”，或者把普适经验伪装为项目事实。
|
||
-->
|
||
|
||
---
|
||
|
||
# 一条 Rule 的六个字段
|
||
|
||
<div class="mt-5 text-xs">
|
||
|
||
```md
|
||
## 状态变更必要信息保护
|
||
|
||
- 级别：观察性约束
|
||
- 适用场景：Service 方法会写入业务状态或释放、占用资源。
|
||
- 必须：在任何写入前校验本次状态变更必需的信息。
|
||
- 禁止：仅依赖前端必填；将条件必填扩大为全表非空。
|
||
- 来源证据：状态更新、资源更新与现有调用链。
|
||
- 验收方式：无效输入被拒绝；正常路径及副作用单独验证。
|
||
```
|
||
|
||
</div>
|
||
|
||
<!--
|
||
逐字稿：这六个字段把 Rule 变成了可运行的约束。注意这里没有把 cancelReason、接口路径或权限码写进去，因为那些会随项目变化。真正可迁移的是：涉及状态写入和资源变更时，要在写入前校验必要信息，并分别验证无效输入和正常副作用。
|
||
|
||
这六个字段使 Rule 能被 Agent 和人共同使用。Rule 中没有写取消原因字段名、接口路径或权限码，因为它们属于项目输入，而不是可迁移的约束本身。
|
||
-->
|
||
|
||
---
|
||
|
||
# 常见的 Rule 失效方式
|
||
|
||
<div class="mt-5 text-xs">
|
||
|
||
| 写法 | 为什么失效 | 改写方向 |
|
||
|---|---|---|
|
||
| “后端要做好校验” | 没有触发点、位置和验收 | 指出状态写入前的必要信息保护 |
|
||
| “所有字段都不能空” | 把条件规则扩大为数据模型规则 | 写清具体状态与字段条件 |
|
||
| “统一使用 Service” | 把架构偏好误当业务约束 | 说明为什么该规则需要覆盖复用入口 |
|
||
| “严格测试” | 无法判断是否满足 | 写出无效输入、正常路径和副作用验证 |
|
||
|
||
</div>
|
||
|
||
<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
|
||
好的 Rule 约束行为，不替人猜业务，也不替项目做架构重写。
|
||
</div>
|
||
|
||
<!--
|
||
逐字稿：Rule 失效常常不是因为方向错，而是因为范围过大或没有验收条件。比如“所有字段都不能空”把条件校验扩大成数据模型规则，“严格测试”又没有说清要测什么。好的 Rule 只约束真正需要保护的行为，不替项目做无依据的架构重写。
|
||
|
||
可以让学员对照这张表检查自己的 Rule。Rule 的力量来自足够具体，但又不携带一个项目的字段名和临时结论。
|
||
-->
|
||
|
||
---
|
||
|
||
# Rule 的验收不是“读起来像规范”
|
||
|
||
<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
|
||
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">能触发<br><span class="text-xs op-70">知道什么时候应用</span></div>
|
||
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">能约束<br><span class="text-xs op-70">必须与禁止清楚</span></div>
|
||
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">能取证<br><span class="text-xs op-70">来源不是主观偏好</span></div>
|
||
<div class="p-3 rounded-xl bg-purple-500/10 border border-purple-500/30">能验证<br><span class="text-xs op-70">可用代码、测试或检查确认</span></div>
|
||
</div>
|
||
|
||
<!--
|
||
逐字稿：一条 Rule 是否进入长期资产，至少看四件事：能否触发、能否约束、能否追溯来源、能否验证结果。任何一项缺失，都意味着它只能作为建议，不能作为默认工作方式。这个门槛能避免资产库逐渐变成个人偏好的集合。
|
||
|
||
这一页可作为 Rule 的质量门禁。只要其中一项回答不上来，Rule 就不应进入长期资产。
|
||
-->
|