diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9282181
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,50 @@
+# vps-manager
+
+VPS 数字资产统一管理面板：多云 VPS / 域名 / AI 账号 / 凭据的登记、监控、续费提醒与同步。
+
+## 技术栈
+
+FastAPI + SQLModel + SQLite 分库（assets.db / metrics.db）+ Vue 3 + Tailwind CSS + Fernet 加密。
+
+## 目录导航
+
+| 目录 | 职责 |
+|------|------|
+| `app/` | FastAPI 后端：routers（API 路由）、services（业务逻辑）、models（SQLModel 模型）、adapters（云厂商 SDK 适配层）、core（配置/加密/鉴权） |
+| `static/` | Vue 3 SPA 前端：js/（视图/状态/模态框）、css/、templates/ |
+| `scripts/` | 运维脚本：AI 余额同步、SSL 证书巡检、续费提醒 |
+| `agent/` | VPS 采集 Agent：资源监控、安全状态、上报中心 |
+| `deploy/` | 部署编排：systemd 单元、update.sh 自动更新、backup.sh 备份 |
+| `tests/` | pytest 测试套件（22 个文件） |
+| `static/js/__tests__/` | vitest 前端测试（4 个文件） |
+
+## 关键约束
+
+- **移动端优先**：底部 Tab 导航，无横向溢出；桌面端侧边栏
+- **凭据中心化**：`credentials` 表是唯一事实源，账号通过 `credential_id` 关联
+- **适配器注册**：`app/adapters/registry.py` 的 `@register` 是唯一事实源；新增 AI 适配器须同步 `app/core/seed.py`
+- **部署链路**：Gitea push → cc1 `update.sh` 自动拉取 → 健康闸门 → 失败回滚
+- **Service Worker**：HTML `network-first`，静态资源 `stale-while-revalidate` + `?v={mtime}`
+
+## 常用命令
+
+```bash
+# 本地运行
+./run.sh
+
+# Python 测试
+.venv/bin/python -m pytest tests/ -x -q
+
+# JS 测试
+npx vitest run
+
+# 部署
+./deploy/deploy.sh
+```
+
+## 专项规则
+
+- 编码规范与架构细节 → `.qoder/rules/coding-standards.md`
+- 部署验收流程 → `.qoder/rules/deploy-verification.md`
+- JS 测试闸门 → `.qoder/rules/js-test-gate.md`
+- Python 测试规则 → `.qoder/rules/vps-manager-pytest.md`