12 · .trae/rules 规则系统

规则是给 AI 的”项目宪法”——告诉它技术栈是什么、代码风格怎么定、什么东西不能碰。一次配置，Chat、Builder、SOLO 全模式通用。

01 什么是 .trae/rules

.trae/rules 是 Trae 项目中用来约束 AI 行为的规则文件系统。你把它放到项目根目录，AI 在每次与项目交互时就会自动读取里面的规则，然后按照你的要求来生成代码、回答问题、执行任务。

可以把规则理解为给 AI 看的项目文档——但不是给人看的 README，而是精准控制 AI 行为的行为规范。如果说 AI 是一辆车，那么规则就是它要遵守的交通规则：在哪里开、开多快、什么路不能上。

具体来说，规则能做的事情包括：

规则文件一旦保存，立即生效，无需重启 IDE。

02 规则的两级体系

Trae 的规则分为两个层级，分别对应不同作用范围：

个人规则

个人规则保存在 Trae 的用户配置目录中，独立于任何项目。你设置一次，所有打开的项目都会应用它。

适合放的内容：

• “所有回答使用中文”
• “代码注释用中文写，变量名用英文”
• “生成的命令行路径使用 macOS 格式”
• “输出尽可能简洁，不要过度解释”

项目规则

项目规则存放在项目目录下的 .trae/rules/ 中，可以提交到 Git 仓库，与团队成员共享。如果个人规则和项目规则有冲突，项目规则优先级更高——这是为了确保团队协作时的规范统一性。

适合放的内容：

• “本项目使用 pnpm，不要用 npm 或 yarn”
• “API 返回格式统一为 { code, data, message }”
• “禁止在业务代码中直接使用 console.log，用封装的 logger”

冲突时的处理逻辑

用户输入（对话中的指令）  → 最高优先级
自定义 Agent Prompt       → 次高优先级
项目规则（project_rules） → 中优先级，覆盖个人规则
个人规则（user_rules）   → 基础优先级

在对话中手动输入指令（比如”这次用 snake_case”）可以覆盖任何规则文件中的内容。自定义 Agent 的 Prompt 也会覆盖规则文件中的配置。而当项目规则和个人规则冲突时，项目规则优先。

03 .trae/rules 文件的创建与格式

通过 UI 创建

最简单的方式是通过 Trae 的规则管理面板：

1. 点击 IDE 右上角的设置图标进入设置中心
2. 在左侧导航栏选择规则
3. 点击 + 创建，选择项目规则
4. 输入规则名称（例如 “React 规范”）
5. 系统自动在项目根目录生成 .trae/rules/规则名称.md
6. 在 --- 分割线下方用 Markdown 编写规则内容
7. 点击保存

手动创建

你完全可以手动创建规则文件，格式没有任何特殊要求——就是普通的 Markdown：

.trae/rules/
├── general-rules.md
├── react-best-practices.md
├── backend-api.md
└── git-commit-rules.md

Frontmatter 字段

通过 UI 创建的项目规则文件会自动在顶部生成 YAML 风格的 frontmatter。如果你手动创建，也可以自行添加：

---
scene: git_message
description: 用于规范 Git 提交信息的格式
globs: src/**/*.ts
alwaysApply: false
---
 
# 提交信息规范
 
## 格式
type(scope): subject
 
## type 类型
- feat: 新功能
- fix: 修复
- refactor: 重构
- docs: 文档

支持的 frontmatter 字段：

04 四种生效模式

项目规则支持四种生效方式，这是 Trae 规则体系中最值得花时间理解的部分：

模式一：始终生效（Always Apply）

---
alwaysApply: true
---

当前项目中的每一次 AI 对话都会自动加载这条规则。适合放那些每个对话都需要遵守的通用规范，比如技术栈声明、输出语言、命名规范。

适合的场景：项目通用规范、技术栈定义、语言偏好、禁止事项。

模式二：指定文件生效（File-Glob）

---
alwaysApply: false
globs: "*.tsx, *.jsx"
---

只有在 AI 读取或引用了匹配 globs 模式的文件时，这条规则才会被激活。未匹配时不会浪费 Token。

# 只在前端文件中生效
globs: "src/frontend/**/*.tsx"
 
# 只在测试文件中生效
globs: "**/*.test.ts, **/*.spec.ts"
 
# 在多个目录下生效
globs: "src/components/**/*.tsx, src/pages/**/*.tsx"

适合的场景：按文件类型或目录定制的规则，比如只在前端组件文件中执行的 JSX 规范、只在测试文件中执行的测试规则。

模式三：智能生效（Smart Activation）

---
alwaysApply: false
description: "当涉及数据库查询优化或 ORM 使用时，参考此规则"
---

AI 根据 description 字段的描述自行判断当前对话是否需要这条规则。不需要精确匹配，AI 会做语义理解。

如果你写 “当讨论数据迁移或 Schema 变更时参考”，那么当你在对话中问 “给 users 表加一个 age 字段” 时，AI 会自动激活这条规则。

适合的场景：那些不频繁但在特定场景下很重要的规则，比如部署流程、数据库迁移步骤、回滚方案。

模式四：手动触发生效（Manual Trigger）

---
alwaysApply: false
---

规则默认不激活。只有当你在对话中输入 #规则文件名 时才会强制生效。

例如，如果你的规则文件叫 rollback-procedure.md，在对话中输入 #rollback-procedure，AI 就会加载这条规则。

#Rule 的优先级最高——即使规则被设为”指定文件生效”或”智能生效”，通过 #Rule 手动引用也会强制激活。这在紧急情况下非常有用。

适合的场景：高风险操作规范、回滚流程、紧急发布检查清单。

模式选择指南

你想这个规则什么情况下生效？
│
├─ 每次对话都需要 → 「始终生效」
├─ 只在特定文件中 → 「指定文件生效」
├─ 只在特定话题下 → 「智能生效」
├─ 只在明确要求时 → 「手动触发生效」
│

核心原则：能用”指定文件生效”就不要用”始终生效”。规则越精准，AI 的上下文越干净，回答质量越高。始终生效的规则太多，会导致 AI 的上下文被占满，核心指令反而被稀释。

05 规则的目录作用域与嵌套机制

.trae/rules 不仅限于项目根目录——你可以在项目的任意子目录下创建 .trae/rules/ 文件夹。这样做的好处是：当 AI 读取该子目录下的文件时，对应的规则会被自动激活。

my-project/
├── .trae/rules/
│   └── global-style.md                # 项目根规则，全局生效
├── frontend-module/
│   ├── AGENTS.md
│   └── .trae/rules/
│       └── react-practices.md         # 仅在前端目录下自动激活
└── backend-module/
    └── .trae/rules/
        └── api-design.md              # 仅在后台目录下自动激活

这种按目录自动匹配的机制，让你可以按模块拆分规则，无需手动配置 globs。Trae 会自动识别文件所在的目录层级，加载对应的规则。

子目录嵌套的深度限制

为了性能考虑，.trae/rules/ 内部的子目录嵌套最多支持 3 层。第 4 层及更深层的规则文件不会被读取：

.trae/rules/
├── level-1/                    # 第1层 ✓
│   ├── rules-1.md
│   └── level-2/                # 第2层 ✓
│       ├── rules-2.md
│       └── level-3/            # 第3层 ✓
│           ├── rules-3.md      # ← 会被读取
│           └── level-4/        # 第4层 ✗
│               └── rules-4.md  # ← 被忽略！

建议最多用到 2 层嵌套就足够清晰：

.trae/rules/
├── general.md
├── frontend/
│   ├── react-best-practices.md
│   ├── css-naming.md
│   └── testing/
│       └── unit-test-rules.md      # 2层，合理
└── backend/
    ├── api-design.md
    └── error-handling.md

06 规则优先级的完整机制

多条规则同时生效时，它们的优先级如何决定？下面是完整的优先级链：

按来源分

按生效方式分

当同一条规则的多种生效方式被满足时：

1. #Rule 手动触发优先级最高——即使规则本身设定了 globs 或 description，只要你在对话中 #Rule 了，它一定会激活
2. 始终生效的规则自动进入上下文
3. 指定文件生效和智能生效由 AI 判断是否加载

规则冲突的处理

如果两条规则给出了相互矛盾的指令——例如一条说 “用 camelCase”，另一条说 “用 snake_case”——AI 会倾向于遵循更具体的那一条。但最好的做法是从源头避免冲突：

个人规则里只放个人偏好，不要把团队规范写进去。 项目规则里每条规则只聚焦一个主题，不要在一个文件里塞进所有东西。 定期检查规则文件，删除相互矛盾的条目。

07 规则在 Chat / Builder / SOLO 中的传播

规则的一个核心特质是跨模式共享——你只需配置一次，所有模式都会自动使用。

Chat 模式

侧边栏 Chat 和 Inline Chat 都会读取项目规则。当你打开新对话时，Trae 会将当前项目下所有 “始终生效” 的规则以及匹配当前上下文的文件规则注入到 AI 的上下文中。

在 Chat 中使用 #Rule：如果你需要手动触发某条规则，在对话框里输入 #RuleName 即可。注意文件名大小写。

Builder 模式

Builder 在生成项目结构、批量创建文件时，会严格遵循 .trae/rules 中的声明。特别是：

• 技术栈声明决定了生成代码时用什么框架、库、语言
• 目录结构规范决定了文件生成的路径
• 禁止事项会阻止 Builder 在禁用的目录或文件中创建内容

例如，如果规则声明了 “使用 Tailwind CSS，禁止 CSS Module”，Builder 在生成组件时就会用 Tailwind 类名，不会生成 .module.css 文件。

SOLO 模式

SOLO 模式下的每个子任务（Coder、Builder）也会读取项目根目录下的 .trae/rules 规则。这意味着：

• SOLO Coder 在解析任务时，会参考规则来确定代码风格和规范
• SOLO Builder 在生成文件时，会遵循规则中的目录结构和命名规范
• 规则的一致性保证了你从 Chat 讨论方案到 SOLO 自动执行，AI 的输出风格始终统一

一个常见场景：你通过 Chat 和 AI 讨论了项目架构，定好了规则，然后切到 SOLO 模式让 AI 批量生成代码——由于规则共享，SOLO 生成的代码风格和 Chat 讨论的方案完全一致。

设置入口

在 SOLO 模式下配置规则：

• IDE 模式：设置 > 规则
• SOLO 模式：SOLO 面板右上角设置图标 > 规则

两种模式的管理面板完全一致，全局规则和项目规则的配置方式相同。

08 兼容文件：AGENTS.md 与 CLAUDE.md

Trae 不仅支持 .trae/rules，还支持其他 AI 编程工具的规则文件格式，以实现跨平台复用。

AGENTS.md

AGENTS.md 是放在项目根目录的轻量级 AI 行为指引文件。它与 .trae/rules 概念相近，但更加通用——可以在 Trae、Codex 等多个 IDE 中复用。

Trae 默认不会读取 AGENTS.md，需要手动开启：

设置 > 规则 > 导入设置 > 勾选”将 AGENTS.md 包含在上下文中”

开启后，Trae 会读取项目根目录的 AGENTS.md 并注入到 AI 上下文中。它也支持按目录激活——在子目录下放一个 AGENTS.md，只在 AI 读取该目录文件时生效。

CLAUDE.md / CLAUDE.local.md

如果你将一个原本在 Claude Code 中开发的项目导入 Trae，Trae 会自动识别根目录下的 CLAUDE.md 和 CLAUDE.local.md 文件。

同样需要在设置中开启：

设置 > 规则 > 导入设置 > 勾选”将 CLAUDE.md 包含在上下文中”

三者的关系

建议：如果你只使用 Trae，用 .trae/rules 就够了。如果团队部分成员使用其他工具，可以在 .trae/rules 写详细的规则，同时在根目录放一个轻量的 AGENTS.md 或 CLAUDE.md 做兼容。

09 Git 提交信息规则

Trae 的规则系统可以对 AI 生成的 Git 提交信息进行定制。有两种方式：

方式一：在已有规则文件中添加 scene 字段

在任意 .trae/rules 文件的 frontmatter 中添加 scene: git_message，该文件的正文就会在 AI 生成提交信息时生效。

---
scene: git_message
---
 
# 提交信息规范
 
## 格式
<type>(<scope>): <subject>
 
## 类型
- feat: 新功能
- fix: 修复
- refactor: 重构
- perf: 性能优化
- style: 代码风格
- test: 测试
- docs: 文档
- chore: 构建/工具
 
## 要求
- subject 使用中文
- scope 使用对应模块名
- 正文（body）可选，如果改动复杂需要简要说明原因

方式二：自动生成 git-commit-message.md

在源代码管理（Source Control）面板中，点击下拉菜单 > 配置提交信息生成规则，Trae 会自动在 .trae/rules/ 目录下生成 git-commit-message.md 文件。如果已有文件包含 scene: git_message，则会打开已有的。

多个文件同时包含 scene: git_message 也没问题——AI 会同时遵循所有这类文件中的规则。

10 实战示例一：React 前端项目

这是一个使用 React + TypeScript + Tailwind CSS 的 SPA 项目规则：

# React 前端项目规则
 
## 技术栈
React 18 + TypeScript (strict mode)
状态管理：Zustand（优先），React Context（次要）
样式：Tailwind CSS
HTTP 请求：React Query (TanStack Query) + Axios
路由：React Router v6
构建：Vite
 
## 组件规范
- 函数式组件 + Hooks，禁止 Class Component
- 文件名 = 组件名，PascalCase（Button.tsx, UserCard.tsx）
- Props 用 interface 定义，放在组件文件底部
- 一个文件一个组件，禁止同文件放多个组件
- 页面组件放 pages/，可复用组件放 components/
- hooks 文件放 hooks/，以 use 开头（useAuth.ts）
 
## 样式规范
- 使用 Tailwind 类名，禁止内联 style
- 自定义样式用 @apply 写在 components layer 中
- 响应式设计：先写移动端，再用 sm:/md:/lg: 断点覆盖
- 颜色使用 Tailwind 内置色板，禁止自定义颜色值
 
## 命名规范
- 组件：PascalCase
- 文件/目录：kebab-case（user-profile.tsx）
- 变量/函数：camelCase
- 常量：UPPER_SNAKE_CASE
- 事件处理函数：handleXxx 命名
 
## 禁止事项
- 不用 any 类型，用 unknown 替代
- 不直接操作 DOM，使用 React 状态管理
- 不引入新的 npm 包，优先使用已有依赖
- 不修改 tailwind.config.ts
- 不在组件外使用 React hooks

11 实战示例二：Python 数据项目

一个使用 FastAPI + SQLAlchemy + Pandas 的数据分析后端项目：

# Python 数据项目规则
 
## 技术栈
Python 3.12 + FastAPI
ORM: SQLAlchemy 2.0 (async)
数据库：PostgreSQL 16
数据管道：Apache Airflow
数据格式：Parquet（存储）, Arrow（传输）
测试：pytest + pytest-asyncio
 
## 代码规范
- 所有类型标注完整，禁止裸变量
- 函数超过 30 行必须拆分
- 异常处理：使用自定义 Exception 类，禁止裸 raise Exception
- 异步函数使用 async/await，禁止 asyncio.run() 嵌套
- 日志用 structlog，禁止 print
 
## 命名规范
- 变量/函数：snake_case
- 类名：PascalCase
- 常量：UPPER_SNAKE_CASE
- 数据库表：snake_case 复数形式（users, orders）
- 数据库列：snake_case（created_at, user_id）
 
## 目录结构要求
- src/models/：SQLAlchemy 模型
- src/schemas/：Pydantic 验证模型
- src/routes/：FastAPI 路由
- src/services/：业务逻辑
- src/utils/：工具函数
- tests/：测试文件，镜像 src 的结构
 
## 禁止事项
- 禁止在路由函数中直接写数据库查询
- 禁止使用 sync ORM session（必须用 async session）
- 禁止硬编码敏感信息（数据库密码、API Key）
- 禁止使用 pickle 序列化（用 JSON 或 Parquet）

12 实战示例三：Monorepo 多包项目

Monorepo 结构最适合发挥 Trae 规则系统的按目录激活能力：

my-monorepo/
├── .trae/rules/
│   └── monorepo-global.md           # 全局规则：pnpm workspace、统一工具链
├── packages/
│   ├── ui/
│   │   └── .trae/rules/
│   │       └── ui-component.md      # 仅在 packages/ui 下激活
│   ├── api/
│   │   └── .trae/rules/
│   │       └── api-conventions.md   # 仅在 packages/api 下激活
│   └── shared/
│       └── .trae/rules/
│           └── shared-lib.md        # 仅在 packages/shared 下激活

monorepo-global.md

# Monorepo 全局规则
 
## 基础设施
包管理：pnpm workspace
构建：Turborepo
TypeScript：Project References
环境变量：dotenv + zod 校验（所有 env 必须定义类型）
 
## 依赖管理
- 所有公共依赖提升到根 node_modules（通过 pnpm）
- 各包之间引用走 workspace protocol（workspace:*）
- 版本号统一管理，不要在各包中单独定义

packages/ui/.trae/rules/ui-component.md

---
alwaysApply: false
globs: packages/ui/**/*.tsx
---
 
# UI 组件库规则
 
- 使用 Radix UI 作为无障碍组件基础
- 所有组件必须支持 ref 透传（forwardRef）
- 使用 Storybook 可视化测试
- 组件 API 遵循 shadcn/ui 风格

packages/api/.trae/rules/api-conventions.md

---
alwaysApply: false
globs: packages/api/**/*.ts
---
 
# API 规范
 
- 所有端点返回标准格式：{ success: boolean, data?: T, error?: string }
- 使用 zod 做请求体校验
- 每个端点记录结构化日志（请求ID、耗时、状态码）
- 速率限制：认证用户 100 次/分钟，未认证用户 20 次/分钟

当你在 Chat 中提到 packages/ui/Button.tsx 时，AI 会自动激活 ui-component.md 中的规则，同时根目录的 monorepo-global.md 也会生效。而 api-conventions.md 不会被加载——因为当前上下文不匹配它的 globs 模式。

13 常见错误与避坑指南

错误一：规则文件太长

最普遍的问题。有人一个规则文件写上百行，把 AI 教程、代码示例、详细的框架文档全部塞进去。结果是 AI 的上下文被大量冗余信息挤占，真正关键的规则反而被淹没。

正确做法：每个规则文件聚焦一个主题，控制在 30 行以内。把关键信息放在前三行——AI 的注意力是线性的，前面的内容最容易被记住。

# ❌ 差（120 行，包含大量框架教程）
- React 18 新增了 useTransition、useDeferredValue...
- （详细讲了一遍 React 特性）
- 本项目使用 React 18
 
# ✅ 好（15 行，只写必要约束）
## 技术栈
- React 18 + TypeScript strict mode
- 使用 Vite 构建，禁止 eject CRA

错误二：把关键规则埋在末尾

如果你有一条绝对不能忘记的规则——比如”不要修改数据库 Schema”——不要把它写在文件最后。AI 在处理长文本时存在明显的”近因效应”，开头的指令最牢靠，中间的容易丢失，末尾的如果不是被专门追问也很难记住。

正确做法：把禁止事项和最关键的技术限制放在规则文件的前面，次要内容往后放。

错误三：规则之间相互矛盾

规则 A：所有 API 返回 { data, error } 格式
规则 B：API 返回 { success, result, message } 格式

两条规则同时生效时，AI 不知道该听谁的。产生相互矛盾的输出是必然的。

正确做法：定期检查项目中的所有规则文件，确保它们不矛盾。项目规则和个人规则检查冲突尤其容易忽略。

错误四：忽视了个人规则的作用

很多开发者只写项目规则，忽略了个人规则。结果是 AI 的英文回答可能不符合你的阅读习惯、生成的命令不适应你的操作系统、输出过于啰嗦。

正确做法：设置个人规则处理”你”的偏好，设置项目规则处理”项目”的规范。两者互不替代。

错误五：修改规则后不新开对话

AI 的对话历史记住了旧规则下的行为。如果你修改了规则但没有新开对话，AI 可能在当前会话中继续遵循旧模式。

正确做法：保存规则文件后，点击 Trae Chat 面板的”新对话”按钮（或 Cmd+N），让 AI 在新上下文中重新加载规则。

错误六：规则数量过多

Trae 官方建议 .trae/rules/ 中的文件数量控制在 10-20 条以内。超过这个数量，AI 的上下文会被大量规则塞满，不仅消耗 Token，还会导致 AI 对每条规则的关注度下降——规则泛化的问题。

正确做法：

10 条以下 → 最佳，每个文件聚焦一个主题
10-20 条 → 尚可，需要检查是否有冗余
20 条以上 → 需要合并和精简

14 小结

规则系统的终极目标不是约束 AI，而是让 AI 在正确的框架下发挥最大的创造力。一个精心配置的 .trae/rules 目录，比你反复在对话中纠正 AI 要高效得多——它让你的项目规范沉淀为可复用、可分享、可版本控制的代码资产。

写规则的最佳时机：项目初始化的第一天。越早写，AI 的产出越少走弯路。

下一篇： 13 MCP 集成 —— 用 MCP 协议让 Trae 连接数据库、文件系统、云服务等外部工具。