AI IDE 工程规范：Cursor Rules 与 Claude Code 实战

原创 Maurice

A 推荐提升 | 约 18 分钟阅读更新于 2026-02-27

AI 导读

AI IDE 工程规范：Cursor Rules 与 Claude Code 实战作者：Maurice | 灵阙学院为什么需要规范文件 2023 年以前，我们谈 AI 编程，谈的是"自动补全"。 2025 年，局面已经完全不同。Claude、GPT-4o、Gemini 这些模型的代码能力早已超过大多数初级工程师。Cursor、Claude Code、Windsurf 等 AI IDE...

AI IDE 工程规范：Cursor Rules 与 Claude Code 实战

作者：Maurice | 灵阙学院

为什么需要规范文件

2023 年以前，我们谈 AI 编程，谈的是"自动补全"。

2025 年，局面已经完全不同。Claude、GPT-4o、Gemini 这些模型的代码能力早已超过大多数初级工程师。Cursor、Claude Code、Windsurf 等 AI IDE 不再是"聪明的代码提示器"，而是真正的结对编程伙伴——它们能独立完成整个功能模块，自主运行测试，甚至提交代码。

问题随之而来：这个伙伴太聪明了，但它对你的项目一无所知。

你用的是 Next.js App Router 还是 Pages Router？
错误处理是 Result<T> 模式还是 try-catch？
提交信息要不要遵循 Conventional Commits？
哪些文件绝对不能修改？

每次开启新会话，这些上下文都要重新建立。规范文件，就是你给 AI 伙伴的"入职手册"——一次写好，永久生效。

本文覆盖三大主流 AI IDE 的规范体系，从格式到方法论，从模板到高级技巧，是 2025-2026 年最完整的中文实战指南。

一、三大 AI IDE 规范体系对比

1.1 全景对比

维度	Cursor Rules	Claude Code	Windsurf
主配置文件	`.cursor/rules/*.mdc`	`CLAUDE.md`	`.windsurfrules`
补充配置	用户级规则（全局）	`.claude/rules/*.md`	无分层
能力模块	无原生支持	`.claude/skills/`	无原生支持
触发方式	类型字段 + glob pattern	自动加载 + 目录继承	始终加载
继承层级	项目 > 用户	全局 > 项目 > 子目录	单层
格式	YAML frontmatter + Markdown	纯 Markdown	纯 Markdown
生态丰富度	awesome-cursorrules（数百模板）	社区增长中	较少
适用场景	日常编码 + 重构	复杂长任务 + Agent 模式	轻量补全

1.2 核心差异

Cursor Rules 的核心价值在于精细化触发。你可以为 .tsx 文件、src/api/** 路径，甚至特定的 Agent 任务分别定义不同规则，做到按需激活、精准注入。

Claude Code 的核心价值在于层次化 + 可执行。它不只是"给 AI 看的文档"，还能定义可调用的 Skills（技能模块），让 AI 直接执行封装好的操作流程，是名副其实的工程化配置体系。

Windsurf 的核心价值在于简单直接。单文件、纯 Markdown、零配置，适合个人项目和快速上手。代价是缺乏条件触发和模块化能力。

二、Cursor Rules 深度解析

2.1 从 `.cursorrules` 到 `.mdc`：格式进化

旧格式（已废弃）：

# 项目根目录
.cursorrules       # 一个文件，始终加载，无法按场景分组

新格式（2024 Q4 起推荐）：

# 项目结构
.cursor/
  rules/
    01-base.mdc           # 始终加载的基础规则
    02-react.mdc          # 针对 React 文件自动触发
    03-api.mdc            # 针对 API 路由自动触发
    04-testing.mdc        # 仅在 Agent 请求时加载

.mdc 文件结构：

---
description: React 组件开发规范（当操作 .tsx 文件时自动激活）
globs:
  - "src/**/*.tsx"
  - "src/**/*.jsx"
alwaysApply: false
---

# React 组件规范

## 组件结构
- 使用函数组件，禁止 class component
- Props 必须定义 TypeScript interface，命名为 `XxxProps`
- 状态管理优先 Zustand，局部状态用 useState

## 示例

**正确：**
```tsx
interface UserCardProps {
  userId: string;
  onSelect: (id: string) => void;
}

export function UserCard({ userId, onSelect }: UserCardProps) {
  const user = useUserStore((s) => s.users[userId]);
  return <div onClick={() => onSelect(userId)}>{user.name}</div>;
}

错误（禁止）：

// 禁止：匿名导出
export default function({ id }) { ... }

// 禁止：any 类型
const handler = (e: any) => { ... }


### 2.2 四种规则类型详解

| 类型 | 配置方式 | 触发时机 | 适用场景 |
|------|---------|---------|---------|
| `always` | `alwaysApply: true` | 每次对话都加载 | 项目全局约束、禁止项 |
| `auto` | `globs` 字段（文件 glob） | 匹配文件时自动注入 | 语言/框架专项规范 |
| `agent-requested` | `description` 字段（AI 判断） | Agent 认为相关时加载 | 复杂流程、工作流规范 |
| `manual` | 无自动触发 | 用户手动 `@rules` 引用 | 临时规则、实验性规范 |

**always 规则示例（`01-base.mdc`）：**

```yaml
---
description: 项目基础规范
alwaysApply: true
---

# 全局约束

## 语言
- 代码注释、变量名、函数名：英文
- 用户可见文案、文档说明：中文

## 禁止事项
- 禁止使用 `any` 类型（eslint-disable 例外需注释说明原因）
- 禁止 `console.log` 进入 git（开发调试可用，提交前必须清理）
- 禁止修改 `src/lib/auth/` 目录下任何文件（安全敏感区域）

## 错误处理
- 所有 async 函数必须处理异常，不得静默吞掉 error
- API 路由统一使用 `{ success: boolean, data?: T, error?: string }` 响应格式

auto 规则示例（03-api.mdc）：

---
description: API 路由开发规范
globs:
  - "src/app/api/**/*.ts"
  - "src/pages/api/**/*.ts"
alwaysApply: false
---

# API 路由规范

## 响应格式（统一）
```ts
// 成功
return NextResponse.json({ success: true, data: result });

// 失败
return NextResponse.json(
  { success: false, error: 'RESOURCE_NOT_FOUND', message: '资源不存在' },
  { status: 404 }
);

认证（必须）

每个受保护路由必须调用 withAuth() 中间件，不得手动解析 JWT。

参数校验

使用 zod schema 校验请求体，schema 定义放在 src/lib/schemas/ 目录。


### 2.3 项目级 vs 用户级规则

**项目级规则**（`.cursor/rules/`）：
- 随仓库提交，团队共享
- 覆盖具体项目的技术栈、架构约束
- 优先级：低于用户级

**用户级规则**（Cursor 设置 > Rules）：
- 本地生效，不进入 git
- 适合个人编码习惯、通用偏好
- 示例：偏好简洁注释风格、不喜欢生成冗长说明

**最佳实践**：项目规则放技术约束（框架/禁止项/流程），用户规则放个人偏好（语气/详略/语言）。两者互补，不要重叠。

### 2.4 规则编写原则

**原则一：具体 > 模糊**

差：

遵循 React 最佳实践。


好：

React 组件必须：

使用函数组件（禁止 class component）
Props 定义独立 interface（命名格式：XxxProps）
副作用通过 useEffect，依赖数组不得为空数组除非明确注释原因


**原则二：示例 > 描述**

差：

正确处理错误。


好：

错误处理示例： // 正确 try { const data = await fetchUser(id); return { success: true, data }; } catch (err) { logger.error('fetchUser failed', { id, err }); return { success: false, error: 'FETCH_FAILED' }; }

// 禁止（静默吞掉错误） try { const data = await fetchUser(id); } catch (e) {}


**原则三：约束 > 建议**

"建议使用 TypeScript 严格模式" 的效果远不如 "必须在 `tsconfig.json` 中设置 `"strict": true`，违反时 CI 将阻断"。

---

## 三、Claude Code 规范体系

Claude Code 是 Anthropic 官方 CLI，其规范体系远比 Cursor 更深入。它不只是"读规范文件"，而是构建了完整的**工程化配置层次**。

### 3.1 四层配置架构

~/.claude/CLAUDE.md # 全局规范（所有项目共享） ~/.claude/projects// # 项目级记忆（自动管理） memory/MEMORY.md # Auto Memory（跨会话持久化）

project_root/ CLAUDE.md # 项目规范（主入口，自动加载） .claude/ rules/ # 分组规则文件 01-coding-philosophy.md # 编码哲学 02-workflow-discipline.md # 工作流纪律 03-project-docs.md # 文档规范 04-frontend-validation.md # 前端验证流程 05-safety-security.md # 安全约束 skills/ # 可复用技能模块 deploy.md # 部署技能 review.md # 代码审查技能 settings.json # Claude Code 项目设置

src/ components/ CLAUDE.md # 子目录规范（覆盖父级）


**继承规则**：全局 CLAUDE.md > 项目 CLAUDE.md > 子目录 CLAUDE.md。子目录规范可以增量覆盖，不影响其他目录。

### 3.2 CLAUDE.md 核心结构

一个工程化的 CLAUDE.md 应包含五个部分：

```markdown
# CLAUDE.md - 项目规范

## 1. 角色定位
你是一位 Next.js 全栈工程师，专注于构建高性能、可维护的 SaaS 应用。
优先级：可读性 > 正确性 > 性能 > 简洁性。

## 2. 技术栈
- 框架：Next.js 15（App Router），TypeScript 5.x strict
- 样式：Tailwind CSS v4，shadcn/ui 组件库
- 状态：Zustand（全局），React Query（服务端状态）
- 数据库：PostgreSQL + Prisma ORM
- 认证：NextAuth.js v5

## 3. 核心约束
- 禁止：any 类型、console.log 提交、修改 src/lib/auth/
- 必须：zod 校验 API 输入、统一错误响应格式、每个 PR 附测试
- API 响应格式：{ success: boolean, data?: T, error?: string }

## 4. 工作流
- 分支命名：feat/xxx、fix/xxx、chore/xxx
- 提交格式：Conventional Commits（feat/fix/docs/refactor/test/chore）
- 完成标志：通过 `npm run check`（lint + typecheck + test）

## 5. 文档
- 架构文档：doc/SYSTEM_ARCHITECTURE.md
- API 文档：doc/API.md
- 变更必须同步更新对应文档

3.3 .claude/rules/ 分组规范

将规范拆分到多个文件的好处是清晰分组、按需引用。Claude Code 在每次会话启动时自动加载所有规则文件。

示例：02-workflow-discipline.md

# Workflow Discipline

## Task Complexity Assessment
- trivial：< 10 行，单一修复 → 直接执行
- moderate：单文件非trivial逻辑 → 先计划再实现
- complex：跨模块/并发/迁移 → 严格计划模式

## Code Mode 纪律
1. 先说明将修改哪些文件及原因
2. 最小可审阅的 diff（不要整文件输出）
3. 说明验证方式（命令/测试/手动检查）
4. 发现重大问题时，切回 Plan 模式

## 完成标准（Definition of Done）
- Round 1：`npm run check` 全部通过
- Round 2：按用户体验地图做人工验收并留存截图证据

3.4 Skills：可复用能力封装

Skills 是 Claude Code 最具工程价值的特性——把常用操作封装为可调用的能力模块，类似于函数，而不是又一份文档。

示例：.claude/skills/deploy.md

# Skill: Deploy to Production

## 触发命令
`ai skills run deploy`

## 前置检查
1. 确认 git worktree 清洁（无未提交变更）
2. 确认当前分支为 main
3. 运行 `npm run check` 全部通过

## 执行步骤
```bash
# Step 1: 构建
npm run build

# Step 2: 推送
git push origin main

# Step 3: 触发部署（Vercel 自动触发或手动）
# 如果是 VPS：ssh user@host 'cd /app && git pull && pm2 restart app'

# Step 4: 健康检查
curl -f https://your-domain.com/api/health || echo "ERROR: 健康检查失败"

完成标志

部署 URL 返回 200
关键功能可用（登录/主流程）
无 5xx 错误日志


### 3.5 Memory 系统：跨会话持久化

Claude Code 的 Auto Memory 机制会自动将重要信息写入 `memory/MEMORY.md`，在新会话中自动读取，解决了 AI 会话无状态的痛点。

这些信息会被自动记忆：
- 已知 Bug 和修复方案
- 重要架构决策
- 团队约定和规范变更
- 常见错误模式和防范措施

你也可以手动在 CLAUDE.md 中添加持久化重要信息，指导 AI 避开历史坑点。

---

## 四、规范文件编写方法论

### 4.1 黄金结构：三段式

[开头] 身份 + 目标（谁在做什么，优先级是什么） [中间] 技术约束（框架/风格/禁止项/示例） [结尾] 工作流（提交/测试/review/完成标志）


这个结构来自"角色扮演"心理学——AI 需要先建立身份认知，再接受约束，最后理解流程。顺序颠倒会导致规则记忆不稳定。

### 4.2 常见误区

**误区一：规范越长越好**

实验表明，超过 500 行的规范文件，AI 对后半部分的遵守率显著下降。建议：
- 单个规范文件控制在 100-200 行
- 使用 `.cursor/rules/` 或 `.claude/rules/` 拆分到多个文件
- 每个文件聚焦一个主题

**误区二：矛盾指令**

错误示例（矛盾）

代码要简洁
所有函数必须写完整的 JSDoc 注释

正确示例（明确优先级）

公共 API 函数必须写 JSDoc（接口契约）
内部工具函数：有意图不明显时才写注释


**误区三：只写"应该"，不写"不应该"**

"禁止"列表往往比"推荐"列表更有效。AI 模型对否定约束的遵守率通常高于正向建议，因为边界更清晰。

**误区四：没有示例**

任何规范，有示例的部分遵守率比没有示例的部分高 30-50%（基于工程团队实际观测）。哪怕只是一个两行的"正确/错误"对比，效果也远胜纯文字描述。

### 4.3 测试你的规范

规范写好后，用以下问题测试它：

1. 拿一个新人入职场景——规范能让 AI 独立完成第一个任务吗？
2. 对着规范提一个边界问题——AI 的回答符合预期吗？
3. 删掉规范，AI 会犯什么错？补回规范，那些错消失了吗？

---

## 五、实战模板

### 5.1 React / Next.js 项目规范模板

```yaml
---
description: Next.js 全栈项目规范
alwaysApply: true
---

# Project: Next.js SaaS Starter

## Stack
- Next.js 15 App Router, TypeScript strict
- Tailwind CSS v4 + shadcn/ui
- Zustand + React Query
- PostgreSQL + Prisma

## Component Rules
- Function components only (no class components)
- Props interface: `XxxProps`, exported from component file
- Server Components by default; add `'use client'` only when needed
- No inline styles; Tailwind classes only

## API Routes
- Response format: `{ success: boolean, data?: T, error?: string, code?: string }`
- Input validation: zod schema (in `src/lib/schemas/`)
- Auth: `withAuth()` wrapper (never manual JWT parse)
- Error codes: SCREAMING_SNAKE_CASE strings

## Forbidden
- `any` type (use `unknown` + type guard)
- `console.log` in commits
- Modifying `src/lib/auth/**` without security review
- Hardcoded secrets (use env vars via `src/lib/env.ts`)

## Commit Format
feat: add user profile page
fix: resolve auth token refresh race condition
chore: update dependencies

## Done = `npm run check` passes (lint + typecheck + test)

5.2 Python 后端项目规范模板

# Python Backend Rules

## 环境
- Python 3.12+，使用 uv 管理依赖
- FastAPI + SQLAlchemy 2.0（async）
- Pydantic v2 做数据校验

## 代码风格
- 格式化：ruff format（不要手动格式化）
- Linting：ruff check
- 类型检查：mypy strict 模式
- 函数签名必须有类型注解（参数 + 返回值）

## 项目结构

src/ api/ # FastAPI 路由 services/ # 业务逻辑（无框架依赖） models/ # SQLAlchemy ORM 模型 schemas/ # Pydantic 请求/响应模型 core/ # 配置、日志、异常


## 错误处理
- 使用 `Result[T, E]` 模式（returns 库）处理业务错误
- HTTP 异常通过 FastAPI `HTTPException`
- 禁止裸露的 `except Exception`

## 测试
- pytest + httpx（async 测试）
- 每个 API 端点必须有集成测试
- 业务逻辑必须有单元测试
- 覆盖率目标：> 80%

## 完成标准
`make check`（ruff + mypy + pytest）全部通过

5.3 全栈项目规范（Claude Code CLAUDE.md 格式）

# CLAUDE.md - 全栈项目工程规范

## 角色定位
你是一名全栈工程师，负责这个 SaaS 产品的端到端实现。
优先级：可读性 > 正确性 > 性能 > 简洁性。

## 技术架构

### 前端（apps/web）
- Next.js 15 App Router + TypeScript strict
- Tailwind CSS + shadcn/ui
- 状态：Zustand（全局）/ TanStack Query（服务端）

### 后端（apps/api）
- FastAPI（Python 3.12）
- PostgreSQL + SQLAlchemy 2.0 async
- Redis（缓存 + 任务队列）

### 基础设施
- Docker Compose（本地开发）
- GitHub Actions（CI/CD）
- Vercel（前端）/ 自建 VPS（后端）

## 全局约束
- API 契约：`docs/api-contract.yaml`（修改后必须同步）
- 错误格式统一：`{ success: false, error: string, code: string }`
- 禁止：any 类型、mock 数据进生产、未经审查的 npm 包

## 工作流纪律
1. 修改前先读 `docs/ARCHITECTURE.md`
2. 跨服务改动必须先确认 API 契约
3. 提交前运行 `make check`（前端 + 后端）
4. 数据库 Schema 变更必须提供 migration 文件

## 三端一致性检查（任务完结必做）
```bash
# 本地
git status --porcelain && git rev-parse HEAD

# GitHub
gh api repos/owner/repo/commits/main --jq .sha

# 生产
ssh user@vps 'cd /app && git rev-parse HEAD'

安全红线

认证相关代码：修改前必须人工审查
密钥：只能存 .env，禁止硬编码
数据文件（.csv/.db/*.json）：禁止在清理任务中删除


---

## 六、高级技巧

### 6.1 条件触发：按路径精准激活规则

Cursor Rules 的 glob 触发机制是最被低估的特性之一。善用它可以让不同类型的文件自动获得专属规范，无需 AI 判断：

```yaml
# 针对测试文件
---
globs: ["**/*.test.ts", "**/*.spec.ts", "**/__tests__/**"]
---
# 测试规范：必须测哪些情况、命名规则、mock 策略...

# 针对数据库 migration
---
globs: ["prisma/migrations/**", "src/db/migrations/**"]
---
# Migration 规范：幂等性、回滚方案、数据安全检查...

# 针对 Storybook
---
globs: ["src/**/*.stories.tsx"]
---
# Story 规范：必须覆盖哪些状态、交互测试要求...

6.2 Skills 封装：把操作变成"命令"

Claude Code 的 Skills 让你把复杂操作封装为一行命令：

# .claude/skills/pr-review.md

## Skill: PR Code Review

## 触发
`ai skills run pr-review`

## 执行步骤
1. 读取 git diff（当前分支 vs main）
2. 检查清单：
   - [ ] 无 any 类型
   - [ ] 无 console.log
   - [ ] API 路由有 zod 校验
   - [ ] 有对应测试文件
   - [ ] 文档已同步更新
3. 输出：通过项（✓）、问题项（需修复）、建议项（可选优化）

## 输出格式

Review Result: [PASS/FAIL] Issues (must fix): ... Suggestions (optional): ...

6.3 团队规范共享

将规范文件提交到 git，是确保团队一致性最简单的方式：

# .gitignore
# 不要忽略规范文件
# .cursor/rules/ 和 .claude/ 应该进入 git

# CI 检查：规范文件存在性验证
# .github/workflows/check-rules.yml
jobs:
  check-rules:
    steps:
      - name: Verify AI rules exist
        run: |
          test -f .cursor/rules/01-base.mdc || exit 1
          test -f CLAUDE.md || exit 1
          echo "OK: AI rules files present"

新人入职流程：

git clone 自动获得规范
打开 Cursor/Claude Code 自动加载
无需额外配置，立即开始开发

6.4 规范版本管理

随着项目演进，规范需要更新。建议在文件头部维护版本记录：

# CLAUDE.md

> v3.0 | 2025-12-01 | 新增 Agent Teams 协作规范
> v2.0 | 2025-06-01 | 重构为三段式结构
> v1.0 | 2025-01-01 | 初版

重大变更时，在规范文件中同时说明"旧做法"和"新做法"，帮助 AI 理解迁移方向，避免基于历史代码推断出错误规范。

七、awesome-cursorrules 社区精选

GitHub 仓库 awesome-cursorrules 收录了数百个社区贡献的规范模板，按技术栈分类。以下是高赞类目：

类别	模板名称	核心价值
Next.js	nextjs-typescript-tailwind	App Router + shadcn 完整约束
Python	fastapi-best-practices	async 模式 + Pydantic v2
React Native	expo-react-native	移动端特殊约束（性能/平台差异）
Go	golang-backend	错误处理惯用法 + interface 设计
全栈	t3-stack	tRPC + Prisma + NextAuth 一体化
AI 应用	langchain-python	Agent/Chain 最佳实践

使用建议：不要直接复制，而是把社区模板作为"检查清单"，取其中适合自己项目的约束，删除不相关的部分，加入项目特有约束。

八、效果度量：如何验证规范是否有效

规范文件写完不代表结束，需要用数据验证它的效果。

8.1 定量指标

指标	含义	测量方式
一次性通过率	AI 生成代码无需修改直接可用的比例	记录每次是否需要手动改动
Lint 报错率	AI 生成代码触发 lint 警告的频率	CI 统计
格式合规率	提交信息、文件命名符合规范的比例	git log 统计
返工次数	同一功能需要重新生成的次数	任务记录

8.2 定性验证方法

测试一：新会话测试 关闭并重新打开 AI IDE，提出一个边界问题（例如"帮我写一个错误处理函数"），看 AI 的回答是否符合规范中的约束。

测试二：对比实验 在相同任务上，分别使用"有规范"和"无规范"的模式各生成一次，对比代码质量差异。

测试三：新人体验 让刚加入团队的工程师仅凭规范文件指导 AI，完成一个小任务，看是否能达到预期代码质量。

8.3 迭代改进循环

观察问题（AI 又犯了哪个错？）
  ↓
定位规范缺口（是没有规定，还是规定太模糊？）
  ↓
更新规范（添加明确约束 + 示例）
  ↓
验证（用测试一确认 AI 行为改变）
  ↓
提交（进入 git，团队共享）

每次 AI 犯错，都是完善规范的机会。一个成熟项目的规范文件，往往是从几十次"AI 犯错 → 补充规范"迭代而来的。

九、最佳实践总结

立即能做的三件事：

今天：在你的主力项目里创建 CLAUDE.md 或 .cursor/rules/01-base.mdc，哪怕只有 20 行，写下三条最重要的约束。
本周：把规范文件提交到 git，和团队达成共识。把 "AI 规范"纳入 onboarding checklist。
本月：建立迭代机制——每发现一个 AI 犯错模式，补充一条规范。目标是让规范文件成为项目的"活文档"。

长期原则：

规范是项目知识的结晶，不是一次性配置
简洁有效 > 面面俱到但无人遵守
示例的价值高于描述的价值
规范文件和代码一样需要 review 和维护

AI IDE 的真正潜力，不在于它能生成多少代码，而在于你能把多少工程经验，转化为让 AI 持续遵守的规范。

Maurice | maurice_wen@proton.me

AI 导读

AI IDE 工程规范：Cursor Rules 与 Claude Code 实战

为什么需要规范文件

一、三大 AI IDE 规范体系对比

1.1 全景对比

1.2 核心差异

二、Cursor Rules 深度解析

2.1 从 .cursorrules 到 .mdc：格式进化

认证（必须）

参数校验

3.3 .claude/rules/ 分组规范

3.4 Skills：可复用能力封装

完成标志

错误示例（矛盾）

正确示例（明确优先级）

5.2 Python 后端项目规范模板

5.3 全栈项目规范（Claude Code CLAUDE.md 格式）

安全红线

6.2 Skills 封装：把操作变成"命令"

6.3 团队规范共享

6.4 规范版本管理

七、awesome-cursorrules 社区精选

八、效果度量：如何验证规范是否有效

8.1 定量指标

8.2 定性验证方法

8.3 迭代改进循环

九、最佳实践总结

2.1 从 `.cursorrules` 到 `.mdc`：格式进化