代码和设计对不上号？试试这套一致性核验漏斗

代码和设计对不上号？试试这套一致性核验漏斗

【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills

设计文档写得明明白白，代码看起来也"挺对"，可一上线就翻车——这是很多算子、模块评审的常态。设计实现一致性检视，就是给这种"假一致"做体检：拿设计文档当基准，逐层核验代码，把偏差找出来并定性。

从一场翻车现场说起

有个算子要过评审。对照设计文档，名字对、接口对、输入输出形状对，你觉得稳了。结果上板一测，UT 挂了一条，性能比基线差三成。定位花了三天，最后发现：设计写的是__vector__逐元素核，代码里却混进了一段__global__的归约逻辑；设计里 bf16 走独立精度分支，代码压根没实现，一路 fallback 到 fp16。

问题不在代码写没写对，而在"代码和设计各说各话"。肉眼擅长发现"有没有"，很难发现"对不对得上"。

上面这种"大部分任务 SUCCESS、唯独 UT_Test 挂掉"的界面你一定不陌生。要避免它，得把"靠感觉对"升级成"按清单核"。

搭一条主线：把检视装进三层漏斗

一致性检视不该是几十个检查项平铺开乱点，而是一个漏斗，从上到下越来越细：

1. 骨架层：Kernel 类型、硬件单元、流水线、存储层级——先看方向对不对。
2. 细节层：分支、API、数据流、参数语义——方向对了，再抠实现细不细。
3. 结论层：约束合规加综合评级——最后给"一致 / 部分一致 / 不一致"的定性。

每一层都有明确的出口规则：骨架层不过关，直接定性，不用再往下比——方向都歪了，细节再像也是徒劳。

先看骨架：四问锁定方向性偏差

打开设计文档的架构章节，只问四个问题，就能完成宏观核验：

💡小贴士：这四个问题十分钟内能查完。先把架构比对做完再碰细节，能省掉一半无用功。

判定规则：骨架层不匹配，直接定性为"不一致"。架构是方向的偏差，逐细节比对没有意义。

再抠细节：用清单兜住漏网之鱼

骨架对上了，进入细节层。这一步的核心是把设计文档变成可勾选的清单，而不是重新读一遍。

用分支矩阵兜住漏网分支

把设计里所有 if/else、switch、场景表整理成矩阵，逐格去代码里找对应处理：

标记两类异常："设计有、代码无"的缺失分支，和"代码有、设计无"的多余分支——后者往往是偷偷加的逻辑，最容易逃过测试。

把 API 清单当对照表用

设计文档的 API 映射章节，就是一张现成的对照表。逐条 grep 代码，核对三点：API 名是否一致、参数细节（RoundMode、数据布局）是否合规、有没有碰禁用接口。

顺着数据流追搬运链路

以设计文档的数据流图为路线图，走一遍"输入 GM → 搬运 → 计算 → 搬运 → 输出 GM"。每一步问三个问题：用什么 API 搬、搬到哪里、中间结果存在哪。设计说用DataCopy搬进 UB，代码却直接引用 GM 地址——性能差往往就是这么来的。

抠参数语义：别只看"有没有"，要看"怎么算出来的"

这是最阴的坑。参数存在，不代表逻辑存在。比如设计里有blockNum字段，你查代码，确实在 TilingData 里声明了——但实现直接把blockNum设为全长，循环一次跑完，分块逻辑是假的。遇到这种情况，要顺着参数的"赋值链路"追到源头，看它到底怎么算出来的。

伪代码逐行映射

设计里的伪代码块是最好的对照物。给每行伪代码找对应的实现行，标记缺失行、替换行和顺序错位行：

# 设计伪代码 for each block in tiling: # 行1：外层按块循环 copy_gm_to_ub(in[block]) # 行2：搬运输入 compute_vector(out) # 行3：Vector 计算 copy_ub_to_gm(out[block]) # 行4：搬回输出

如果实现里"行2"变成了copy_gm_to_gm、"行3"从 Vector 换成了 Cube 指令，逐行对照时一眼就能抓出来。

最后下结论：先查约束，再给评级

细节都核对完，收口做两件事。

第一件，约束合规。把设计文档"关键约束与限制"章节逐条打勾：禁用 API 有没有误用？精度管理策略一致吗（中间精度、Cast 的 RoundMode）？约束是设计的红线，碰了哪怕一条，评级直接降档。

第二件，综合评级。用下面这把尺子下结论：

评级不是终点，处置才是。哪怕只是"部分一致"，也建议当场把偏差记进 issue，别让"先放着"变成"以后没人记得"。

落地一页纸：核验记录表照填就行

把下面这张表打印出来，每次评审照填，十分钟出结论：

综合评级：一致 / 部分一致 / 不一致处置动作：______

避开三个高频翻车现场

反例一：有参数，没逻辑。设计写了blockNum，代码也声明了，评审直接打勾。直到性能不达标回头查，才发现分块逻辑是假的——全程单块跑。核对参数时，永远多问一句"这个值是怎么算出来的"。

反例二：API 同名，语义不同。代码里确实用了设计指定的 API，但用的是默认 RoundMode，设计要求的是RoundMode::CAST_ROUND。名字对、行为错，grep 打勾拦不住，得抠参数细节。

反例三：只对成功路径，忽略退化分支。所有主路径测试都绿了，唯独shape == 1这类边界场景没有分支处理，一触发就崩。分支矩阵的价值，就是把"没测到"变成"没实现"，明明白白摆上台面。

写在最后

一致性检视不是什么高深理论，本质就是把"设计文档说了什么"和"代码实际做了什么"变成一张可以逐格打勾的表。骨架四问把方向定住，细节清单把偏差捞干净，最后用评级和记录表收口。下次再遇到"看着全对"的代码，别急着信眼睛——让漏斗替你说话。

【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills