# AGENTS.md 模板集 ## 模板 1：通用项目模板（最常用） 适用于大多数单体项目。 ```markdown # AGENTS.md ## 项目概述 [项目名称] 是一个 [一句话描述]。技术栈：[列出主要技术]。 ## 开发环境设置 ### 前置要求 - Node.js >= [版本] - [数据库/运行时/其他依赖] ### 安装依赖 ```bash [安装命令，如 pnpm install / npm install / pip install -r requirements.txt] ``` ### 常用命令 ```bash # 启动开发服务器 [dev command] # 运行测试 [test command] # 代码检查 [lint command] # 构建生产版本 [build command] ``` ## 项目结构 ``` [简要目录树，标注关键目录用途] ``` ## 编码规范 ### 命名约定 - 组件：PascalCase - 函数/变量：camelCase - 常量：UPPER_SNAKE_CASE - 文件名：[规则] ### 代码风格 - [规则1，如：使用 TypeScript 严格模式] - [规则2，如：单引号，无分号] - [规则3，如：优先使用函数式模式] ## 测试说明 ### 测试结构 - 单元测试：[说明位置和命名规范] - 集成测试：[说明位置] - E2E 测试：[说明位置] ### 运行测试 ```bash # 运行所有测试 [command] # 运行特定测试 [command --filter "..."] ``` ## PR 规范 - 标题格式：`[scope] 简短描述` - 提交前必须通过 lint 和 test - [其他规则] ## 注意事项 - [已知陷阱/特殊约定] - [安全敏感的操作] ``` --- ## 模板 2：Monorepo 根级模板 适用于 monorepo 根目录，给子包留有指导空间。 ```markdown # AGENTS.md (Root) ## 仓库概述 这是一个 [技术栈] monorepo，包含 [N] 个子包。 ## Monorepo 管理工具 - 包管理器：[pnpm workspaces / yarn workspaces / nx / turborepo] - 构建工具：[工具名] ## 子包概览 | 包名 | 路径 | 用途 | |------|------|------| | [name] | packages/[name] | [说明] | | [name] | packages/[name] | [说明] | ## 全局命令 ```bash # 安装所有依赖 [command] # 运行所有测试 [command] # 全局 lint [command] ``` ## 子包操作 AI 代理会自动使用离当前编辑文件最近的 AGENTS.md。 各子包可在自己目录下放置独立的 AGENTS.md 覆盖本配置。 ## 通用规范 - [跨包通用规则] - [代码提交规范] ``` --- ## 模板 3：前端项目模板 适用于 React/Vue/Next.js 等前端项目。 ```markdown # AGENTS.md ## 项目概述 [项目名] 是一个基于 [框架] 的前端应用。 ## 技术栈 - 框架：[Next.js 14 / React 18 / Vue 3 / ...] - 语言：TypeScript (strict mode) - 样式：[TailwindCSS / CSS Modules / styled-components] - 状态管理：[Zustand / Redux / Pinia] - 包管理：[pnpm / npm / yarn] ## 常用命令 ```bash # 开发 pnpm dev # 构建 pnpm build # 测试 pnpm test # 检查 pnpm lint pnpm type-check ``` ## 目录结构 ``` src/ ├── components/ # 可复用 UI 组件 ├── pages/ # 页面 / 路由组件 ├── hooks/ # 自定义 React Hooks ├── utils/ # 工具函数 ├── types/ # TypeScript 类型定义 ├── stores/ # 状态管理 └── styles/ # 全局样式 ``` ## 组件规范 ### 文件结构 ``` ComponentName/ ├── index.ts # 导出 ├── ComponentName.tsx # 组件实现 ├── ComponentName.test.tsx # 测试 └── types.ts # Props 类型 ``` ### 编码约定 - 组件用 PascalCase，文件同名 - 一个文件一个组件（除非紧密关联的小组件） - Props 使用 TypeScript interface 定义 - 优先使用函数组件 + Hooks - 使用 TailwindCSS 工具类（如已采用） ## 状态管理 - 服务端状态：[React Query / SWR / ...] - 客户端状态：[Zustand / Redux / ...] - 表单状态：[React Hook Form / Formik / ...] ## 测试 ```bash # 单元测试（Vitest） pnpm test # 组件测试（Testing Library） pnpm test:component # E2E（Playwright / Cypress） pnpm test:e2e ``` ``` --- ## 模板 4：后端项目模板 适用于 Node.js/Python/Go 等后端项目。 ```markdown # AGENTS.md ## 项目概述 [项目名] 是一个 [语言/框架] 后端服务。 ## 技术栈 - 运行时/语言：[Node.js 20 / Python 3.12 / Go 1.22] - 框架：[Express / FastAPI / Gin / ...] - 数据库：[PostgreSQL / MongoDB / Redis] - ORM：[Prisma / SQLAlchemy / GORM] ## 常用命令 ```bash # 安装依赖 [command] # 启动开发服务器 [command] # 运行测试 [command] # 数据库迁移 [command] # 代码检查 [command] ``` ## 项目结构 ``` src/ ├── controllers/ # 请求处理 ├── services/ # 业务逻辑 ├── models/ # 数据模型 ├── middleware/ # 中间件 ├── routes/ # 路由定义 ├── utils/ # 工具函数 └── config/ # 配置 tests/ ├── unit/ ├── integration/ └── e2e/ ``` ## API 规范 - RESTful 风格 - 响应格式：`{ success: boolean, data: any, error?: string }` - 错误处理：统一错误中间件 - 请求验证：[Joi / Zod / Pydantic] ## 数据库 ### 迁移 [说明数据库迁移的流程和命令] ### 查询规范 - 使用 ORM 而非原生 SQL（除非必要） - 避免 N+1 查询 - 大查询加分页 ## 测试 ```bash # 所有测试 [command] # 特定测试 [command --filter="auth"] ``` ## 安全 - [认证方式说明] - [授权模型说明] - 敏感配置使用环境变量 ``` --- ## 模板 5：轻量级模板（小项目/库） 适用于小型项目或库，极简风格。 ```markdown # AGENTS.md ## Setup ```bash pnpm install ``` ## Commands - `pnpm dev` - Start dev server - `pnpm test` - Run tests - `pnpm build` - Build for production - `pnpm lint` - Lint and format ## Code Style - TypeScript strict mode - Single quotes, no semicolons - Functional patterns preferred - Export named, not default ## Testing - Unit tests alongside source files (`*.test.ts`) - Run `pnpm test -- --coverage` for coverage report ```