前端开发场景实战
<h1 id="reactvue项目怎么写agentsmd">React/Vue项目怎么写AGENTS.md</h1><h2 id="开头先说说">开头先说说</h2>
<p>前面两篇把基础概念讲完了，这篇我们来点实在的，专门聊聊前端项目怎么写AGENTS.md。</p>
<p>我自己在前端项目里踩过不少坑。最开始写AGENTS.md的时候，我把后端那一套搬过来，结果AI该不会的还是不会——它不知道前端用什么构建工具、组件怎么组织、样式怎么写。后来慢慢摸索，才总结出一些前端特有的门道。</p>
<h2 id="react项目的agentsmd怎么写">React项目的AGENTS.md怎么写</h2>
<p>先上一个我在React项目里用的AGENTS.md模板。</p>
<pre><code class="language-markdown"># AGENTS.md - React Monorepo 项目
## 项目架构
基于 pnpm + Turborepo 的 Monorepo 项目，包含多个 React 应用包。
## 技术栈
- React 18
- TypeScript
- Vite
- React Router 6
- Zustand（状态管理）
- TanStack Query（服务端状态）
- Vitest + Testing Library
## 开发命令
### 安装依赖
```bash
pnpm install
</code></pre>
<h3 id="启动开发服务器">启动开发服务器</h3>
<pre><code class="language-bash">pnpm dev # 启动所有
pnpm dev --filter @myapp/web # 启动特定应用
</code></pre>
<h3 id="构建">构建</h3>
<pre><code class="language-bash">pnpm build
pnpm build --filter @myapp/web
</code></pre>
<h3 id="测试">测试</h3>
<pre><code class="language-bash">pnpm test # 监听模式
pnpm test -- --run # 单次运行
pnpm test -- --coverage # 带覆盖率
</code></pre>
<h3 id="代码检查">代码检查</h3>
<pre><code class="language-bash">pnpm lint
pnpm typecheck
</code></pre>
<h2 id="代码规范">代码规范</h2>
<h3 id="组件规范">组件规范</h3>
<ul>
<li>使用函数式组件 + Hooks</li>
<li>组件文件使用 PascalCase（如 UserProfile.tsx）</li>
<li>使用 <code><script setup></code> 语法糖（Vue 项目）</li>
</ul>
<h3 id="样式规范">样式规范</h3>
<ul>
<li>使用 CSS Modules 或 styled-components</li>
<li>样式文件使用 kebab-case（如 user-profile.module.css）</li>
<li>禁止使用全局样式（除 reset/normalize）</li>
</ul>
<h3 id="typescript-规范">TypeScript 规范</h3>
<ul>
<li>启用 strict 模式</li>
<li>禁止使用 any 类型</li>
<li>接口使用 I 前缀（如 IUser）</li>
<li>类型定义优先使用 type</li>
</ul>
<h3 id="状态管理">状态管理</h3>
<ul>
<li>服务端状态使用 TanStack Query</li>
<li>客户端状态使用 Zustand</li>
<li>组件内部状态使用 useState</li>
</ul>
<h3 id="目录结构">目录结构</h3>
<pre><code>src/
├── components/ # 公共组件
├── features/ # 功能模块
├── hooks/ # 自定义 Hooks
├── services/ # API 调用
├── stores/ # Zustand stores
├── types/ # 类型定义
└── utils/ # 工具函数
</code></pre>
<h2 id="测试要求">测试要求</h2>
<ul>
<li>测试文件放在源文件同目录或 <strong>tests</strong> 目录</li>
<li>测试文件命名：xxx.test.tsx 或 xxx.spec.tsx</li>
<li>单元测试覆盖率达到 70% 以上</li>
<li>提交前必须通过所有测试</li>
<li>UI 组件使用 Testing Library 测试用户行为</li>
</ul>
<h2 id="注意事项">注意事项</h2>
<ul>
<li>路由配置在 src/routes/ 目录</li>
<li>API 请求统一使用 services/ 目录下的模块</li>
<li>公共组件必须包含 Storybook stories</li>
<li>图片等静态资源放在 public/ 或 src/assets/</li>
<li>环境变量使用 .env.local，本地敏感配置使用 .env.local.example 作为模板</li>
</ul>
<pre><code>
这个模板基本上覆盖了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 # 代码检查
</code></pre>
<h2 id="vue-特定规范">Vue 特定规范</h2>
<h3 id="组件规范-1">组件规范</h3>
<ul>
<li>使用 <code><script setup></code> 语法糖</li>
<li>组件 props 使用 TypeScript 泛型定义</li>
<li>事件使用 <code>emits</code> 声明</li>
<li>组合式函数使用 useXxx 命名（如 useUser）</li>
</ul>
<h3 id="样式规范-1">样式规范</h3>
<ul>
<li>使用 SCSS</li>
<li>使用 scoped CSS 避免样式污染</li>
<li>遵循 BEM 命名规范</li>
<li>公共样式放在 src/styles/ 目录</li>
</ul>
<h3 id="目录结构-1">目录结构</h3>
<pre><code>src/
├── components/ # 公共组件
├── composables/ # 组合式函数（Vue 3 特色）
├── views/ # 页面组件
├── router/ # 路由配置
├── stores/ # Pinia stores
├── api/ # API 接口
└── styles/ # 全局样式
</code></pre>
<h3 id="pinia-使用规范">Pinia 使用规范</h3>
<ul>
<li>Store 使用 defineStore</li>
<li>命名使用 useXxxStore 形式</li>
<li>State 使用箭头函数返回对象</li>
<li>Getters 纯函数化</li>
<li>Actions 支持 async/await</li>
</ul>
<h2 id="注意事项-1">注意事项</h2>
<ul>
<li>Vue 3 推荐使用 Composition API，不要使用 Options API</li>
<li>组件通信优先使用 props/emits，复杂场景使用 provide/inject</li>
<li>表单验证使用 Vuelidate 或 Zod</li>
<li>不要在模板中使用复杂的表达式，复杂的逻辑放到 computed 或 methods 中</li>
</ul>
<pre><code>
## 小程序项目的AGENTS.md
如果你是做微信小程序或者支付宝小程序的，AGENTS.md 里需要特别说明平台限制和兼容性问题。
```markdown
# AGENTS.md - 微信小程序项目
## 技术栈
- 原生微信小程序
- TypeScript
- Vant Weapp（UI 组件库）
- MobX（状态管理）
## 开发命令
```bash
npm install
npm run dev:wechat # 开发模式
npm run build:wechat# 生产构建
</code></pre>
<h2 id="平台限制">平台限制</h2>
<ul>
<li>不支持 window 对象</li>
<li>不支持 DOM 操作</li>
<li>不支持 ES6 装饰器</li>
<li>文件系统操作使用 wx.getFileSystemManager()</li>
<li>网络请求使用 wx.request()</li>
</ul>
<h2 id="目录结构-2">目录结构</h2>
<pre><code>src/
├── components/ # 自定义组件
├── pages/ # 页面
├── utils/ # 工具函数
├── services/ # API 服务
└── styles/ # 样式文件
</code></pre>
<h2 id="样式规范-2">样式规范</h2>
<ul>
<li>使用 rpx 单位实现自适应</li>
<li>小程序样式不支持 CSS 变量</li>
<li>图片资源放在 static/ 目录</li>
<li>使用 iconfont 字体图标</li>
</ul>
<h2 id="注意事项-2">注意事项</h2>
<ul>
<li>所有页面需要在 app.json 中注册</li>
<li>自定义组件需要在对应页面的 json 文件中声明</li>
<li>使用 webview 组件需要配置业务域名</li>
<li>用户授权使用 wx.getUserProfile（注意接口变化）</li>
</ul>
<pre><code>
## 前端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 这些常见技术栈。敬请期待。
---
</code></pre><br><br>
来源：https://www.cnblogs.com/fanshaoO/p/19714624
頁:
[1]