为你的代码仓库打造专属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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
## 背景:
我在用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模型更好的有目的性的分析既有的前端工程,并理解每个模块的大致功能。梳理既有的、正在执行的代码规范,并在今后的辅助编码过程中遵守规范和习惯,帮我写出易读、结构清晰、可维护性强的代码。
- 这是一个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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
作为我的 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如下。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
# 项目编码规范与协作指南 (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

Buy me a coffee ☕