一文讲透 .trae 文件夹 - Trae IDE 配置指南和最佳实践

一文讲透 .trae/ 文件夹：Trae IDE 配置指南和最佳实践

有不少文章把 .trae/ 文件夹拆开讲了个遍：Rules、Skills、Agents、MCP、Settings，该有的都有。但文章看完，真正落地的时候还是一头雾水：哪些东西应该提交 Git，哪些只能留本机？哪些是"提示词层面的期望"，哪些是"客户端层面的强制"？几个配置叠在一起，优先级到底怎么算？

这篇文章想把这些问题说清楚，但有一点要先说明：Trae 迭代很快，具体字段名和语法以官方文档 docs.trae.ai 为准，这里讲的是思路和框架。

---

一、不同目录下的 .trae/

很多人以为 Trae 的配置就一个地方，其实它有一套完整的作用域体系，从内到外分多层：

实际工作中最常用的是这三个：

• 项目级（团队共享）：项目目录里的 .trae/——rules/、skills/、agents/、settings.json、mcp.json 都放这，提交 Git，协作成员行为一致。
• 用户级（个人全局）：用户主目录的 ~/.trae/——你的个人偏好和跨项目复用的资产放这，不会影响别人。
• 本地覆盖（仅本机）：.trae/settings.local.json——这个文件默认被 gitignore，用来做个人实验或临时调整，不会污染团队配置。

还有一个经常被忽视的区别：~/.trae/settings.json 和项目里的 .trae/settings.json 是两个完全不同的东西。前者存的是 UI 状态、用户偏好、主题设置，后者才是行为配置。排查"配置怎么没生效"的时候，先把这两个分清楚。

用文件结构表示的话大概长这样：

your-repo/
├── CLAUDE.md                  # ✅ 团队共享（兼容 Claude Code）
├── CLAUDE.local.md            # 🟡 本地有效（gitignored）
└── .trae/
    ├── settings.json          # ✅ 团队共享
    ├── settings.local.json    # 🟡 本地有效（gitignored）
    ├── mcp.json               # ✅ 团队共享
    ├── rules/                 # ✅ 团队共享
    │   ├── user_rules.md     # 个人规则（项目级）
    │   └── project_rules.md  # 项目规则
    ├── skills/                # ✅ 团队共享
    │   └── <skill-name>/
    │       └── SKILL.md
    └── agents/                # ✅ 团队共享
        └── <agent-name>.md

注意：Trae 的 Rules 分为 user_rules.md（个人规则）和 project_rules.md（项目规则），这和 Claude Code 的设计略有不同。

1.1 作用域优先级

当个人规则和项目规则冲突时，项目规则优先级更高，不会被人个偏好覆盖。这点和 Claude Code 一致。

项目 rules > 用户 rules > 默认行为

1.2 常见误区

• 全局生效的 project_rules.md：project_rules.md 并不是全局生效，而是项目级生效。如果你在项目 A 写了 Vue3 规范，项目 B 是 React，这两个规范不会互相影响。
• MCP 配置位置：MCP 服务器配置在 .trae/mcp.json，而不是 settings.json。这是两个独立的配置体系。
• skills 的作用域：早期版本的 skills 只能在当前目录下生效，新版本已经支持全局 skills（~/.trae/skills/），但项目级 skills 仍然是团队协作的最佳实践。

---

二、Rules：把"每次都要重复说的话"固化下来

用 Trae 用得顺了之后会发现，能让 AI 稳定按你期望工作的，不是提示词技巧，而是把"这个项目默认怎么运转"写进一个长期存在的文件。这就是 Rules 的用途：每次会话开始时自动注入，承载编码规范、工作流、架构边界。

2.1 两种规则类型

user_rules.md（个人规则）：定义通用习惯，如"所有注释用中文""React 组件必须用函数式写法"，一次配置全项目生效。适合放：

• 编程语言偏好（用 TypeScript 代替 JavaScript）
• 代码风格偏好（用 Prettier 格式化）
• 交互方式偏好（直接回答，不要反问）

project_rules.md（项目规则）：针对特定项目的技术栈约束，如"本项目强制使用 Vue3+TypeScript""API 请求必须包含错误处理"。适合放：

• 技术栈约束（本项目使用 X 框架）
• 架构规范（分层结构、目录约定）
• 安全要求（禁止使用某些 API）

2.2 按路径生效的规则

Trae 支持带 paths frontmatter 的规则，只在 AI 处理匹配路径的文件时触发。这可以减少无关噪音：

---
paths:
  - "src/server/api/**/*.ts"
---

# API 约定
- 所有 handler 必须做输入校验
- 对外错误返回统一结构 { data, error }
- 禁止把内部堆栈直接返回给客户端

比如上面的规则，只在处理 src/server/api/**/*.ts 文件时才会被激活，处理前端代码时不会加载。

2.3 使用方式

在 Trae 界面中：

1. 点击 AI 对话窗口右上角的 "Settings" 图标
2. 选择 "Rules" 选项
3. 在对应区域点击 "+ 创建" 按钮

系统会自动在 .trae/rules/ 目录下创建对应的规则文件。

2.4 规则不生效的常见原因

• 包含敏感词（如"可能""尽量"会降低规则权重，AI 会觉得这不是硬性要求）
• 规则被更高优先级覆盖（用户输入指令 > 项目规则）
• 文件路径不正确（个人规则在 ~/.trae/rules/，项目规则在项目 .trae/rules/）
• 规则太长太杂（建议每个规则文件控制在 200 行以内）

2.5 写多长合适

一个实用的经验值：控制在 200 行以内。文件一旦过长，有效信息被稀释，AI 的遵循度会明显下降。内容膨胀了就拆成多个规则文件，或者用 @path/to/import 导入独立文件。

---

三、Skills：把重复工作流变成一条命令

Rules 解决"Trae 一直知道什么"，Skills 解决"Trae 能快速干什么"。创建一个 Skill，就能让 AI 在特定场景下自动调用相关工作流。

3.1 Skill 结构

.trae/skills/<skill-name>/
├── SKILL.md              # 必须
├── <其他文件>            # 可选（脚本、参考文档等）

每个 Skill 的 SKILL.md 包含：

• name: 技能名称
• description: 技能描述（用于自动触发匹配，包含关键词会触发自动加载）
• Instructions: 具体指令和工作流

3.2 值得用好的能力

自动触发：description 中的关键词可以触发 Skill 自动加载。比如一个 description 为 "代码审查，检查潜在 bug、安全风险、测试缺口" 的 Skill，当用户请求代码审查时会自动匹配。

动态上下文：支持 !command` 语法，执行 shell 命令并将输出注入 prompt：

---
name: review-pr
description: 审查当前分支相对 main 的改动，输出按文件分组的可执行建议
---

## 变更文件
!`git diff --name-only main...HEAD`

## 详细 diff
!`git diff main...HEAD`

请按文件输出：
- 潜在 bug / 边界条件
- 安全风险
- 测试缺口
- 可维护性建议（只提必要的）

这样 /review 命令可以自动注入 git diff 结果，团队零额外操作。

按需加载：Skill 只在相关任务出现时才加载，不占用额外 context window。这点和 Rules 不同——Rules 是持续加载的。

3.3 Skill 安装方式

方式一：通过 UI 创建 在 Trae 的 Settings > Rules & Skills 界面，点击创建新 Skill。

方式二：手动创建 在 .trae/skills/ 目录下创建子文件夹，放入 SKILL.md 文件。

方式三：通过 npx skills 命令安装社区 Skills

npx skills add vercel-labs/agent-skills

这会从 skills.sh 安装开源 Skills 库。

3.4 与 Rules 的区别

特性	Rules	Skills
加载方式	持续加载	按需加载
作用	始终生效	任务匹配时触发
适用场景	代码风格、架构约束	特定工作流、临时任务
context 影响	占用 context window	几乎不占用
触发方式	自动注入	关键词匹配或手动调用

---

四、Agents：让"重活"在隔离窗口里跑

Agents 是 Trae 特有的功能（对应 Claude Code 的 Subagents）。任务复杂到需要大量检索、阅读、比对的时候，主对话上下文很容易被塞满。Agents 跑在独立上下文里，有独立系统提示词，可以指定工具集，可以单独选模型，结果摘要回传主线程。

4.1 Agent 文件结构

.trae/agents/
└── <agent-name>.md

每个 Agent 文件是一个独立配置：

---
name: code-reviewer
description: 专职代码审查员，适合合并前、自测失败、或重构后稳定性检查
tools: Read, Glob, Grep, Bash(git diff *)
model: sonnet
---

你是资深 code reviewer，重点看：
- 逻辑正确性和边界
- 可读性、命名、复杂度
- 并发、权限、注入、资源泄露等风险点

输出要具体到文件和行范围，给出可以直接动手改的建议。

4.2 Agent 配置项

• name: Agent 名称
• description: Agent 描述，用于选择合适的 Agent
• tools: 允许这个 Agent 使用的工具（用逗号分隔）
• model: 指定这个 Agent 使用的模型（可以比主对话更便宜）
• system prompt: 角色定义和行为规范

4.3 适合交给 Agent 的三类任务

1. 大量文件检索：让 research agent 读文件、跑 grep/glob，只把要点带回主线程。
2. 强约束审查：比如"安全审计 agent 只允许 Read/Grep/Glob，禁止 Write/Edit"，工具权限写在配置里，不依赖 AI 自觉。
3. 成本控制：可并行、可概括的任务下沉到更快更便宜的模型，主线程留给关键决策。

4.4 创建 Agent 的方式

1. UI 创建：Settings > Agents > Create Agent
2. Smart Generate：用自然语言描述需求，Trae 自动生成 Agent 配置
3. 手动创建：在 .trae/agents/ 目录下创建 .md 文件

---

五、MCP Servers：扩展 AI 的"感官"

MCP（Model Context Protocol）是 Anthropic 提出的开放标准，让 AI 可以调用外部工具和服务。通过 MCP，Trae 可以连接文件系统、数据库、浏览器、第三方服务等。

5.1 MCP 配置位置

• 项目级：.trae/mcp.json
• 用户级：~/.trae/mcp.json

5.2 配置示例

Stdio 方式（本地命令）：

{
  "mcpServers": {
    "supabase_local": {
      "command": ["supabase", "mcp"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@0.0.27"]
    }
  }
}

SSE 方式（远程服务）：

{
  "mcpServers": {
    "github_agent": {
      "url": "https://agent.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

5.3 常用 MCP 服务器

MCP 名称	描述
filesystem-mcp	本地文件系统操作
playwright	浏览器自动化
supabase	数据库操作
github	GitHub API 操作
trae-rules-mcp	自动生成规则文件
trae-memory-mcp	长期记忆存储
trae-swagger-mcp	Swagger 文档解析

5.4 使用方式

在 Trae 中配置好 MCP 后，MCP 服务器会作为 Tools 供 Agent 调用。用户可以在对话中自然地请求："帮我查一下数据库里的用户列表"，Agent 会自动调用 MCP 工具执行。

---

六、Settings.json：安全边界不要靠"希望 Trae 记得"

settings.json 把"能做什么"从提示词期望提升为客户端强制规则。

6.1 基础编辑器配置

{
  "editor.fontSize": 14,
  "editor.lineHeight": 22,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,
  "editor.minimap.enabled": false,
  "editor.codeActionsOnSave": {
    "source.fixAll": true
  }
}

6.2 文件性能优化配置

{
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true,
    "**/build/**": true,
    "**/.git/**": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/package-lock.json": true,
    "**/dist": true
  }
}

6.3 AI 相关配置

{
  "trae.ai.enabled": true,
  "trae.ai.model": "claude-sonnet-4-20250514",
  "trae.ai.codeIndex.enabled": true,
  "trae.ai.codeIndex.autoBuild": true,
  "trae.rules.autoLoad": true,
  "trae.ai.chatLanguage": "auto"
}

6.4 Git 相关配置

{
  "git.autofetch": true,
  "git.enableSmartCommit": true,
  "git.enableCommitSigning": false
}

6.5 Terminal 配置

{
  "terminal.integrated.fontSize": 13,
  "terminal.integrated.shell.linux": "/bin/zsh",
  "terminal.integrated.cursorBlink": true
}

---

七、tasks.json：自定义任务自动化

Trae 支持在 .trae/tasks.json 中定义自定义任务，类似于 VS Code 的 tasks。

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Deploy to Production",
      "type": "shell",
      "command": "npm run build && npm run deploy",
      "group": "build",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      },
      "problemMatcher": []
    },
    {
      "label": "Run E2E Tests",
      "type": "npm",
      "script": "test:e2e",
      "group": "test",
      "presentation": {
        "reveal": "never",
        "panel": "shared"
      }
    },
    {
      "label": "Lint & Format",
      "type": "shell",
      "command": "pnpm lint && pnpm format",
      "group": "none"
    }
  ]
}

---

八、Trae 与 Claude Code 的关键区别

特性	Trae (.trae/)	Claude Code (.claude/)
个人规则文件	user_rules.md	~/.claude/rules/*.md
项目规则文件	project_rules.md	.claude/rules/*.md
规则加载顺序	用户规则先加载，项目规则覆盖	用户规则先加载，项目规则覆盖
Skills 目录	.trae/skills/	.claude/skills/
Agents/Subagents	.trae/agents/	.claude/agents/
配置文件	settings.json	settings.json
本地覆盖	settings.local.json	settings.local.json
MCP 配置	.trae/mcp.json	独立配置
Tasks	.trae/tasks.json	无原生支持

8.1 Trae 特有的能力

• MCP 原生支持：Trae 对 MCP 的支持更加原生和深入
• tasks.json：原生的任务自动化支持
• 多模型切换：在 UI 中更容易切换不同模型

8.2 Claude Code 特有的能力

• CLAUDE.md：更灵活的多层级上下文注入
• hooks：模型循环之外的确定性自动化
• sandbox：更强的安全隔离

---

九、一套可以直接用的最小配置

.trae/rules/project_rules.md

# 项目规范

## 常用命令
pnpm dev      # 启动开发
pnpm test     # 跑测试
pnpm lint     # lint/format
pnpm build    # 构建

## 关键结构
- 后端：src/server/
- 前端：src/web/
- 通用：src/shared/

## 约定
- 改动要补测试（明确说明可以不补的除外）
- 错误处理走 src/shared/logger，禁止随手 console.log
- 优先修补，不要动不动大重构

## 容易踩的坑
- 严格类型检查默认开启
- 本地测试依赖 Redis（见 docs/dev.md）

.trae/rules/api.md（按路径生效的规则）

---
paths:
  - "src/server/api/**/*.ts"
---

# API 约定
- 所有 handler 必须做输入校验
- 对外错误返回统一结构 { data, error }
- 禁止把内部堆栈直接返回给客户端

.trae/skills/review-pr/SKILL.md

---
name: review-pr
description: 审查当前分支相对 main 的改动，输出按文件分组的可执行建议
---

## 变更文件
!`git diff --name-only main...HEAD`

## 详细 diff
!`git diff main...HEAD`

请按文件输出：
- 潜在 bug / 边界条件
- 安全风险
- 测试缺口
- 可维护性建议（只提必要的）

.trae/agents/code-reviewer.md

---
name: code-reviewer
description: 专职代码审查员，适合合并前、自测失败、或重构后稳定性检查
tools: Read, Glob, Grep, Bash(git diff *), Bash(git status)
model: sonnet
---

你是资深 code reviewer，重点看：
- 逻辑正确性和边界条件
- 可读性、命名、复杂度
- 并发、权限、注入、资源泄露等风险点

输出要具体到文件和行范围，给出可以直接动手改的建议。

.trae/settings.json

{
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,
  "editor.minimap.enabled": false,
  "editor.codeActionsOnSave": {
    "source.fixAll": true
  },
  "files.autoSave": "onFocusChange",
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true,
    "**/build/**": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/package-lock.json": true
  },
  "terminal.integrated.fontSize": 13,
  "git.autofetch": true,
  "trae.ai.enabled": true,
  "trae.rules.autoLoad": true,
  "trae.ai.codeIndex.enabled": true
}

---

十、整体分层思路

┌─────────────────────────────────────┐
│ project_rules.md / user_rules.md    ← 行为建议      │
├─────────────────────────────────────┤
│ settings.json                       ← 客户端强制    │
├─────────────────────────────────────┤
│ agents/                             ← 上下文隔离   │
├─────────────────────────────────────┤
│ skills                              ← 可复用工作流  │
├─────────────────────────────────────┤
│ mcp.json                            ← 外部能力扩展  │
└─────────────────────────────────────┘

---

十一、写在最后

Trae 的 .trae/ 目录本质上是把团队的"集体记忆"沉淀为可复用的配置资产。配置做好之后，你会发现 Trae 和团队成员的感觉越来越像——它知道什么该做、什么不能做，遇到特定任务能自动套用正确的工作流。

刚开始可以从简单规则（如命名规范）入手，逐步添加复杂约束。记住：好的配置不是一次性设置完成的，而是随着开发习惯和项目需求不断迭代优化的"AI 训练手册"。

Trae 作为字节跳动推出的 AI 编程工具，正在快速迭代。虽然具体的字段名和语法可能会变，但背后的思路和框架是通用的——理解这些，才能真正用好这个工具。