📄 本页由源文件
rules/按需-验证行为详细规范.mdc自动投影生成（单一权威源）。请勿直接编辑本页。
按需-验证行为详细规范
从 AI 行为规范精简版移出（2026-05-26）。基线规则见 AI 行为规范 §「验证行为规范」。
跨文件交叉引用必须双向闭环（2026-05-15）
设计原则文档 / 规则文档 / 实施沉淀文档之间，引用必须双向闭环而非单向。判定标准：对每条新增的「A 文档引用 B 文档」，必须同时检查「B 文档是否引用回 A 文档」；自检命令：在 A、B 双方各自 grep 对方的关键标识符，若任一方为空 → 断链待修。
编辑工具假性成功兜底（2026-05-19 ×4 同形 promote）
编辑工具（replace_in_file / multi_replace / edit_file）回报 success 不等于内容真实落盘；grep_search / codebase_search 工具结果存在缓存延迟，不能作为承诺一致性的最终证据。
同形病灶累积：
replace_in_file报 success 但磁盘未变（5/15）multi_replace越权重写整个文件（5/19 早）multi_replace含中文标点 old_string 偶发匹配失败（5/19 晚）grep_search显示零命中但终端 grep 实测全命中（5/19 晚）
强制范式：
- 关键编辑后立即
grep -c "<新增关键词>" <文件>+wc -l <文件>双重验证 - 工具失败 1 次后立即降级换工具（
multi_replace→replace_in_file→edit_file→ 终端printf >> tmp; mv -f），禁止重试同工具同参数 - 含中文标点（
（）/、/""/「」）的 old_string 优先用edit_file占位符模式
批量重命名/全局替换三大陷阱（2026-05-21 ×5 同形 promote）
批量替换/重命名场景中，连环 bash 命令存在三类独立陷阱常导致假性成功：
① 链式 sed + [[ ]] && mv 短路判断
一行 bash 串多个 sed + grep + 条件判断 + mv 时，终端回显被截断 + 短路链使 mv 静默跳过，但前置 echo "✅" 仍执行 → 误判落盘。
强制：改用 sed -i ''（macOS 语法）单文件单行命令。
② grep -c 子串污染
grep -c "issue-trace" 同时匹配 "issues-trace"（子串），DIFF_AFTER 报告值不可靠。
强制：只看残留旧名命中数（应为 0），不依赖新名命中数。
③ wc -l 终端渲染伪影
wc -l < file.txt 报告非 0 数字但 cat 显示空文件，是终端缓冲区残影。
强制：用 ls -la 看 size 字节数 + hexdump -C file | head 二进制视图 + file file 三重物理事实兜底。
SOP
备份 → 双向扫描原始引用点（旧名 + 新名兜底）→ sed -i '' 单文件单行替换 → ls/hexdump 物理验证 → 双向 grep 实测（旧 0 + 新 N）→ 跑回归。
感知类效果不做自建验证（2026-09-20 事故复盘）
事故：为确认 Select「面板样式 / 图标切换过渡」两个纯视觉问题，AI 自建「临时入口页 + CDP 驱动无头 Chrome + 动态挂载演示页」完整验证链路，连续 6 轮以上脚本迭代（端口冲突、public 下 HTML 不走 Vite 转换、无头环境路由异常、用例传 show-arrow=false 取不到目标元素……），单轮 30 秒以上，累计数十次工具调用；最终结论仍是「我这边无法复现，需你确认」——与直接询问用户收益相同，成本却高出两个数量级。
验证分流表：
| 验证对象 | 手段 | 上限 |
|---|---|---|
| 编译 / 类型 / 规范 | lint、type-check、grep、读代码 | 不限（廉价） |
| 逻辑行为（DOM 存在性 / 状态机 / 事件） | 单测（vitest + test-utils） | 一轮；失败即改断言，不加设施 |
| 样式 / 动画 / 布局 / 视觉 / 手感 | 不做自建验证：说明预期 + 交用户目视 | 0 |
熔断阈值（硬）：
- 同一验证目标连续失败 2 次 → 停止，立即降级
- 为验证同一问题新增验证设施达 3 次工具调用仍无结论 → 停止
- 需要「起浏览器 / 起额外 dev server / 造临时入口页」级设施时，先自问：能否直接让用户看？能则不发车
交付话术模板：
该效果属目视验证项，我无法自证。预期表现：{具体现象}。请你在 {页面} 按 {步骤} 确认，不符请反馈 {截图 / 描述}。
临时文件纪律：验证用临时文件（入口页 / 脚本 / 测试桩）统一放 /tmp/，禁止落在用户工作区；确需落在工作区时，任务收尾必须立刻删除（2026-09-20 事故中曾在项目根、tests/、public/ 散落 4 个临时文件）。