# 规则

> 规则是一个 Markdown 文件，在会话开始时或工作触及它所适用的文件时送达模型。规则存放在 .qwen/rules/ 中，而 paths: 字段使第二类场景成为可能：当你编辑 Makefile 时，关于 React 组件的指导不必出现在…

- 网址：https://funcoding.ai/agents/qwen-code/users/features/rules/
- 来源：Qwen Code 官方文档原文（中文），Apache-2.0 许可，同步于 2026-10-11
- 官方原文：https://qwenlm.github.io/qwen-code-docs/zh/users/features/rules

---
规则是一个 Markdown 文件，在会话开始时或工作触及它所适用的文件时送达模型。规则存放在 `.qwen/rules/` 中，而 `paths:` 字段使第二类场景成为可能：当你编辑 Makefile 时，关于 React 组件的指导不必出现在提示词中。

它们是上下文文件（`QWEN.md`）的低成本对等物，后者在每个会话的**每个**请求中都会被携带——参见[常驻上下文成本](https://funcoding.ai/agents/qwen-code/users/features/context-cost/)。

## 规则的存放位置

| 位置                                        | 加载时机                       |
| ------------------------------------------- | ------------------------------ |
| `~/.qwen/rules/`（或 `$QWEN_HOME/rules/`）  | 始终加载                       |
| `<project>/.qwen/rules/`                    | 工作区受信任时加载             |
| 活跃扩展的 `rules/`                         | 始终加载，仅限条件规则——见下文 |

这些目录下的每个 `.md` 文件都会被发现，包括子目录中的文件，发现顺序是确定性的。

## 基线规则与条件规则

```markdown
---
description: How we write React components
paths:
  - 'src/**/*.tsx'
  - 'src/**/*.jsx'
---

Components are function components. Co-locate the test beside the component.
Never reach for a global store for state one screen owns.
```

- **带有 `paths:`** —— _条件_规则。在工具调用读取或编辑匹配其 glob 之一的文件之前，它不会进入提示词；匹配后，它会被注入一次并在会话的剩余时间内保持生效。
- **不带 `paths:`** —— _基线_规则。从第一个请求起它就是系统提示词的一部分，与上下文文件完全相同，并且在每一轮都产生相同的开销。

两个字段都是可选的，完全没有 frontmatter 的规则即为基线规则。

值得了解的细节：

- Glob 相对于**项目根目录**的路径进行匹配，所有平台均使用正斜杠，并且会匹配 dotfile。
- 符号链接会被解析，因此无论工具调用使用的是链接还是真实路径，规则都会匹配。
- 条件规则在**每个会话中只注入一次**——第二个匹配的文件不会重复注入。
- HTML 注释在规则的正文发送之前会被剥离。

## 来自扩展的规则

扩展可以附带一个 `rules/` 目录，而**其规则必须是条件规则**：没有 `paths:` 的规则会被跳过，并在启动时输出警告指明该规则。这一限制正是其核心设计意图。扩展的上下文文件（`contextFileName`）会被拼接到该扩展活跃的每个会话的每个请求中，没有相关性门控——在某次实测会话中，九个扩展的上下文文件合计达到 9,989 个 token，占该会话所有始终开启上下文的 65%。基线扩展规则会完全重现这一问题，只是换了一种机制。

扩展规则在提示词中按其所有者标注——`charts:rules/charting.md`，而非一个攀出项目的路径——因此会话记录中可以清楚地看到是哪条规则被触发。

它们不受工作区信任的门控，这与项目规则不同：安装扩展本身已经是一个显式行为，并且同一个扩展可以提供 MCP server、命令、skill 以及一个无门控的上下文文件。如果对这个比上下文文件更窄、更廉价的唯一机制要求信任检查，只会把作者推回那个更昂贵的选项。

**如果你编写扩展**，以下是需要进行的迁移：

| 内容                                                                | 放置位置                                       |
| ------------------------------------------------------------------- | ---------------------------------------------- |
| 始终为真的事实——扩展的身份、其术语、一条硬性约束                     | 上下文文件                                     |
| "在处理 X 时，执行 Y"                                               | 一个 `paths:` 门控的规则，或一个 [skill](https://funcoding.ai/agents/qwen-code/users/features/skills/) |
| 模型按需运行的一个过程                                               | 一个 [skill](https://funcoding.ai/agents/qwen-code/users/features/skills/)                        |

## 规则、skill 与上下文文件

|                             | 从一开始就在提示词中         | 按需加载                          |
| --------------------------- | ---------------------------- | --------------------------------- |
| 上下文文件（`QWEN.md`）     | 始终，完整包含               | —                                 |
| 基线规则                    | 始终，完整包含               | —                                 |
| 条件规则（`paths:`）        | 无内容                       | 当匹配的文件被触及时加载          |
| Skill                       | 仅名称 + 描述                | 正文，当模型调用它时加载          |

Skill 是模型选择遵循的过程的正确归宿；条件规则是适用于代码库某一区域的约束的正确归宿，无论模型是否想到去查找它。Skill 也可以[基于 `paths:` 进行门控](https://funcoding.ai/agents/qwen-code/users/features/skills/#optional-gate-a-skill-on-file-paths-paths)，这使得它们的列表条目在相关之前都不会出现在提示词中。

## 另见

- [常驻上下文成本](https://funcoding.ai/agents/qwen-code/users/features/context-cost/) —— 如何衡量你的前缀开销，以及其他可用的调节手段。
- [Skill](https://funcoding.ai/agents/qwen-code/users/features/skills/)
- [Memory](https://funcoding.ai/agents/qwen-code/users/features/memory/)