trae-rules-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Trae Rules Writer

Trae规则编写器

Create Trae IDE rules by analyzing project conventions first, then designing rules that match existing patterns.

先分析项目规范，再设计匹配现有模式的Trae IDE规则。

Workflow

工作流程

0. SIZE CHECK → Is project too large? If yes, ask user to specify folders
1. ANALYZE    → Scan project structure (spawn Project Scanner Agent for deep analysis)
2. IDENTIFY   → Extract conventions (spawn Convention Detector Agent)
3. DESIGN     → Choose rule type and application mode based on needs
4. CREATE     → Write rules in Trae's official format
5. VALIDATE   → Ensure no conflicts (spawn Quality Validator Agent)
6. VERIFY     → Check syntax and test rule activation
7. REFRESH    → Start new chat for rules to take effect

0. 规模检查 → 项目是否过大？如果是，请求用户指定文件夹
1. 分析 → 扫描项目结构（启动Project Scanner Agent进行深度分析）
2. 识别 → 提取规范（启动Convention Detector Agent）
3. 设计 → 根据需求选择规则类型和应用模式
4. 创建 → 按照Trae的官方格式编写规则
5. 验证 → 确保无冲突（启动Quality Validator Agent）
6. 核验 → 检查语法并测试规则激活
7. 刷新 → 开启新对话使规则生效

Agent-Enhanced Analysis

代理增强分析

For deeper project analysis, spawn specialized agents:

Stage	Agent	When to Use
ANALYZE	Project Scanner	Large/unfamiliar projects
IDENTIFY	Convention Detector	Extract naming/style conventions
VALIDATE	Quality Validator	Comprehensive rule validation

How to use:

Spawn agent with Task tool:
- Agent: agents/convention-detector.md
- Input: {project_path: "/path/to/project", file_types: ["*.ts", "*.tsx"], output_path: "/tmp/conventions"}
- Wait for structured JSON output with suggested_rules
- Use suggested rules as starting point

如需更深入的项目分析，可启动专用代理：

阶段	代理	适用场景
分析	Project Scanner	大型/不熟悉的项目
识别	Convention Detector	提取命名/风格规范
验证	Quality Validator	全面规则验证

使用方法：

通过Task工具启动代理：
- Agent: agents/convention-detector.md
- Input: {project_path: "/path/to/project", file_types: ["*.ts", "*.tsx"], output_path: "/tmp/conventions"}
- 等待结构化JSON输出，其中包含suggested_rules
- 将建议规则作为编写起点

Large Project Handling

大型项目处理

Before analyzing, check project size. If the project is too large (many folders, monorepo, >50 top-level items):

STOP - Do not attempt to analyze the entire project
INFORM - Tell user the project is too large for comprehensive analysis
ASK - Use
```
AskUserQuestion
```
to request target folders:
- "Which folders should I focus on for creating rules?"
- "Please provide 1-3 specific directories (e.g.,
```
src/components/
```
  ,
```
lib/utils/
```
  )"
SCOPE - Only create rules for the user-specified folders

Example response for large projects:

This project appears to be large (I see 20+ top-level directories).
To create focused, useful rules, please specify which folders I should analyze:
- Which directories contain your main application code?
- Any specific areas where you want AI guidance?

Example: "Focus on src/features/ and src/shared/"

Indicators of "too large":

Monorepo with multiple packages
50 files/folders at root level
Multiple independent modules or services
No clear single entry point

分析前先检查项目规模。如果项目过大（包含大量文件夹、单体仓库、根目录下有超过50个条目）：

停止 - 不要尝试分析整个项目
告知 - 告知用户项目过大，无法进行全面分析
询问 - 使用
```
AskUserQuestion
```
工具请求用户指定目标文件夹：
- "我应该重点分析哪些文件夹来创建规则？"
- "请提供1-3个具体目录（例如：
```
src/components/
```
  ,
```
lib/utils/
```
  ）"
限定范围 - 仅为用户指定的文件夹创建规则

大型项目示例回复：

该项目看起来规模较大（我发现有20+个顶级目录）。
为了创建精准实用的规则，请指定我需要分析的文件夹：
- 哪些目录包含您的主应用代码？
- 您希望在哪些特定区域获得AI指导？

示例："重点分析src/features/ 和 src/shared/"

“过大”的判断指标：

包含多个包的单体仓库
根目录下有超过50个文件/文件夹
包含多个独立模块或服务
没有明确的单一入口点

User Interaction Guidelines

用户交互指南

When to ask user for clarification:

Project scope is unclear (large project, monorepo)
Multiple valid rule types are possible
User's intent is ambiguous (always apply vs file-specific)
Choosing between user rules vs project rules

Use
AskUserQuestion
tool with options like:

Question: "What application mode should this rule use?"
Options:
- "Always Apply" - Active for all AI chats in project
- "File-Specific" - Only for certain file types (e.g., *.ts)
- "Apply Intelligently" - AI determines when relevant
- "Manual Only" - Only when explicitly invoked with #RuleName

需要向用户澄清的场景：

项目范围不明确（大型项目、单体仓库）
存在多种有效的规则类型
用户意图模糊（全局应用 vs 特定文件应用）
难以选择用户规则还是项目规则

使用
AskUserQuestion
工具并提供选项，例如：

问题："此规则应使用哪种应用模式？"
选项：
- "全局应用" - 在项目的所有AI对话中生效
- "特定文件" - 仅适用于特定文件类型（例如：*.ts）
- "智能应用" - 由AI判断何时相关
- "手动触发" - 仅在使用#RuleName明确调用时生效

Path Conventions

路径规范

NEVER use absolute paths in generated rules. Use relative paths or placeholders:

Bad ❌	Good ✅
`/Users/john/project/src/`	`src/` or `{project_root}/src/`
`/home/dev/repo/.trae/rules/`	`.trae/rules/`
`~/Documents/code/lib/`	`lib/` or `{git_root}/lib/`

Path placeholders:

```
{project_root}
```
- Current project root directory
```
{git_root}
```
- Git repository root
Relative paths like
```
./
```
,
```
../
```
,
```
src/
```

Why: Rules are shared across team members with different usernames, clone paths, and environments. Absolute paths break portability.

生成的规则中绝对不要使用绝对路径，请使用相对路径或占位符：

错误示例 ❌	正确示例 ✅
`/Users/john/project/src/`	`src/` 或 `{project_root}/src/`
`/home/dev/repo/.trae/rules/`	`.trae/rules/`
`~/Documents/code/lib/`	`lib/` 或 `{git_root}/lib/`

路径占位符：

```
{project_root}
```
- 当前项目根目录
```
{git_root}
```
- Git仓库根目录
相对路径如
```
./
```
,
```
../
```
,
```
src/
```

原因： 规则会在团队成员间共享，而成员的用户名、克隆路径和环境各不相同。绝对路径会破坏可移植性。

Rule Creation Methods

规则创建方法

Method 1: Direct File Creation (Recommended)

方法1：直接创建文件（推荐）

Create

.trae/rules/<rule-name>.md

files directly in the project.

在项目中直接创建

.trae/rules/<rule-name>.md

文件。

Method 2: UI Creation (Alternative)

方法2：通过UI创建（备选）

Use Trae IDE interface:

User Rules: Settings > Rules & Skills > User Rules > "+ Create"
Project Rules: Settings > Rules & Skills > Project Rules > "+ Create"

使用Trae IDE界面：

用户规则：设置 > 规则与技能 > 用户规则 > " + 创建"
项目规则：设置 > 规则与技能 > 项目规则 > " + 创建"

Rule Format

规则格式

markdown

---
description: Use cases for intelligent mode
globs: *.ts,*.tsx
alwaysApply: false
---

markdown

---
description: 智能模式的适用场景
globs: *.ts,*.tsx
alwaysApply: false
---

Rule Title

规则标题

Concise guidance for AI.


**Frontmatter Properties:**
- `alwaysApply`: Set to `true` for rules effective in all project chats
- `globs`: File patterns for specific files mode (e.g., `*.ts,*.tsx`) - comma-separated, no quotes
- `description`: Use cases for intelligent mode (AI determines relevance)

**Note on frontmatter format:** Use YAML frontmatter with exactly these keys. All properties are optional - omitting `alwaysApply` defaults to `false` (manual invocation only).

**Important:** `globs` format is comma-separated without quotes: `globs: *.ts,*.tsx` (NOT `globs: "*.ts,*.tsx"`)

给AI的简洁指导说明。


**前置属性：**
- `alwaysApply`: 设置为`true`时，规则在项目的所有AI对话中生效
- `globs`: 特定文件模式（例如：`*.ts,*.tsx`），使用逗号分隔，无需引号
- `description`: 智能模式的适用场景（由AI判断相关性）

**前置格式注意事项：** 使用YAML前置格式，且仅包含上述键。所有属性均为可选 - 省略`alwaysApply`默认值为`false`（仅手动触发）。

**重要提示：** `globs`格式为无引号的逗号分隔：`globs: *.ts,*.tsx`（不要写成`globs: "*.ts,*.tsx"`）

Application Modes

应用模式

Mode	Frontmatter	Use Case
Always Apply	`alwaysApply: true`	Effective for all AI chats in project
File-Specific	`globs: .tsx,.jsx`	Only when matching files specified
Apply Intelligently	`description: "When doing X..."`	AI determines relevance in chat
Manual Only	(no frontmatter)	Invoke with `#RuleName` only

模式	前置配置	适用场景
全局应用	`alwaysApply: true`	在项目的所有AI对话中生效
特定文件	`globs: .tsx,.jsx`	仅适用于指定的匹配文件
智能应用	`description: "执行X操作时..."`	由AI判断对话中的相关性
手动触发	（无前置配置）	仅通过 `#RuleName` 调用生效

Rule Types

规则类型

Type	Location	Scope
User Rules	Settings > Rules & Skills > User Rules	Customized for AI based on personal habits, all projects
Project Rules	`.trae/rules/*.md`	Must be followed for current project only

类型	位置	范围
用户规则	设置 > 规则与技能 > 用户规则	根据个人习惯为AI定制，适用于所有项目
项目规则	`.trae/rules/*.md`	仅当前项目必须遵循

Compatible Files

兼容文件

File	Description
`AGENTS.md`	Reusable across IDEs
`CLAUDE.md`	Compatible with Claude Code
`CLAUDE.local.md`	Local-only, gitignored

文件	描述
`AGENTS.md`	可在多IDE间复用
`CLAUDE.md`	兼容Claude Code
`CLAUDE.local.md`	仅本地使用，会被Git忽略

Example

示例

User: "Create rules for this TypeScript React project"

Analysis:
- Structure: src/components/, src/hooks/
- Naming: PascalCase components, camelCase functions
- No existing .trae/rules/

Creating: .trae/rules/

📄 code-style.md
---
alwaysApply: true
---

用户: "为这个TypeScript React项目创建规则"

分析结果:
- 结构: src/components/, src/hooks/
- 命名规范: 组件使用PascalCase，函数使用camelCase
- 无现有.trae/rules/目录

创建文件: .trae/rules/

📄 code-style.md
---
alwaysApply: true
---

Code Style

代码风格

PascalCase for components and types
camelCase for functions and variables

📄 react-patterns.md

globs: .tsx,.jsx

组件和类型使用PascalCase
函数和变量使用camelCase

📄 react-patterns.md

globs: .tsx,.jsx

React Patterns

React模式

Use functional components with hooks
Custom hooks go in src/hooks/

📄 file-organization.md

description: "When organizing project files or creating new components"

使用带Hooks的函数式组件
自定义Hooks放在src/hooks/目录下

📄 file-organization.md

description: "整理项目文件或创建新组件时"

File Organization

文件组织

Components in src/components/
Hooks in src/hooks/
Use relative imports: import Hook from '../hooks/Hook'

undefined

组件放在src/components/目录下
Hooks放在src/hooks/目录下
使用相对导入：import Hook from '../hooks/Hook'

undefined

Validation Checklist

验证检查表

After creating rules, verify:

Frontmatter Syntax: Valid YAML with correct keys
Globs Format: Comma-separated, no quotes (
```
globs: *.ts,*.tsx
```
)
No Conflicts: Rules don't contradict each other
Proper Granularity: Each rule is focused on one concern
Clear Guidance: AI can follow the instructions unambiguously
Application Mode: Correct mode for intended use case

创建规则后，请核验以下内容：

前置语法: 有效的YAML格式，包含正确的键
Globs格式: 逗号分隔，无引号（
```
globs: *.ts,*.tsx
```
）
无冲突: 规则之间不存在矛盾
粒度合理: 每个规则仅聚焦一个关注点
指导清晰: AI能够明确遵循指令
应用模式: 规则的应用模式符合预期使用场景

Testing Rules

规则测试

After creating rules:

Check syntax:
```
ls .trae/rules/*.md
```
Verify frontmatter: Ensure YAML is valid
Start new chat: Rules don't apply retroactively
Test activation: Use a prompt that should trigger the rule
Verify behavior: Check AI follows the rule

创建规则后：

检查语法:
```
ls .trae/rules/*.md
```
核验前置配置: 确保YAML格式有效
开启新对话: 规则不会追溯应用到之前的对话
测试激活: 使用应该触发规则的提示词
验证行为: 检查AI是否遵循规则

Import Settings

导入设置

Include AGENTS.md in context when working with agents
Include CLAUDE.md in context for Claude-specific guidance

处理代理时，将AGENTS.md纳入上下文
处理Claude专属指导时，将CLAUDE.md纳入上下文

Quick Reference

快速参考

Rule Type	When to Use	Example Frontmatter
Global convention	For all files in project	`alwaysApply: true`
Language-specific	Only for certain file types	`globs: .ts,.tsx`
Context-dependent	Only in specific situations	`description: "When refactoring"`
On-demand	Only when explicitly invoked	(no frontmatter)

规则类型	适用场景	前置配置示例
全局规范	适用于项目中的所有文件	`alwaysApply: true`
特定语言	仅适用于特定文件类型	`globs: .ts,.tsx`
上下文相关	仅在特定场景下适用	`description: "重构时"`
按需触发	仅在明确调用时生效	（无前置配置）

Debugging Tips

调试技巧

Rules not applying? Check if new chat was started (rules don't apply retroactively)
Rule not triggering? Verify frontmatter syntax and application mode
Conflicting rules? Review rule priority: User Rules > Project Rules > File-specific > Intelligent > Manual
Globs not matching? Ensure format is
```
globs: *.ts,*.tsx
```
(no quotes)

规则未生效？ 检查是否开启了新对话（规则不会追溯应用到之前的对话）
规则未触发？ 核验前置语法和应用模式
规则冲突？ 查看规则优先级：用户规则 > 项目规则 > 特定文件 > 智能应用 > 手动触发
Globs不匹配？ 确保格式为
```
globs: *.ts,*.tsx
```
（无引号）

Referencing Rules

规则引用

Always Apply rules display automatically in chat input box
Apply Manually rules are invoked using
```
#RuleName
```
syntax in chat
Example: "Using #security-guidelines, review this authentication code"

全局应用规则会自动显示在对话输入框中
手动触发规则通过在对话中使用
```
#RuleName
```
语法调用
示例："使用#security-guidelines，审核这段认证代码"

References

参考资料

Trae Rules Documentation - Official documentation
Application Mode Examples - Complete examples
Rule Template - Starter template
Rule Types Reference - Selecting appropriate rule types

Trae规则文档 - 官方文档
应用模式示例 - 完整示例
规则模板 - 起始模板
规则类型参考 - 选择合适的规则类型

Agents

代理

Project Scanner - Deep project structure analysis
Convention Detector - Extract naming/style conventions
Quality Validator - Rule validation

Project Scanner - 深度项目结构分析
Convention Detector - 提取命名/风格规范
Quality Validator - 规则验证