> ## 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` 全局读取。

***

<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`。

    **子目录支持：** `.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>