feat: add AGENTS.md

Author: pany-ang

AGENTS.md

@@ -0,0 +1,146 @@
+# 原则
+
+## 1. 编码前思考
+
+**不要假设。不要隐藏困惑。呈现权衡。**
+
+LLM 经常默默选择一种解释然后执行。这个原则强制明确推理：
+
+- **明确说明假设** — 如果不确定，询问而不是猜测
+- **呈现多种解释** — 当存在歧义时，不要默默选择
+- **适时提出异议** — 如果存在更简单的方法，说出来
+- **困惑时停下来** — 指出不清楚的地方并要求澄清
+
+## 2. 简洁优先
+
+**用最少的代码解决问题。不要过度推测。**
+
+对抗过度工程的倾向：
+
+- 不要添加要求之外的功能
+- 不要为一次性代码创建抽象
+- 不要添加未要求的"灵活性"或"可配置性"
+- 不要为不可能发生的场景做错误处理
+- 如果 200 行代码可以写成 50 行，重写它
+
+**检验标准：** 资深工程师会觉得这过于复杂吗？如果是，简化。
+
+## 3. 精准修改
+
+**只碰必须碰的。只清理自己造成的混乱。**
+
+编辑现有代码时：
+
+- 不要"改进"相邻的代码、注释或格式
+- 不要重构没坏的东西
+- 匹配现有风格，即使你更倾向于不同的写法
+- 如果注意到无关的死代码，提一下 —— 不要删除它
+
+当你的改动产生孤儿代码时：
+
+- 删除因你的改动而变得无用的导入/变量/函数
+- 不要删除预先存在的死代码，除非被要求
+
+**检验标准：** 每一行修改都应该能直接追溯到用户的请求。
+
+## 4. 目标驱动执行
+
+**定义成功标准。循环验证直到达成。**
+
+将指令式任务转化为可验证的目标：
+
+| 不要这样做... | 转化为...                            |
+| ------------- | ------------------------------------ |
+| "添加验证"    | "为无效输入编写测试，然后让它们通过" |
+| "修复 bug"    | "编写重现 bug 的测试，然后让它通过"  |
+| "重构 X"      | "确保重构前后测试都能通过"           |
+
+对于多步骤任务，说明一个简短的计划：
+
+```
+1. [步骤] → 验证: [检查]
+2. [步骤] → 验证: [检查]
+3. [步骤] → 验证: [检查]
+```
+
+强有力的成功标准让 LLM 能够独立循环执行。弱标准（"让它工作"）需要不断澄清。
+
+# 命令
+
+```bash
+pnpm i # 安装依赖
+pnpm dev # 启动服务
+pnpm build:staging # 打包构建预发布环境
+pnpm build # 打包构建生产环境
+pnpm preview # 先执行打包构建命令生成 dist 目录后再执行以下预览命令
+pnpm lint # 代码校验与格式化
+pnpm test # 单元测试
+```
+
+# 架构
+
+## 技术栈
+
+- 框架: Vue 3.5
+- 打包构建工具: Vite 7
+- 路由管理: Vue Router 4
+- 状态管理: Pinia 3
+- UI 组件库: Element Plus
+- CSS 预处理器: Scss
+- 代码校验与格式化: ESLint
+- 开发语言: TypeScript
+- 包管理工具: pnpm
+- 网络请求: Axios
+
+## 目录结构
+
+```sh
+v3-admin-vite
+├─ .husky                # commit 时进行代码校验和格式化
+├─ .vscode               # vscode 配置和插件
+├─ public
+│  ├─ favicon.ico        # 网站头像
+│  ├─ app-loading.css    # 首屏 loading 动画
+│  └─ detect-ie.js       # 检测 ie
+├─ src
+│  ├─ common             # 通用目录
+│  │  ├─ apis            # 通用目录 - 接口
+│  │  ├─ assets          # 通用目录 - 静态资源
+│  │  ├─ components      # 通用目录 - 组件
+│  │  ├─ composables     # 通用目录 - 组合式函数
+│  │  ├─ constants       # 通用目录 - 常量
+│  │  └─ utils           # 通用目录 - 工具函数
+│  ├─ http               # 网络请求
+│  ├─ layouts            # 布局
+│  ├─ pages              # 页面
+│  │  └─ login           # 登录模块
+│  │     ├─ apis         # 登录模块 - 私有接口
+│  │     ├─ components   # 登录模块 - 私有组件
+│  │     ├─ composables  # 登录模块 - 私有组合式函数
+│  │     ├─ images       # 登录模块 - 私有图片
+│  │     └─ index.vue    # 登录模块 - 页面
+│  ├─ pinia              # 状态管理
+│  ├─ plugins            # 插件（全局组件、自定义指令等）
+│  ├─ router             # 路由
+│  ├─ App.vue            # 入口页面
+│  └─ main.ts            # 入口文件
+├─ tests                 # 单元测试
+├─ types                 # 类型声明
+│  └─ auto               # 自动生成的类型
+├─ .editorconfig         # 编辑器配置
+├─ .env                  # 所有环境
+├─ .env.development      # 开发环境
+├─ .env.production       # 生产环境
+├─ .env.staging          # 预发布环境
+├─ eslint.config.js      # eslint 配置
+├─ tsconfig.json         # ts 配置
+├─ uno.config.ts         # unocss 配置
+└─ vite.config.ts        # vite 配置
+```
+
+- 保持目录结构清晰，遵循现有目录规范
+- 同一个业务逻辑的代码和资源应当被收拢到了一起，避免在不同的目录间来回跳跃 (例如登录模块的接口应该放在 `src/pages/login/apis` 而不是 `src/common/apis`)
+
+# 约定
+
+参考 `.cursor/rules` 规则

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md