Rules & AGENTS.md - Devin Docs

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:

# 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:

Linux / macOS
Windows

~/.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:

# 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.

Personal Rules with AGENTS.local.md

If you have personal instructions that shouldn’t be shared with collaborators — such as preferred working style, testing habits, or review preferences — create an AGENTS.local.md file next to your AGENTS.md:

# My Personal Rules

- Always start by writing failing tests before implementing a fix
- Prefer functional patterns over imperative code
- Run the full test suite before marking a task as complete

This file is loaded alongside AGENTS.md with the same always-on behavior. Add it to your .gitignore so it stays local:

AGENTS.local.md

This follows the same convention as .devin/config.local.json — the .local. suffix signals a personal override that shouldn’t be committed.

Supported File Names

Devin CLI reads rules from any of these files:

File	Notes
`AGENTS.md`	Recommended
`AGENTS.local.md`	Personal rules (gitignored)
`AGENT.md`	Singular alternative
`.windsurfrules`	Legacy Windsurf workspace rules
`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 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:

Cursor

Devin CLI reads from .cursor/rules/*.md and .cursor/rules/*.mdc.Cursor rules support frontmatter to control activation:

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

Windsurf

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:

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

Claude Code

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):

{
  "read_config_from": {
    "agents_standard": true,
    "cursor": true,
    "windsurf": true,
    "claude": true
  }
}

Standard project rules from AGENTS.md, AGENTS.local.md, AGENT.md, and .windsurfrules are read by default. Set "agents_standard": false to disable importing them.

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

Keep rules concise

Long, verbose rules dilute the agent’s attention. Focus on what matters most.

Be specific

“Use pnpm” is better than “use the right package manager”. Concrete instructions are easier to follow.

Include examples

Show the pattern you want, not just a description of it.

Version control them

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.

​AGENTS.md

​Global Rules

​Personal Rules with AGENTS.local.md

​Supported File Names

​Rules From Other Tools

​Controlling Imports

​Rule Activation Types

​Best Practices

Keep rules concise

Be specific

Include examples

Version control them

AGENTS.md

Global Rules

Personal Rules with AGENTS.local.md

Supported File Names

Rules From Other Tools

Controlling Imports

Rule Activation Types

Best Practices