AGENTS.md

AGENTS.md files provide a simple way to give Cascade context-aware instructions that automatically apply based on where the file is located in your project. This is particularly useful for providing directory-specific coding guidelines, architectural decisions, or project conventions.

How It Works

When you create an AGENTS.md file (or agents.md), Devin Desktop automatically discovers it and feeds it into the same Rules engine that powers .devin/rules/ (and the legacy .windsurf/rules/) — just with the activation mode inferred from the file’s location instead of frontmatter:

Root directory: Treated as an always-on rule — the full content is included in Cascade’s system prompt on every message.
Subdirectories: Treated as a glob rule with an auto-generated pattern of <directory>/** — the content is applied only when Cascade reads or edits files inside that directory.

This location-based scoping makes AGENTS.md ideal for providing targeted guidance without cluttering a single global configuration file.

Creating an AGENTS.md File

Simply create a file named AGENTS.md or agents.md in the desired directory. The file uses plain markdown with no special frontmatter required.

Example Structure

my-project/
├── AGENTS.md                    # Global instructions for the entire project
├── frontend/
│   ├── AGENTS.md                # Instructions specific to frontend code
│   └── src/
│       └── components/
│           └── AGENTS.md        # Instructions specific to components
├── backend/
│   └── AGENTS.md                # Instructions specific to backend code
└── docs/
    └── AGENTS.md                # Instructions for documentation

Example Content

Here’s an example AGENTS.md file for a React components directory:

# Component Guidelines

When working with components in this directory:

- Use functional components with hooks
- Follow the naming convention: ComponentName.tsx for components, useHookName.ts for hooks
- Each component should have a corresponding test file: ComponentName.test.tsx
- Use CSS modules for styling: ComponentName.module.css
- Export components as named exports, not default exports

## File Structure

Each component folder should contain:
- The main component file
- A test file
- A styles file (if needed)
- An index.ts for re-exports

Discovery and Scoping

Devin Desktop automatically discovers AGENTS.md files throughout your workspace:

Workspace scanning: All AGENTS.md files within your workspace and its subdirectories are discovered
Git repository support: For git repositories, Devin Desktop also searches parent directories up to the git root
Case insensitive: Both AGENTS.md and agents.md are recognized

Automatic Scoping

The key benefit of AGENTS.md is automatic scoping based on file location:

File Location	Scope
Workspace root	Applies to all files (always on)
`/frontend/`	Applies when working with files in `/frontend/**`
`/frontend/components/`	Applies when working with files in `/frontend/components/**`

This means you can have multiple AGENTS.md files at different levels, each providing increasingly specific guidance for their respective directories.

Best Practices

To get the most out of AGENTS.md files:

Keep instructions focused: Each AGENTS.md should contain instructions relevant to its directory’s purpose
Use clear formatting: Bullet points, headers, and code blocks make instructions easier for Cascade to follow
Be specific: Concrete examples and explicit conventions work better than vague guidelines
Avoid redundancy: Don’t repeat global instructions in subdirectory files; they inherit from parent directories

Content Guidelines

# Good Example
- Use TypeScript strict mode
- All API responses must include error handling
- Follow REST naming conventions for endpoints

# Less Effective Example
- Write good code
- Be careful with errors
- Use best practices

Comparison with Rules

While both AGENTS.md and Rules provide instructions to Cascade, they serve different purposes:

Feature	AGENTS.md	Rules
Location	In project directories	`.devin/rules/` (or legacy `.windsurf/rules/`) or global
Scoping	Automatic based on file location	Manual (glob, always on, model decision, manual)
Format	Plain markdown	Markdown with frontmatter
Best for	Directory-specific conventions	Cross-cutting concerns, complex activation logic

Use AGENTS.md when you want simple, location-based instructions. Use Rules when you need more control over when and how instructions are applied.

Devin Desktop

Agent Command Center

Releases

Windsurf Plugins

Accounts

Security

How It Works

Creating an AGENTS.md File

Example Structure

Example Content

Discovery and Scoping

Automatic Scoping

Best Practices

Content Guidelines

Comparison with Rules

​How It Works

​Creating an AGENTS.md File

​Example Structure

​Example Content

​Discovery and Scoping

​Automatic Scoping

​Best Practices

​Content Guidelines

​Comparison with Rules

How It Works

Creating an AGENTS.md File

Example Structure

Example Content

Discovery and Scoping

Automatic Scoping

Best Practices

Content Guidelines

Comparison with Rules