项目规则文件

项目规则文件是 Vibe Coding 中"让 AI 持续遵守项目约定"的核心机制。写一次，之后每次对话都自动生效，不需要重复说明。

各工具的规则文件位置

工具	文件位置	加载方式
Cursor	.cursor/rules/*.mdc	按条件自动注入
Claude Code	CLAUDE.md（项目根）或 ~/.claude/CLAUDE.md（全局）	每次对话自动加载
Kiro	.kiro/steering/*.md	每次对话自动加载
Windsurf	.windsurfrules	每次对话自动加载

---

Cursor Rules（.cursor/rules/）

Cursor 的规则系统最灵活，支持按文件类型、目录、场景条件触发不同规则。

文件格式

每个规则是一个 .mdc 文件，包含 frontmatter 和正文：

---
description: 规则描述（Agent 用这个判断何时应用）
globs: src/**/*.tsx
alwaysApply: false
---

规则正文（Markdown 格式）

三种触发模式

alwaysApply: true — 每次对话都加载，适合全局约定：

---
description: 项目全局约定
alwaysApply: true
---

## 技术栈
- Next.js 14 App Router + TypeScript 严格模式
- 样式：Tailwind CSS，禁止内联样式
- 状态：Zustand，禁止引入 Redux

## 禁止事项
- 不引入新的 UI 组件库
- 不直接修改 src/lib/auth/
- 不使用 any 类型

globs — 匹配特定文件时自动注入，适合领域约定：

---
description: React 组件开发规范
globs: src/components/**/*.tsx
alwaysApply: false
---

## 组件约定
- 使用函数组件 + hooks，不使用 class 组件
- Props 类型用 interface 定义，不用 type
- 组件文件只导出一个组件
- 测试文件放在同目录下，命名为 ComponentName.test.tsx

description 触发 — Agent 根据描述判断是否应用，适合场景规则：

---
description: 数据库迁移规范。当任务涉及数据库 Schema 变更时应用。
alwaysApply: false
---

## 迁移规范
- 所有迁移必须可回滚（提供 down 方法）
- 大表变更（超过 100 万行）需要在规格中说明执行策略
- 迁移文件命名：YYYYMMDDHHMMSS_描述.ts
- 不在迁移文件中写业务逻辑

推荐的规则文件结构

.cursor/rules/
  project.mdc          ← 全局约定（alwaysApply: true）
  frontend.mdc         ← 前端组件规范（globs: src/**/*.tsx）
  backend.mdc          ← 后端 API 规范（globs: src/api/**/*.ts）
  database.mdc         ← 数据库迁移规范（description 触发）
  testing.mdc          ← 测试编写规范（globs: **/*.test.ts）

实际示例：全栈项目的 project.mdc

---
description: 项目全局约定
alwaysApply: true
---

## 项目概述
电商平台后台管理系统，Next.js 14 + FastAPI + PostgreSQL。

## 技术栈
- 前端：Next.js 14 App Router，TypeScript 严格模式
- 样式：Tailwind CSS + shadcn/ui，禁止内联样式
- 状态：Zustand（客户端），React Query（服务端状态）
- 后端：FastAPI，Pydantic v2，SQLAlchemy 2.0
- 数据库：PostgreSQL 16，Alembic 迁移

## 代码约定
- 组件：PascalCase（UserCard.tsx）
- 工具函数：camelCase（formatDate.ts）
- API 路由：kebab-case（/api/user-orders）
- 数据库表：snake_case（user_orders）

## 禁止事项
- 不引入新的 npm 包（需要先讨论）
- 不直接修改 src/lib/auth/（安全敏感）
- 不在前端代码中硬编码 API URL
- 不使用 any 类型
- 不在迁移文件中写业务逻辑

## 验证命令
- 前端类型检查：`pnpm tsc --noEmit`
- 前端测试：`pnpm vitest run`
- 后端测试：`pytest`
- 构建检查：`pnpm build`

---

Claude Code（CLAUDE.md）

CLAUDE.md 是纯 Markdown 文件，每次对话自动加载。支持项目级（项目根目录）和全局级（~/.claude/CLAUDE.md）。

# 项目约定

## 技术栈
- Python 3.11 + FastAPI + SQLAlchemy 2.0
- 测试：pytest + pytest-asyncio
- 代码格式：Ruff（lint + format）

## 运行命令
- 启动：`uvicorn main:app --reload`
- 测试：`pytest -x`
- 格式化：`ruff format . && ruff check --fix .`

## 禁止事项
- 不修改 src/auth/（需要安全审查）
- 不引入新依赖（先在 requirements.txt 中确认）
- 不在代码中硬编码密钥或 URL

## 项目结构
src/
  api/        ← 路由层，只做参数验证和响应格式化
  services/   ← 业务逻辑层
  models/     ← SQLAlchemy 模型
  schemas/    ← Pydantic 模型

---

规则文件的维护节奏

规则文件不是一次性配置，而是随项目演进持续更新的活文档。

什么时候更新：

• AI 生成了与项目风格不一致的代码 → 把正确约定补进规则文件
• 某个禁止事项被 AI 反复违反 → 措辞改得更明确
• 引入了新的技术栈或约定 → 及时同步到规则文件
• 复盘时发现某个提示词模式很有效 → 提炼成规则

团队协作：规则文件提交到 Git，团队共享。新成员加入时，规则文件也是项目约定的文档。

---

常见问题

规则文件太长导致 AI 忽略部分内容

把规则拆分成多个文件，按触发条件分类。全局规则保持简洁（20 行以内），领域规则按需加载。

规则和任务简报冲突

任务简报中的约束优先级高于规则文件。如果某次任务需要临时突破规则，在任务简报中明确说明。

验证规则是否生效

在对话开始时问 AI："你了解这个项目的哪些约定？"根据回答判断规则文件是否被正确加载。