让 AI 停止生成过期代码：.cursor/rules 与 CLAUDE.md 配置

你刚刚初始化了一个 Next.js 16 项目，打开 Cursor 让 AI 写一个页面。它认真地给你返回了 getServerSideProps——可你用的是 App Router。同样的场景在 Vue 3 项目中 AI 输出 Options API，在 esm 项目中 AI 用 require()。每次都浪费好几轮对话来纠正。

这不是 AI 笨，是你没告诉它规则。 一行代码没改，加一个文件就能让这类问题减少大半。

一、原理：不是"训练"，是"声明"

项目规则文件相当于给 AI 的入职说明——它在开始工作前自动读一遍，知道这个项目用什么技术栈、禁止什么写法。你不说，AI 只能靠训练数据猜，训练数据里旧模式比新模式多得多。

主流方案很简单：一个文件，放在项目根目录，AI 启动时自动读。

• 用 Cursor → 写 .cursor/rules/*.mdc（支持按文件类型触发）
• 用 Claude Code → 写 CLAUDE.md + .claude/rules/*.md（支持路径匹配）
• 两者都用的用户 → 写 CLAUDE.md 就够了——Cursor 从 2025 年起原生读取

二、Cursor：.cursor/rules/*.mdc

在项目根目录创建 .cursor/rules/ 文件夹，放入 .mdc 文件。每个文件分两部分：YAML 头部（控制触发条件）+ Markdown 正文（规则内容）。

YAML 头部决定了规则的触发模式：

• alwaysApply: true — 每次会话都加载。适合全局技术栈声明
• description + globs — 打开匹配 globs 的文件时自动激活。适合特定文件类型的编码规范
• 只有 description，无 globs — Agent 根据语义自行判断相关性
• 三者都没有 — 仅手动触发（@规则名）

最小可用模板

创建 .cursor/rules/tech-stack.mdc（替换为自己的技术栈）：

---
description: 项目技术栈与编码规范（替换为你的实际技术栈）
alwaysApply: true
---

## 技术栈
- [你的框架] + [你的语言]
- [你的样式方案]

## 禁止事项
- [列2-3条在此项目中绝对不能出现的写法，如"禁止 class 组件""禁止 require()""禁止 axios 用 fetch"]

进阶：按文件类型拆分

当项目变大，可以把全局规则和文件类型规则分开：

# .cursor/rules/react-components.mdc
---
description: React 组件编码规约
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

- 使用函数式组件 + hooks，不写 class 组件
- Props 类型定义放在组件文件内，不另建 .d.ts
- 一个文件只导出一个组件

三、Claude Code：CLAUDE.md + .claude/rules/

Claude Code 在每次会话启动时，自动读取项目根目录的 CLAUDE.md（全大写），作为第一条消息注入上下文。支持 @path/to/file.md 引用外部文件。

最小可用模板

# CLAUDE.md

## 技术栈
- [你的框架 + 语言 + 样式方案]

## 构建命令
- `npm run dev` — 启动开发服务器
- `npx tsc --noEmit` — 类型检查

## 规则
- [2-3 条核心约束，如"不修改 schema 文件，走 migration"]

按路径拆分：.claude/rules/

Claude Code 也支持类似 Cursor 的按路径触发——在 .claude/rules/ 目录放 .md 文件，YAML 头部声明 paths：

# .claude/rules/frontend.md
---
paths: "src/app/**,src/components/**"
---

- 组件使用函数式写法
- 样式使用 Tailwind 原子类，不写独立 CSS

有 paths 的规则文件只在 Claude 读取匹配文件时才加载，不消耗每次会话的上下文配额。

四、两个工具的规则文件怎么选

结论：如果你只用其中一个工具，按对应格式写即可。如果你两个都用，写 CLAUDE.md 就能覆盖两个工具的全局规则（Cursor 原生读取），把文件类型细分规则放到 .cursor/rules/（Cursor）或 .claude/rules/（Claude Code）。

五、验证是否生效

1. 在项目里创建一个新文件，让 AI "帮我新建一个页面组件"
2. 检查生成的代码是否符合你规则文件里的约束
3. 如果不符合：检查规则文件路径是否正确、YAML 头部格式是否有语法错误、是否重启了编辑器或终端

一个快速自测 prompt："这个项目用什么技术栈？有哪些编码规范必须遵守？"——AI 的回答应直接引用你规则文件中的内容。