React/Vue项目怎么写AGENTS.md
开头先说说
前面两篇把基础概念讲完了，这篇我们来点实在的，专门聊聊前端项目怎么写AGENTS.md。
我自己在前端项目里踩过不少坑。最开始写AGENTS.md的时候，我把后端那一套搬过来，结果AI该不会的还是不会——它不知道前端用什么构建工具、组件怎么组织、样式怎么写。后来慢慢摸索，才总结出一些前端特有的门道。
React项目的AGENTS.md怎么写
先上一个我在React项目里用的AGENTS.md模板。
# AGENTS.md - React Monorepo 项目
## 项目架构
基于 pnpm + Turborepo 的 Monorepo 项目，包含多个 React 应用包。
## 技术栈
- React 18
- TypeScript
- Vite
- React Router 6
- Zustand（状态管理）
- TanStack Query（服务端状态）
- Vitest + Testing Library
## 开发命令
### 安装依赖
```bash
pnpm install
启动开发服务器
pnpm dev # 启动所有
pnpm dev --filter @myapp/web # 启动特定应用
构建
pnpm build
pnpm build --filter @myapp/web
测试
pnpm test # 监听模式
pnpm test -- --run # 单次运行
pnpm test -- --coverage # 带覆盖率
代码检查
pnpm lint
pnpm typecheck
代码规范
组件规范
- 使用函数式组件 + Hooks
- 组件文件使用 PascalCase（如 UserProfile.tsx）
- 使用
<script setup> 语法糖（Vue 项目）
样式规范
- 使用 CSS Modules 或 styled-components
- 样式文件使用 kebab-case（如 user-profile.module.css）
- 禁止使用全局样式（除 reset/normalize）
TypeScript 规范
- 启用 strict 模式
- 禁止使用 any 类型
- 接口使用 I 前缀（如 IUser）
- 类型定义优先使用 type
状态管理
- 服务端状态使用 TanStack Query
- 客户端状态使用 Zustand
- 组件内部状态使用 useState
目录结构
src/
├── components/ # 公共组件
├── features/ # 功能模块
├── hooks/ # 自定义 Hooks
├── services/ # API 调用
├── stores/ # Zustand stores
├── types/ # 类型定义
└── utils/ # 工具函数
测试要求
- 测试文件放在源文件同目录或 tests 目录
- 测试文件命名：xxx.test.tsx 或 xxx.spec.tsx
- 单元测试覆盖率达到 70% 以上
- 提交前必须通过所有测试
- UI 组件使用 Testing Library 测试用户行为
注意事项
- 路由配置在 src/routes/ 目录
- API 请求统一使用 services/ 目录下的模块
- 公共组件必须包含 Storybook stories
- 图片等静态资源放在 public/ 或 src/assets/
- 环境变量使用 .env.local，本地敏感配置使用 .env.local.example 作为模板
这个模板基本上覆盖了React项目的主要方面。你可能会问：为什么要写这么详细？
我的经验是：前端项目的坑特别多。AI不知道你的组件怎么组织、状态管理用什么方案、路由怎么配置。稍微写漏一点，AI生成的代码就可能和你项目的实际结构对不上。
## Vue项目的AGENTS.md怎么写
Vue项目的情况有点不一样。Vue 3 的 Composition API 和 React 的Hooks思路比较像，但具体写法上还是有差异的。
```markdown
# AGENTS.md - Vue 3 项目
## 技术栈
- Vue 3 + Composition API
- Vite 5
- Vue Router 4
- Pinia
- TypeScript
## 开发命令
```bash
npm install
npm run dev # 启动开发服务器
npm run build # 生产构建
npm run preview # 预览构建结果
npm run test:unit # 单元测试
npm run test:e2e # E2E 测试
npm run lint # 代码检查
Vue 特定规范
组件规范
- 使用
<script setup> 语法糖
- 组件 props 使用 TypeScript 泛型定义
- 事件使用
emits 声明
- 组合式函数使用 useXxx 命名（如 useUser）
样式规范
- 使用 SCSS
- 使用 scoped CSS 避免样式污染
- 遵循 BEM 命名规范
- 公共样式放在 src/styles/ 目录
目录结构
src/
├── components/ # 公共组件
├── composables/ # 组合式函数（Vue 3 特色）
├── views/ # 页面组件
├── router/ # 路由配置
├── stores/ # Pinia stores
├── api/ # API 接口
└── styles/ # 全局样式
Pinia 使用规范
- Store 使用 defineStore
- 命名使用 useXxxStore 形式
- State 使用箭头函数返回对象
- Getters 纯函数化
- Actions 支持 async/await
注意事项
- Vue 3 推荐使用 Composition API，不要使用 Options API
- 组件通信优先使用 props/emits，复杂场景使用 provide/inject
- 表单验证使用 Vuelidate 或 Zod
- 不要在模板中使用复杂的表达式，复杂的逻辑放到 computed 或 methods 中
## 小程序项目的AGENTS.md
如果你是做微信小程序或者支付宝小程序的，AGENTS.md 里需要特别说明平台限制和兼容性问题。
```markdown
# AGENTS.md - 微信小程序项目
## 技术栈
- 原生微信小程序
- TypeScript
- Vant Weapp（UI 组件库）
- MobX（状态管理）
## 开发命令
```bash
npm install
npm run dev:wechat # 开发模式
npm run build:wechat # 生产构建
平台限制
- 不支持 window 对象
- 不支持 DOM 操作
- 不支持 ES6 装饰器
- 文件系统操作使用 wx.getFileSystemManager()
- 网络请求使用 wx.request()
目录结构
src/
├── components/ # 自定义组件
├── pages/ # 页面
├── utils/ # 工具函数
├── services/ # API 服务
└── styles/ # 样式文件
样式规范
- 使用 rpx 单位实现自适应
- 小程序样式不支持 CSS 变量
- 图片资源放在 static/ 目录
- 使用 iconfont 字体图标
注意事项
- 所有页面需要在 app.json 中注册
- 自定义组件需要在对应页面的 json 文件中声明
- 使用 webview 组件需要配置业务域名
- 用户授权使用 wx.getUserProfile（注意接口变化）
## 前端AGENTS.md的特别注意点
前端项目有一些特殊性，在写AGENTS.md的时候需要特别注意。
构建工具一定要写清楚。现在前端构建工具特别多，Vite、Webpack、Parcel、esbuild，不同的工具命令完全不一样。你不写清楚，AI根本不知道用什么命令来启动项目。
UI框架的版本也要写。React 18 和 React 17 的写法有差异，Vue 3 和 Vue 2 更是两套完全不同的体系。你不说明白，AI 可能给你写出过时的代码。
组件库的选择和用法也要写。如果你用了 Ant Design 或者 Element Plus 这些组件库，最好把常用的组件用法也列一列。要不然 AI 给你调用的 API 可能是错的。
状态管理方案一定要写。前端状态管理现在是百花齐放，Redux、Zustand、Jotai、Recoil、Pinia、Vuex……每个方案的 API 都不同。你不写，AI 生成的代码大概率会用错。
## 小结
前端项目的AGENTS.md，后端项目的要求不太一样。前端更注重组件规范、样式方案、状态管理这些和界面相关的细节。后端则更关注数据处理、业务逻辑、接口设计这些方面。
下期我们聊聊后端项目的AGENTS.md怎么写，包括 Node.js、Java、Go 这些常见技术栈。敬请期待。
---
来源：https://www.cnblogs.com/fanshaoO/p/19714624 |
發表於 2026-3-16 18:36:00