为你的代码仓库打造专属Cursor Rules

我没有在Github上找到自动生成Cursor (或Trae) Rules 的最佳实践，于是自己尝试实践了一把。

思路

1. 先在普通AI聊天窗口让gemini帮我写一个“喂给Cursor或Trae的提示词”，用于后续生成rules；
   • 这里我额外利用 Shotgun 输出项目代码库的目录树，又写了一些注意事项
   • 甚至可以把项目的依赖清单（例如package.json或requirements.txt之类的文件内容）也附上去
   • 如果有更具体的需求和关注点，可以在这个环节尽早提示出来 　
2. 得到AI精心编写的提示词，手工订正一下细节；
3. 将精编提示词喂给Trae，在上下文指明希望Trae扫描分析的目录，得到project_rules.md；
4. 再手工订正一遍，最终保存rules。

问Gemini

## 背景：
我在用Cursor和Trae这两种代码编辑器，辅助我做前端开发，我主要使用Vue.js。我了解到这两种编辑器现在都支持“Rules”特性，AI辅助编程时Rules可以以持久化的方式为AI Agent提供上下文指导。

## 需求：
请你帮我：写一个提示词，以便我粘贴到Cursor或Trae里，让里面接入的大模型（可能会是Claude 4-sonnet或者Gemini 2.5 Pro）帮我分析整个项目结构，生成project_rules.md

## 细节：
- 生成project_rules.md的目的是：让AI模型更好的有目的性的分析既有的前端工程，并理解每个模块的大致功能。梳理既有的、正在执行的代码规范，并在今后的辅助编码过程中遵守规范和习惯，帮我写出易读、结构清晰、可维护性强的代码。除此以外，rules对参与项目协作的程序员同样有帮助意义。
- 这是一个PC web前端工程，XXXXX内部的管理系统。
- 我认为Composition API、setup、ref的写法增加心智负担，收益为负。我仍然在Vue3中采用Options API的写法，好处是保持代码组织感、易读性和可维护性、避免代码凌乱和割裂。
- 克制使用TypeScript：不提倡重度使用 TS。主要在工具函数、Store、类型定义文件中使用，以获得类型提示和代码健壮性。Vue 组件内部逻辑优先使用 JavaScript，除非类型复杂或有明确收益。
- 由于Trae的聊天框最多支持我输入6000个字符，所以请给我6000字符以内的提示词。
- 后附项目目录结构(project tree)和项目依赖(package.json)，供你参考。

---

## 附录信息
### 项目目录结构(project tree)
<code>
xxx-frontend-vue\
├── public （此处略）
├── src
│   ├── assets
│   ├── components
│   │   ├── Ai
│   │   │   ├── AiHeader.vue
(以下太长省略)
</code>

### 项目依赖(package.json)
<code>
{
  "name": "xxxxxxxx",
  "title": "xxxxx",
  "version": "0.2.5",
  "build": "0607",
  "scripts": {
    "dev:mock": "vite --open --mode mock",
(以下太长省略)
</code>

Gemini回答

好的，这是一个为你准备的提示词，你可以粘贴到 Cursor 或 Trae 中，让 Gemini 2.5 Pro 帮你分析项目并生成 project_rules.md。

作为我的 AI 编程助手，请分析我提供的 Vue.js 前端项目信息（项目目录结构和 `package.json`），并为我生成一个名为 `project_rules.md` 的 Markdown 文件。

**`project_rules.md` 的核心目标：**
1.  让你（AI Agent）能够深入理解当前项目的结构、主要模块功能及既有的代码规范和习惯。
2.  在后续的辅助编码、代码审查或重构建议中，严格遵守这些已梳理出的规范和习惯。
3.  最终目的是协助我编写出更易读、结构清晰、可维护性强的代码。
4.  注意此文档对参与项目协作的程序员同样有帮助意义。

**项目背景：**
这是一个 PC Web 前端工程，作为XXXXX内部使用的管理系统。技术栈主要为 Vue.js (Vue 3)。

**关键编码约定（请在 `project_rules.md` 中明确体现，并在未来工作中严格遵守）：**
1.  **Vue.js API 选择：**
*   **坚持使用 Options API。** 我认为 Options API 能更好地保持代码的组织感、易读性和可维护性，避免因 Composition API（如 `setup`、`ref`）的写法可能带来的代码凌乱和逻辑割裂感。所有新组件和现有组件的修改都应遵循 Options API。
2.  **TypeScript 使用策略：**
*   **克制使用 TypeScript。** 不提倡在项目中重度或无差别使用 TS。
*   **主要应用场景：** 工具函数 (如 `src/helper/` 下的文件)、Store (Pinia模块，如 `src/store/`) 以及独立的类型定义文件 (如 `src/interface.ts`, `*.d.ts`)。在这些场景下，TS 用于提供类型提示和增强代码健壮性。
*   **Vue 组件内部：** 组件的内部逻辑优先使用 JavaScript。仅当类型逻辑非常复杂或使用 TS 能带来明确、显著的收益时，才在组件内部谨慎使用 TypeScript。
**`project_rules.md` 文件内容建议（请基于你对项目结构和依赖的分析进行填充和扩展）：**

1.  **项目概览：**
*   简述项目用途（XXXXX内部管理系统）和核心技术栈（例如：Vue 3, Vite, Pinia, tdesign-vue-next 等）。
2.  **核心编码理念与规范：**
*   明确阐述本项目坚持使用 Vue Options API 的原因和要求。
*   详细说明 TypeScript 的克制使用策略和具体应用范围。
3.  **目录结构解析：**
*   概述主要目录（如 `src/assets`, `src/components`, `src/config`, `src/helper`, `src/hooks`, `src/layouts`, `src/pages`, `src/router`, `src/store`, `src/style`）的用途和存放内容。
*   特别关注 `src/components` 下的子目录（如 `Ai`, `Base`, `Xx`, `Xxx`）是如何组织业务或通用组件的。
*   `src/pages` 如何根据业务模块（Ai, Base, Xx, Xxx, Result）组织页面。
4.  **代码风格与约定（基于 `package.json` 和目录结构推断，并结合上述关键约定）：**
*   **Vue 组件编写：** 强调 Options API 的结构。
*   **状态管理：** Pinia 的使用方式（例如 `src/store/modules` 下的模块化组织，`api.ts` 的分离）。
*   **工具函数：** `src/helper` 目录下的工具函数分类和使用。关注 request.ts 如何对ajax请求进行封装。
*   **路由管理：** `src/router/index.ts` 的配置方式。
*   **UI 组件库：** `tdesign-vue-next` 的使用约定（如有）。
*   **代码格式化与 Linting：** 提及项目已集成 Prettier, ESLint, Stylelint (可从 `package.json` 的 `devDependencies` 和 `lint-staged` 配置中推断)，并强调其重要性。
5.  **主要依赖库及其用途：**
*   列出关键依赖（如 `vue`, `vue-router`, `pinia`, `axios`, `tdesign-vue-next`, `echarts`, `dayjs` 等）及其在项目中的作用。
6.  **未来协作指南：**
*   重申 AI 在后续工作中需遵循本文档定义的规则，以确保代码风格统一和项目可维护性。

请根据你对所提供信息的分析，生成内容详实、具有指导意义的 `project_rules.md`。（将文档放置在 xxx-frontend-vue/.trae/rules/ 下）

细节调整

略去。

在Trae中使用提示词

Trae接到我粘贴给它的提示词，一通火花带闪电的分析，得到此项目的专属Rules如下。

# 项目编码规范与协作指南 (Project Rules)

本文档旨在帮助 AI 编程助手及项目参与者深入理解当前 Vue.js 前端项目的结构、主要模块功能、既有的代码规范和习惯。在后续的辅助编码、代码审查或重构建议中，应严格遵守本文档梳理出的规范和习惯，以期共同编写出更易读、结构清晰、可维护性强的代码。

## 1. 项目概览

- **项目用途：** 本项目是一个专为XXXXX内部使用而开发的 PC Web 管理系统。
- **核心技术栈：**
  - **Vue.js:** 主要采用 Vue 3 版本。
  - **Vite:** 作为现代化的前端构建工具。
  - **Pinia:** 用于状态管理。
  - **tdesign-vue-next:** 作为主要的 UI 组件库。
  - **TypeScript:** 克制使用，主要用于工具函数、Store 和类型定义。

## 2. 核心编码理念与规范

### 2.1 Vue.js API 选择：坚持使用 Options API

- **原因：** Options API 能够更好地保持代码的组织感、易读性和可维护性。其结构化的方式（如 `data`, `methods`, `computed`, `watch`, 生命周期钩子等）使得组件逻辑清晰，易于理解和追踪。相比之下，Composition API（如 `setup` 函数、`ref`、`reactive` 等）虽然提供了更高的灵活性，但在大型项目中或团队协作时，若未能妥善组织，可能导致代码分散、逻辑割裂，增加心智负担。
- **要求：**
  - 所有新创建的 Vue 组件必须使用 Options API。
  - 对现有组件的修改和功能迭代，也应遵循 Options API 的风格。
  - 避免在组件中混合使用 Options API 和 Composition API（除非有极特殊且经过充分讨论的理由）。

### 2.2 TypeScript 使用策略：克制使用

- **原则：** 不提倡在项目中重度或无差别地使用 TypeScript。我们追求的是在合适的场景下利用 TS 的优势，而非盲目追求类型化。
- **主要应用场景：**
  - **工具函数：** `src/helper/` 目录下的各类工具函数（如日期处理、请求封装、数据格式化等）。在这些场景下，TS 可以提供良好的类型提示和编译时检查，增强代码的健壮性和可靠性。
  - **Store (Pinia 模块)：** `src/store/` 目录下的 Pinia 状态管理模块。TS 有助于定义 State、Getters、Actions 的类型，确保数据流的类型安全。
  - **独立的类型定义文件：** 如 `src/interface.ts` 或各模块自定义的 `*.d.ts` 文件，用于存放共享的接口（Interface）和类型别名（Type Alias）。
- **Vue 组件内部：**
  - 组件的内部逻辑（如 `data`、`methods`、`computed` 等）**优先使用 JavaScript**。
  - **仅当**组件的类型逻辑非常复杂，或者使用 TS 能够带来明确且显著的收益（例如，复杂 Prop 的类型校验、与外部 TS 模块的强类型交互）时，才在组件内部谨慎使用 TypeScript。
  - 避免为了使用 TS 而过度设计类型，保持组件代码的简洁性。

## 3. 目录结构解析

项目 `src` 目录下的主要子目录及其用途如下：

- **`src/assets`**: 存放静态资源，如图片、SVG 图标等。
- **`src/components`**: 存放全局可复用的 Vue 组件。
  - **`Ai/`**: AI 工具相关组件。
  - **`Base/`**: 基础通用组件，如 `Blank`, `Card`, `ConfirmDialog`, `Empty`, `Form`, `Result`, `UserAvatar` 等。
  - **`Xx/`**: Xx（某某某）模块相关组件。
  - **`Xxx/`**: Xxx（某某某）模块相关组件。
  - 组织方式：按业务模块或功能领域划分组件子目录，提高组件的组织性和可查找性。
- **`src/pages`**: 存放页面级别组件，通常与路由配置对应。
  - 组织方式：与 `src/components` 类似，按业务模块划分，如 `Ai`, `Base`, `Xx`, `Xxx`, `Result`。
- **`src/router`**: 存放 Vue Router 的配置 (`index.ts`)。
  - 包含默认路由 (`defaultRouteList`) 和业务相关路由 (`extraRouteList`)。
- **`src/store`**: 存放 Pinia 状态管理模块。
  - `index.ts` 初始化 Pinia 实例并导出各模块。
  - `modules/` 子目录存放具体的 store 模块，如 `app`, `xx`, `xxx`, `ai`, `user`, `setting`, `tabs-router`。
- **`src/layouts`**: 存放布局组件，如整体页面框架、头部、侧边栏、底部等。
  - `blank.vue`: 空白布局。
  - `setting.vue`: 可能用于设置相关的布局或组件。
  - `components/`: 布局内部的组件，如 `Breadcrumb`, `Content`, `Footer`, `Header`, `MenuContent.tsx`, `Search`, `SideNav.tsx`。
- **`src/hooks`**: 存放 Composition API Hooks (尽管项目优先 Options API，但此处可能包含一些可复用的逻辑)。
  - 例如 `useChart.ts`, `useCounter.ts`, `useJudgeLightOrDark.ts`, `useWindowResize.ts`。
- **`src/helper`**: 存放工具函数和辅助模块。
  - `const.ts`: 常量定义。
  - `date.ts`: 日期时间处理工具。
  - `directives.ts`: 自定义指令。
  - `filter.ts`: 过滤器函数。
  - `formatter.ts`: 数据格式化函数。
  - `func.ts`: 通用功能函数。
  - `index.ts`: 导出 `helper` 模块。
  - `mixins.ts`: Vue Mixins (注意：审慎使用)。
  - `request.ts`: Axios 实例封装和 API 请求处理。
  - `ui.ts`: UI 相关的辅助函数，如消息提示。
  - `util.ts`: 其他通用工具函数。
- **`src/config`**: 存放项目配置信息。
  - `color.ts`: 颜色配置。
  - `index.ts`: 导出配置模块。
  - `proxy.ts`: API 代理配置相关 (如 `getBaseUrl`)。
  - `style.ts`: 样式相关配置。
- **`src/style`**: 存放全局样式和主题文件。
  - `font-family.less`, `font/`: 字体相关。
  - `index.less`: 全局样式入口。
  - `layout.less`: 布局相关样式。
  - `markdown.css`: Markdown 内容样式。
  - `theme/`: 主题相关样式，如 `default.less`, `cyan.less` 等。
  - `variables.less`: Less 变量定义。

## 4. 代码风格与约定

### 4.1 Vue 组件编写

- **命名规范 (Naming Conventions):**
  - 组件文件: PascalCase (e.g., `MyComponent.vue`).
  - 页面级组件内的子组件命名通常应以页面组件名或模块名作为前缀，如 `AiTools.vue` 内的 `AiToolsBody.vue`
  - 组件名 (in `<script>`): PascalCase (e.g., `name: 'MyComponent'`).
  - 组件名 (in `<template>`): kebab-case (e.g., `<my-component>`), 根据 `.eslintrc` `vue/component-name-in-template-casing` 规则。
  - Props: camelCase (e.g., `myProp`).
  - Events:
    - Emission: kebab-case (e.g., `this.$emit('my-event', data)`).
    - Handling methods: camelCase (e.g., `handleMyEvent(data)`).
  - 变量和函数: camelCase (e.g., `let myVariable; function myFunction() {}`).
  - 常量: UPPER_SNAKE_CASE (e.g., `const MY_CONSTANT = 'value'`).
  - Store 模块/actions/getters: camelCase (e.g., `store.myAction()`, `store.myGetter`).
  - CSS 类名: kebab-case (e.g., `.my-class-name`). 项目中也可能使用 BEM 或其他约定，需具体分析组件样式。
- **严格遵循 Options API 结构：** 清晰划分 `name`, `components`, `props`, `data`, `computed`, `watch`, `methods`, 以及生命周期钩子 (如 `created`, `mounted`, `updated`, `beforeUnmount`) 等选项。
- **Props 定义：** 尽量为 Props 提供明确的 `type`，必要时提供 `default` 值和 `required` 声明，以及 `validator` 函数。
- **事件触发：** 使用 `$emit` 触发事件，事件名使用 kebab-case (短横线分隔命名)。
- **关注点分离**: 模板(Pug/HTML)、逻辑(JavaScript/TypeScript in `<script>`)、样式(Less in `<style scoped>`)在 `.vue` 文件中分离。
- 组件职责：保持组件的单一职责原则，高内聚低耦合。优先抽取可复用逻辑到 `src/helper`。

### 4.2 状态管理 (Pinia)

- **模块化 Store：** 在 `src/store/modules/` 目录下，根据业务功能或数据领域划分独立的 Store 模块。
- **类型定义：** 结合 TypeScript 为 State, Getters, Actions 提供类型定义，确保类型安全。
- **Actions 异步操作：** 异步操作（如 API 请求）应在 Actions 中处理，并返回 Promise。

### 4.3 工具函数 (`src/helper`)

- **分类清晰：** 工具函数应按功能分类存放在不同的文件中，例如 `date.ts` 处理日期，`string.ts` 处理字符串。
- **`request.ts`：** 封装全局的 HTTP 请求逻辑（通常基于 `axios`），包括请求拦截、响应拦截、错误处理、基础 URL 配置、超时设置等。
- **纯函数优先：** 尽量编写无副作用的纯函数，便于测试和复用。
- **API 请求 (API Requests):**
  - 封装方式: 在 `src/helper/request.ts` 中封装 Axios 实例，统一处理请求拦截、响应拦截、错误处理、baseURL、timeout、withCredentials 等。
  - 请求和响应处理：
    - 请求前: 可在拦截器中处理如 token 添加、参数序列化等。
    - 响应后: 在拦截器中根据后端返回的 `code` (期望为 `200`) 判断业务成功与否，提取 `data`，处理错误消息提示 (`$singleMessage`)。
    - 文件下载: 通过 `config.download` 和 `config.downloadFileName` 处理。
    - 文件上传: 通过 `config.upload` 处理，自动转换 `FormData`。
    - 静默请求: `config.silent` 可使请求不展示错误提示。
  - 错误处理机制: 统一在响应拦截器中处理，包括网络错误、业务错误 (code !== 200)、401 未授权跳转 SSO 等。

### 4.4 路由管理 (`src/router/index.ts`)

- **路由命名：** 为路由规则定义 `name` 属性，便于编程式导航。
- **懒加载：** 对页面组件使用动态导入 (dynamic import) 实现路由懒加载，优化首屏加载速度。
- **路由守卫：** 合理使用全局前置守卫 (`beforeEach`)、路由独享守卫 (`beforeEnter`)、组件内守卫，处理权限控制、页面跳转逻辑等。

### 4.5 UI 组件库 (`tdesign-vue-next`)

- **按需引入：** 推荐配置按需引入，减少打包体积。
- **统一风格：** 遵循 `tdesign-vue-next` 的设计规范和 API，保持 UI 风格的一致性。
- **自定义主题：** 如有需要，可通过修改样式变量或覆盖组件样式来实现自定义主题。

### 4.6 代码格式化与注释

- **工具集成：** 项目通常会集成 Prettier (代码格式化)、ESLint (JavaScript/TypeScript 代码检查)、Stylelint (CSS/SCSS/Less 代码检查)。
- **严格遵守：** 所有提交的代码都必须通过 Linting 检查，并符合 Prettier 的格式化标准。
- **配置文件：** 遵循项目根目录下 `.prettierrc`, `.eslintrc.js`, `.stylelintrc.js` (或类似名称) 等配置文件中的规则。
- **`lint-staged` 和 `husky`：** 推荐配置 `lint-staged` 结合 `husky`，在代码提交前自动执行 Linting 和格式化，确保代码质量。
- 对复杂逻辑、核心算法、重要函数、组件 Props/Events、Store 的 getters/actions、以及配置项等，应添加清晰的注释说明其用途、参数、返回值和注意事项。

## 5. 主要依赖库及其用途

以下列出项目可能依赖的关键库及其在项目中的主要作用（具体依赖请查阅项目 `package.json` 文件）：

- **`vue`**: Vue.js 核心库，构建用户界面的渐进式框架。
- **`vue-router`**: Vue.js 官方路由管理器，用于实现单页面应用 (SPA) 的导航。
- **`pinia`**: Vue.js 的官方推荐状态管理库，轻量、易用且对 TypeScript 支持友好。
- **`axios`**: 一个基于 Promise 的 HTTP 客户端，用于浏览器和 Node.js，负责与后端 API 进行数据交互。
- **`tdesign-vue-next`**: TDesign 的 Vue 3 版本 UI 组件库，提供丰富、高质量的组件，加速开发。
- **`echarts`**: 一个强大的数据可视化库，用于生成各种图表。
- **`dayjs`**: 一个轻量的 JavaScript 日期库，用于解析、校验、操作和显示日期时间。
- **`vite`**: 下一代前端开发与构建工具，提供极速的冷启动和热模块替换 (HMR)。
- **`typescript`**: JavaScript 的超集，为项目提供可选的静态类型检查。
- **`eslint`**, **`prettier`**, **`stylelint`**: 代码规范和格式化工具，保证代码质量和风格统一。

## 6. 未来协作指南

- **严格遵守上述规范**: 新增或修改代码时，必须遵循本文档中定义的命名约定、组件设计原则、状态管理模式、API 请求方式等。
- **组件化与复用**: 积极识别可复用的 UI 和逻辑，封装成组件 (`src/components`) 或工具函数 (`src/helper`, `src/hooks`)。
- **DRY (Don't Repeat Yourself)**: 避免重复代码，通过抽取公共部分到函数、组件、Mixins（审慎使用）或 Store 来实现代码复用。
- **可读性与可维护性**: 编写清晰、易懂的代码。使用有意义的变量名和函数名。复杂逻辑务必添加注释。
- **代码审查**: 所有主要的代码变更都应经过团队成员的代码审查，确保符合项目规范。
- **利用工具**: 充分利用 ESLint, Prettier, Stylelint 等工具来保证代码质量和风格一致性。
- **文档同步**: 对于重要的架构决策、新增的模块或复杂的组件，应及时更新相关文档或在本 `project_rules.md` 中补充说明。
- **性能考虑**: 关注组件渲染性能、API 请求效率、资源加载大小等，避免不必要的性能瓶颈。
- **AI 编程助手：** 在后续的辅助编码、代码审查、重构建议等工作中，请严格遵循本文档定义的各项规则和约定，确保生成的代码符合项目规范，保持代码风格的统一性和项目整体的可维护性。
- **项目成员：** 所有参与本项目的开发人员，均应熟悉并遵守本文档的规范。在引入新的编码习惯或技术选型时，应进行团队讨论并更新本文档。

通过共同遵守这些规范，我们可以构建一个更加健壮、易于维护和协作的前端应用。

后记：

这样做的好处在于，通过 前置提示词 (prompt of prompt) + 项目目录树信息 (project tree)，尽可能的让前置模型理解（或猜测）项目架构、主要技术栈、模块划分，以及你对“未来智能副驾”的更多要求，生成 用于让Trae生成rules的提示词 (prompt of rules)，明确指导AI分析项目代码并生成 “符合你关注点的”项目Rules。

由于生成式人工智能的特点，多次用相同的提示词提问，会收到多样性的回答，可以利用这个特性生成多份Rules，选取各自精粹的部分进行拼合，得到一份更优质的Rules。

前面提到的Shotgun本来有更暴力的用法（将代码库爆炸成巨大的文本丢给大模型），但我觉得那样有点过于滥用账号的免费调用额度了，没考虑那样做（心疼Gemini一秒钟），只用了Shotgun的生成目录树功能。

目前还不确定最终project_rules（相比无rules，或者笼统的通用型rules）在Trae vibe-coding中能带来多少实际效果提升，但这个rules可以算得上相当清晰、全面、符合项目的现状，至少对项目成员来说可读性是很强的，在团队协作、约定开发规范上也能提供帮助。

icheer.me