> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 规则与 AGENTS.md

> 提供始终生效的指示和上下文，在每次会话中引导 Agent

规则是持续生效的指示，用于规定 Devin CLI 在你的项目中的行为方式。它们会在每次会话开始时注入到 Agent 的上下文中，确保整个团队的行为保持一致。

规则的常见用途包括编码标准、架构指南、偏好的库、测试规范以及项目特有的约束。

**为了提升编码能力、加快完成速度并降低成本**，我们强烈建议**在可能的情况下优先使用 Skills**。Skills 只有在相关时才会注入上下文。**Rules 和 AGENTS 应尽可能保持精简。**

**我们推荐的做法**是使用规则来引用模型应在特定场景下使用的 Skills。

***

<div id="agentsmd">
  ## AGENTS.md
</div>

添加规则最简单的方法，是在项目根目录中使用一个 `AGENTS.md` 文件：

```markdown theme={null}
# Project Rules

- Use TypeScript for all new files
- Follow the existing patterns in src/components/
- Always run `npm run lint` before committing
- Use pnpm, not npm or yarn
- Write tests for all new utility functions
```

Devin CLI 会自动读取此文件。

<Tip>
  `AGENTS.md` 是管理项目规则的推荐做法。它易于阅读、支持版本控制，并且适用于多种 AI 工具。
</Tip>

***

<div id="global-rules">
  ## 全局规则
</div>

你也可以在用户配置目录中放置一个 `AGENTS.md` 文件，创建适用于**所有项目**的规则：

<Tabs>
  <Tab title="Linux / macOS">
    ```
    ~/.config/devin/AGENTS.md
    ```
  </Tab>

  <Tab title="Windows">
    ```
    %APPDATA%\devin\AGENTS.md
    ```
  </Tab>
</Tabs>

全局规则会在每次会话开始时加载，无论你当前在处理哪个项目。你可以用它们来设置在所有地方都生效的个人偏好：

```markdown theme={null}
# My Global Rules

- Always write commit messages in conventional commit format
- Prefer functional patterns over imperative code
- Run tests before suggesting a task is complete
```

全局规则与项目规则会同时生效——两者会一并加载。此位置也支持 `AGENT.md`。

<Tip>
  如果你使用 Claude Code，Devin CLI 也会将 `~/.claude/CLAUDE.md` 作为全局规则读取。
</Tip>

***

<div id="personal-rules-with-agentslocalmd">
  ## 使用 AGENTS.local.md 设置个人规则
</div>

如果你有一些不应与协作者共享的个人指示——例如你偏好的工作方式、测试习惯或代码评审偏好——请在你的 `AGENTS.md` 旁边创建一个 `AGENTS.local.md` 文件：

```markdown theme={null}
# 我的个人规则

- 始终先编写失败的测试，再实现修复
- 优先使用函数式模式，而非命令式代码
- 将任务标记为完成前，运行完整的测试套件
```

该文件会与 `AGENTS.md` 一同加载，并具有相同的始终生效特性。请将它添加到你的 `.gitignore` 中，以便仅保留在本地：

```gitignore theme={null}
AGENTS.local.md
```

<Tip>
  这与 `.devin/config.local.json` 遵循相同的约定——`.local.` 后缀表示这是个人覆盖配置，不应提交。
</Tip>

***

<div id="supported-file-names">
  ## 支持的文件名
</div>

Devin CLI 会从以下任一文件中读取规则：

| 文件 | 说明 |
| - | - |
| `AGENTS.md` | 推荐 |
| `AGENTS.local.md` | 个人规则 (已加入 gitignore) |
| `AGENT.md` | 单数形式的替代名称 |
| `.windsurfrules` | Legacy Windsurf 工作区规则 |
| `CLAUDE.md` | 兼容 Claude Code |

这些文件都会被一视同仁地处理——其内容都会作为始终生效的规则加载。

这些文件可以位于项目中的多个层级 (不只是根目录) 。工作区根目录中的文件会在会话开始时加载。子目录中的文件则会在 Agent 访问该目录中的文件时按需发现，从而让上下文聚焦于代码库中相关的部分。

你也可以将这些文件放在[全局配置目录](#global-rules)中，使其对所有项目生效，但 `CLAUDE.md` 除外；它会从 `~/.claude/CLAUDE.md` 全局读取。

已安装的[插件](/zh/cli/extensibility/plugins/overview)也可以附带规则：插件根目录中有一个始终生效的 `AGENTS.md`，以及带有 `trigger` frontmatter 的 `rules/*.md` 文件。

***

<div id="rules-in-the-devin-directory">
  ## `.devin` 目录中的 规则
</div>

Devin CLI 还会从 `.devin/` 目录读取规则，每个文件定义一条规则：

| 路径 | 说明 |
| - | - |
| `.devin/rules/*.md` | 每个文件定义一条规则。支持 `trigger` frontmatter |
| `.devin/global_rules.md` | 单个始终生效的文件 |

这些文件使用与 `.windsurf/rules/*.md` 相同的 frontmatter，因此 `trigger` 的 `always_on`、`manual`、`model_decision`、`agent` 和 `glob` 值同样适用。

`.devin/` 是首选位置，其优先级高于 `.windsurf/`。如果 `.devin/global_rules.md` 和 `.windsurf/global_rules.md` 同时存在，Devin CLI 仅加载 `.devin/global_rules.md`。`.devin/rules/` 和 `.windsurf/rules/` 中的规则文件都会被加载。

与其他项目规则一样，系统会在工作区根目录，以及工作区根目录与当前目录之间的每个目录中读取这些目录。你也可以将它们放在主目录中 (`~/.devin/rules/*.md`、`~/.devin/global_rules.md`) ，以便将其应用于每个项目。

***

<div id="rules-from-other-tools">
  ## 来自其他工具的规则
</div>

如果你是从其他 AI 编码工具迁移过来的，Devin CLI 可以读取你现有的规则：

<AccordionGroup>
  <Accordion title="Cursor">
    Devin CLI 会读取 `.cursor/rules/*.md` 和 `.cursor/rules/*.mdc`。

    Cursor 规则支持使用 frontmatter 控制激活方式：

    ```markdown theme={null}
    ---
    description: "React component guidelines"
    globs: "src/components/**/*.tsx"
    alwaysApply: false
    ---

    Use functional components with hooks. Never use class components.
    ```

    **激活行为：**

    * `alwaysApply: true` — 始终激活
    * 指定了 `globs` — 处理匹配文件时激活
    * 只有 `description` — 由 Agent 决定何时应用
    * 以上都不满足 — 用户必须手动调用
  </Accordion>

  <Accordion title="Windsurf">
    Devin CLI 会读取 `.windsurf/rules/*.md` 和 `.windsurf/global_rules.md`。Devin 原生的 [`.devin/` 对应规则](#rules-in-the-devin-directory)具有更高优先级。

    **子目录支持：** `.windsurf/rules/` 目录可以存在于项目中的多个层级，而不只是在根目录。工作区根目录中的规则会在会话开始时加载。子目录中的规则会被延迟发现——当 Agent 访问该目录中的文件时，会自动加载在那里找到的任何 `.windsurf/rules/` (以及父目录中直到工作区根目录的 `.windsurf/rules/`) 。这样可以避免项目中无关部分的规则污染 Agent 的上下文。

    Windsurf 规则支持 frontmatter：

    ```markdown theme={null}
    ---
    description: "API design rules"
    trigger: always_on
    ---

    All API endpoints must return JSON with a consistent envelope format.
    ```

    **触发器值：** `always_on`, `manual`, `model_decision`, `agent`, `glob`
  </Accordion>

  <Accordion title="Claude Code">
    Devin CLI 会读取 `.claude/` 目录。
  </Accordion>
</AccordionGroup>

<Warning>
  Devin CLI 不支持 `.codeiumignore` 文件。如果你使用 Codeium 的自动补全功能，并且已配置忽略模式，这些模式将不会对 Devin CLI 生效。
</Warning>

***

<div id="controlling-imports">
  ## 控制导入
</div>

你可以在配置文件 (`~/.config/devin/config.json`，或 Windows 上的 `%APPDATA%\devin\config.json`，或 `.devin/config.json`) 中启用或禁用读取特定工具格式的功能：

```json theme={null}
{
  "read_config_from": {
    "agents_standard": true,
    "cursor": true,
    "windsurf": true,
    "claude": true
  }
}
```

默认会读取 `AGENTS.md`、`AGENTS.local.md`、`AGENT.md` 和 `.windsurfrules` 中的标准项目规则。如需禁用导入这些规则，请设置 `"agents_standard": false`。

***

<div id="rule-activation-types">
  ## 规则激活类型
</div>

从外部格式加载的规则可能具有不同的激活方式：

| 类型 | 行为 |
| - | - |
| **始终生效** | 在每个会话中都处于激活状态，无需用户操作 |
| **Glob 激活** | 当 Agent 处理与特定模式匹配的文件时激活 |
| **Agent 决定** | Agent 根据规则的描述来决定何时应用 |
| **用户可调用** | 仅在用户明确触发时才会激活 |

来自 `AGENTS.md` 的规则始终为“始终生效”。

***

<div id="best-practices">
  ## 最佳实践
</div>

<CardGroup cols={2}>
  <Card title="保持规则简洁" icon="compress">
    冗长的规则会分散 Agent 的注意力。只聚焦最重要的内容。
  </Card>

  <Card title="具体明确" icon="bullseye">
    “使用 pnpm”比“使用合适的包管理器”更好。具体的指示更容易遵循。
  </Card>

  <Card title="包含示例" icon="code">
    展示你想要的模式，而不只是描述它。
  </Card>

  <Card title="纳入版本控制" icon="code-branch">
    将规则保存在你的 repo 中，这样整个团队都能遵循同一套准则。
  </Card>
</CardGroup>

<Note>
  对于大多数常见类型的规则，建议改用 skills。skills 能让你更灵活地控制它们何时以及如何生效。
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.