Trae Rules 配置指南：打造懂你项目的 AI

为什么需要 Trae Rules

你有没有遇到过这种情况：AI 生成的代码能跑，但风格和你项目完全不搭？比如你用的是 camelCase，它给你来个 snake_case；你项目用 Zustand，它非要给你写 Redux。

Trae Rules 就是解决这个问题的。它是一个项目级的 AI 行为配置文件，告诉 Trae：“我的项目是这样的，请按这个规范来。“

Rules 的核心价值

没有 Rules	有 Rules
AI 按通用习惯生成代码	AI 按你的项目规范生成代码
每次都要手动纠正风格	一次配置，持续生效
团队成员 AI 输出不一致	全团队统一的 AI 行为
需要反复解释项目上下文	AI 自动理解项目背景

Rules 文件的位置与格式

Trae Rules 的配置文件放在项目根目录下，文件名为 .trae/rules。你也可以使用 YAML 或 Markdown 格式：

# 项目结构
my-project/
├── .trae/
│   └── rules          # Trae Rules 配置文件
├── src/
├── package.json
└── ...

Rules 文件本质上是一个纯文本文件，用自然语言描述你的项目规范。Trae 会在每次对话时自动读取这个文件作为上下文。

创建你的第一个 Rules 文件

# 在项目根目录创建 .trae 目录和 rules 文件
mkdir -p .trae
touch .trae/rules

然后用你喜欢的编辑器打开 .trae/rules，开始编写规则。

基础配置：技术栈与编码规范

一个好的 Rules 文件应该从项目的基本信息开始：

# 项目概述
这是一个基于 React 18 + TypeScript 的电商前端项目。
使用 Vite 作为构建工具，pnpm 作为包管理器。

# 技术栈
- 框架：React 18 with Hooks
- 语言：TypeScript（严格模式）
- 样式：Tailwind CSS v3
- 状态管理：Zustand
- 路由：React Router v6
- HTTP 请求：Axios
- 表单：React Hook Form + Zod
- 测试：Vitest + React Testing Library

# 编码规范
- 使用函数组件，不使用 class 组件
- 使用 named export，不使用 default export
- 文件命名使用 kebab-case（如 user-profile.tsx）
- 组件命名使用 PascalCase（如 UserProfile）
- 变量和函数使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
- 缩进使用 2 个空格
- 字符串使用单引号

文件结构规范

告诉 AI 你的项目目录结构，这样它生成新文件时会放到正确的位置：

# 文件结构
src/
├── components/       # 可复用组件
│   ├── ui/          # 基础 UI 组件（Button, Input, Modal 等）
│   └── business/    # 业务组件
├── hooks/           # 自定义 Hooks
├── pages/           # 页面组件
├── stores/          # Zustand stores
├── services/        # API 请求层
├── types/           # TypeScript 类型定义
├── utils/           # 工具函数
└── constants/       # 常量定义

进阶配置：命名约定与模式

命名约定

# 命名约定
- 组件文件：kebab-case.tsx（如 user-card.tsx）
- Hook 文件：use-xxx.ts（如 use-auth.ts）
- Store 文件：xxx-store.ts（如 cart-store.ts）
- Service 文件：xxx-service.ts（如 user-service.ts）
- 类型文件：xxx.types.ts（如 user.types.ts）
- 工具文件：xxx-utils.ts（如 date-utils.ts）
- 常量文件：xxx-constants.ts（如 api-constants.ts）

错误处理模式

# 错误处理
- API 请求统一使用 try-catch，不使用 .then().catch()
- 错误信息使用自定义 AppError 类
- 所有 async 函数必须有错误处理
- 用户可见的错误信息使用 toast 提示

示例：
async function fetchUser(id: string): Promise<User> {
  try {
    const { data } = await api.get<User>(`/users/${id}`);
    return data;
  } catch (error) {
    if (error instanceof AxiosError) {
      throw new AppError(error.response?.data?.message ?? '请求失败');
    }
    throw new AppError('未知错误');
  }
}

测试规范

# 测试规范
- 测试文件放在 __tests__ 目录下
- 测试文件命名：xxx.test.ts 或 xxx.test.tsx
- 使用 describe/it 结构组织测试
- Mock 外部依赖，不 mock 内部模块
- 组件测试优先使用 getByRole 查询
- 每个公共函数至少一个测试用例

全局 Rules vs 项目 Rules

Trae 支持两个层级的 Rules：

特性	全局 Rules	项目 Rules
位置	~/.trae/rules	项目/.trae/rules
作用范围	所有项目	当前项目
优先级	低	高（覆盖全局）
适合内容	个人编码习惯	项目特定规范

# 全局 Rules（你的个人偏好）
mkdir -p ~/.trae
cat > ~/.trae/rules << 'EOF'
# 个人编码偏好
- 我偏好函数式编程风格
- 优先使用 const，避免 let
- 注释使用中文
- commit message 使用英文
- 代码中不使用 any 类型
EOF

当全局 Rules 和项目 Rules 同时存在时，项目 Rules 的优先级更高。如果有冲突，以项目 Rules 为准。

实战模板：React + TypeScript 项目

这是一个完整的 React + TypeScript 项目 Rules 模板，你可以直接复制修改：

# 项目：电商平台前端
# 技术栈：React 18 + TypeScript + Vite + Tailwind CSS

## 代码风格
- 使用函数组件 + Hooks，禁止 class 组件
- 使用 named export
- Props 类型定义使用 interface，命名为 XxxProps
- 状态管理使用 Zustand，store 使用 create 函数创建
- 样式使用 Tailwind CSS，不写自定义 CSS

## 组件模板
每个组件文件应遵循以下结构：
1. import 语句（外部库 → 内部模块 → 类型 → 样式）
2. interface 定义
3. 组件函数
4. 辅助函数（如果有）

示例：
import { useState, useCallback } from 'react';
import { Button } from '@/components/ui/button';
import type { UserCardProps } from './user-card.types';

export function UserCard({ user, onEdit }: UserCardProps) {
  const [isExpanded, setIsExpanded] = useState(false);

  const handleToggle = useCallback(() => {
    setIsExpanded(prev => !prev);
  }, []);

  return (
    <div className="rounded-lg border p-4 shadow-sm">
      <h3 className="text-lg font-semibold">{user.name}</h3>
      {isExpanded && <p className="mt-2 text-gray-600">{user.bio}</p>}
      <Button onClick={handleToggle}>
        {isExpanded ? '收起' : '展开'}
      </Button>
    </div>
  );
}

## API 请求
- 使用 Axios 实例，baseURL 从环境变量读取
- 请求函数放在 services/ 目录
- 返回类型必须明确标注
- 使用 interceptor 统一处理 token 和错误

## 测试
- 使用 Vitest + React Testing Library
- 测试文件与源文件同目录的 __tests__ 文件夹
- 优先测试用户交互行为，而非实现细节

实战模板：Python FastAPI 项目

# 项目：用户管理 API 服务
# 技术栈：Python 3.12 + FastAPI + SQLAlchemy + PostgreSQL

## 代码风格
- 遵循 PEP 8 规范
- 使用 type hints，所有函数参数和返回值都要标注类型
- 使用 Pydantic v2 做数据验证
- 使用 async/await 处理异步操作
- 文档字符串使用 Google 风格

## 项目结构
app/
├── api/           # 路由定义
│   └── v1/        # API 版本
├── core/          # 核心配置
├── models/        # SQLAlchemy 模型
├── schemas/       # Pydantic schemas
├── services/      # 业务逻辑
├── repositories/  # 数据访问层
└── utils/         # 工具函数

## 路由定义模板
from fastapi import APIRouter, Depends, HTTPException, status
from app.schemas.user import UserCreate, UserResponse
from app.services.user_service import UserService

router = APIRouter(prefix="/users", tags=["users"])

@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
async def create_user(
    user_data: UserCreate,
    service: UserService = Depends(get_user_service),
) -> UserResponse:
    """创建新用户。"""
    return await service.create(user_data)

## 错误处理
- 业务异常使用自定义 AppException
- HTTP 异常在路由层抛出
- 数据库异常在 repository 层捕获并转换

## 测试
- 使用 pytest + httpx
- 测试数据库使用 SQLite in-memory
- 每个 endpoint 至少测试正常和异常两种情况

Rules 编写最佳实践

该写什么

✅ 技术栈和版本信息
✅ 编码规范和命名约定
✅ 文件组织结构
✅ 常用的代码模式和模板
✅ 错误处理策略
✅ 测试规范
✅ API 设计约定
✅ Git 提交规范

不该写什么

❌ 过于具体的业务逻辑（AI 应该从代码中理解）
❌ 敏感信息（API Key、密码等）
❌ 过长的文档（保持在 500 行以内）
❌ 与代码矛盾的规范（会让 AI 困惑）
❌ 过于宽泛的描述（"写好代码"没有意义）

保持 Rules 的更新

# 建议把 .trae/rules 加入版本控制
git add .trae/rules
git commit -m "chore: add trae rules for project conventions"

团队成员都能共享同一份 Rules，确保 AI 在每个人的环境中行为一致。

traerules.io 社区规则目录

traerules.io 是一个社区驱动的 Trae Rules 模板集合，类似于 cursor.directory 之于 Cursor。你可以在这里：

• 浏览不同技术栈的 Rules 模板
• 提交你自己的 Rules 模板
• 根据项目类型快速找到合适的起点

# 常见的社区模板分类
- Frontend: React, Vue, Angular, Svelte
- Backend: Node.js, Python, Go, Rust
- Mobile: React Native, Flutter
- Full-stack: Next.js, Nuxt, SvelteKit

Trae Rules Generator MCP Server

如果你觉得手写 Rules 太麻烦，可以用 Trae Rules Generator MCP Server 自动分析项目并生成规则：

{
  "mcpServers": {
    "trae-rules-generator": {
      "command": "npx",
      "args": ["-y", "trae-rules-generator"],
      "env": {}
    }
  }
}

配置好之后，在 Trae 的 Chat 中输入：

帮我分析当前项目，生成 Trae Rules 配置

AI 会扫描你的项目结构、依赖、代码风格，自动生成一份 Rules 文件。你只需要审查和微调就行。

与 .cursorrules 的语法对比

如果你之前用过 Cursor，这个对比表能帮你快速迁移：

特性	Trae Rules	.cursorrules
文件位置	.trae/rules	.cursorrules
文件格式	纯文本 / Markdown	纯文本 / Markdown
全局配置	~/.trae/rules	Cursor Settings
语法	自然语言描述	自然语言描述
代码示例	支持	支持
多文件规则	单文件	单文件
社区模板	traerules.io	cursor.directory

两者的语法非常相似，核心都是用自然语言描述项目规范。如果你已经有 .cursorrules 文件，大部分内容可以直接复制到 .trae/rules 中使用。

# 快速迁移 cursorrules 到 trae rules
mkdir -p .trae
cp .cursorrules .trae/rules

当然，迁移后建议根据 Trae 的特性做一些调整和优化。

小结

Trae Rules 是提升 AI 编码质量的关键配置。花 30 分钟写好一份 Rules，能在之后的每次对话中节省大量纠正时间。记住：

1. 从基础信息开始：技术栈、编码规范、文件结构
2. 逐步完善：根据 AI 的输出质量不断调整
3. 团队共享：把 Rules 加入版本控制
4. 保持简洁：Rules 不是文档，是给 AI 的指令

“好的工具配置就像好的团队文化——一旦建立，每个人都会自然而然地遵循。花时间定义规则，是为了节省更多的时间。”