diff --git a/CLAUDE.md b/CLAUDE.md
index 38fb900..1c33be1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -76,6 +76,23 @@ daoqi 仓库当前并存两条工作线：
   - 改完启动相关任意一项**必须做**：长按 app → 删除 → Xcode 重新 Run；或模拟器 Erase All Content and Settings；或 `xcrun simctl uninstall booted <bundleID>`
   - **终端用户不受影响**：从 IPA 首次安装、或升级新 IPA 第一次启动后即被 iOS 自动刷新；只是开发期反复迭代同一台 device 时会被迷惑
 
+### 典型案例：H5 与原生通讯接口的真实路径
+
+- **症状**：Design / Contract 文档描述 H5 用 `window.settings.getXxx()` 同步函数读渠道值（如 `getothername` / `getchannelName`）；按文档实现完 polyfill 后 H5 业务行为不对，user 反馈"H5 读不到数据"
+- **错误做法**：基于 Contract §附录 A 列出的旧桥 JSExport 28 方法实现 polyfill，把 9 项 getter 注入到 `window.settings`，认为这是 H5 端的主路径
+- **去原项目找答案**：grep `var app_` 在 `daoqi/msext/Class/RootVC/NewRootVC.m:1204` / `gameController.m:2160` / `AppDelegate.m:259`
+  - 发现 1：原项目 `initJSdata()` 是 `[NSString stringWithFormat:@"var app_xxx=...;"]` + `writeToFile:` **写 .js 文件到沙盒**，H5 业务用 `<script src="app_data.js">` 同步引入预生成的 12 个全局变量直接读
+  - 发现 2：Contract §附录 A 自身标注「iOS<9 路径使用的旧协议，新外壳如最低系统 ≥ iOS 14 可不实现」，新项目最低 iOS 15.6 → 旧桥 polyfill **完全不必要**
+  - 发现 3：Contract §4.2 之前列的 11 项变量与原项目代码不一致 — 漏 6 项（version / Launchtype / getwifisignalLevel / gamename / invitationcode / gamesname）、多 2 项（gameid / compareCode 原项目根本不写）、文件名与变量名混淆（文件 `app_battery.js` 内的变量名是带 get 的 `app_getbattery`，文件名不带 get）
+- **修复**：
+  1. 撤销已实现的 `window.settings.getXxx()` polyfill 章节（Design §3.4.1）
+  2. 新增 Design §7.5「H5 `app_*.js` 预注入文件机制」覆盖 15 个变量的写入逻辑
+  3. 按原项目代码全面修订 Contract §4.2（删 gameid/compareCode、补 6 项、修正 battery/network 变量名带 get、注明大厅/子游戏字面差异、加修订记录小节）
+- **教训**：
+  - **文档与代码冲突时，原项目代码是真理**。Contract 也可能写错（一份 10 年前写就的文档遗漏 / 误传是常态），必须用 `grep` 验证字面字符串
+  - **优先验证字面字符串、不要依赖语义猜测**：`app_getbattery` 与 `app_battery` 一字之差，AI 助手凭语义"应该就是 app_battery 吧" 100% 会犯错
+  - **iOS 最低系统版本是契约边界的天然过滤器**：契约里 iOS<9 路径明示可不实现的接口（如 §附录 A 旧桥），新项目最低 iOS 15.6 应当主动剔除，不要"出于完备性"反而实现一份用不到的 polyfill
+
 ---
 
 ## 文档索引