diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..1452474
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,162 @@
+# CLAUDE.md
+
+适用于 `mingxi_platform` 仓库的 Claude Code 协作规则。
+
+---
+
+## 会话启动
+
+每次新 session 开始时，按顺序执行：
+
+1. 读取 `docs/明析平台-软件重构设计文档.md` — 了解整体架构和当前阶段
+2. 执行 `git log --oneline -10` — 查看最近提交，了解上次做到哪里
+3. 确认当前处于哪个 Phase（Demo / POC / 产线），再开始任务
+
+> 用户说"继续开发"或"继续上次的"时，完成以上步骤后直接接续，不重新介绍项目背景。
+
+---
+
+## 项目定位
+
+**明析平台**——基于机器视觉的PCB线路板缺陷检测系统。
+
+- **参赛背景**：梅州市2026年新一代电子信息暨人工智能产业创新创业大赛·初创企业（创客）组
+- **当前阶段**：Phase 1 Demo（目标：2026年6月决赛前完成可路演版本）
+- **团队规模**：5人，AI辅助开发，所有改动优先保证可读、可理解、可接手
+- **核心链路**：前置相机 → mingxi-capture → mingxi-vision → mingxi-backend → 浏览器管理后台
+
+**两台机器部署：**
+- 前置机（Windows 7 SP1+工业PC）：运行 `mingxi-capture.exe`
+- 推理服务器（Linux + GPU）：运行 `mingxi-vision`、`mingxi-backend`、`mingxi-frontend`
+
+---
+
+## 目录职责
+
+| 目录 | 说明 |
+|------|------|
+| `mingxi-capture/` | PyQt5 Windows桌面程序：相机采集、手动触发、结果展示、异步上报 |
+| `mingxi-vision/` | FastAPI推理服务：YOLOv8/ONNX推理、asyncio.Lock串行、模型热重载 |
+| `mingxi-backend/` | Django业务后端：三级权限、SQLite落库、模型管理、REST API |
+| `mingxi-frontend/` | Vue3管理后台：纯管理端（组长/厂长/管理员），短轮询实时监控 |
+| `docs/` | 所有技术文档，与代码同等重要 |
+| `docs/明析平台-软件重构设计文档.md` | 系统整体架构，**每次架构变更必须同步更新** |
+| `docs/mingxi-vision-架构设计.md` | vision子项目详细设计 |
+| `references/` | 参考视频和脚本，不进核心开发流程 |
+
+---
+
+## 修改原则
+
+- 先读现有实现和相关文档，再动手；优先最小化改动范围。
+- 已有实现可复用时，不新增平行实现。
+- 先定位根因，再修复问题，不做只遮盖现象的补丁。
+- 非任务要求，不改数据库字段名、API响应字段名、接口路径。
+- 涉及推理引擎（`engine/`）、数据库迁移（`migrations/`）、模型管理时，必须保守处理。
+
+---
+
+## 文档同步要求
+
+**代码和文档必须同步提交，不允许代码改了文档没跟上。**
+
+| 发生什么 | 必须更新 |
+|---------|---------|
+| 架构或接口发生变化 | `docs/明析平台-软件重构设计文档.md` |
+| mingxi-vision 内部设计变化 | `docs/mingxi-vision-架构设计.md` |
+| 做了重要技术决策 | `docs/decisions/` 新增 ADR 文件 |
+| 阶段目标或优先级变化 | `docs/明析平台-软件重构设计文档.md` 第10节 |
+
+ADR 文件命名：`docs/decisions/00N-简短描述.md`，包含：背景、决策、原因、影响。
+
+---
+
+## 技术约定
+
+### 通用
+- **Python 版本**：所有 Python 子项目统一使用 **Python 3.8**，不使用 3.9+ 特性
+- **注释语言**：中文注释，只写 WHY，不写 WHAT
+
+### mingxi-capture
+- GUI 框架：**PyQt5**（不用 PyQt6，需兼容 Windows 7 SP1）
+- 推理调用：同步 HTTP，在 `QThread` 中执行，禁止在主线程发网络请求
+- 上报队列：异步线程 + 本地 SQLite，失败重试不超过 10 次
+- 打包：PyInstaller，目标平台 Windows x64
+
+### mingxi-vision
+- 框架：FastAPI，启动参数 `--workers 1`（GPU 不支持多进程共享）
+- Pydantic：使用 **v1**（`pydantic==1.10.x`），不使用 v2 语法
+- 推理并发：**必须通过 `asyncio.Lock` 串行化**，不允许并发进入 `engine.detect()`
+- 模型加载：启动时加载并 warmup，禁止懒加载（避免路演首次延迟）
+- 图像读取：使用内存读取（`np.frombuffer` + `cv2.imdecode`），禁止写临时文件
+
+### mingxi-backend
+- 框架：Django 4.1，数据库 **SQLite**（内网单服务器，无需 MySQL）
+- 认证：JWT，从 `yolo_classification_system` 复用，不重写
+- 权限过滤：`operator` 只见自己的记录，`leader` 见本组，`admin` 见全部
+- 模型备份上限：10个，超出自动删除最早的非活跃版本及文件
+
+### mingxi-frontend
+- 框架：Vue 3 + Vite + TypeScript
+- 实时更新：**短轮询**（每1秒），不引入 WebSocket（部署复杂度不值得）
+- 定位：纯管理后台，操作工不使用浏览器
+
+---
+
+## 安全要求
+
+- **严禁**将 `.env`、`config.ini`、`queue.db`、模型文件（`.pt`/`.onnx`）提交到 git
+- 模型文件单独管理（共享盘或对象存储），git 只存代码和文档
+- `config.ini` 含服务器地址，已在 `.gitignore` 中，永远不提交
+- 如需提供配置示例，创建 `config.ini.example`（含占位值，不含真实地址）
+
+---
+
+## 验证要求
+
+改动完成后做最小必要验证：
+
+- **推理链路改动**：用测试图片确认 `/api/detect` 返回结构正确，`verdict` / `defects` 字段完整
+- **数据库改动**：运行 `python manage.py migrate`，确认无报错，查询结果符合预期
+- **权限改动**：分别用三种角色的 token 验证返回数据范围正确
+- **capture UI 改动**：在 Windows 环境确认界面渲染、按钮响应、结果展示正常
+- 如无法本地验证，必须说明原因和风险
+
+---
+
+## 提交规范
+
+格式：`<type>(<scope>): <简短描述>`
+
+| type | 用途 |
+|------|------|
+| `feat` | 新功能 |
+| `fix` | 修复问题 |
+| `docs` | 文档变更 |
+| `refactor` | 重构（不改功能） |
+| `chore` | 构建/配置/依赖 |
+| `test` | 测试相关 |
+
+scope 对应子项目或文档：
+
+```
+feat(vision): 实现 asyncio.Lock 推理串行化
+feat(capture): 完成 MockCamera 模拟模式
+feat(backend): 新增模型管理上传接口
+feat(frontend): 完成检测历史列表页
+fix(vision): 修复 ONNX 后处理坐标还原错误
+docs: 更新软件重构设计文档至 v2.0
+chore(capture): 更新 PyInstaller 打包配置
+```
+
+---
+
+## 提交前检查
+
+- [ ] 未改动无关文件
+- [ ] 未引入不必要重构
+- [ ] 未硬编码服务器地址、密码、密钥等敏感信息
+- [ ] 未提交 `.env`、`config.ini`、`.pt`/`.onnx` 模型文件
+- [ ] 未留下临时代码、调试 `print`、未说明的 `TODO`
+- [ ] 接口字段变更已同步更新 `docs/明析平台-软件重构设计文档.md`
+- [ ] 重要架构决策已补 `docs/decisions/` ADR 文件