Design Docs Are All You Need：技术学习文档

性能模型夹在两个高速变化层之间：上层模型架构不断出现 MoE、潜在注意力、异构推理阶段；下层加速器、内存层级和互连也持续变化。任何“当前看起来合理”的抽象，都可能很快失效。

论文的做法是定期重新计算 C = G(S)，不把旧实现 Ct 喂给下一轮，从流程上切断补丁历史。这里的“债务归零”是一个研发过程定义：它消除了由旧代码作为额外输入产生的偏差，但不会自动消除规格本身的错误、生成器随机性或验证盲区。

来源：PDF 第 1-2 页，公式（1）及 Introduction。

来源：PDF 第 2-3 页，Figure 1 与 Cost and iteration speed。成本是作者当时实践数据，不应外推为固定价格。

主分支几乎不保存实现代码，而是保存可以组合成有向无环图的 Markdown 文档。依赖顺序由内容决定，例如拓扑和数值类型必须先于集合通信成本，后者又必须先于模型目录。

来源：PDF 第 2-3 页，Design docs as the source of truth。

高层规则像“宪法”，能约束结构，却不一定固定细节语义。论文强调补上一种自底向上的表达：逐步工作示例。它既是人类可读的解释，也是生成 Agent 的上下文示范。

实用判断：如果读者只能“理解大意”，却不能拿纸笔复演出中间状态和最终值，这份文档仍不足以作为可再生代码的规格。

来源：PDF 第 3 页，An opinionated way of writing design docs。

稳定再生成要求被描述的系统足够小、正交且不随架构变化频繁改形。SMART 将模型压缩为一种递归操作 Op：内部节点表达循环或子图，叶子节点表达硬件可定价的原子动作。

Op
├─ inputs  : List[Tensor]          # 符号形状
├─ outputs : List[Tensor]
├─ cost    : OpCost                # compute / memory / comm 的 SymPy 表达式
├─ rrt     : ResourceReservation   # 资源 × 周期占用表
└─ params
   ├─ InnerLoop(n_iter, body)      # 带迭代次数的循环
   ├─ GraphParams(graph)           # 普通子图
   └─ LeafParams(...)              # 系统定价叶子

解耦结果：替换注意力算法主要改模型文档；替换互连或加速器代际主要改系统定价文档。递归结构不需要跟着每个模型家族重写。

来源：PDF 第 3 页，A minimal symbolic IR 与 The Op abstraction。

模型作者不直接手写 Op 树，而是在轻量 Python 内嵌 DSL 中写出可追踪的计算。装饰器 block 形成命名子图；两类 loop 则保留并行与归约语义。

@smart_map_loop(n_iter = Tq / q_block)
def each_query_block():
    q_tile = load(q)
    acc = load(initial_value)

    @smart_loop(n_iter = Tkv / kv_block)
    def reduce_over_kv(acc):
        k_tile, v_tile = load(k), load(v)
        scores = mxu("Q × Kᵀ", q_tile, k_tile)
        partial = mxu("scores × V", scores, v_tile)
        return add(acc, partial)

    return store(acc)

关键不是 Python 语法，而是 trace 后保留了层级、循环类型、符号迭代次数和硬件 leaf。因为 Tq 与 Tkv 不被提前绑定，同一个图可表示 Tq=Tkv=T 的 prefill，也可表示 Tq=1, Tkv=Tctx 的 decoding。

来源：PDF 第 3-4 页，The builder DSL 与 Listing 1。示例为语义化缩写，并非原代码复制。

数据分布通过 Tensor 的 sharding annotation 表达，而不是由模型作者到处手插 collective。sharded einsum 根据输入、权重和输出的布局推断必要通信。

来源：PDF 第 4 页，Distribution is expressed as sharding annotations。

RRT 怎样工作

Resource Reservation Table 的行是资源（例如 MXU、VMEM、ICI），列是 cycle，单元格是该周期占用数量。Modulo Scheduling 寻找可重复启动循环迭代的最小可行间隔 II，同时满足数据依赖与资源容量，然后把该结果作为父级 Op 的成本继续向上汇总。

符号传播为什么重要

batch、序列长度、带宽、mesh 轴、数据类型宽度都保持为 SymPy 自由变量。构图一次，只有在设计空间边界才做数值替换。因此：

• 同一模型结构可以服务大量参数 sweep。
• 文档可直接声明期望的闭式成本表达式。
• 测试不仅比较数值，还能比较符号化简后的结构或等价性。

来源：PDF 第 4 页，Rolling up the Op hierarchy 与 Symbolic propagation。

来源：PDF Abstract、Section 2、Section 4。上述“未给出”基于所附 5 页 PDF 的内容范围。

不要第一天就删除生产代码。更稳妥的验证方式是选择一个边界清晰、可精确对账的模块，建立“规格 → 隔离生成 → 验证 → 发布”的旁路，再根据结果扩大范围。

建议的硬门禁

• 禁止生成任务读取上一版 generated/，避免旧实现成为隐式输入。
• 依赖接口必须先验收再暴露给下游；同一波次只能依赖更早波次。
• 所有数值模块至少包含一个符号对账和一个具体数值对账。
• 关键路径采用多样化验证：测试生成者与代码生成者使用不同提示上下文或独立 oracle。
• 发布采用全有或全无；不得把局部通过模块拼进生产分支。

工程方案依据论文工作流扩展而来；目录、门禁和分阶段试点属于可执行的工程推导，不是论文原样规定。

# 模块名称

## 1. 目标与非目标
- 必须实现什么
- 明确不负责什么

## 2. 公开接口
- 输入 / 输出 / 类型 / shape / 单位
- 错误与边界行为

## 3. 依赖与不变量
- 允许依赖的上游文档
- 跨模块必须始终成立的条件

## 4. 语义步骤
1. 从输入开始逐步执行
2. 写出每一步中间 shape、值、资源动作
3. 给出最终符号表达式

## 5. Worked Example
- 固定一组小输入
- 完整列出中间结果
- 写出唯一正确的最终输出

## 6. 反例与参数保护
- 非法输入
- 容易混淆的情况
- 应抛出的错误

## 7. Reconciliation Anchor
- preset
- exact_expected_output
- symbolic_equivalence_rule

## 8. 验收条件
- 类型 / 单元 / 属性 / 差分 / 性能 / 安全测试

六类主要风险