# [LEARN-20260501-002] AI 在 SSH 远程开发机上**完全有能力**自己跑 L2，不要把"给用户的隧道命令"当成自己的限制

## 触发场景

完成 flow-diagram 模块前后端实现后，跳过了 L2 端到端测试就直接合并 PR，理由（错误的）：
> "你的开发机是 SSH 远程的，起前端 dev server 后还要给你 SSH 隧道命令本地浏览器才能访问"

被用户当场指出错误："本开发机本身就能启动前后端以及 MCP 服务，看看是哪里给你误导"。

这违反了 CLAUDE.md 明文规则：**"For UI or frontend changes, start the dev server and use the feature in a browser before reporting the task as complete."**

## 根因

误读了 memory 条目 `feedback_ssh_remote_dev.md`，把它当成"AI 不能在本机测 UI"的禁令。

memory 原文意思是：当用户想用**自己的本地浏览器**点页面时，AI 起完 dev server 应该主动给一条 `ssh -L 3000:localhost:3000` 命令模板。

**这条规则的对象是用户，不是 AI 自己。**

实际可用资源（每次会话都齐备）：
- ✅ Bash：可以 `cd backend && npm run start:dev` 后台跑
- ✅ Bash：可以 `cd frontend && npm run dev` 后台跑
- ✅ Playwright MCP（`mcp__plugin_playwright_playwright__*`）：在开发机上运行无头/有头浏览器，**直接访问 `http://localhost:3000`**，跟 SSH 客户端无关
- ✅ curl：直接打 `http://localhost:3001/api/v1/...` 验证后端

整条链路全在开发机内部闭环，**不经过 SSH 隧道**。SSH 隧道只在用户想用本地 macOS/Windows 的浏览器看页面时才需要。

## 正确的 L2 流程（任何 UI/前端改动后必跑）

```bash
# 1. 起后端（后台）
cd backend && npm run start:dev   # run_in_background: true

# 2. 等 backend ready（监听 health endpoint）
until curl -sf http://localhost:3001/api/v1/health; do sleep 2; done

# 3. 起前端（后台）
cd frontend && npm run dev        # run_in_background: true

# 4. 等 frontend ready
until curl -sf http://localhost:3000; do sleep 2; done

# 5. 用 Playwright MCP 驱动浏览器
#    - browser_navigate http://localhost:3000/<新页面>
#    - browser_snapshot 确认渲染
#    - browser_click / browser_fill_form 走业务流程
#    - browser_console_messages 检查无 error/warning（含 i18n missing key）
```

完整 flow 后才能说"这个 PR 验证完了"。**没在浏览器点过的 UI 改动 = 没验证。**

## 适用范围

任何使 frontend/* 或 backend API 路径变化的 PR。包括：
- 新模块（如 flow-diagram）
- 新页面 / 新组件
- 修改现有页面交互
- 改 API 契约（哪怕后端 L1 全过，前端联通仍可能挂）

## 触发短语 / 自我提醒

- 看到"远程开发机"、"SSH"、"隧道"——**那是给用户准备的导航，不是给我自己的限制**
- 准备说"L2 跳过"前——再问一次"我真的不能跑吗"。99% 答案是"能"
- 完成 PR 前的 self-check：「我在浏览器里点过新加的页面吗？」否就回去补，不要把 L2 写进 followups 当借口

## 与现有规则的关系

- `CLAUDE.md` §"Doing tasks"：UI 改动必须在浏览器测——本 learning 是这条的**执行细节**
- `feedback_ssh_remote_dev.md` memory：仅适用于"用户想本地访问"场景；不要扩展解读为"AI 跑不了 dev server"
- `test-frontend` skill：MCP-driven E2E 的标准流程

## 后续行动

1. ✅ 沉淀此 learning
2. ⏳ 在当前 PR #218 上补做 L2 smoke 测试，验证主流程能跑通
3. ⏳ 评估是否给 `CLAUDE.md` 加一行强提示："起 dev server + Playwright MCP 是 AI 自带能力，不是要用户配合"——避免下一个 AI 重蹈