AI 编码工具协同规范

2025+ 必补的一环：Cursor / Claude Code / GitHub Copilot / Trae 等 AI 编码工具已普及，光有 ESLint + Prettier 已经不够。项目需要专门给 AI 写一套「对话规则」，让 AI 真正吃透项目规范。

核心方法论：别把 lint / 格式规则抄进 AI 规则文件——那是双重维护。正确做法是告诉 AI 「改完跑对应命令自查」。规则文件只放工具检查不出来的项目特有约定（业务语义、架构决策）。

一、避坑指南

1. 不要把 lint / 格式规则写进 AI 规则文件：

   • ❌ 把 ESLint 规则抄进 .cursorrules（双重维护、改一处忘一处）
   • ❌ 在规则文件里写「用 2 空格缩进、单引号、不加分号」（Prettier 已经管了）
   • ✅ 规则文件只放工具检查不出来的内容：业务语义、架构决策、命名哲学
   • ✅ 让 AI 改完代码自己跑 lint：规则文件写一句「修改后执行 pnpm lint」即可

   2025+ 共识：规则文件是「项目 context」，不是「项目 rules」。format / lint 的唯一真理来源是配置文件本身。

2. AI 生成的代码必须过 lint：

   • 不要因为「AI 写的」就免检
   • CI / pre-commit 一视同仁，不搞特殊通道
   • 推荐在规则文件里明确告知 AI：「完成修改后必须执行 pnpm lint && pnpm typecheck，有报错就修」

3. 规则文件也要版本管理：

   • .cursorrules / CLAUDE.md 必须 commit 到 git
   • 团队共用一套规则，新人 clone 后即生效

4. 敏感信息绝不入规则文件：

   • 数据库 schema 的字段含义可以写
   • 生产密钥、客户名单、商业机密 绝不能写

5. 避免「AI 写什么我都不管」的心态：

   • AI 是放大器，不是替代品
   • 用得好效率 ×3，用不好技术债 ×3

二、主流 AI 工具与规则文件

工具	规则文件	作用	优先级
Cursor	.cursorrules（旧）/ .cursor/rules/*.mdc（新）	上下文注入	⭐⭐⭐⭐⭐
Claude Code	CLAUDE.md / .claude/CLAUDE.md	项目记忆	⭐⭐⭐⭐⭐
GitHub Copilot	.github/copilot-instructions.md	提示词增强	⭐⭐⭐⭐
Windsurf	.windsurfrules	规则注入	⭐⭐⭐⭐
Trae	.trae/rules / AGENTS.md	规则注入	⭐⭐⭐⭐
通用标准	AGENTS.md / CLAUDE.md	跨工具规范（新趋势）	⭐⭐⭐⭐⭐

2025+ 趋势：AGENTS.md 正在成为跨 AI 工具的事实标准（Cursor 0.45+ / Claude Code / Trae / Windsurf 都已支持）。推荐优先用 AGENTS.md 写一遍，工具专有文件用 @import 引用。

AGENTS.md vs .cursorrules（怎么选？）

维度	AGENTS.md	.cursorrules（旧）	.cursor/rules/*.mdc（新）
出身	跨工具社区标准（2024+）	Cursor 私有（早期）	Cursor 官方新格式
格式	纯 Markdown	纯 Markdown	Markdown + YAML frontmatter
支持工具	Cursor / Claude / Trae / Windsurf	仅 Cursor	仅 Cursor
上下文粒度	整文件注入	整文件注入	可按 glob 分文件、按需加载
多文件	一个文件	一个文件	✅ 可拆成多个（react.mdc 等）
维护成本	1 份	1 份	1 份（但要分文件）

2026 现实：用 Cursor 0.45+ / Claude Code 2+ / Trae 主流版本，只写 AGENTS.md 一个文件，所有工具都会自动加载。

一个项目需要同时有这俩吗？

答：不需要写两份。 三种方案按场景选：

你的情况	推荐方案	文件结构
多 AI 工具混用（最常见）	A. 写一份 AGENTS.md	AGENTS.md
只用 Cursor + 项目大	B. 用 .mdc 分文件	.cursor/rules/{topic}.mdc
Cursor 深度用户 + 多工具备份	C. AGENTS.md 为主 + .mdc 引用	AGENTS.md + .cursor/rules/*.mdc 用 @import

方案 A：单文件 AGENTS.md（90% 项目首选）

# 项目根
AGENTS.md     # 一份文件，Cursor/Claude/Trae/Windsurf 全读

# AGENTS.md

## Tech Stack

...（所有内容写在这）

优点：一份真理来源，零适配成本，团队新人 clone 即用。

方案 B：Cursor .mdc 多文件

适合「项目大到要按需加载」「不同类型文件有不同规则」的场景：

.cursor/
  rules/
    react.mdc           # 只在改 React 文件时加载
    api.mdc             # 只在改 API 路由时加载
    testing.mdc         # 只在改测试时加载
    project.mdc         # 全局规则（alwaysApply: true）

react.mdc 示例：

---
description: React 组件规范
globs:
  - "**/*.{tsx,jsx}"
alwaysApply: false # 只匹配 glob 时加载
---

## React Rules

- 优先用 Server Component
- 不要在 useEffect 里调接口，用 useQuery
- ...

方案 C：AGENTS.md + .mdc 引用（进阶）

## <!-- .cursor/rules/project.mdc -->

description: 项目核心规范
alwaysApply: true

---

<!-- 复用 AGENTS.md 的内容 -->

@import ../../AGENTS.md

<!-- Cursor 专属优化 -->

## Cursor Tips

- 改完用 `pnpm test --watch` 验证

决策树

开始
├─ 你用几个 AI 工具？
│   ├─ 1 个（仅 Cursor）→ 方案 B（.mdc）或方案 A（AGENTS.md 都行）
│   ├─ 1 个（仅 Claude Code / Trae）→ 方案 A（AGENTS.md）
│   └─ 多个 → 方案 A（**AGENTS.md 一份搞定**）
│
└─ 项目规模？
    ├─ 小（< 50 文件）→ 方案 A（单文件足够）
    └─ 大（> 50 文件）→ 方案 B（拆 .mdc 按需加载，省 token）

实测推荐

场景	推荐
团队项目 / 多人协作	AGENTS.md（一份同步）
个人项目 / 主要用 Cursor	.cursor/rules/*.mdc
新项目起步	AGENTS.md（不锁工具）
老项目已经用 .cursorrules	不用改，新版 Cursor 也会读 AGENTS.md

常见误区

• ❌ 「AGENTS.md 是 Cursor 专属」 → 不是，是跨工具标准
• ❌ 「必须两个都写才保险」 → 不必，AGENTS.md 一个够了
• ❌ 「.cursorrules 要立刻迁移到 AGENTS.md」 → 不用迁移，Cursor 0.45+ 同时支持两个

三、必须配置的内容

按重要性排序，前 5 项缺失，AI 几乎一定会出岔子。

风格/缩进/引号/分号不要写在这里——交给 Prettier，让 AI 自己跑 pnpm format。

3.1 技术栈

## Tech Stack

- Frontend: Next.js 15 (App Router) + React 19 + TypeScript 5
- Styling: Tailwind CSS v4
- State: Zustand (client) / Server Component state (server)
- ORM: Prisma + PostgreSQL
- Monorepo: pnpm workspace + Turborepo
- Test: Vitest + Playwright

价值：防止 AI 推荐过时的方案（如「用 getServerSideProps」「用 Redux Saga」）。

3.2 命名约定

## Naming Conventions

- Components: PascalCase (UserCard.tsx)
- Hooks: camelCase with `use` prefix (useUser.ts)
- Utils: camelCase (formatDate.ts)
- Constants: UPPER_SNAKE_CASE (MAX_RETRY)
- API routes: kebab-case (/api/user-profile)
- DB models: PascalCase singular (User, Order)

3.3 目录结构

## Directory Structure

```text
src/
  app/              # Next.js App Router pages
  components/       # 业务组件（按功能分目录）
  components/ui/    # shadcn/ui 原子组件
  lib/              # 工具与配置
  server/           # 服务端代码（仅 server actions 用）
  stores/           # Zustand stores
  hooks/            # 自定义 hooks
```

价值：AI 直接 import "@/lib/db" 而不是问「这文件放哪」。

3.4 必用 / 禁止项（只放工具查不出来的）

## Must Use

- 异步请求用 `useUserQuery`（在 hooks/queries/ 下）
- 日期用 dayjs，不用 moment
- 客户端组件按需加 `"use client"`，默认 Server Component
- 表单用 react-hook-form + zod

## Don'ts

- 不要用 lodash 整个包，用 lodash-es 按需引入
- 不要在 Server Component 用 useState / onClick
- 不要直接调用 axios，统一走 `@/lib/request`
- 不要写 `any`，必须用具体类型或 unknown

不写：「用 2 空格缩进」「用单引号」「行尾不加分号」——这些 Prettier 配置已经管了。

3.5 业务核心概念

## Domain Concepts

- **商品 (Product)**：有 SKU 的可售物品
- **订单 (Order)**：用户下单后的实体，状态机：created → paid → shipped → done
- **购物车 (Cart)**：未下单前的临时集合
- **用户角色 (Role)**：guest / member / vip / admin，影响价格计算

价值：让 AI 知道「订单状态机」的存在，避免写出直接改状态的代码。

四、可选但强烈推荐

4.1 Self-verify Workflow（必配）

核心模式：让 AI 改完代码自己跑命令自查，有错就修。

下面是 .cursorrules / AGENTS.md 里建议写的段落（用 4 个反引号包裹以支持内部嵌套代码块）：

## Self-verify

修改完成后，**必须**依次执行以下命令并确保全部通过：

```bash
pnpm lint          # ESLint + Prettier 检查
pnpm typecheck     # TypeScript 类型检查
pnpm test          # 单测（如果改了对应文件）
```

- 有报错就**当场修**，不要把 lint 错误留给用户
- 如果规则与项目约定冲突，**改规则文件**，不要 `--no-verify` 跳过
- 跑通后再交付

为什么这样设计：把「保证代码质量」的责任前置到 AI。AI 改完自己跑一遍，比 PR 阶段再被 CI 拦下友好 10 倍——AI 会自动改到自己过 lint 为止。

4.2 架构决策记录

## Architecture Decisions

- **为什么用 RSC？** 首屏直出 + 零 JS 下发
- **为什么用 Zustand 而不是 Redux？** 业务简单，Zustand 足够
- **为什么用 Prisma？** 类型安全 + migration 工具完善
- **不要重构这些模块**（已稳定）：`lib/payment/`、`lib/auth/`

4.3 引导 AI 主动探索

## How to Explore This Project

1. 先看 `package.json` 了解技术栈
2. 看 `src/app/layout.tsx` 了解路由结构
3. 看 `src/lib/db.ts` 了解数据层
4. 看 `prisma/schema.prisma` 了解业务模型
5. 提问时引用具体文件路径，不要泛泛而问

五、实战模板

5.1 .cursor/rules/project.mdc（Cursor 新格式）

---
description: 项目核心规范（必读）
globs:
  - "**/*.{ts,tsx,js,jsx}"
alwaysApply: true
---

# Project: [项目名]

## Tech Stack

- Next.js 15 + React 19 + TypeScript 5
- Tailwind CSS v4 + shadcn/ui
- Prisma + PostgreSQL
- Zustand / Server Component

## Key Conventions

- 优先用 Server Component，需要交互的子组件加 `"use client"`
- 异步请求走 `@/lib/request`，不要直接 axios
- 不用 lodash 全量引入，用 lodash-es 按需
- 类型用 zod 校验，request/response 都要

## Don'ts

- 不要写 any
- 不要在 Server Component 用 useState
- 不要修改 `lib/payment/` 和 `lib/auth/`（已稳定）

## Self-verify（重要）

**改完代码后必须**依次执行，确保全部通过再交付：

- `pnpm lint`
- `pnpm typecheck`
- `pnpm test`（如果改了对应文件）

有报错就当场修，**不要 `--no-verify` 跳过**。lint 规则与项目约定冲突时，**改规则文件**而不是绕过检查。

对比之前版本：去掉了手写的「缩进 / 引号 / 分号」style 规则（Prettier 会处理），改用「Self-verify」段落让 AI 自己跑命令。

5.2 AGENTS.md（跨工具标准）

# AI Agent Guidelines

## Project

[项目一句话描述]，[目标用户]，[核心业务]。

## Tech Stack

Next.js 15 + React 19 + TypeScript 5 / Tailwind v4 / Prisma / Zustand

## Key Conventions

- Server Component 默认，需要交互的子组件加 `"use client"`
- 异步请求走 `@/lib/request`
- 类型用 zod 校验

## Don'ts

- 不要 any、不要修改 lib/payment/ 和 lib/auth/

## Workflow

1. 修改前先 `git pull` 确认无冲突
2. **修改后必须跑** `pnpm lint && pnpm typecheck`，有报错就修
3. 跑通了再交付，不要把 lint 错误留给用户
4. 提交前确保 commit message 符合 conventional commits
5. **不直接 push 到 main**，必须 PR

5.3 .github/copilot-instructions.md

# Copilot Instructions

This is a Next.js 15 + TypeScript project using Server Components by default.

## Conventions

- Prefer Server Components; use `"use client"` only when needed
- Use `import type` for type-only imports
- Always handle errors with try/catch in async server actions
- API calls go through `@/lib/request`
- Database access via Prisma in `lib/db.ts`
- Forms use react-hook-form + zod

## After You Edit

Run `pnpm lint` and `pnpm typecheck`. Fix any errors before claiming the task is done.

六、协同工作流

6.1 AI 适合的活

任务	适合度	原因
样板代码（CRUD、DTO）	⭐⭐⭐⭐⭐	模式固定，AI 写得不走样
单元测试	⭐⭐⭐⭐⭐	输入输出明确，AI 写得快
文档（注释、README）	⭐⭐⭐⭐	需要人工润色
重构（rename、拆函数）	⭐⭐⭐⭐	机械操作
类型定义	⭐⭐⭐⭐	写类型不需要业务理解
翻译 i18n	⭐⭐⭐⭐⭐	AI 翻译比人工快 5x

6.2 AI 不擅长的活

任务	适合度	原因
复杂业务逻辑	⭐⭐	需要深度业务理解
跨模块架构设计	⭐	全局视野，AI 容易顾此失彼
性能调优	⭐⭐	需要 profile 数据，AI 瞎猜
安全相关（鉴权、支付）	⭐	AI 代码必须人工 review

6.3 强制 Review

# .github/workflows/ai-code-check.yml
name: AI Code Quality Check
on: [pull_request]
jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint # ESLint 一视同仁
      - run: pnpm typecheck # TypeScript 一视同仁
      - run: pnpm test # 测试覆盖必须有

铁律：AI 写的代码 ≠ 免检代码。所有 AI 提交必须过 CI + 至少 1 人 review。

七、与现有规范的关系

项目规范
├─ 编码规范（ESLint/Prettier/Commitlint）  ← 工具自动执行
├─ 项目级规范（架构/命名/目录）             ← 文档约束
└─ AI 协同规范（.cursorrules/AGENTS.md）   ← AI 上下文

三者互相补位：

• 编码规范管「格式怎么写」（Prettier/lint 配置文件）
• 项目规范管「项目结构怎么组织」（架构文档）
• AI 规范管「让 AI 知道这一切 + 改完自己跑 lint 验证」

关键洞察：不要把 lint 规则同时写在「编码规范配置文件」和「AI 规则文件」——前者是真理来源，后者是「告诉 AI 跑命令」即可。

八、面试话术

「我们项目接了 Cursor，给它配了 .cursorrules 和 AGENTS.md。关键经验是别把 lint 规则抄进规则文件——那是双重维护，正确做法是让 AI 改完自己跑 pnpm lint 自查，有报错就修。这样 ESLint 配置改了 AI 行为自动跟着改。规则文件只放项目特有的内容：技术栈、命名哲学、业务核心概念、必用/禁止项。」

九、相关文档

• 项目规范总览
• 统一编码规范
• 制定项目规范
• Git Workflow