用Trae规则搞定API文档生成

适用平台：Trae IDE | 难度：零基础 | 阅读时间：约7分钟

前言

写 API 文档大概是后端开发者最不愿意做的事情之一。代码写完了，文档总是能拖就拖。如果你用 Trae IDE，其实只需要配一条 Rule（规则），就能让 AI 在你写完代码后自动生成标准格式的 API 文档。

和 WorkBuddy、Qoder 的 Skill 体系不同，Trae 的定制方式是 Rules（规则）——你通过 Markdown 文件告诉 AI 在什么场景下应该遵循什么规范。虽然不叫 Skill，但本质思路是一样的：把你的经验沉淀成 AI 能理解的指令。

Trae Rules 基础

Trae 的规则系统分两层：

个人规则（Global Rules）：全局生效，适用于你所有项目。在 Trae 设置界面的 "Rules" 面板中配置。

项目规则（Project Rules）：跟随项目，存放在 .trae/rules/ 目录下，可以和代码一起提交到 Git，实现团队共享。

每条规则都是一个 .md 文件，顶部有 YAML frontmatter 控制触发条件。

开始动手

我们要做的是：在项目根目录下创建一条规则，让 AI 在生成 API 文档时遵循统一格式。

第一步：创建规则目录

在你的项目根目录下：

mkdir -p .trae/rules

第二步：编写规则文件

创建 .trae/rules/api-docs.md，写入以下内容：

—
description: 当用户要求生成或更新 API 文档时，按此规则执行
alwaysApply: false
globs:
– "**/controllers/**"
– "**/routes/**"
– "**/api/**"
—

# API 文档生成规范

## 触发条件

当用户提到"生成 API 文档""更新接口文档""写接口说明"等意图时，执行本规则。

## 文档格式

每个 API 端点按以下模板输出：

[HTTP方法] /api/路径

功能说明：一句话描述这个接口做什么

请求参数：

请求示例： （给出 curl 命令示例）

响应示例： （给出 JSON 响应示例，包含成功和失败两种情况）

错误码：

## 执行要求

1. 从代码中自动提取路由定义、请求参数、响应结构。
2. 参数的类型和必填性从代码的校验逻辑中推断，不要瞎猜。
3. 响应示例要包含真实的数据结构，不要用 `…` 省略。
4. 如果代码中有 Swagger/OpenAPI 注解，优先以注解为准。
5. 输出为 Markdown 格式，存放到项目根目录的 `docs/api/` 下，按模块分文件。

## 风格约束

– 使用中文描述
– 保持简洁，不要加多余的解释性文字
– 路径中的变量用 `{}` 包裹，如 `/api/users/{id}`

第三步：理解触发机制

注意 frontmatter 中的三个关键字段：

description 描述了这条规则的用途，Trae 的 AI 会根据它来判断是否需要加载这条规则。

alwaysApply 设为 false，意味着这条规则不会始终生效，只在匹配时才触发。如果你设成 true，那每次对话 Trae 都会带上这条规则——适合代码风格之类的通用规则，但不适合我们这个场景。

globs 定义了文件匹配模式。当你打开或编辑 controllers/、routes/、api/ 目录下的文件时，Trae 会自动关联这条规则。

除了文件匹配自动触发，你还可以在对话中手动引用规则：输入 #api-docs 即可。

第四步：验证效果

在 Trae 中打开一个 controller 文件，然后在聊天框输入：

帮我把这个文件里的接口都生成文档

Trae 会自动加载你的规则，按照你定义的模板格式输出文档。

项目规则 vs 个人规则

什么时候用项目规则？当这个规范是团队共享的、和具体项目绑定的，比如 API 文档格式、代码风格、commit 规范。放在 .trae/rules/ 里提交到 Git，队友拉取代码后自动生效。

什么时候用个人规则？当你个人的偏好，比如"回答问题用中文""代码注释用英文""优先使用函数式写法"。这些跟项目无关，配在全局就好。

规则文件的组织技巧

如果你的规则越来越多，.trae/rules/ 下可以用子目录分组：

.trae/rules/
├── docs/
│ ├── api-docs.md
│ └── changelog.md
├── code-style/
│ ├── naming.md
│ └── error-handling.md
└── testing/
└── unit-test.md

Trae 会自动递归扫描子目录，所有 .md 规则文件都会被识别。

和其他平台的核心区别

Trae 的 Rules 和 WorkBuddy/Qoder 的 Skills 最大的区别在于：Rules 更偏"约束和规范"，是附加在 AI 对话上的上下文；而 Skills 更偏"流程和执行"，定义了完整的任务步骤。

如果你要做的事情是"在特定场景下遵守特定规范"（比如代码风格、文档格式），Trae Rules 完全够用。如果你需要"让 AI 按一套流程自动执行多步任务"，可能更适合用 Skill 体系。

小结

Trae 的 Rule 系统胜在轻量——一个 .md 文件就是一条规则，三个 frontmatter 字段控制触发条件，学习成本几乎为零。对于"API 文档生成"这类需要统一格式的场景，配一条规则比重复叮嘱 AI 高效得多。建议你从自己最常重复的需求开始，逐步积累规则库。

⭐免费体验渠道

想免费体验也可以前往魔芋AI官网https://www.moyu.info/register?aff=uZut注册，即可领取免费额度，先跑起来再决定要不要升级。