# 启动检查

1. 严格按照 dev-rules.md 规则来执行
2. **调用 `mcp_devmemory_status`** 获取会话状态（阻塞、进度、待处理）
3. 然后按问题跟踪步骤执行

**⚠️ 无论用户问什么问题，第一个动作必须是调用 MCP status**

---

# 项目知识（从 MCP 加载）

**每次新会话加载项目知识**：`mcp_devmemory_recall`（tags: ["项目知识"], scope: "project", top_k: 100）

**查询踩坑记录**：`mcp_devmemory_recall`（query: 关键词, tags: ["踩坑"]）

# 开发规则

> 核心原则、问题处理原则、常用账号、IDE 卡死防范、Playwright 规则、自测要求已在 Hook 中配置，此处不再重复。
> 禁止口头承诺，一切以测试通过为准。
> 任何文件修改前必须强制严谨思考。
> 遇到报错或异常时严禁盲目测试，必须分析问题根本原因。
---

## 知识库（通过 MCP remember/recall 管理）

**遇到问题必记**：命令失败、框架踩坑、技术要点 → `mcp_devmemory_remember`（标签：`踩坑`）

**查询踩坑记录**：`mcp_devmemory_recall`（query: 关键词, tags: ["踩坑"]）

---

## 会话状态（通过 MCP status 管理）

**新会话开始时**：调用 `mcp_devmemory_status`（不传 state 参数 = 读取）

**⚠️ 阻塞状态优先级最高**：
- 新会话先检查 `is_blocked` 和 `block_reason`
- 有阻塞 → 等用户反馈，禁止执行任何操作
- 无阻塞 → 按正常流程执行

**更新时机**：任务开始、完成子任务、遇到问题转向、任务完成
- 调用 `mcp_devmemory_status` 传 state 参数更新

**MCP status 字段说明**：
- `is_blocked`：是否阻塞
- `block_reason`：阻塞原因
- `next_step`：下一步（只能由用户确认后填写）
- `current_task`：当前任务
- `progress`：进度列表
- `recent_changes`：最近修改（不超过10条）
- `pending`：待处理列表

**分工**：
- MCP status：阻塞状态、当前进度、最近修改
- MCP track：问题追踪（create/update/archive/list）

**⚠️ "next_step"字段只能由用户确认后填写，禁止擅自填写**

**⚠️ 禁止猜测用户意图**：
- "用户倾向"、"用户选择"、"用户确认" → 必须有用户明确表态才能记录

**何时设置阻塞**（`is_blocked: true`）：
- 修复完成等用户验证时
- 方案待用户确认时
- 需要用户决策时

**何时清除阻塞**（`is_blocked: false`）：
- 用户确认验证通过
- 用户确认方案
- 用户做出决策

---

## 任务文档

**任务文档位置**：`.kiro/specs/*/tasks.md`

**任务文档规范**：
- 每个任务细化到最小可执行单元
- 使用 checkbox `- [ ]` 标记状态
- **每完成一个子任务，立即更新为 `- [x]`**
- 禁止批量完成后再统一更新

**整理任务文档时**：必须打开设计文档逐条核对，发现遗漏先补充任务文档再执行

---

## 代码风格

**简洁优先**：
- 能用三目运算符，不用 if-else
- 能用短路求值，不用条件判断
- 能用解构赋值，不用逐个取值
- 能用模板字符串，不用字符串拼接

**避免冗余**：
- 不写无意义的注释
- 不写重复的代码，提取公共函数
- 变量命名清晰，不需要注释解释

---

## 页面设计

**设计稿位置**：`tests/html-designs/`（客户端）、`tests/frontend/`（网站前端）

**⚠️ 设计稿必须先确认**：
- 创建/修改设计稿后，必须等用户确认
- 用户确认后，再将设计稿转为代码
- 禁止设计稿和代码一起提交

**有设计稿时**：
1. 先读取设计稿 HTML/CSS 文件
2. HTML 结构直接转 Vue template，禁止自己改
3. CSS 样式直接复制，禁止自己改
4. SVG 图标直接复制，禁止用 emoji 替代

**没有设计稿时**：
```bash
python3 .shared/ui-ux-pro-max/scripts/search.py "关键词" --domain color/style/typography/ux
```

---

## 任务执行

- 按 tasks.md 顺序执行，禁止跳过
- 全自动执行，禁止要求用户手动操作
- 遇到问题自行解决，记录到问题跟踪文档
- 禁止用"后续迭代"跳过任务

---

## 完成标准

**禁止模糊表述**：
- 禁止"基本完成"、"差不多"、"大致实现"等词汇
- 任务只有两种状态：**完成** 或 **未完成**

**完成确认流程**：
1. 逐项检查：对照 tasks.md 逐一验证
2. 代码验证：确认代码存在且正确
3. 功能测试：Playwright 或编译测试
4. 标记完成：测试通过后才标记 `[x]`

---

## 翻译规则

**开发阶段只改中文**，英文后续统一翻译：
- 后台：`app/admin/lang/zh-cn/zh-cn.php`
- 前端：`frontend/locales/zh-cn/`
- 客户端：`license_gui/frontend/src/i18n/locales/zh-CN.js`

**⚠️ 禁止修改英文翻译文件**

---

## 代码修改检查

**修改前**：
- `mcp_devmemory_recall` 查询相关踩坑记录
- 确认翻译规则（只改中文）
- **必须先查看该功能的现有实现**
- **涉及数据存储时，必须确认数据流向**

**修改后**：
- PHP：`php -l file.php`
- Go：`go build -o /dev/null .`
- Vue：确认 template 标签闭合

---

## 问题追踪（通过 MCP track 管理）

**工具**：`mcp_devmemory_track`（action: create/update/list/archive）

**问题处理原则**：
- 一次只修一个问题
- 修复过程中发现新问题 → `track create` 记录标题后继续当前问题
- 用户中途打断提出新问题 → 同样 `track create` 记录，再决定优先级
- 当前问题修复完成后，再按顺序处理新问题

**发现新问题时判断**：新问题不解决，当前问题能否继续？
- 能继续 → `track create` 记录标题，继续当前问题
- 不能继续（阻塞）→ `track update` 当前问题标注阻塞，先处理阻塞问题

**问题记录流程**：
1. `track create`：记录问题标题 + 调用 `mcp_devmemory_status` 更新 pending
2. 排查问题原因，`track update` 更新 content（根因、方案）
3. 向用户说明问题和方案
4. 修改代码并自测
5. 自测通过后 `track update` 更新结论，等用户验证
6. 用户确认没问题 → `track archive` 归档

**⚠️ 问题追踪必须及时更新**：每完成一个步骤立即 `track update`，避免会话切换时重复执行

---

## Git 分支工作流

**日常开发在 `dev` 分支**，master 只接受合并：
- 所有代码修改、提交、推送都在 `dev` 分支
- **禁止直接在 master 分支提交代码**
- 提交前先确认当前分支是 `dev`（`git branch --show-current`）

## Git 提交流程

**只有用户明确要求提交时**，才依次执行（禁止用 && 连接）：
- 先确认当前在 dev 分支：`git branch --show-current`
- `git add -A`
- `git commit -m "fix: 问题简述"`
- `git push origin dev`

**合并到 master**（仅用户明确要求时）：
- `git checkout master`
- `git merge dev`
- `git push`
- `git checkout dev`

---

## 上下文优化

- 优先 `grepSearch` 定位，再 `readFile` 读取特定行
- 代码修改用 `strReplace`，不要先读后写

---

## 内容迁移/拆分

**⚠️ 禁止凭记忆重写**：
- 迁移/拆分内容时，必须从原文件逐行复制
- 禁止凭记忆重写，会导致内容遗漏或精简

**创建索引后必须验证**：
- 索引中引用的所有文件都必须存在
- 每个文件的内容必须与原文件对应章节完全一致

---

## 错误处理

**反复失败时**：
1. 记录已尝试的方法
2. 换一种思路解决
3. 仍然失败则询问用户

---

## 自检要求

**完成任务前必须自问**：
1. 排查是否完整？
2. 数据是否准确？
3. 逻辑是否严谨？

**禁止**：
- 禁止说"大部分"、"基本上"、"应该是"等模糊词
- 禁止未经验证就下结论
