docs: 教学注释规范与接口回看规则入 CLAUDE.md；新增 CLAUDE.md 取舍决策附录

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CLAUDE.md

@@ -49,10 +49,23 @@ conda activate ars-opd && ruff check ars_opd/ --fix && ruff format ars_opd/
 2. 重构一个模块前，先对照参考实现列出其全部行为（含 trick 和 workaround），逐一确认保留/替代/删除。
 3. 每个纯逻辑模块完成后，用 toy 数据对拍参考实现的对应逻辑（参考其 `validate_mc_estimator.py` / `validate_chunk_mc_estimator.py`）。
 4. 文档规范：优先表格与公式，代码块 ≤15 行（展示思路用伪代码，完整代码引用文件路径），引用参考实现必须带 `文件:行号`。
+5. **每层完成后做接口回看**：逐模块自问"接口是否比实现简单得多"（深模块判据）；若某接口的参数/约定复杂到接近实现本身，先记录并重构，再进入下一层。规则来源与哲学对照见 `docs/appendix-claudemd-decisions.md`。
 
-## 7. 代码规范
+## 7. 代码规范（教学导向）
 
-- 公共函数完整类型注解；模块/类/函数写中文 docstring（功能、参数、返回、关键实现细节）。
+**注释分工**：`docs/` 章节负责讲原理，代码注释负责做索引，两者不重复。代码注释只写三类内容：
+
+| 类型 | 要求 | 示例 |
+|------|------|------|
+| 论文锚点 | 实现论文公式/机制的函数，docstring 首行标出处；关键行旁给公式本体 | `# 式(5): π̂ = (k_sem + α·π̄) / (N + α)` |
+| 非显然约束 | 只解释"为什么必须这样"及违反后果，不解释"这行在干什么"；load-bearing 的反直觉点必须写 | `# π̂ 必须 detach：否则学生通过抬高自身先验自我强化，训练塌缩` |
+| 差异标注 | 凡有意偏离论文或参考实现处，注明对方做法与我们的理由 | `# 参考实现(trainer:2205)对 chunk 内取 mean，论文式(8)为 sum，此处从论文` |
+
+**类型与 shape**：
+- 模块间公共接口（`ars_opd/` 各模块导出的函数/类）强制完整类型注解——接口注解本身就是教学信息；模块内私有 helper 从宽。
+- 类型注解表达不了张量 shape，故 shape 是硬要求：docstring 注明参数/返回的 shape，函数体内关键变换旁加行注释（如 `# (B, T, V) -> (B, T)`）。
+- docstring 用中文，含功能、参数、返回、关键实现细节。
+
+**其余硬规则**：
 - **严禁** `except Exception: pass`；出错直接报错，不用默认值兜底。
-- 张量函数在 docstring 中注明各参数的 shape。
 - 提交信息用中文，说明"这一步对应哪一章/哪个模块"。