> ## 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.
# Rules & AGENTS.md
> Provide always-on instructions and context that guide the agent in every session
Rules are persistent instructions that shape how Devin CLI behaves in your project. They're injected into the agent's context at the start of every session, ensuring consistent behavior across your team.
Common uses for rules include coding standards, architectural guidelines, preferred libraries, testing conventions, and project-specific constraints.
**To improve coding ability, speed of completion, and lower cost**, we highly recommend **using Skills instead whenever possible**. Skills are only injected into the context when relevant. **Rules and AGENTS should be kept as small as possible.**
**Our recommended pattern** is to use a rule to reference skills that the model should use in particular scenarios.
***
## AGENTS.md
The simplest way to add rules is with an `AGENTS.md` file at your project root:
```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 reads this file automatically.
`AGENTS.md` is the recommended approach for project rules. It's easy to read, version-controlled, and works across multiple AI tools.
***
## Global Rules
You can also create rules that apply to **every project** by placing an `AGENTS.md` file in your user config directory:
```
~/.config/devin/AGENTS.md
```
```
%APPDATA%\devin\AGENTS.md
```
Global rules are loaded at the start of every session, regardless of which project you're working in. Use them for personal preferences that apply everywhere:
```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
```
Global rules work alongside project rules — both are loaded and active at the same time. `AGENT.md` is also supported at this location.
If you use Claude Code, Devin CLI also reads `~/.claude/CLAUDE.md` as a global rule.
***
## Supported File Names
Devin CLI reads rules from any of these files:
| File | Notes |
| ----------- | --------------------------- |
| `AGENTS.md` | Recommended |
| `AGENT.md` | Singular alternative |
| `CLAUDE.md` | Compatible with Claude Code |
All of these are treated identically — their contents are loaded as always-on rules.
These files can exist at multiple levels in your project (not just the root). Files at the workspace root are loaded at session start. Files in subdirectories are discovered lazily when the agent accesses files in that directory, keeping the context focused on the relevant part of the codebase.
They can also be placed in the [global config directory](#global-rules) to apply across all projects, except `CLAUDE.md` which is read globally from `~/.claude/CLAUDE.md`.
***
## Rules From Other Tools
If you're coming from another AI coding tool, Devin CLI can read your existing rules:
Devin CLI reads from `.cursorrules` and `.cursor/rules/*.md`.
Cursor rules support frontmatter to control activation:
```markdown theme={null}
---
description: "React component guidelines"
globs: "src/components/**/*.tsx"
alwaysApply: false
---
Use functional components with hooks. Never use class components.
```
**Activation behavior:**
* `alwaysApply: true` — Always active
* `globs` specified — Active when working with matching files
* `description` only — Agent decides when to apply
* None of the above — User must invoke manually
Devin CLI reads from `.windsurf/rules/*.md` and `.windsurf/global_rules.md`.
**Subdirectory support:** `.windsurf/rules/` directories can exist at multiple levels in your project, not just the root. Rules at the workspace root are loaded at session start. Rules in subdirectories are discovered lazily — when the agent accesses files in that directory, any `.windsurf/rules/` found there (and in parent directories up to the workspace root) are automatically loaded. This avoids polluting the agent's context with rules from unrelated parts of the project.
Windsurf rules support frontmatter:
```markdown theme={null}
---
description: "API design rules"
trigger: always_on
---
All API endpoints must return JSON with a consistent envelope format.
```
**Trigger values:** `always_on`, `manual`, `model_decision`, `agent`, `glob`
Devin CLI reads from the `.claude/` directory.
Devin CLI does not support `.codeiumignore` files. If you use Codeium's autocomplete and have configured ignore patterns, those patterns will not apply to Devin CLI.
***
## Controlling Imports
You can enable or disable reading from specific tool formats in your config file (`~/.config/devin/config.json` — or `%APPDATA%\devin\config.json` on Windows — or `.devin/config.json`):
```json theme={null}
{
"read_config_from": {
"cursor": true,
"windsurf": true,
"claude": true
}
}
```
`AGENTS.md` is always read and cannot be disabled.
***
## Rule Activation Types
Rules loaded from external formats may have different activation behaviors:
| Type | Behavior |
| ------------------ | ----------------------------------------------------------------- |
| **Always-on** | Active in every session, no user action needed |
| **Glob-activated** | Active when the agent works with files matching specific patterns |
| **Agent-decided** | The agent chooses when to apply based on the rule's description |
| **User-invocable** | Only active when explicitly triggered by the user |
Rules from `AGENTS.md` are always "always-on".
***
## Best Practices
Long, verbose rules dilute the agent's attention. Focus on what matters most.
"Use pnpm" is better than "use the right package manager". Concrete instructions are easier to follow.
Show the pattern you want, not just a description of it.
Keep rules in your repo so the whole team benefits from the same guidelines.
For most common types of rules, consider using skills instead. Skills give you more control over when and how they're applied.