docs: L3's measured effect — it fixes the same cascade L2 does, and only for engines without L2

Author: speak-agent

.agents/docs/2026-08-13-build-optimization-status.md

@@ -65,7 +65,29 @@ L3 指的是**改 mcpp 自己的 138 个模块**——把定义从接口单元
 **可以做的**:拉一个临时分支/PR,只为**量出具体收益**(推算是链 74.6s → ~10.4s),
 测完即弃,不合入。收益数字回填到本文。
 
-### L3 / L4:优化被构建工程,不是优化构建器
+### L3 的收益已经量出来了 —— 而且它和 L2 治的是同一个病
+
+不用拉分支:bench 的 `modules-impl` 变体测的**正是** L3(定义写在接口单元 vs 移到实现
+单元),数据已经在 `bench/results/five-way-20260812/` 里。同一 fixture、同一编译器:
+
+| 场景 | mcpp:modules → modules-impl | cmake:modules → modules-impl |
+|---|---|---|
+| cold (gcc) | 3.53 → 3.25s **(+7.8%)** | 13.05 → 12.80s (+2.0%) |
+| cold (clang) | 2.50 → 2.19s **(+12.3%)** | 4.00 → 3.96s (+0.9%) |
+| **edit-body (gcc)** | 0.29 → 0.31s **(−6.2%)** | **10.29 → 0.79s (+92.3%)** |
+| edit-body (clang) | 0.46 → 0.31s (+32.5%) | 2.62 → 0.42s (+84.0%) |
+
+**看 `edit-body` 那两行。** 把定义移出接口单元,给 cmake 带来 **92%** 的提升,
+给 mcpp 带来 **−6%**(即没有)。原因是同一个:改函数体时接口没变,
+cmake 按 BMI 的 mtime 级联,mcpp 比 BMI 的内容。**L3 是给没有 L2 的引擎准备的绕行方案。**
+引擎做了这件事之后,工程再去重构,在这条轴上什么都买不到。
+
+真正留下来的是 **cold 上 +8%~12%** —— 接口单元变薄,关键链就变短。这是真的,
+但它是"顺手的好设计",不是一条值得为性能去改 138 个模块的理由。
+
+**所以 L3 的文档提示是:先要引擎的 L2,再谈重构。** 顺序反了会做很多白工。
+
+### L4 与这条界线
 
 ⚠️ **这是本轮最重要的一条界线。** 「优化 mcpp 的构建性能」指的是**通用构建性能**,
 不是把 mcpp 这一个工程调快。**通过改被测目标来变快,不能算数** ——