diff --git a/docs/04-architecture.md b/docs/04-architecture.md
index 6bdf084..cc7c980 100644
--- a/docs/04-architecture.md
+++ b/docs/04-architecture.md
@@ -139,6 +139,18 @@ CREATE TABLE vocab (
 | wasm 首屏体积 | Go wasm 最小约 2MB，首屏较慢 | 离线缓存后续访问快 |
 | 离线音频 | 大体积音频缓存策略 | Service Worker 按需缓存 |
 
+### go-app 注意事项（避坑表）
+
+实际写代码踩到的 go-app 框架行为，**持续累积**；动手前扫一眼，再踩到新坑往这里补：
+
+| 坑 | 现象 | 规避 |
+| --- | --- | --- |
+| Handler 只为**已注册路由**返回 app shell | 未注册的路径返回 `404 page not found`（不是页面） | 路由用 `app.Route` 注册，且放在 `init()` 里，确保「服务器渲染 / wasm 入口 / 测试」三处都生效（见 `main.go`） |
+| 前端/后端同包共存 | server-only 依赖（`net/http`、SQLite、`os`）误进 wasm 会构建失败或体积暴涨 | 后端代码用 `//go:build !wasm` 或单独包隔离，只被 server 入口引用（见第六节） |
+| wasm 由 `app.js` 引导 | app shell 里**没有**直接的 `app.wasm` script 标签，而是 `/wasm_exec.js` + `/app.js` | 验证引导是否注入时看这两个脚本，别找 `app.wasm` 标签 |
+| 服务器默认从 `web/` 读 `app.wasm` | 没把 wasm 构建到 `web/app.wasm` 时页面空白 | 起 server 前先 `GOOS=js GOARCH=wasm go build -o web/app.wasm` |
+| `Handler.Name` 不进 `<title>` | 设了 `Name` 但页面标题为空 | 标题由组件的 `Title()` 等设置，不要指望 `Name` 自动成为 title |
+
 ## 五、推荐开发顺序
 
 1. **先写「音频 + 时间戳字幕同步」最小原型**（验证最难一环）
diff --git a/docs/05-coding-rules.md b/docs/05-coding-rules.md
index 1c4cfb4..31eb136 100644
--- a/docs/05-coding-rules.md
+++ b/docs/05-coding-rules.md
@@ -45,6 +45,7 @@
 
 ## 5. Go / go-app 代码规范
 
+- **写 go-app 代码前先扫** [架构设计](04-architecture.md) 第四节的「go-app 注意事项（避坑表）」；踩到新坑往那里补，别让同一个坑被踩第二次。
 - 提交前过 `gofmt` 和 `go vet`；构建用 `GOOS=js GOARCH=wasm go build`（前端）/ 普通 `go build`（后端）。
 - **错误必须处理**：不忽略 `err`、不用 `_` 吞错；正常流程里不 `panic`（初始化致命错误除外）。
 - 包 / 文件按职责划分，对照 [架构设计](04-architecture.md) 第二节的前后端职责组织（列表 / 播放器 / 字幕同步 / 生词本 / API 封装）。