ai-proj-helper/skills-req/req-test-gate-plugin/skills/convention-flow.md

Convention Flow — 约定建立流程

核心理念

每个 bug 都是一个建立约定的机会。 修复 bug 后，立即将教训固化为自动化检测，防止同类问题再次出现。

流程总览

Step 1: 修 Bug          → 标准修复，代码层面解决问题
    ↓
Step 2: 文档化约定      → 写入 CLAUDE.md（让 AI 和人都知道这条规则）
    ↓
Step 3: 自动化检测      → 创建 scripts/check-*.sh（让 CI 自动阻止违规）
    ↓
Step 4: 记录追踪        → 创建【约定】任务关联需求（仅 /req cr 自动触发时）

Step 1-3 是核心流程（手动和自动都执行）。Step 4 仅在 /req cr 自动触发时执行，用于在 ai-proj 中留痕。

Step 1: 修 Bug

标准的 bug 修复流程。此步骤无特殊要求。

Step 2: 文档化约定

在项目的 CLAUDE.md 中添加约定段落，格式参见 harness-engineering.md 的「CLAUDE.md 约定文档格式」。

必须包含：

• 原因描述（为什么这是个问题）
• 一句话规则
• 正例和反例代码
• 检查命令

Step 3: 自动化检测

创建 scripts/check-{name}.sh 脚本：

1. 扫描代码库查找违反约定的模式
2. 输出违规文件和行号
3. 支持 --ci 模式（退出码 0/1）
4. 零违规时输出 PASSED 消息

Step 4: 记录追踪（自动触发时）

当 convention flow 由 /req cr 自动触发时，产出物必须关联到当前需求：

ai-proj task create --title "【约定】{约定名称}"
ai-proj req link --id <req_id> --task-ids <task_id>   # linkRole=documentation
ai-proj create-and-attach --id <task_id> --content "..."  # 约定详情文档

约定详情文档内容：

## 约定: {名称}

| 字段 | 值 |
|------|-----|
| 来源需求 | REQ-XXXX |
| 触发 bug | {bug 描述} |
| 根因模式 | {代码模式} |
| 策略 | {hard wall / ratchet(N)} |
| 现有违规 | {N} 处 |

### 产出物
- CLAUDE.md 约定段落: ✅ 已添加
- 检测脚本: `scripts/check-{name}.sh` ✅ 已创建
- 首次运行结果: PASS

### 约定规则
{规则内容，与 CLAUDE.md 中一致}

这样在需求归档时能看到：这个 bug 不仅被修了，还产出了一条防止复发的约定。

Commit 策略

Convention flow 的产出物（CLAUDE.md 修改 + scripts/check-*.sh 新脚本）必须单独提交，不与 bug fix 代码混在一起：

# 1. Bug fix 已经提交
git add src/...
git commit -m "fix: 修复 Modal 重叠导致弹窗无法关闭"

# 2. Convention 产出物单独提交
git add CLAUDE.md scripts/check-modal-safety.sh
git commit -m "chore: 建立 Modal 安全约定和自动检测"

原因：

• bug fix 可能需要 cherry-pick 到其他分支，约定脚本不应跟着走
• 约定提交的 review 焦点不同（规则是否合理 vs 代码是否正确）
• git log --oneline scripts/ 可以快速看到所有约定建立历史

可检测性判断

/req cr 自动触发时，AI 必须先判断 bug 根因是否能自动检测。判断标准：

可检测（建议约定） — 根因是一个代码模式，能用 grep/regex 在源码中匹配：

模式类别	示例	grep 可行性
API 误用	Modal.success() 后直接 setState	grep Modal.success + 上下文检查
禁止导入	handler 直接 import database 层	grep import 路径
缺失守卫	SQL 拼接而非参数化查询	grep 字符串拼接模式
遗漏回调	Promise 无 .catch()	grep .then( 无配对 .catch
硬编码	密钥/密码直接写在代码中	grep 常见密钥模式

不可检测（仅记录根因） — 根因是逻辑/设计问题，代码形态上看不出来：

模式类别	示例	为什么不行
算法错误	排序方向反了、边界条件漏了	代码语法正确，逻辑错误
业务规则遗漏	退款应该校验订单状态但没校验	缺失的代码无法被 grep
竞态条件	两个请求并发修改同一资源	需要运行时才能暴露
配置错误	环境变量填错、超时值设太小	值的正确性取决于上下文

快速判断法：问自己「能不能写一条 grep 命令找到所有同类问题？」能 → 可检测，不能 → 不可检测。

选择策略

修完 bug 后，根据当前违规数量选择不同策略：

现有违规数	策略	脚本类型	说明
0	Hard wall	纯检测脚本（有 → FAIL）	刚修完最后一个违规，或首次建立
1-10	Ratchet + 排期清理	Ratchet 脚本 + 基线	创建任务逐一清理遗留
>10	Ratchet only	Ratchet 脚本 + 基线	不立即清理，仅防止恶化
不可计数	仅检测/告警	告警脚本（exit 0）	如"代码风格"类软约定

实例 1: Modal 安全规则

Bug：Ant Design Modal.success() 非阻塞，后续 setState 立即执行导致两个 modal 重叠，第一个无法关闭。

Step 1 — 修 Bug： 将 setNextModalOpen(true) 移入 onOk 回调。

Step 2 — 文档化： 在 CLAUDE.md 添加：

### Frontend: Modal 安全规则

Ant Design 的 `Modal.success()` / `Modal.info()` 是**非阻塞**调用。

**规则：`Modal.success/info/warning/error` 之后如果还有 UI 操作，必须放在 `onOk` 回调中。**

// WRONG — 两个 modal 同时弹出
Modal.success({ title: '成功' });
setNextModalOpen(true);

// CORRECT — 等用户确认后再打开
Modal.success({ title: '成功', onOk: () => setNextModalOpen(true) });

**检查命令**：`./scripts/check-modal-safety.sh`

Step 3 — 自动化： 创建 scripts/check-modal-safety.sh：

• 扫描 .tsx 文件中的 Modal.success/info/warning/error 调用
• 检查 25 行内是否有 onOk 回调
• 如果没有且后续 20 行内有 set*Open(true)，标记为违规
• 策略：现有违规 = 0 → Hard wall

实例 2: 架构层级约束

问题：Handler 直接调用 database 层，绕过 service 层导致业务逻辑散落。

Step 1 — 识别问题： 发现 108 个 handler 直接 import database 的文件。

Step 2 — 文档化： 在 CLAUDE.md 和 docs/architecture/LAYER_RULES.md 中描述依赖矩阵和正反示例。

Step 3 — 自动化： 创建 scripts/check-architecture.sh（ratchet 脚本）：

• 5 条规则，3 个 ratchet + 2 个 hard wall
• 基线记录各规则的当前违规数
• 策略：遗留 108 个 → Ratchet（只能减不能增）

执行流程

自动触发（/req cr + bug 类需求）

触发条件（满足任一）：

• category == bug
• category 为空但标题含 fix、修复、bug、问题、缺陷
• category 为空但 description 含 根因、复现步骤

1. /req cr 五视角扫描完成后
2. 检测是否为 bug 类需求（按上述条件判断）
3. 分析本次 bug 的根因模式（从 git diff 提取）
4. 判断：根因是否可自动检测？（判断规则见上方「可检测性判断」）
   - 不可检测 → 仅在 CR 报告记录根因，不建议约定 → 结束
   - 可检测 → 继续下一步
5. 检查是否已有覆盖此模式的脚本：
   - ls scripts/check-*.sh，读取每个脚本的注释头（# ... detects ...）
   - 已有覆盖 → CR 报告记录「已有约定: check-{name}.sh」→ 结束
   - 无覆盖 → 继续下一步
6. 扫描代码库统计同类模式的现有数量（N）
7. AskUserQuestion（按 N 值调整措辞）：
   - N=0:  「此 bug 模式已修复，当前代码无同类问题。建立约定可防止未来复发，是否建立？」
   - N>0:  「代码库中还有 {N} 处同类模式。建立约定可防止恶化 + 逐步清理，是否建立？」
   - 否 → 记录到 CR 报告「约定建议：用户跳过」
   - 是 → 执行 convention flow（Step 2 + Step 3 + Step 4）
8. 约定产出物关联到当前需求（Step 4）
9. 约定检查结果写入 CR 报告

手动触发（/harness convention [name]）

1. 询问约定名称和类别（如果未提供）
2. 分析刚修复的 bug，提取约定规则
3. 扫描代码库统计现有违规数量
4. 根据违规数量选择策略
5. 生成 CLAUDE.md 约定段落
6. 生成 scripts/check-{name}.sh 脚本
7. 运行脚本验证（应该 PASS）
8. 输出摘要：约定名称、策略、违规数、文件清单