当代码和设计文档"闹分手"，来一次设计一致性检视

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

先讲一个真实到有点扎心的现场：设计文档里白纸黑字写着"半精度输入、全精度累加，数据用异步流水线搬运"，可等有人把实现代码翻了个底朝天，却发现累加器用的是半精度，流水线是同步的，搬运路径上还莫名其妙多了一层拷贝。再一查提交记录，这个状态已经悄悄活了三个星期——期间 UT 跑过、静态检查过、CI 也绿过，愣是没人察觉。

更离谱的是，拿着证据去找写代码的同事，对方一脸无辜："我照着文档写的啊。"你把文档翻到修订记录，才发现它改过三版，正文却一直停留在最初那套架构方案上。

没错，代码和文档都在"按时交付"，但从来没有真正对齐过。这正是设计一致性检视要解决的问题：不是等出了事故再去追责，而是主动给"想做的"和"做出来的"做一次对账。下面从一个翻车现场出发，拆解脱节的病根，再带你从宏观到微观，把算子彻底"体检"一遍。

病根都在哪？脱节从来不是故意的

先说结论：没有哪个开发者是存心跟文档对着干的，但偏差一定会发生。原因翻来覆去，无非这三条。

第一，文档是"写出来"的，不是"活着的"。方案评审通过的那一刻，设计文档往往就完成了它的历史使命，再没人维护。代码这边两轮重构、三轮性能优化改得热火朝天，文档那边还停留在最初的架构，偏差就这么悄悄生了根。所以很多"不一致"，本质上是一份过期的文档对着一套新写的代码。

第二，接口理解出现了"翻译偏差"。设计文档写"用 Mmad 完成矩阵乘累加"，实现的时候，因为对 API 语义拿不准，或者嫌麻烦，就用 Mul 加 ReduceSum 凑合。乍一看功能差不多，可指令数、精度行为、寄存器压力完全是两码事。这种偏差最阴险——它不报错、不崩溃，只有你把 API 逐个摆在一起对照，才看得出端倪。⚠️

第三，参数名还在，语义却被"架空"了。文档里定义了 TilingData 的分块大小，代码里也确实声明了这个参数——但实现图省事，直接把分块大小设成了全长，等于参数只是个摆设，分块逻辑压根不存在。这类问题最坑人：你用 grep 搜参数名，一切正常；只有追着"这个值到底是怎么算出来的"一路问下去，真相才浮出水面。

把这三条摆在一起你会发现，脱节不是某个人的失误，而是流程里缺少一道"对账"的工序。所以别赌运气，把它当成系统性问题来对待。

先看骨架，再看血肉，最后抠细节

想高效地揪出偏差，别上来就逐行读代码——那就像体检一进门就查血常规，大概率白忙活。正确的姿势是分三个维度递进：先看骨架，再看血肉，最后抠细节。

第一层：看骨架，判断"方案本身对不对"

拿到实现的第一眼，先回答四个大问题，别管细节：

• Kernel 类型对不对？文档写的是__vector__，实现是不是真的落在 Vector 单元上，还是悄悄换成了__global__？
• 硬件单元分对了吗？Cube、Vector、Scalar 各司其职，还是把本该给 Cube 的活压给了 Vector？
• 流水线模式吻合吗？该异步的地方是不是被改成了同步，AIC-AIV 协同是不是被拆散了？
• 存储层级对得上吗？L1、L0、CO1、UB 各归各位，还是中间数据被放错了楼层？

这一层如果就不对，千万别再往下逐行较真——骨架歪了，细节越精确越离谱。这种偏差直接定性为"方案不一致"，返工比重写更划算。

第二层：看血肉，验证"该走的路都走了"

骨架没问题，接下来盯两条线。

一条是分支覆盖。把设计文档里所有 if/else 和场景分支列出来，逐个去实现里找对应处理。文档说"bf16 和 fp16 都要支持"，代码里只剩 fp16，那就是缺失；反过来，代码里多出一条文档压根没提的分支，也可能是实现者自己加戏，得问一句"这条分支哪来的"。

另一条是数据流。挑一个关键张量，跟着它从输入 GM 出发：搬运、计算、再搬运、写回输出 GM，每一步用的搬运 API、暂存的楼层都要和文档对得上。同样的数据，被放进 UB 还是 L1，性能和精度可能天差地别。

第三层：抠细节，把参数语义和约束红线翻个底朝天

到了这一层，看的就是诚意了。

• 同名参数，语义必须一致。文档里的"分块大小"和代码里的"分块大小"名字一样，不代表是一回事——要追问：这个值到底怎么算出来的？是真切了块，还是整个数组一把梭？
• 伪代码逐行对账。把设计文档里的伪代码当成剧本，一行一行去实现里找演员。缺了哪一行？哪一行被悄悄换了实现？同步操作、循环结构有没有错位？
• 约束红线不能碰。文档明令禁止的 API，grep 一下有没有破例；中间精度、Cast 的 RoundMode 这些精度管理细节，也得和文档一一对上。

三层走完，一次完整的设计体检基本就到站了：宏观定方向，中观查覆盖，微观核语义。

一套能揣兜里的检视心法 💡

道理归道理，最后给你一套直接能上手的东西——"五个自问"加"三句箴言"。

每次动手前，先默念一遍这五个问题：

• 我确认过 Kernel 类型和硬件单元，和文档一致吗？
• 文档里的每个分支场景，代码里都有对应处理吗？
• 文档指定的 API，代码里真的是这么调的吗？RoundMode、数据布局这些参数也对得上吗？
• 关键张量从输入到输出的每一步，我都能说清楚吗？
• 每一个同名参数，我是不是真的验证过"值是怎么算出来的"？

再记住三句箴言：

• "先看骨架，再查血肉，最后抠细节。" —— 顺序错了，效率至少砍半。
• "参数存在，不等于语义一致。" —— 名字只是表象，算法才是真相。
• "文档禁止的，一个都不许碰；文档要求的，一个都不能少。"

还有一条加分项：把对账结论落到数据上。检视不是纸上谈兵，跑一遍基准测试，让性能曲线和精度数据做最终裁判——文档和代码再能吵，数字不会说谎。比如在 CANNBot 的算子开发记录里，就能看到这样的对账痕迹：设计文档评审通过、构建通过、测试全绿，一次一致性对账才算走完闭环。

检视不是找茬，而是对齐

说句掏心窝的话，检视这件事最容易被误解成"找茬"。写文档的人担心被挑毛病，写代码的人觉得被质疑能力，气氛一紧张，对账就变成了辩论赛。

但换个角度看：写文档的人需要确认自己的设计真的落了地，写代码的人需要确认自己的每一步都有依据——这本是一场让"想"和"做"重新接上信号的握手。检视不是零和游戏，它的本质是对齐。

给你三条今天就能开始的动作 📌：

1. 把设计文档当"活文档"维护。每次代码变更，顺手更新受影响的段落，哪怕只改一行描述，也好过让它烂在评审会上。
2. 把对账变成固定动作，而不是应急动作。给自己定一个周期性的"对账时间"，跑一遍那五个自问，别等问题爆了才想起检查。
3. 让数据参与评审。文档和代码各说各话时，用基准测试和精度对比做最终裁决，白纸黑字的数字比任何解释都有说服力。

最后留个问题给你：上一次发现代码和文档对不上，你是在提交前抓到的，还是被线上问题逼出来的？想清楚这个答案，你对"对齐"的理解可能会不一样。

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