AI 编程规则全攻略

前面讲了 Prompt 模板，那是临时的武器，用完就扔。这一章讲的是永久装备——规则配置文件。

AI 有一个先天缺陷：它没有记忆。每次对话都是从零开始。你上次告诉它"用 TypeScript"、"遵循 Airbnb 代码风格"、"不要使用 any 类型"，下次它全忘了。

规则配置文件解决的就是这个问题。你把那些需要反复强调的规则写成文件，放在项目里，AI 每次开始工作时都会自动读取。就像给 AI 一本"项目手册"，让它先看懂再干活。

不同的 AI 编程工具有不同的规则文件格式。Cursor 认 .cursorrules，Claude Code 认 CLAUDE.md，Windsurf 认 .windsurfrules，GitHub Copilot 认 .github/copilot-instructions.md。还有一个试图统一它们的新标准叫 AGENTS.md，越来越多的工具开始支持。

这一章帮你搞懂这些规则文件怎么写、写什么、放在哪里。

为什么规则文件这么重要

先说一个真实的场景。

你用 Cursor 在写一个 Next.js 项目，样式用 Tailwind CSS，数据库用 Prisma，认证用 Better Auth。你问 AI 帮你写一个用户登录的组件。

如果你没有规则文件，AI 可能会用 styled-components 来写样式（因为它也很流行），可能用原生 SQL 查数据库（因为它不知道你在用 Prisma），可能用 next-auth 做认证（因为 Better Auth 的资料比较少）。你得花时间告诉它用错了，它改完又可能犯别的错。

如果你有规则文件，明确写着"样式用 Tailwind CSS"、"数据库操作用 Prisma"、"认证用 Better Auth"，AI 一开始就会朝着正确的方向写。省下的不只是沟通时间，还有你的心智负担。

规则文件的本质是持久化的系统提示。系统提示是 AI 开始对话之前就加载的指令，影响它后续所有的输出。平时你和 AI 聊天时说的话是"用户提示"，它的优先级比系统提示低。规则文件就是让你自定义系统提示的入口。

还有一个好处是团队统一。规则文件可以放进版本控制，团队成员都能用。这样不管谁用 AI 写代码，生成的风格都是一致的，不会你的代码用驼峰命名，我的代码用下划线命名。

Cursor 规则配置详解

Cursor 是目前最流行的 AI 编程工具，它的规则系统也最成熟。先把 Cursor 搞清楚，其他工具触类旁通。

Cursor 支持两种规则：全局规则和项目规则。

全局规则在 Cursor 的设置里配置，打开 Settings，找到 Rules for AI。你在这里写的规则会应用到你打开的所有项目。适合放一些通用的偏好，比如"用中文回复"、"代码要有注释"、"使用 TypeScript"。

项目规则放在项目目录里。早期的做法是在项目根目录创建一个 .cursorrules 文件，这个方式现在还能用，但已经不推荐了。新版 Cursor 建议用 .cursor/rules/ 目录，每个规则一个 .mdc 文件。

.mdc 是 Cursor 自己定义的格式，其实就是 Markdown 加一个 YAML 头部。头部用来定义规则的元数据，比如什么时候生效、匹配哪些文件。

一个典型的 .mdc 文件长这样：

---
description: Next.js 前端开发规范
globs:
  - "app/**/*"
  - "components/**/*"
alwaysApply: false
---

# Next.js 前端规范

使用 TypeScript，不使用 any 类型。

组件使用函数式写法，不使用 class 组件。

样式使用 Tailwind CSS，不使用 CSS-in-JS。

状态管理优先使用 React 内置功能（useState、useContext），复杂状态再考虑 Zustand。

API 请求使用 SWR 或 TanStack Query，不手动 fetch。

这个规则只在你编辑 app/ 或 components/ 目录下的文件时才会被加载。alwaysApply: false 意味着 Cursor 会根据上下文智能判断是否使用这个规则。如果设成 true，它会永远生效。

你可以创建多个规则文件，每个管一个领域。比如 frontend.mdc 管前端、backend.mdc 管后端、database.mdc 管数据库。Cursor 会根据你当前编辑的文件自动选择相关的规则。

Claude Code 的 CLAUDE.md

Claude Code 是 Anthropic 官方的命令行 AI 编程工具。它认的规则文件叫 CLAUDE.md。

和 Cursor 不同，CLAUDE.md 的设计更强调层级化。它会从多个位置读取规则文件：

项目根目录的 CLAUDE.md 是项目级规则，提交到 Git，团队共享。

子目录里也可以有 CLAUDE.md，比如 packages/api/CLAUDE.md。当你在那个子目录工作时，Claude Code 会同时读取父目录和子目录的规则，子目录的优先级更高。这对 monorepo 结构的项目特别有用。

~/.claude/CLAUDE.md 是全局规则，适用于你电脑上的所有项目。用来放个人偏好，比如回复语言、编码习惯。

还有一个叫 CLAUDE.local.md 的文件，用来放不想提交到 Git 的本地规则。可以在 .gitignore 里忽略它。

Claude Code 官方推荐的 CLAUDE.md 内容包括三部分：WHY、WHAT、HOW。

WHY 是项目的背景，告诉 Claude 这个项目是做什么的，为谁做的。

WHAT 是项目的结构，包括技术栈、主要文件和目录、核心概念。

HOW 是工作方式，告诉 Claude 怎么跑测试、怎么构建、有什么特殊约定。

一个实用的 CLAUDE.md 模板：

# 项目概述

这是一个面向独立开发者的 SaaS 启动模板，帮助用户快速上线收费产品。

技术栈：Next.js 14 + TypeScript + Tailwind CSS + Prisma + PostgreSQL

## 目录结构

- app/: Next.js App Router 页面
- components/: React 组件
- lib/: 工具函数和业务逻辑
- prisma/: 数据库 schema 和迁移

## 常用命令

- pnpm dev: 启动开发服务器
- pnpm build: 构建生产版本
- pnpm lint: 运行代码检查
- pnpm db:push: 同步数据库 schema

## 代码规范

使用函数式组件，不用 class 组件。

优先使用 server components，需要交互才用 client components。

数据库操作统一使用 lib/db.ts 导出的 prisma 实例。

API 错误统一使用 lib/errors.ts 的自定义错误类。

## 安全提醒

不要把 API Key 硬编码在代码里，使用环境变量。

不要删除 prisma/migrations 目录下的任何文件。

修改 schema.prisma 后记得运行 pnpm db:push。

Claude Code 还有一个技巧叫"渐进式披露"。如果项目很大，不要把所有信息都塞进 CLAUDE.md，那样会浪费 token。只放最核心的信息，然后告诉 Claude 哪里能找到更详细的文档。比如写"API 设计规范详见 docs/api-standards.md"。Claude 需要的时候会自己去读。

Windsurf 规则配置

Windsurf 是 Codeium 推出的 AI IDE，它的规则文件叫 .windsurfrules，放在项目根目录。

Windsurf 的规则有一个硬限制：单个规则文件不能超过 6000 字符，所有规则加起来不能超过 12000 字符。这个限制是为了避免规则占用太多上下文窗口。如果你的规则太长，Cascade（Windsurf 的 AI 组件）处理效率会下降。

Windsurf 也支持全局规则，放在 global_rules.md 文件里。在 Windsurf 设置的底部栏可以找到规则管理入口。

Windsurf 的规则激活方式比较灵活。可以设为"Always On"永远生效，可以设为"Model Decision"让 AI 自己决定是否使用，也可以设为"Glob"模式根据文件路径匹配。

一个 .windsurfrules 的例子：

# 项目规则

## 技术栈

- 框架: Next.js 14 with App Router
- 样式: Tailwind CSS + Shadcn UI
- 状态: TanStack Query
- 数据库: Prisma + PostgreSQL

## 代码风格

文件名使用 kebab-case，如 user-profile.tsx。

React 组件名使用 PascalCase，如 UserProfile。

使用 named exports，不使用 default export。

## 架构规则

页面组件只负责布局和数据获取，业务逻辑放在 lib/ 目录。

数据库查询封装在 lib/queries/ 目录，不在组件里直接写 prisma。

## 禁止事项

不要使用 any 类型。

不要使用 var，使用 const 或 let。

不要在客户端组件里直接调用数据库。

GitHub Copilot 自定义指令

GitHub Copilot 用的是 .github/copilot-instructions.md。把这个文件放在项目的 .github/ 目录下，Copilot 就会在每次代码补全和聊天时参考它。

使用前需要确保 VS Code 里的 github.copilot.chat.codeGeneration.useInstructionFiles 设置是开启的，默认应该是开的。

Copilot 还支持更细粒度的指令文件。在 .github/instructions/ 目录下可以放多个 .instructions.md 文件，用 YAML 头部指定它们适用于哪些文件：

---
applyTo:
  - "**/*.tsx"
  - "**/*.ts"
---

# TypeScript 开发规范

使用严格模式。

接口优先于类型别名。

禁止使用 enum，使用 const 对象代替。

这种方式可以对前端和后端用不同的规则，对测试文件用专门的规则。

Copilot 还有一个企业级功能：组织管理员可以设置组织级别的统一规则，自动应用到组织下所有成员。如果你的公司在用 GitHub Copilot Enterprise，可以让管理员配置这个。

AGENTS.md：新兴的通用标准

2024 年底，一个叫 AGENTS.md 的标准开始获得关注。它的目标是成为跨 AI 工具的通用规则格式，不管你用 Cursor、Claude Code、Copilot 还是别的工具，都能认这个文件。

AGENTS.md 的设计原则是保持简单。它就是一个普通的 Markdown 文件，放在项目根目录或者子目录里。内容用自然语言写，描述项目信息、编码规范、常用命令等。

目前的情况是：Gemini CLI 原生支持 AGENTS.md（如果同时有 GEMINI.md，GEMINI.md 优先）。GitHub Copilot 的 coding agent 功能也开始支持。Claude Code 可以配置读取。Cursor 可以通过 Always Attached 的方式引用。

如果你想用一个文件兼容多个工具，可以把核心内容放在 AGENTS.md 里。然后对于特定工具，可以在它的规则文件里引用 AGENTS.md 的内容，加上工具特有的配置。

AGENTS.md 的典型结构：

# AGENTS.md

## 项目信息

名称：MyApp
描述：一个帮助开发者快速启动 SaaS 的模板
技术栈：Next.js, TypeScript, Tailwind, Prisma, PostgreSQL

## 开发命令

安装依赖：pnpm install
开发模式：pnpm dev
构建：pnpm build
测试：pnpm test
代码检查：pnpm lint

## 编码规范

语言：TypeScript 严格模式
命名：文件 kebab-case，组件 PascalCase，变量 camelCase
样式：Tailwind CSS，避免内联样式

## 目录结构说明

app/: 页面路由（Next.js App Router）
components/: 可复用组件
lib/: 工具函数和业务逻辑
prisma/: 数据库定义

## 安全约定

API 密钥使用环境变量，不硬编码
用户输入必须验证和清洗
删除操作需要二次确认

Linux Foundation 在 2025 年成立了 Agentic AI Foundation，AGENTS.md 是其中一个重点推进的标准。OpenAI、Anthropic、Google、Microsoft、AWS 都参与了。虽然完全统一还有很长的路，但趋势是明确的：业界希望有一个通用的方式来指导 AI agent。

规则文件写什么

知道格式还不够，关键是内容。什么东西应该写进规则文件？

技术栈信息是最重要的。告诉 AI 你用的框架、库、工具的版本。"使用 Next.js 14 App Router"比"使用 Next.js"精确得多。AI 的训练数据包括各种版本的用法，你不明确说，它可能给你旧版本的代码。

编码规范是第二重要的。命名规则、文件组织、注释风格。这些不写清楚，不同的对话会生成风格不一致的代码。"函数名用 camelCase"、"React 组件文件用 PascalCase"、"目录名用 kebab-case"。

项目结构说明帮助 AI 理解代码放在哪里。"页面组件放 app/ 目录"、"共享组件放 components/"、"业务逻辑放 lib/"。AI 新建文件时就知道该放哪儿。

常用命令让 AI 能正确执行项目操作。"安装依赖用 pnpm install 不是 npm install"、"测试用 pnpm test"、"数据库迁移用 pnpm db:migrate"。

禁止事项明确告诉 AI 什么不能做。"不要使用 any 类型"、"不要删除 migrations 文件"、"不要在前端暴露数据库连接"。这些防护很重要，AI 有时候会做出让你后悔的事。

安全提醒也应该放进去。"API Key 放环境变量"、"用户输入要验证"、"删除操作要确认"。

有几个要点：

保持简洁。规则文件会占用 AI 的上下文窗口。500 行以内是一个不错的目标。如果规则太多，考虑拆分成多个文件。

用自然语言。AI 是理解自然语言的，不需要用特殊语法。"使用 TypeScript"比什么配置格式都好懂。

给具体例子。"命名用 camelCase"还不够具体，"函数命名如 getUserById、createOrder"更清楚。

定期更新。技术栈变了、规范调整了，记得更新规则文件。过时的规则比没有规则更糟糕。

我的实战模板

分享几个我实际在用的规则模板，你可以直接复制然后根据自己项目调整。

全局规则（放在编辑器设置或 ~/.claude/CLAUDE.md）：

# 全局规则

用中文回复所有问题。

遵循第一性原理解决问题。先理解问题本质，再选择方案。

不要过度设计。简单的问题简单解决，不需要设计模式的地方不要硬套。

写代码前先检查是否有现成实现可以复用。

修改现有代码时最小化改动范围。只改必须改的，不顺手重构其他东西。

每次完成任务后主动 git commit。commit message 用中文，简洁描述改动内容。

Next.js 项目规则：

# Next.js 项目规范

## 技术栈

- Next.js 14 App Router
- TypeScript 严格模式
- Tailwind CSS + shadcn/ui
- Prisma + PostgreSQL
- Better Auth 认证

## 目录结构

- app/: 页面和 API 路由
- components/: React 组件
- lib/: 工具函数和业务逻辑
- prisma/: 数据库 schema

## 代码规范

组件使用函数式写法，不使用 class。

优先使用 Server Components，需要客户端交互才用 'use client'。

样式只用 Tailwind，不用 CSS 文件或 CSS-in-JS。

类型定义放在同一文件或 types.ts，不单独建 interfaces 目录。

## API 设计

Server Actions 放在对应页面的 actions.ts。

需要被多处调用的 API 放在 app/api/ 作为 Route Handler。

返回统一格式：{ success: boolean, data?: T, error?: string }

## 数据库

使用 lib/db.ts 导出的 prisma 实例，不要新建。

查询封装在 lib/queries/，修改封装在 lib/mutations/。

不在组件里直接写复杂查询。

## 禁止事项

不要使用 any。

不要 console.log 调试，用完要删。

不要在客户端组件调用 prisma。

不要硬编码 API Key。

Python 后端规则：

# Python 后端规范

## 技术栈

- Python 3.11+
- FastAPI
- SQLAlchemy + Alembic
- Poetry 包管理

## 代码风格

使用 type hints。

函数和类要有 docstring。

遵循 PEP 8。

使用 Pydantic 做数据验证。

## 项目结构

- app/: 主应用代码
- app/api/: API 路由
- app/models/: SQLAlchemy 模型
- app/schemas/: Pydantic 模型
- app/services/: 业务逻辑
- tests/: 测试代码

## 命令

启动开发: poetry run uvicorn app.main:app --reload

运行测试: poetry run pytest

代码检查: poetry run ruff check .

格式化: poetry run ruff format .

## 数据库

迁移脚本: poetry run alembic revision --autogenerate -m "描述"

执行迁移: poetry run alembic upgrade head

常见问题和解决方案

AI 无视我的规则怎么办？

这是最常见的抱怨。检查几个点：规则文件位置对不对？Cursor 要放在 .cursor/rules/ 或者项目根目录。规则优先级够不够高？如果是可选规则，AI 可能选择性忽略。规则是不是太多了？太多反而让 AI 找不到重点。

一个技巧是把最重要的规则放在文件开头，用醒目的语言强调。"关键规则：以下必须严格遵守" 比平铺直叙更有效。

规则文件会暴露敏感信息吗？

会。规则文件会发送给 AI 服务。不要在里面放 API Key、密码、内部系统地址这些敏感信息。如果必须提及某个服务，只写名称不写凭证。

多个规则文件冲突怎么办？

一般是优先级更高的生效。项目规则优先于全局规则，子目录规则优先于父目录规则。如果同级规则冲突，AI 会自己判断或者按文件名顺序。最好的办法是提前设计好规则的分层，避免冲突。

规则文件要不要提交到 Git？

项目规则要提交，团队需要共享。.cursorrules、CLAUDE.md、.windsurfrules 都应该在版本控制里。个人的全局规则不用提交，那是你自己的偏好。本地特有的规则可以用 .local.md 后缀然后加到 .gitignore。

规则文件是提升 AI 编程效率的利器。花几十分钟写一个好的规则文件，能省下后续无数次的纠正和返工。它不是一次性的投入，而是会持续产生回报的资产。

一开始不需要写得很完美。先写一个基础版本，用一段时间，发现 AI 老是犯某个错，就把那条规则加进去。规则文件是迭代出来的，不是一步到位的。

下一章讲域名和部署，你的产品要让全世界都能访问到。