设计文档从不撒谎一次算子检视抓出的四层偏差【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills设计与代码一致靠读起来差不多判断迟早翻车。本文复盘一次算子检视两轮 review 都说一致最终抓出四个偏差。从最响到最无声的四层偏差地图配可直接抄走的对照模板读完即可上手检视。某次检视对象是一个融合 Softmax 算子。代码已经过两轮 review结论栏都写着与设计一致。检视者没有急着 grep而是先问自己一个问题如果这里真有偏差它会藏在哪一层这个问题决定了后面三个小时的动作。偏差是有响度的。有的偏差很响编译期或肉眼就能暴露有的偏差完全无声——字段名全对、单测全绿、review 全过直到线上数据把问题炸出来。把常见偏差按响度从高到低排成一张风险地图就是本次检视的路线架构 → 分支 → 数据流 → 参数语义。越往下走偏差越贵。先对架构四件事响的偏差一眼定生死结论先行Kernel 类型、硬件单元、流水线模式、存储层级四件事只要错一件直接定性方案不一致后面逐细节比对全部可以停。为什么架构是方向方向错了细节越对错得越远——把__vector__内核写成__global__或声称 AIC-AIV 协同却只用 Vector这类偏差不需要证据链看一眼就足够。怎么做把设计文档里的架构声明抄成四行卡片逐行到代码里找对应物找不到就问一句这个声明去哪了。架构要素设计声明代码实际判定Kernel 类型__vector__单核__vector__✅硬件单元Vector 为主Scalar 辅助同左✅流水线模式同步流水同步✅存储层级GM→UB→GM同左✅怎么看这张表四行全绿只代表方向没跑偏它回答不了细节对不对。本次检视第一层全过但这恰恰是最常见的误判来源——很多人认为架构过了就等于全过于是收工。真正的坑在下一层。分支被剪了一刀文档里承诺过的东西去哪了结论先行设计文档里每个 if/else、每个分支场景表代码里必须逐格找得到对应处理缺一格就是偏差不能因为这个场景没人用放行。为什么分支往往藏在文档小节的深处——比如精度策略里三行小字写着 bf16/fp16/fp32 三档——读代码的人默认都是 Cast不都一样嘛剪掉一档毫无知觉。怎么做把文档分支抄成矩阵一行一档每档去代码里找证据找不到的标红。分支条件设计有实现有状态bf16✅❌缺失fp16✅✅一致fp32✅✅一致本次检视就在这里抓到第一个偏差设计明确分三档精度实现只有两档。它能活过两轮 review是因为统一走了一条 Cast 路径小 shape 下行为完全一致。这张矩阵的作用就是把文档承诺过但代码里消失的东西变成可见的一行红字——它不依赖实现者的自觉只依赖表格的完整。数据流被换道跟着伪代码走别跟着代码走结论先行以设计的伪代码为路线图追踪数据流GM→搬运→计算→搬运→GM每一步的搬运 API 与中间存储位置都要对得上不要跟着代码走代码会给你一种确实在搬数据的错觉。为什么换 API 通常不是孤立的——设计用DataCopyPad对齐搬运实现改成DataCopy加手动边界边界分支就得自己补补错一处尾部数据悄悄被覆盖。怎么做把伪代码逐行映射成一张搬运链路表每行注明存储位置、API、同步点。步骤设计伪代码实现代码判定输入搬运DataCopyPad(dst, src, 对齐长度)DataCopy 手动边界⚠️块内计算UB 上按块计算同左✅块间同步sync同左✅输出回搬整块写回 GM同左✅怎么看这张表它强迫你回答每一步到底在哪搬、用什么搬。手动边界的分支只在 shape 非对齐时才触发单测若只用整倍 shape这条路径一辈子跑不到——这不是巧合而是本次检视第二个偏差的成因边界条件写错尾部数据被覆盖而测试完全没有覆盖到。参数换皮名字还在语义已经换了人结论先行参数名还在不等于语义还在。检查同名参数必须看值是怎么算出来的警惕一切有参数但无逻辑的实现。为什么这是最贵的一类偏差字段名与 TilingData 完全对得上review 查名字、单测查行为都查不出来只有跑大数据量或性能基线时才现形。怎么做把 TilingData 每个字段做成三列——设计语义、实现取值、取值怎么算出来的——逐个追算不许只看字段名。字段设计语义实现取值判定blockNum分块数量按 shape 推导正确推导✅tileLength单块长度循环分多块直接等于输入全长❌对齐策略按 32B 对齐处理尾部无尾部分支⚠️本次检视最贵的发现就在这里tileLength字段在实现却把它直接赋成输入全长分块循环只执行一次——有参数、无分块。单测全绿因为单测从没把性能是否符合设计纳入断言。这一条最终把整个检视定级为部分一致。偏差定级不是所有偏差都要改代码结论先行先定级再处置别把检视变成情绪劳动。判定规则只有三条评级判定条件处置建议一致四层全绿无需干预部分一致架构通过偏差不超过 3 处且非核心修偏差或更新文档对齐实现不一致架构不符或偏差超过 3 处按设计重构或重估设计可行性怎么用定级的目的不是打标签而是决定下一步动作的成本归属——改代码、改文档、还是重新评估方案。本次检视两处 ⚠️、一处 ❌处置是修复偏差并补上非对齐 shape 的单测。自动化验证兜底但不兜全。CI 里的检查任务全绿、单元测试全过只代表测过的用例没炸不代表与设计一致——偏差经常是带着绿勾回家的因为它们不在单测覆盖的 shape 里也不在参数名的字典里。仓库里这类实践其实早已制度化skill 入库前由 cannbot-skill-reviewer 跑结构门禁与质量评分需求分析文档则按 需求分析模板 把结构契约与判定依据写死并用摘要核对传递内容不被篡改——文档与代码的一致性被当成一条可执行的流水线在对待。下一步现在就做三件事挑一个手头的 design code按四层地图走一遍把结果落成一张速查表十分钟内必有发现。把分支矩阵和参数语义三列两张模板抄进团队 review checklist让一致性成为门禁而不是自觉。把检视结论写进文档的修订记录别让下一次检视从零开始。常见误判自检清单误判单测通过 一致单测只证明测过的用例没炸。误判参数名对得上 语义对去看值是怎么算出来的。误判代码短 没毛病分块变全长往往就是一行赋值的事。误判架构没错 全对架构只覆盖最响的那一层。误判文档没写 不算数文档没写不等于实现可以对。设计文档说的是打算怎么做代码说的是实际怎么做检视者的全部工作就是让这两句话逐字对齐——因为从设计到代码之间那个唯一的缝隙名字叫人。【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考