AGENTS.md 配置指南

your-project/
  AGENTS.md          ← 仓库级配置
  src/
  tests/
  package.json

# AGENTS.md

- All code should be written in TypeScript with strict mode enabled
- Use Prettier for formatting, ESLint for linting
- Tests use Vitest, placed in `__tests__/` directories
- Run `npm run lint && npm test` before completing any task
- Never modify files in the `vendor/` directory
- API responses must follow the standard envelope format: `{ code, data, message }`

# AGENTS.md

## 代码规范

- 使用 TypeScript strict 模式
- 变量命名使用 camelCase，类型使用 PascalCase
- 每个函数不超过 50 行

## 测试要求

- 单元测试覆盖率目标：80%
- 测试文件与源文件同名，后缀 `.test.ts`
- Mock 外部依赖，不发起真实网络请求

## 禁止事项

- 不要使用 `any` 类型
- 不要直接操作 DOM（使用 React 状态管理）
- 不要在循环中使用 `await`（使用 `Promise.all`）

# 全局 AGENTS.md

## 通用规范

- 代码注释使用英文
- Git commit message 遵循 Conventional Commits
- 所有密码、密钥、token 不得硬编码在源码中
- 生成代码前先阅读相关的现有代码，保持风格一致
- 如果不确定某个改动的影响，先在注释中说明，不要自行决定

## 输出偏好

- 优先使用项目已有的依赖库，不随意引入新依赖
- 错误处理要完整，不要吞掉异常
- 日志输出要有意义，包含上下文信息

# AGENTS.md

## 项目简介
这是一个 React + Node.js 全栈电商项目，使用 TypeScript 开发。

## 技术栈

- 前端：React 19 + TailwindCSS + Zustand
- 后端：Node.js + Fastify + Prisma
- 数据库：PostgreSQL 16
- 测试：Vitest + Playwright

## 代码规范

- 组件文件使用 PascalCase：`UserProfile.tsx`
- 工具函数使用 camelCase：`formatDate.ts`
- API 路由使用 kebab-case：`/api/user-orders`
- 数据库字段使用 snake_case：`created_at`

## 项目结构

- `src/components/` - React 组件
- `src/pages/` - 页面组件
- `src/api/` - 后端 API 路由
- `src/lib/` - 共享工具库
- `prisma/` - 数据库 schema 和迁移

## 运行命令

- `npm run dev` - 启动开发服务器
- `npm run build` - 构建生产版本
- `npm test` - 运行所有测试
- `npm run lint` - 代码检查
- `npx prisma migrate dev` - 执行数据库迁移

your-project/
  AGENTS.md                  ← 项目级规则
  src/
    components/
      AGENTS.md              ← 组件目录规则
    api/
      AGENTS.md              ← API 目录规则

# 组件规范

- 所有组件必须是函数组件（不用 class 组件）
- Props 必须有 TypeScript 接口定义
- 每个组件必须有 displayName
- 样式使用 TailwindCSS，不要写内联 style
- 复杂组件拆分为子组件，单文件不超过 200 行
- 通用组件放在 `ui/` 子目录

# API 规范

- 所有端点必须有请求参数校验（使用 Zod schema）
- 统一错误格式：`{ code: number, message: string, details?: any }`
- 数据库操作必须在事务中执行
- 敏感操作必须记录审计日志
- 分页接口统一使用 cursor-based pagination

全局（~/.codex/AGENTS.md）
  ↓ 被仓库级覆盖
仓库根（项目/AGENTS.md）
  ↓ 被子目录覆盖
子目录（项目/src/api/AGENTS.md）← 最高优先级

# AGENTS.md

## 项目信息
React 19 + TypeScript + TailwindCSS 前端项目。

## 代码规范

- 使用函数组件 + Hooks，禁止 class 组件
- 状态管理使用 Zustand，不要引入 Redux
- 样式使用 TailwindCSS，不写 CSS 文件
- 使用 `@/` 路径别名引用 src 下的模块
- 组件 Props 定义为 interface，命名为 `{组件名}Props`

## 文件命名

- 组件文件：PascalCase（`UserAvatar.tsx`）
- Hook 文件：camelCase + use 前缀（`useAuth.ts`）
- 工具文件：camelCase（`formatDate.ts`）
- 常量文件：camelCase（`apiEndpoints.ts`）

## 组件规范

- 每个组件导出 Props 类型和组件本身
- 使用 `React.memo` 包装纯展示组件
- 事件处理函数命名为 `handle{事件名}`
- 避免在 render 中创建新对象或函数

## 测试

- 使用 Vitest + React Testing Library
- 测试文件放在 `__tests__/` 目录
- 优先测试用户行为，而非实现细节
- 运行命令：`npm test`

## 依赖管理

- 添加新依赖前检查现有依赖是否已能满足需求
- 优先使用轻量级库
- 所有依赖必须有 TypeScript 类型定义

# AGENTS.md

## 项目信息
Python 3.12 + FastAPI + SQLAlchemy 后端服务。

## 代码规范

- 类型注解：所有函数参数和返回值必须有类型注解
- 异步优先：IO 操作一律使用 async/await
- 文档字符串：所有公开函数使用 Google 风格 docstring
- 导入排序：标准库 → 第三方 → 本地模块（用 isort 管理）

## 项目结构

- `app/api/` - API 路由（按功能分 router）
- `app/models/` - SQLAlchemy 数据模型
- `app/schemas/` - Pydantic 请求/响应模型
- `app/services/` - 业务逻辑层
- `app/core/` - 配置、安全、依赖注入
- `tests/` - 测试文件，镜像 app 目录结构
- `alembic/` - 数据库迁移

## 编码规范

- 路由函数命名：`get_users`、`create_order`（动词_名词）
- Service 层方法命名：与路由函数对应
- 数据模型字段使用 snake_case
- 所有数据库操作通过 Service 层，路由层不直接操作 ORM
- 敏感数据（密码、token）不能出现在日志和响应中

## 错误处理

- 业务异常使用自定义 Exception 类
- 统一异常处理器返回标准格式：`{"code": int, "message": str}`
- 数据库操作包裹在 try/except 中，捕获 IntegrityError 等
- 不要使用 bare except

## 测试

- 框架：pytest + pytest-asyncio + httpx
- 使用 fixture 管理测试数据库和客户端
- 运行：`pytest -v --cov=app`
- 最低覆盖率目标：80%

## 环境管理

- 使用 .env 文件管理配置，通过 pydantic-settings 加载
- 不同环境的配置差异通过环境变量覆盖
- 绝不在代码中硬编码数据库连接字符串、密钥等

# AGENTS.md

## 项目信息
全栈 Web 应用：前端 Next.js 15 + 后端 API Routes + PostgreSQL。
Monorepo 结构，使用 Turborepo 管理。

## 目录结构

- `apps/web/` - Next.js 前端
- `apps/api/` - 独立 API 服务（Node.js + Fastify）
- `packages/ui/` - 共享 UI 组件库
- `packages/types/` - 共享 TypeScript 类型
- `packages/utils/` - 共享工具函数
- `packages/db/` - 数据库 schema（Drizzle ORM）

## 通用规范

- 语言：TypeScript strict 模式
- 格式化：Prettier（配置已在根目录）
- Lint：ESLint（配置已在根目录）
- 提交前运行：`turbo lint test`

## 前端规范（apps/web/）

- 使用 App Router，不用 Pages Router
- Server Components 优先，Client Components 只在必要时使用
- 数据获取使用 Server Actions 或 Route Handlers
- 样式使用 TailwindCSS
- 图片使用 next/image 组件

## API 规范（apps/api/）

- RESTful 设计，URL 使用 kebab-case
- 请求校验使用 Zod
- 返回格式：`{ success: boolean, data?: T, error?: string }`
- 认证使用 JWT，中间件统一校验
- 限流规则写在路由装饰器中

## 数据库规范（packages/db/）

- 使用 Drizzle ORM，schema 定义在 `schema/` 目录
- 迁移命令：`pnpm db:migrate`
- 命名：表名复数（`users`），字段 snake_case
- 所有表必须有 `created_at` 和 `updated_at`
- 软删除使用 `deleted_at` 字段

## 共享包规范

- packages 之间通过 workspace 引用
- 共享类型定义在 `packages/types/` 中
- 不在 packages 中引用 apps 的代码

your-project/
  AGENTS.md          ← Codex 读取
  CLAUDE.md          ← Claude Code 读取
  src/
  ...

# AGENTS.md

> 本项目同时使用 Codex 和 Claude Code。核心规范见下文。
> Claude Code 用户请参考 CLAUDE.md。

## 核心规范
（共享内容）

git add AGENTS.md
git commit -m "feat: add AGENTS.md for Codex configuration"

<!-- PR 描述 -->
## 改动说明
更新 AGENTS.md：

- 新增 API 分页规范（cursor-based）
- 明确禁止在组件中直接调用 fetch
- 添加日志格式要求

## 高效指令（Codex 遵循度高）

- 明确的格式要求：使用 PascalCase 命名组件文件
- 明确的禁止事项：不要使用 any 类型
- 运行命令：完成后运行 npm test 确认通过
- 文件位置规范：测试文件放在 __tests__ 目录
- 依赖限制：不要引入新的 npm 包，使用现有依赖

## 低效指令（建议避免）

- 过于模糊：写好的代码
- 主观判断：使用最佳实践
- 超出范围：考虑用户体验（AI 无法运行 UI）
- 矛盾指令：优先性能 + 优先可读性（需要明确优先级）

## 文件类型规则

### *.test.ts 文件

- 每个 describe 块不超过 10 个 test
- 使用 factory 函数创建测试数据，不要硬编码
- 异步测试必须有超时设置

### *.api.ts 文件

- 必须有请求参数校验
- 必须有错误处理
- 返回值必须有类型注解

### migrations/*.sql 文件

- 不要直接修改，使用 ORM 迁移工具生成

cp CLAUDE.md AGENTS.md

## 代码风格

在本项目中，我们遵循 Google TypeScript 风格指南。所有变量名
使用 camelCase，类名使用 PascalCase。特别注意，枚举值使用
全大写 SNAKE_CASE。导入语句需要按以下顺序排列：首先是 Node.js
内置模块，然后是第三方包，最后是本地模块。每组之间空一行。

## 代码风格

- 遵循 Google TypeScript 风格指南
- 变量名：camelCase
- 类名：PascalCase
- 枚举值：SCREAMING_SNAKE_CASE
- 导入顺序：内置模块 → 第三方包 → 本地模块（组间空行）

## Codex 特定配置

- 完成所有文件修改后，运行 `npm run lint && npm test` 验证
- 如果测试失败，自动修复并重新运行
- 不要修改 .env 和 .env.local 文件

# 假设 AGENTS.md 要求使用 TypeScript
codex "创建一个 hello world 函数"

# 如果 AGENTS.md 生效，Codex 会生成 .ts 文件而非 .js 文件