diff --git a/docs/superpowers/specs/2026-06-27-dev-services-port-rules-design.md b/docs/superpowers/specs/2026-06-27-dev-services-port-rules-design.md
new file mode 100644
index 0000000..867d546
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-27-dev-services-port-rules-design.md
@@ -0,0 +1,156 @@
+---
+author: claude
+created_at: 2026-06-27
+purpose: 规范本地服务管理：强制使用 dev-services.py 控制前后端服务，固定前端/H5 端口从 5178 开始累加，优化热加载避免无意义重启
+---
+
+# 本地服务管理规则优化设计
+
+## 背景
+
+当前项目使用 `dev-services.py` 管理本地前后端服务，但存在以下问题：
+
+1. 前端/H5 端口分散配置在各自 `vite.config.*` 中，未统一管理
+2. `dev-services.py` 端口冲突时自动递增，导致端口号不稳定
+3. 用户已习惯使用 `dev-services.py`，但缺少"禁止无意义重启"的强制约束
+4. 热加载场景下，开发者可能误重启支持热更新的前端服务，浪费时间
+
+## 目标
+
+1. 强制：启动/重启/停止本地前后端服务必须使用 `dev-services.py`
+2. 固定：前端和 H5 服务端口从 5178 开始累加分配
+3. 优化：`dev-services.py restart` 在无必须重启的变更时禁止重启
+4. 一致：更新 CLAUDE.md 规则文档，与脚本行为对齐
+
+## 方案选择
+
+采用 **方案 A：dev-services.py 内置固定端口表 + 修改各项目 vite 配置**
+
+- 端口控制集中且与项目配置一致
+- 与现有 `dev-services.py` 架构兼容
+- 便于开发者直接查看配置文件了解端口
+
+## 详细设计
+
+### 1. 固定端口分配表
+
+| 服务 | 目录 | 类型 | 固定端口 |
+|---|---|---|---|
+| Emotion-museum-web | `web/` | Vite | 5178 |
+| Emotion-museum-admin | `web-admin/` | Vite | 5179 |
+| Emotion-museum-uniapp | `mini-program/` | UniApp H5 | 5180 |
+| Life-script 前端 | `life-script/` | Vite | 5181 |
+
+后端服务端口保持现有配置不变。
+
+### 2. dev-services.py 修改
+
+#### 2.1 新增固定端口映射
+
+```python
+FIXED_FRONTEND_PORTS = {
+    "web": 5178,
+    "web-admin": 5179,
+    "mini-program": 5180,
+    "life-script": 5181,
+}
+```
+
+按项目目录名匹配。如果目录名不在映射中，仍按原有逻辑处理。
+
+#### 2.2 修改端口分配逻辑
+
+在 `assign_unique_ports()` 中：
+- 对 `FIXED_FRONTEND_PORTS` 中定义的服务，强制使用固定端口
+- 如果固定端口被非前端服务占用，报错退出
+- 如果固定端口被另一个前端服务占用，报错退出（说明映射配置错误）
+- 不再对前端服务自动递增端口
+
+#### 2.3 新增 restart 热加载保护
+
+定义"必须重启才能生效"的文件模式：
+
+```python
+RESTART_REQUIRED_PATTERNS = [
+    r'vite\.config\.(ts|js|mjs|cjs)$',
+    r'tsconfig\.json$',
+    r'\.env(\.[^/]*)?$',
+    r'package\.json$',
+    r'application.*\.ya?ml$',
+    r'pom\.xml$',
+    r'build\.gradle(\.kts)?$',
+]
+```
+
+`restart` 命令执行前：
+1. 获取 git 工作区中已修改的文件列表：`git diff --name-only`
+2. 如果没有修改，提示"未检测到代码变更，无需重启"
+3. 如果修改文件匹配 `RESTART_REQUIRED_PATTERNS`，允许正常 restart
+4. 如果修改文件不匹配，拒绝 restart 并提示：
+   > 当前修改只涉及支持热加载的源码文件，无需重启。如需强制重启，请使用 `python dev-services.py restart --force`
+
+#### 2.4 支持 `--force` 参数
+
+在 `restart` 子命令解析中增加 `--force` 选项，允许用户绕过热加载保护强制重启。
+
+### 3. 前端项目配置修改
+
+| 文件 | 修改内容 |
+|---|---|
+| `web/vite.config.ts` | `server.port` 改为 5178 |
+| `web/.env.development` | 添加 `VITE_PORT=5178` |
+| `web-admin/vite.config.ts` | `server.port` 改为 5179 |
+| `web-admin/.env.development` | `VITE_APP_PORT` 改为 5179 |
+| `mini-program/vite.config.js` | `server.port` 改为 5180 |
+| `mini-program/.env.development` | 添加 `VITE_PORT=5180` |
+| `life-script/vite.config.js` | `server.port` 改为 5181 |
+| `life-script/.env.development` | 添加 `VITE_PORT=5181`（不存在则创建） |
+
+### 4. CLAUDE.md 规则更新
+
+新增"本地服务管理规则"章节：
+
+1. **必须使用 dev-services.py**：
+   - 启动、重启、停止本地前后端服务必须使用 `python dev-services.py [命令] [服务名]`
+   - 禁止直接使用 `npm run dev`、`npm run dev:h5`、`mvn spring-boot:run` 等命令
+
+2. **前端/H5 固定端口**：
+   - `web`: 5178
+   - `web-admin`: 5179
+   - `mini-program`: 5180
+   - `life-script`: 5181
+
+3. **禁止无意义重启**：
+   - 只有修改必须重启才能生效的文件时，才允许执行 `restart`
+   - 修改源码文件（`.vue`、`.tsx`、`.ts`、`.js`、`.css`、`.scss` 等）时禁止 restart
+   - 确需强制重启时，使用 `python dev-services.py restart --force`
+
+4. **热加载规则**：
+   - 前端修改源码文件优先利用热加载
+   - 后端修改代码按现有规则处理（本地不启动后端，使用服务器验收）
+
+### 5. 边界情况
+
+| 场景 | 行为 |
+|---|---|
+| 固定端口被占用 | `dev-services.py` 报错，要求先停止占用该端口的服务 |
+| 无代码变更执行 restart | 提示无需重启 |
+| 只修改 `.vue` 文件执行 restart | 拒绝重启，提示使用 `--force` 或无需重启 |
+| 修改 `vite.config.ts` 执行 restart | 允许正常 restart |
+| 多个服务同时 restart | 每个服务独立检测，符合规则的重启，不符合的跳过 |
+| 用户传 `--force` | 跳过所有检测，强制重启 |
+
+## 修改范围
+
+| 文件 | 操作 |
+|---|---|
+| `dev-services.py` | 修改：添加固定端口映射、优化端口分配、新增热加载保护 |
+| `web/vite.config.ts` | 修改：端口改为 5178 |
+| `web/.env.development` | 修改/创建：添加 `VITE_PORT=5178` |
+| `web-admin/vite.config.ts` | 修改：端口改为 5179 |
+| `web-admin/.env.development` | 修改：`VITE_APP_PORT` 改为 5179 |
+| `mini-program/vite.config.js` | 修改：端口改为 5180 |
+| `mini-program/.env.development` | 修改/创建：添加 `VITE_PORT=5180` |
+| `life-script/vite.config.js` | 修改：端口改为 5181 |
+| `life-script/.env.development` | 修改/创建：添加 `VITE_PORT=5181` |
+| `CLAUDE.md` | 修改：更新本地服务管理规则 |