learnwy/trae-rules-writer

Trae 规则编写器

创建解决具体问题的规则——而非泛化规则。分析项目的结构和约定，然后设计一条约束 AI 行为的规则。始终在生成文件前通过 AskUserQuestion 与用户确认。

核心原则：先理解问题，再分析项目，第三步设计规则，仅在用户确认后生成。

适用场景

适合调用：

• 用户说"创建一条规则"、"为……创建规则"、"设置代码风格"
• 用户说"让 AI 始终……"、"强制命名约定"、"配置 AI 行为"
• 用户引用了 .trae/rules/... 或使用 #RuleName 语法
• 用户想为特定项目或文件模式约束 AI 行为

不适合调用：

• 用户想创建技能 → 转交 project-skill-writer
• 用户想创建智能体 → 转交 project-agent-writer
• 用户想安装现有技能 → 转交 project-skill-installer
• 用户询问 Trae 规则文档（直接回答，无需生成）

前置条件

• Node.js >= 18
• Trae IDE（支持 .trae/rules/）

工作流

[L1: 问题理解]
       ↓
[L2: 项目分析]  ← 并行子智能体
       ↓
[L3: 规则设计]
       ↓
[L4: 确认]  ← AskUserQuestion（必须确认）
       ↓
[L5: 生成 & 验证]

L1：问题理解

提取用户需要什么——不要问"你想要什么规则？"而是从问题推断：

问题分类

| 问题模式 | 规则类型 | 应用模式 | 示例 | |---------|---------|---------|------| | "AI 总用错误的命名" | 约定 | 文件特定（globs） | .ts 用 camelCase，.py 用 snake_case | | "AI 应该始终做 X" | 行为 | 始终应用（alwaysApply: true） | 始终使用项目的日志库 | | "AI 忽略我们的架构" | 结构 | 智能（description） | 强制分层架构边界 | | "AI 生成错误的导入" | 风格 | 文件特定（globs） | 在 .tsx 文件中使用 @/ 路径别名 | | "我想手动切换规则" | 手动 | 手动（#RuleName） | 临时代码审查清单 |

提取规则规格

从用户的问题中提取：

• 问题：AI 做错了什么（或应该开始做什么）
• 范围：规则适用于哪些文件或上下文
• 行为：AI 应该有什么不同的行为
• 例外：规则不应适用的情况

L2：项目分析

扫描项目以理解上下文。通过 Task 工具并行启动这些智能体：

| 智能体 | 用途 | 工具调用 | |-------|------|---------| | 项目扫描器 | 结构、现有规则、模式 | Task(subagent_type="search", query="...") | | 约定检测器 | 命名、风格和模式约定 | Task(subagent_type="search", query="...") |

检测目标

| 信号 | 查找内容 | 工具 | |------|---------|------| | 语言 | 文件扩展名（.ts、.py、.swift、.go） | Glob | | 框架 | package.json deps、Podfile、go.mod、Cargo.toml | Read | | 现有规则 | .trae/rules/*.md 文件及其 frontmatter | Glob + Read | | 代码风格 | ESLint、Prettier、EditorConfig、Ruff 配置 | Glob | | 命名模式 | 变量大小写、文件命名、目录结构 | Grep | | 架构 | 分层、模块边界、导入模式 | LS + Grep |

分析输出

项目：{name}
语言：{检测到的语言}
现有规则：{列出应用模式，或"无"}
代码风格工具：{检查器、格式化器}
约定：{命名、导入、架构模式}
冲突：{与提议规则重叠的现有规则}

L3：规则设计

基于问题（L1）+ 分析（L2），设计规则：

应用模式选择

参考应用模式和规则类型获取详细指导。

| 模式 | 适用场景 | Frontmatter | |------|---------|-------------| | 始终应用 | 规则适用于每次 AI 交互 | alwaysApply: true | | 文件特定 | 规则仅适用于特定文件类型 | globs: *.tsx,*.ts + alwaysApply: false | | 智能 | AI 根据描述判断规则是否相关 | description: "..." + alwaysApply: false | | 手动 | 用户通过 #RuleName 显式调用 | 无 frontmatter，使用 #RuleName |

设计规格

规则：{name}
问题：{用户原话描述的问题}
应用模式：{始终应用|文件特定|智能|手动}
范围：{哪些文件/上下文}

内容摘要：
- {约束 1}
- {约束 2}

Frontmatter：
  description: {此规则何时应用}
  globs: {文件模式，如适用}
  alwaysApply: {true|false}

要创建的文件：
  - .trae/rules/{rule-name}.md

设计原则

1. 单一问题 — 一条规则 = 解决一个问题
2. 遵循约定 — 使用项目现有的风格工具作为事实来源
3. 最小范围 — 将规则应用到覆盖问题的最窄文件集
4. 无冲突 — 验证新规则不与现有规则矛盾

关键格式规则

| 错误写法 | 正确写法 | |---------|---------| | globs: "*.ts" | globs: *.ts,*.tsx | | globs: ["*.ts"] | globs: *.ts | | /Users/.../src/ | src/ | | 缺少 description | 始终包含 description | | alwaysApply: true 和 globs: 同时激活 | 只用其一 |

L4：确认（必须使用 AskUserQuestion）

关键：在生成任何文件之前，通过 AskUserQuestion 展示设计。

AskUserQuestion 调用

使用 AskUserQuestion：

{
  "questions": [{
    "question": "我已根据您的项目设计了此规则。是否创建？",
    "header": "规则",
    "multiSelect": false,
    "options": [
      {
        "label": "创建 {rule-name}（推荐）",
        "description": "{应用模式}规则 — {1 句话行为描述}。输出：.trae/rules/{rule-name}.md"
      },
      {
        "label": "调整设计",
        "description": "在生成前让我调整规则设计"
      },
      {
        "label": "跳过",
        "description": "暂不创建规则"
      }
    ]
  }]
}

规则：

• 始终展示设计的规则名称和应用模式
• 包含输出路径以便用户知道文件位置
• 如果多种应用模式有效，提供备选：

{
  "questions": [{
    "question": "此规则可以用不同模式运行。哪种最合适？",
    "header": "应用模式",
    "multiSelect": false,
    "options": [
      {
        "label": "始终启用规则（推荐）",
        "description": "alwaysApply: true — 在每次 AI 交互中生效"
      },
      {
        "label": "文件特定规则",
        "description": "globs: *.tsx — 仅当匹配文件参与时生效"
      },
      {
        "label": "跳过",
        "description": "暂不创建规则"
      }
    ]
  }]
}

• 绝不在用户确认前生成文件
• 如果用户说"调整设计"，回到 L3 并纳入反馈

L5：生成 & 验证

用户确认后：

生成

1. 确定输出路径：目标项目根目录的 .trae/rules/
2. 使用 scripts/cli.cjs init 或 rule.md.template 创建规则文件
3. 从 L3 设计填入 frontmatter（description、globs、alwaysApply）
4. 编写规则内容——可操作的约束，而非模糊的指南
5. 确保规则内容中所有路径为项目相对路径，绝不使用绝对路径

生成命令

node scripts/cli.cjs init \
  --skill-dir <this-skill-dir> \
  --name <rule-name> \
  --description "<when-this-rule-applies>" \
  --output-dir <project>/.trae/rules/

回退方案：如果 cli.cjs init 失败或模板不适用，直接按模板结构编写 .md 文件。

验证

对生成的规则运行质量验证器。

交付前的最低检查：

• [ ] globs 格式：逗号分隔，无引号，无数组
• [ ] 规则中无绝对路径
• [ ] description 存在且描述了规则何时应用
• [ ] alwaysApply 和 globs 不同时激活
• [ ] 不与现有规则冲突（来自 L2 分析）
• [ ] 规则内容可操作（具体约束，非模糊建议）
• [ ] 内容使用英文

交付报告

创建的规则：
  名称：{rule-name}
  模式：{始终应用|文件特定|智能|手动}
  路径：{项目相对路径}

Frontmatter：
  description: {value}
  globs: {value, 如适用}
  alwaysApply: {value}

使用方式：{基于应用模式的说明}

错误处理

| 问题 | 解决方案 | |------|---------| | 用户的问题太模糊 | 从上下文推断最可能的规则类型，在 L4 确认 | | 多种有效的应用模式 | 在 AskUserQuestion 中展示备选，让用户选择 | | 不存在 .trae/rules/ 目录 | 在项目根目录创建 .trae/rules/ | | 用户请求创建技能/智能体 | 转路由到 project-skill-writer 或 project-agent-writer | | 用户在 L4 说"调整设计" | 回到 L3，纳入反馈 | | 规则包含绝对路径 | 拒绝，转换为项目相对路径 | | 规则与现有规则冲突 | 展示对比，询问用户是合并、替换还是重命名 | | globs 格式错误 | 自动修复：去除引号，展平数组，使用逗号分隔 | | 项目无可检测的约定 | 回退到语言默认值，在交付报告中注明假设 |

边界约束

此技能仅处理：

• 分析项目以获取规则设计上下文
• 基于用户问题设计规则
• 通过 AskUserQuestion 确认设计
• 将 .trae/rules/*.md 文件生成到项目相对路径
• 针对质量门禁验证生成的规则

此技能不处理：

• 创建技能 → project-skill-writer
• 创建智能体 → project-agent-writer
• 安装技能 → project-skill-installer
• 全局规则安装（始终限定在项目范围）
• 编辑 Trae IDE 设置或配置文件

智能体

• 项目扫描器：结构、现有规则和模式分析
• 约定检测器：命名、风格和约定提取
• 质量验证器：生成后规则验证

参考文档

• 规则类型：根据问题选择规则类型
• 应用模式：所有模式示例及 frontmatter
• 规则模板：新规则脚手架
• Trae 规则文档：官方文档快照