AGENTS.md 统一配置实战：一份文件驱动四大编码工具

1项目根目录/
2├── CLAUDE.md        # 给 Claude Code 看的
3├── .cursorrules     # 给 Cursor 看的
4├── .windsurfrules   # 给 Windsurf 看的
5├── copilot-instructions.md   # 给 GitHub Copilot 看的
6└── AGENTS.md        # 给 Codex 看的

1仓库根/
2├── AGENTS.md              ← 全局约定（必读）
3├── src/
4│   ├── AGENTS.md          ← src/ 下的约定
5│   └── api/
6│       └── AGENTS.md      ← src/api/ 下的约定（最具体）
7└── tests/
8    └── AGENTS.md

11. 仓库根/AGENTS.md          优先级 低
22. src/AGENTS.md                  ↓
33. src/api/AGENTS.md         优先级 高

1# 项目名称
2
3一句话说明这个项目做什么，以及它的核心约束。
4
5## 技术栈
6（语言 / 框架 / 版本 / 包管理器 / 关键依赖）
7
8## 常用命令
9（构建 / 测试 / lint / 迁移，可直接复制执行）
10
11## 代码规范
12（命名 / 文件组织 / 注释 / 错误处理 / 类型）
13
14## 测试要求
15（什么必须测 / 覆盖率 / 怎么跑）
16
17## 架构速览
18（目录职责 + 关键模块关系）
19
20## 禁区
21（绝对不能做的事，含原因）
22
23## 工作流约定
24（分支 / 提交 / PR / Code Review）
25
26## 环境说明
27（环境变量 / 本地启动 / 依赖服务）

1## 技术栈
2- TypeScript 5.6（strict 模式，**不要关 strict**）
3- Next.js 14.2 App Router（不要用 Pages Router）
4- Tailwind CSS 3.4（不要升 4.x，配置文件格式变了）
5- PostgreSQL 15 + Prisma 5.22
6- 包管理器：pnpm 9（**不要用 npm/yarn**）

1## 常用命令
2# 开发
3pnpm dev                    # 启动开发服务器 localhost:3000
4
5# 测试
6pnpm test                   # 跑全部单测
7pnpm test -- --watch        # 监听模式
8pnpm test:integration       # 集成测试（需要本地 Postgres 起来）
9
10# 质量
11pnpm lint                   # ESLint
12pnpm typecheck              # tsc --noEmit
13pnpm format                 # Prettier 写入
14
15# 数据库
16pnpm prisma migrate dev     # 本地建迁移
17pnpm prisma studio          # 可视化查看数据

1## 禁区
2
31. **禁止直接改 `prisma/schema.prisma` 后手动写 SQL 迁移**
4   原因：本项目用 `prisma migrate dev` 自动生成迁移，手写会导致迁移历史与 schema 不一致。
5
62. **禁止在 `app/` 目录下写 `console.log`**
7   原因：CI 有 lint 规则拦截，且线上日志采集用的是 `lib/logger.ts`。
8
93. **禁止删除 `lib/legacy/` 下的任何文件**
10   原因：这批文件在灰度切流中，还有 12% 流量依赖，删除即 P0。
11
124. **禁止在组件里直接 fetch，一律走 `lib/api/client.ts`**
13   原因：统一的错误处理和鉴权拦截在那里面。
14
155. **禁止提交 `.env*` 文件**
16   原因：历史上有过一次密钥泄露事故。

11. 当前目录及祖先目录的 CLAUDE.md（如果存在）
22. 否则回退到 AGENTS.md
33. 用户级 ~/.claude/CLAUDE.md
44. 项目级 .claude/CLAUDE.local.md（本地私有，不提交）

1# 让 Claude Code 自己说出来
2claude -p "列出你当前加载的所有记忆文件内容来源"

1# 初始化
2codex
3
4# 指定工作目录（影响 AGENTS.md 加载路径）
5codex --cd ./src/api

1# 把旧的 .cursorrules 内容合并进 AGENTS.md 的「代码规范」区块
2cat .cursorrules >> /tmp/old_rules.md
3# 手动整理后合并，然后删除
4rm .cursorrules

1ls -la | grep -iE "claude|cursor|agents|windsurf|copilot"

1git mv CLAUDE.md AGENTS.md

1ln -s AGENTS.md CLAUDE.md
2echo "CLAUDE.md" >> .gitignore    # 软链不提交

1# Claude Code
2claude -p "你读到的项目规范第一条是什么"
3
4# Codex
5codex "你读到的项目规范第一条是什么"
6
7# Cursor / Trae
8# 在对话框里问同样的问题

1## 代码规范
2
3### TypeScript
4- strict 模式全开，禁止 `any`（确需时用 `unknown` + 类型守卫）
5- 导出组件用命名导出，不用 default 导出
6- 类型定义放 `types/` 目录，不要散落在组件文件里
7- 异步函数一律返回 `Result<T, E>`，不用 try/catch 吞异常
8- 禁止 `as` 断言，用类型守卫函数
9
10### 命名
11- 文件名：kebab-case（`user-profile.tsx`）
12- 组件：PascalCase
13- 函数/变量：camelCase
14- 常量：SCREAMING_SNAKE_CASE
15- 数据库表：snake_case 复数（`user_profiles`）
16
17### 注释
18- 只写「为什么」，不写「做了什么」
19- 每个导出函数必须有 JSDoc
20- 禁止注释掉的代码，直接删（git 里有历史）

1## 测试要求
2
3- 每个 service 方法必须有单测，覆盖率门槛 70%
4- 涉及金额/权限/状态机的逻辑，覆盖率必须 100%
5- 测试文件命名 `*.test.ts`，与源码同目录
6- 用 `describe` 描述被测对象，`it` 描述预期行为（用中文也行，但要一致）
7- **禁止 mock 数据库**，用 testcontainers 起真实 Postgres
8- 集成测试标记 `@integration`，CI 单独跑

1## 工作流约定
2
3- 分支：`feature/xxx` `fix/xxx` `chore/xxx`
4- 提交信息：Conventional Commits（`feat:` `fix:` `chore:`）
5- 提交前必跑：`pnpm lint && pnpm typecheck && pnpm test`
6- PR 描述必须包含：改了什么 / 为什么改 / 怎么验证
7- **禁止 force push 到 main**
8- PR 单文件改动超 500 行要拆分（审查不过来）

1## 架构速览
2
3\`\`\`
4┌─────────────┐
5│   app/      │  Next.js App Router 页面
6├─────────────┤
7│ components/ │  纯展示组件，不含业务逻辑
8├─────────────┤
9│   lib/      │  业务逻辑层
10│  ├ api/     │  外部 API 封装
11│  ├ db/      │  Prisma 数据访问
12│  └ utils/   │  纯函数工具
13├─────────────┤
14│   types/    │  全局类型
15└─────────────┘
16\`\`\`
17
18关键约定：
19- `app/` 只做路由和布局，不写业务逻辑
20- `components/` 不直接调 API，通过 props 接收数据
21- `lib/db/` 是唯一允许直接操作 Prisma 的地方

1## 错误处理
2
3统一使用 `Result<T, E>` 模式：
4
5\`\`\`typescript
6type Result<T, E = AppError> =
7  | { ok: true; value: T }
8  | { ok: false; error: E };
9\`\`\`
10
11规则：
12- 不抛异常，返回 Result
13- 错误信息必须包含上下文（哪个操作、哪个 id）
14- 面向用户的错误走 `AppError`，内部错误记日志
15- **禁止空 catch 块**（`catch {}`）

1## 环境说明
2
3必需环境变量（缺一个启动失败）：
4- `DATABASE_URL`      Postgres 连接串
5- `REDIS_URL`         Redis 连接串
6- `JWT_SECRET`        JWT 签名密钥
7
8可选：
9- `LOG_LEVEL`         默认 info
10- `SENTRY_DSN`        不配则不启用错误上报
11
12本地启动：
131. `docker compose up -d`  起 Postgres + Redis
142. `cp .env.example .env`
153. `pnpm prisma migrate dev`
164. `pnpm dev`

1## 性能约束
2
3- 单页面首屏 JS bundle < 200KB（CI 有门禁）
4- 数据库查询必须走索引，`EXPLAIN` 确认无全表扫描
5- 列表查询一律分页，单页最多 100 条
6- **禁止在循环里查数据库**（N+1），用 `include` 或批量查询
7- 图片一律走 next/image，禁止裸 `<img>`

1## 安全约定
2
3- 所有用户输入必须校验，用 zod schema
4- SQL 一律用 Prisma 参数化查询，禁止字符串拼接
5- 敏感字段（密码/token/身份证）响应前必须剔除
6- **禁止把密钥写进代码**，走环境变量
7- 接口鉴权用 `lib/auth/middleware.ts`，不要自己实现

1## AI 协作约定
2
3- 改动前先说明你要改哪些文件，等我确认
4- 一次只改一个关注点，不要顺手重构无关代码
5- 不确定 API 是否存在时去查 `node_modules` 里的类型定义，不要凭印象写
6- 生成的代码必须通过 `pnpm typecheck`，不通过不要交付
7- 如果发现 AGENTS.md 的规范与实际情况冲突，**告诉我，不要自行违反**

1## 禁区
2
31. 禁止修改 `lib/legacy/` —— 灰度中，12% 流量依赖
42. 禁止改 `prisma/migrations/` 下已提交的迁移 —— 会导致线上 schema 漂移
53. 禁止在 `app/api/` 写业务逻辑 —— 那层只做参数校验和转发
64. 禁止引入新的 UI 库 —— 已在去 antd 化的过程中
75. 禁止提交 `console.log` —— CI 拦截

1# 电商中台 API
2
3基于 Next.js 14 App Router 的电商中台后端，为 B 端商家后台和 C 端小程序提供接口。
4核心约束：金额计算必须用 Decimal，禁止浮点数。
5
6## 技术栈
7- TypeScript 5.6（strict，禁止 any）
8- Next.js 14.2 App Router
9- Prisma 5.22 + PostgreSQL 15
10- Redis 7（缓存 + 会话）
11- pnpm 9（不要用 npm/yarn）
12
13## 常用命令
14pnpm dev                 开发服务器 :3000
15pnpm test                单测
16pnpm test:integration    集成测试（需先 docker compose up -d）
17pnpm lint && pnpm typecheck   提交前必跑
18pnpm prisma migrate dev  建迁移
19
20## 代码规范
21- 金额一律用 Decimal.js，禁止 number 做金额运算
22- 所有 service 返回 Result<T>
23- 文件名 kebab-case，类型定义进 types/
24- 禁止 console.log，用 lib/logger
25
26## 测试要求
27- service 层覆盖率 ≥70%，金额/库存逻辑 100%
28- 禁止 mock 数据库，用 testcontainers
29- 每个 PR 必须带测试
30
31## 架构速览
32app/api/          路由层（只做校验转发）
33lib/service/      业务逻辑（主要在这里写代码）
34lib/db/           数据访问（唯一允许用 Prisma 的地方）
35lib/cache/        Redis 封装
36types/            全局类型
37
38## 禁区
391. 禁止金额用 number —— 浮点精度会导致对账不平，出过一次 P0
402. 禁止直接改已提交的迁移文件
413. 禁止在 service 里直接写 SQL
424. 禁止提交 .env
43
44## 工作流
45- 分支 feature/xxx，Conventional Commits
46- PR 必须说明：改了什么 / 为什么 / 怎么验证
47- 单 PR 不超 500 行改动

1<!-- src/api/legacy/AGENTS.md -->
2# 遗留接口层特别约定
3
4这里是 2024 年的老接口，正在逐步迁移到 src/api/v2/。
5
6## 特别约定
7- 不要在这里新增接口，新增一律去 v2
8- 修改时**不要顺手重构**，保持最小改动（这批接口没有测试覆盖）
9- 命名风格是 snake_case（与全局 kebab-case 不同，是历史遗留，不要改）
10- 如果要动这里的逻辑，先告诉我迁移计划，我评估后再动

1<!-- src/components/AGENTS.md -->
2# 组件规范
3- 用 TypeScript          ← 根目录已写，重复
4- 命名用 PascalCase      ← 根目录已写，重复
5- 组件不超过 200 行       ← 这才是该写的例外

1# .github/workflows/agents-md.yml
2name: AGENTS.md 规范检查
3on: [pull_request]
4
5jobs:
6  check:
7    runs-on: ubuntu-latest
8    steps:
9      - uses: actions/checkout@v4
10
11      - name: 禁止提交旧的配置文件
12        run: |
13          for f in .cursorrules .windsurfrules copilot-instructions.md CLAUDE.md; do
14            if [ -f "$f" ]; then
15              echo "❌ 发现 $f，请合并到 AGENTS.md 后删除"
16              exit 1
17            fi
18          done
19
20      - name: AGENTS.md 必须存在
21        run: |
22          test -f AGENTS.md || { echo "❌ 缺少 AGENTS.md"; exit 1; }
23
24      - name: 长度检查（根目录不超过 200 行）
25        run: |
26          lines=$(wc -l < AGENTS.md)
27          if [ "$lines" -gt 200 ]; then
28            echo "❌ AGENTS.md 有 $lines 行，超过 200 行上限，请精简"
29            exit 1
30          fi
31
32      - name: 必须包含核心区块
33        run: |
34          for sec in "技术栈" "常用命令" "代码规范" "禁区"; do
35            grep -q "## $sec" AGENTS.md || { echo "❌ 缺少区块：$sec"; exit 1; }
36          done

1monorepo/
2├── AGENTS.md              ← 全局：包管理器、Node 版本、CI 流程
3├── packages/
4│   ├── web/AGENTS.md      ← Next.js 相关
5│   ├── api/AGENTS.md      ← 后端相关
6│   └── shared/AGENTS.md   ← 公共库相关

1详细的 API 设计规范见 [docs/api-conventions.md](./docs/api-conventions.md)。
2涉及接口设计时先读这份文档。

1<!-- .github/pull_request_template.md -->
2- [ ] 本次改动是否涉及技术栈/规范变化？是 → 已同步更新 AGENTS.md

1claude -p "这个项目里金额用什么类型？为什么？"