Skip to main content
Watch: I Built an AI App Without Leaving Databricks

Instruction files - verified

Which coding agent reads which instruction file

13 of 14 coding agents read AGENTS.md out of the box and Gemini CLI reads it once you name it in a setting. Most also keep a file of their own, which is where tool-specific rules belong.

Below, each tool's own file (the first one its docs list). Every value traces back to the doc that states it; for commands, flags and settings, see the CLI reference.

Tools
14
Read AGENTS.md
13
Import syntax
7
Rules directory
8

Support matrix

Yes links to the doc that says so and How opens the detail. Opt-in means the tool reads AGENTS.md only after you name it in a setting. Not stated means the docs do not say either way, and None documented means they name no such file or syntax. Scroll the table sideways on a small screen.

14 coding agents with the instruction files their docs say they read, whether they read AGENTS.md, their user-level file, nested files, import syntax and rules directory
ToolFiles it readsReads AGENTS.mdUser-level fileNested filesImportsRules directory
Claude Code
  • CLAUDE.md
  • .claude/CLAUDE.md
  • CLAUDE.local.md
  • AGENTS.md
  • .claude/AGENTS.md
Yes
How

Native, controlled by the Project instructions setting. Default value claude-md-or-agents-md reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it; claude-md-and-agents-md reads both (each directory's CLAUDE.md first, AGENTS.md after). Set via /config or pluginConfigs under cc-plugin-agents-md@builtin (option instructionFiles). Requires v2.1.277 or later; where unavailable, put an @AGENTS.md import in a CLAUDE.md. AGENTS.local.md, AGENTS.override.md and anything under .agents/ are not read.

~/.claude/CLAUDE.mdYes@path/to/import.claude/rules/
OpenAI Codex CLI
  • AGENTS.md
  • AGENTS.override.md
Yes
How

Native default. In each directory Codex checks AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames (set in ~/.codex/config.toml), and includes at most one file per directory. Empty files are skipped and the combined size is capped by project_doc_max_bytes (32 KiB by default).

~/.codex/AGENTS.mdYesNone documentedNone documented
Gemini CLI
  • GEMINI.md
Opt-in
How

Not by default (default context file name is GEMINI.md). Documented via the context.fileName property in settings.json, which accepts a name or list of names, for example ["AGENTS.md", "CONTEXT.md", "GEMINI.md"].

~/.gemini/GEMINI.mdYes@file.mdNone documented
GitHub Copilot
  • .github/copilot-instructions.md
  • .github/instructions/**/*.instructions.md
  • AGENTS.md
  • CLAUDE.md
  • GEMINI.md
Yes
How

Native. Copilot cloud agent reads AGENTS.md (or a single CLAUDE.md or GEMINI.md at the repository root); VS Code Copilot sessions list .github/copilot-instructions.md or AGENTS.md as recommended project instructions. For the VS Code Local harness, chat.useAgentsMdFile toggles AGENTS.md support and chat.useNestedAgentsMdFiles (disabled by default) controls nested AGENTS.md files.

~/.copilot/copilot-instructions.mdYesNone documented.github/instructions
GitHub Copilot CLI
  • .github/copilot-instructions.md
  • .github/instructions/**/*.instructions.md
  • AGENTS.md
  • CLAUDE.md
  • .claude/CLAUDE.md
  • GEMINI.md
Yes
How

Native. AGENTS.md is discovered in the standard locations: the repository root, the current working directory, intermediate directories between them, and any directories nested in the path of a file it is working on. Directories listed in COPILOT_CUSTOM_INSTRUCTIONS_DIRS add more AGENTS.md and *.instructions.md files. The /instructions command shows discovered files and can enable or disable each one.

$HOME/.copilot/copilot-instructions.mdYes@ followed by a relative path.github/instructions
Cursor
  • .cursor/rules/*.mdc
  • AGENTS.md
  • CLAUDE.md
Yes
How

Native, no setting needed. AGENTS.md is a plain markdown alternative to .cursor/rules, supported in the project root and in subdirectories. CLAUDE.md is documented only for the Cursor CLI, which reads AGENTS.md and CLAUDE.md at the project root and applies them as rules alongside .cursor/rules.

None documentedYesNone documented.cursor/rules
Windsurf
  • .devin/rules/*.md
  • .windsurf/rules/*.md
  • .windsurfrules
  • AGENTS.md
  • agents.md
  • ~/.codeium/windsurf/memories/global_rules.md
Yes
How

Native, no setting needed. AGENTS.md (or agents.md, case insensitive) is fed into the same Rules engine: root file is always-on, subdirectory files become glob rules scoped to <directory>/**. The default Devin Local agent reads AGENTS.md through the Devin CLI rules system, whose docs also list AGENTS.local.md, AGENT.md, .windsurfrules and CLAUDE.md, and allow disabling via "read_config_from": {"agents_standard": false}.

~/.codeium/windsurf/memories/global_rules.mdYesNone documented.devin/rules
Zed
  • .rules
  • .cursorrules
  • .windsurfrules
  • .clinerules
  • .github/copilot-instructions.md
  • AGENT.md
  • AGENTS.md
  • CLAUDE.md
  • GEMINI.md
  • ~/.config/zed/AGENTS.md
Yes
How

Native: AGENTS.md is the primary instruction file. For project instructions Zed uses only the first matching file in its list (.rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md), so a .rules or other earlier file wins over AGENTS.md. Personal AGENTS.md lives at ~/.config/zed/AGENTS.md (Windows: %APPDATA%\Zed\AGENTS.md). Applies to the Zed Agent; External Agents and Terminal Threads may read their own native instruction files directly, and Zed's instruction loader does not control them.

~/.config/zed/AGENTS.mdNot statedNone documentedNone documented
Cline
  • .clinerules/
  • .cline/rules/
  • .cursorrules
  • .windsurfrules
  • AGENTS.md
  • ~/.agents/AGENTS.md
Yes
How

Native, automatically detected: AGENTS.md at the project root plus the cross-tool global ~/.agents/AGENTS.md. Like every detected rule type it appears in the Rules panel and can be toggled individually.

~/Documents/Cline/Rules (global rules directory; also ~/.cline/rules, ~/Cline/Rules and ~/.agents/AGENTS.md)Not statedNone documented.clinerules/
Kiro
  • .kiro/steering/
  • AGENTS.md
  • ~/.kiro/steering/
Yes
How

Native, picked up automatically from the workspace root, subdirectories, or the global ~/.kiro/steering/ location. AGENTS.md files do not support inclusion modes and are always included. Custom agents do not load steering automatically; it must be added to the agent resources config.

~/.kiro/steering/Yes#[[file:<relative_file_name>]].kiro/steering
opencode
  • AGENTS.md
  • CLAUDE.md
  • ~/.config/opencode/AGENTS.md
  • ~/.claude/CLAUDE.md
Yes
How

Native default: AGENTS.md in the project root (found by traversing up from the current directory) plus global ~/.config/opencode/AGENTS.md. CLAUDE.md is a fallback used only if no AGENTS.md exists; ~/.claude/CLAUDE.md is used only if no ~/.config/opencode/AGENTS.md exists. OPENCODE_DISABLE_CLAUDE_CODE=1 disables all .claude support; OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 disables only ~/.claude/CLAUDE.md. Extra files can be added via the "instructions" array in opencode.json.

~/.config/opencode/AGENTS.mdNot statedNone documentedNone documented
Amp
  • AGENTS.md
  • AGENT.md
  • CLAUDE.md
  • $HOME/.config/amp/AGENTS.md
  • $HOME/.config/AGENTS.md
  • /etc/ampcode/AGENTS.md
  • /Library/Application Support/ampcode/AGENTS.md
  • %ProgramData%\ampcode\AGENTS.md
Yes
How

AGENTS.md is the native default. If no AGENTS.md exists in a directory but AGENT.md or CLAUDE.md does, that file is included. AMP_IGNORE_GUIDANCE_FILES (colon-delimited globs) skips matching guidance files; AMP_IGNORE_GUIDANCE_FILES='*' disables all automatic loading.

$HOME/.config/amp/AGENTS.mdYes@-mention in agent files, e.g. When making commits, see @doc/git-commit-instructions.md.; relative paths resolve from the containing file, absolute paths and @~/some/path supported, globs such as @doc/*.md or @.agent/**/*.md supported, mentions in code blocks ignored. Mentioned files may set globs in YAML front matter to apply only when matching files are read.None documented
Qwen Code
  • QWEN.md
  • ~/.qwen/QWEN.md
  • .qwen/QWEN.local.md
  • AGENTS.md
Yes
How

Native: "If your repository already has an AGENTS.md file for other AI tools, Qwen reads that too." The context file name defaults to QWEN.md and is configurable via the context.fileName setting (string or array, e.g. ["CONTEXT.md", "QWEN.md"]).

~/.qwen/QWEN.mdNot stated@path/to/file anywhere in QWEN.md (e.g. See @README.md for project overview.); relative paths resolve from the QWEN.md file itself..qwen/rules/
goose
  • AGENTS.md
  • .goosehints
  • ~/.config/goose/.goosehints
  • ~/.config/goose/AGENTS.md
Yes
How

Default: goose looks for AGENTS.md then .goosehints; the CONTEXT_FILE_NAMES environment variable (JSON array, default ["AGENTS.md", ".goosehints"]) changes the list, e.g. export CONTEXT_FILE_NAMES='["CLAUDE.md", ".goosehints", "project_rules.txt"]'. The Developer extension must be enabled to use hints files.

~/.config/goose/.goosehintsYes@ syntax automatically includes file content, e.g. @README.md or @relative/path/testing.md; plain references without @ only point goose to files to review when needed.None documented

Tool by tool

How each tool combines its files when more than one applies, the docs it was read from, and the quote behind every value.

  • Claude Code

    CLAUDE.md

    Files are concatenated rather than overriding each other, loaded from broadest to most specific (managed policy, user, project, local) and ordered from the filesystem root down to the working directory, with CLAUDE.local.md appended after CLAUDE.md in each directory and subdirectory files loaded on demand.

    AGENTS.md
    Yes
    User-level
    ~/.claude/CLAUDE.md
    Nested
    Yes

    Sources

    Where each value comes from
    Files it reads
    code.claude.com/docs/en/memory: locations table lists ./CLAUDE.md or ./.claude/CLAUDE.md (project), ./CLAUDE.local.md (local); AGENTS.md section: 'every AGENTS.md and .claude/AGENTS.md in your working directory and the directories above it'. Managed policy file: /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux and WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows).Claude Code docs: How Claude remembers your project
    Reads AGENTS.md
    code.claude.com/docs/en/memory: 'Claude Code can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without adding a CLAUDE.md, an import, or a setting.'Claude Code docs: How Claude remembers your project
    AGENTS.md details
    code.claude.com/docs/en/memory, sections 'When Claude Code reads AGENTS.md', 'Choose which instruction files load', 'When AGENTS.md support is unavailable'.Claude Code docs: How Claude remembers your project
    User-level file
    code.claude.com/docs/en/memory locations table: User instructions ~/.claude/CLAUDE.md.Claude Code docs: How Claude remembers your project
    Nested files
    code.claude.com/docs/en/memory: 'Claude also discovers CLAUDE.md and CLAUDE.local.md files in subdirectories under your current working directory. Instead of loading them at launch, Claude Code loads each one once Claude reads, writes, or edits another file in that subdirectory.'Claude Code docs: How Claude remembers your project
    Imports
    code.claude.com/docs/en/memory: 'CLAUDE.md files can import additional files using @path/to/import syntax.' Relative paths resolve from the importing file; maximum depth of four hops.Claude Code docs: How Claude remembers your project
    Rules directory
    code.claude.com/docs/en/memory: 'Place markdown files in your project's .claude/rules/ directory... All .md files are discovered recursively.' User-level rules: ~/.claude/rules/. Path scoping via a paths frontmatter field.Claude Code docs: How Claude remembers your project
    How files combine
    code.claude.com/docs/en/memory: 'All discovered files are concatenated into context rather than overriding each other. Across the directory tree, content is ordered from the filesystem root down to your working directory... Within each directory, CLAUDE.local.md is appended after CLAUDE.md.'Claude Code docs: How Claude remembers your project

  • OpenAI Codex CLI

    AGENTS.md

    Codex reads the global file in the Codex home first (AGENTS.override.md if present, otherwise AGENTS.md), then walks from the project root down to the current working directory taking one file per directory, and concatenates them so files closer to the current directory appear later and override earlier guidance.

    AGENTS.md
    Yes
    User-level
    ~/.codex/AGENTS.md
    Nested
    Yes

    Sources

    Where each value comes from
    Files it reads
    learn.chatgpt.com/docs/agent-configuration/agents-md: 'In each directory along the path, it checks for AGENTS.override.md, then AGENTS.md, then any fallback names in project_doc_fallback_filenames.'Codex docs: Custom instructions with AGENTS.md (developers.openai.com/codex/guides/agents-md redirects here)
    Reads AGENTS.md
    learn.chatgpt.com/docs/agent-configuration/agents-md: 'Codex reads AGENTS.md files before doing any work.'Codex docs: Custom instructions with AGENTS.md (developers.openai.com/codex/guides/agents-md redirects here)
    AGENTS.md details
    learn.chatgpt.com/docs/agent-configuration/agents-md, sections 'How Codex discovers guidance' and 'Customize fallback filenames' (example: project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]).Codex docs: Custom instructions with AGENTS.md (developers.openai.com/codex/guides/agents-md redirects here)
    User-level file
    learn.chatgpt.com/docs/agent-configuration/agents-md: 'Create ~/.codex/AGENTS.md with reusable preferences'; Codex home defaults to ~/.codex unless CODEX_HOME is set; ~/.codex/AGENTS.override.md is a temporary global override.Codex docs: Custom instructions with AGENTS.md (developers.openai.com/codex/guides/agents-md redirects here)
    Nested files
    learn.chatgpt.com/docs/agent-configuration/agents-md: 'Starting at the project root (typically the Git root), Codex walks down to your current working directory.' Only directories on the path from project root to the current directory are read: 'Codex stops searching once it reaches your current directory.'Codex docs: Custom instructions with AGENTS.md (developers.openai.com/codex/guides/agents-md redirects here)
    Imports
    Not documented on the official AGENTS.md page read today.
    Rules directory
    No instruction rules directory documented. The Codex 'Rules' page covers controlling which commands Codex can run outside the sandbox (Starlark), not instruction files.
    How files combine
    learn.chatgpt.com/docs/agent-configuration/agents-md: 'Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt.'Codex docs: Custom instructions with AGENTS.md (developers.openai.com/codex/guides/agents-md redirects here)

  • Gemini CLI

    GEMINI.md

    The CLI loads the global ~/.gemini/GEMINI.md, then GEMINI.md files in the configured workspace directories and their parent directories, then just-in-time GEMINI.md files found when a tool accesses a file or directory, and concatenates all found files and sends them with every prompt.

    AGENTS.md
    Opt-in
    User-level
    ~/.gemini/GEMINI.md
    Nested
    Yes

    Sources

    Where each value comes from
    Files it reads
    geminicli.com/docs/cli/gemini-md/: 'Context files, which use the default name GEMINI.md'.Gemini CLI docs: Provide context with GEMINI.md files
    Reads AGENTS.md
    geminicli.com/docs/cli/gemini-md/ 'Customize the context file name': 'To specify a different name or a list of names, use the context.fileName property.' Example: {"context": {"fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]}}.Gemini CLI docs: Provide context with GEMINI.md files
    AGENTS.md details
    geminicli.com/docs/cli/gemini-md/ 'Customize the context file name'.Gemini CLI docs: Provide context with GEMINI.md files
    User-level file
    geminicli.com/docs/cli/gemini-md/: 'Global context file: Location: ~/.gemini/GEMINI.md (in your user home directory).'Gemini CLI docs: Provide context with GEMINI.md files
    Nested files
    geminicli.com/docs/cli/gemini-md/: 'Just-in-time (JIT) context files: When a tool accesses a file or directory, the CLI automatically scans for GEMINI.md files in that directory and its ancestors up to a trusted root.'Gemini CLI docs: Provide context with GEMINI.md files
    Imports
    geminicli.com/docs/cli/gemini-md/: 'importing content from other files using the @file.md syntax. This feature supports both relative and absolute paths.' Examples: @./components/instructions.md, @../shared/style-guide.md.Gemini CLI docs: Provide context with GEMINI.md files
    Rules directory
    No rules directory documented on the page read today.
    How files combine
    geminicli.com/docs/cli/gemini-md/ 'Understand the context hierarchy': 'concatenates the contents of all found files, and sends them to the model with every prompt. The CLI loads files in the following order' (global, environment and workspace, JIT).Gemini CLI docs: Provide context with GEMINI.md files
    Docs notice
    Page banner read today: 'Unpaid tier and Google One users: Gemini CLI was replaced by Antigravity CLI on June 18th, 2026.' Page last updated Jun 18, 2026.

  • GitHub Copilot (VS Code + coding agent)

    .github/copilot-instructions.md

    Personal instructions take the highest priority, then repository instructions, then organization instructions, but all relevant sets are provided to Copilot; VS Code states instruction sources are additive and you should not depend on a file order or precedence rule, while for AGENTS.md the nearest file in the directory tree takes precedence.

    AGENTS.md
    Yes
    User-level
    ~/.copilot/copilot-instructions.md
    Nested
    Yes

    Sources

    Where each value comes from
    Files it reads
    docs.github.com custom-instructions-support: Copilot cloud agent supports .github/copilot-instructions.md, .github/instructions/**/*.instructions.md, and 'AGENTS.md, CLAUDE.md or GEMINI.md files'; VS Code Copilot Chat supports .github/copilot-instructions.md, .github/instructions/**/*.instructions.md and 'an AGENTS.md file'. VS Code page: Local harness also supports CLAUDE.md, .claude/CLAUDE.md, ~/.claude/CLAUDE.md and CLAUDE.local.md when chat.useClaudeMdFile is enabled.GitHub Docs: Support for different types of custom instructions
    Reads AGENTS.md
    docs.github.com add-repository-instructions: 'You can create one or more AGENTS.md files, stored anywhere within the repository.' VS Code page: AGENTS.md is a cross-agent format that 'Multiple harnesses, including Copilot and OpenAI Codex, support'.GitHub Docs: Adding repository custom instructions for GitHub Copilot
    AGENTS.md details
    docs.github.com add-repository-instructions: 'Alternatively, you can use a single CLAUDE.md or GEMINI.md file stored in the root of the repository.' VS Code page sections 'Use an AGENTS.md file' and 'Use multiple AGENTS.md files'.GitHub Docs: Adding repository custom instructions for GitHub Copilot
    User-level file
    VS Code page: 'For personal, always-on instructions in Copilot sessions, use ~/.copilot/copilot-instructions.md.' Copilot user .instructions.md folder: ~/.copilot/instructions. The GitHub support table lists no personal instructions for Copilot cloud agent.VS Code docs: Use custom instructions in VS Code
    Nested files
    docs.github.com add-repository-instructions: 'When Copilot is working, the nearest AGENTS.md file in the directory tree will take precedence.' VS Code Local harness: chat.useNestedAgentsMdFiles 'is disabled by default'.GitHub Docs: Adding repository custom instructions for GitHub Copilot
    Imports
    No @-import syntax documented. VS Code page: 'To reference files or URLs in instructions, use Markdown links. Relative file paths resolve from the instructions file.' (Local harness setting chat.includeReferencedInstructions covers linked instructions.)
    Rules directory
    docs.github.com add-repository-instructions: 'one or more NAME.instructions.md files within or below the .github/instructions directory', scoped with applyTo frontmatter; VS Code instructions file locations table: Copilot workspace .github/instructions, Copilot user ~/.copilot/instructions.GitHub Docs: Adding repository custom instructions for GitHub Copilot
    How files combine
    docs.github.com add-repository-instructions: 'Personal instructions take the highest priority. Repository instructions come next, and then organization instructions are prioritized last. However, all sets of relevant instructions are provided to Copilot.' VS Code page: 'Applicable instruction sources are additive. Do not depend on a file order or precedence rule to resolve conflicts.'GitHub Docs: Adding repository custom instructions for GitHub Copilot

  • GitHub Copilot CLI

    .github/copilot-instructions.md

    Copilot CLI combines applicable user-level and repository instruction files and removes duplicate copies of identical files, but does not define a general precedence order between them; path-specific files are included only when their applyTo value matches a file it is working with.

    AGENTS.md
    Yes
    User-level
    $HOME/.copilot/copilot-instructions.md
    Nested
    Yes

    Sources

    Where each value comes from
    Files it reads
    docs.github.com Copilot CLI add-custom-instructions locations table: .github/copilot-instructions.md, .github/instructions/**/*.instructions.md, AGENTS.md, CLAUDE.md ('Copilot CLI also uses .claude/CLAUDE.md'), GEMINI.md.GitHub Docs: Adding custom instructions for GitHub Copilot CLI
    Reads AGENTS.md
    docs.github.com Copilot CLI add-custom-instructions: 'AGENTS.md: Agent instructions, discovered in the standard locations.'GitHub Docs: Adding custom instructions for GitHub Copilot CLI
    AGENTS.md details
    docs.github.com Copilot CLI add-custom-instructions: definition of standard locations, COPILOT_CUSTOM_INSTRUCTIONS_DIRS row, and the /instructions command.GitHub Docs: Adding custom instructions for GitHub Copilot CLI
    User-level file
    docs.github.com Copilot CLI add-custom-instructions: '$HOME/.copilot/copilot-instructions.md: User-level instructions that apply across repositories.' Also $HOME/.copilot/instructions/**/*.instructions.md; COPILOT_HOME replaces $HOME/.copilot when set.GitHub Docs: Adding custom instructions for GitHub Copilot CLI
    Nested files
    docs.github.com Copilot CLI add-custom-instructions: standard locations include 'intermediate directories between them, and any directories nested in the path of a file it is working on.' .github/instructions files are 'discovered in the standard locations but not intermediate directories.'GitHub Docs: Adding custom instructions for GitHub Copilot CLI
    Imports
    docs.github.com Copilot CLI add-custom-instructions: 'In .github/copilot-instructions.md, AGENTS.md, or CLAUDE.md, use @ followed by a relative path to include another file.' 'Absolute paths and paths beginning with ~/ are not loaded. File references are not expanded in GEMINI.md or *.instructions.md files.'GitHub Docs: Adding custom instructions for GitHub Copilot CLI
    Rules directory
    docs.github.com Copilot CLI add-custom-instructions: 'Create one or more NAME.instructions.md files' in .github/instructions with applyTo frontmatter; modular user-level files in $HOME/.copilot/instructions/.GitHub Docs: Adding custom instructions for GitHub Copilot CLI
    How files combine
    docs.github.com Copilot CLI add-custom-instructions 'How multiple instruction files interact': 'It removes duplicate copies of identical user-level copilot-instructions.md, repository-wide, and agent instructions, but does not define a general precedence order between these files.'GitHub Docs: Adding custom instructions for GitHub Copilot CLI

  • Cursor

    .cursor/rules/*.mdc

    Rules apply in the order Team Rules, then Project Rules, then User Rules, all merged with earlier sources winning on conflict; nested AGENTS.md files combine with parent directories and the more specific file takes precedence.

    AGENTS.md
    Yes
    User-level
    None documented
    Nested
    Yes

    Sources

    Where each value comes from
    Files it reads
    cursor.com/docs/rules: project rules live in .cursor/rules as .mdc files ('A plain .md file in .cursor/rules is ignored'); AGENTS.md section. cursor.com/docs/cli/using: 'The CLI also reads AGENTS.md and CLAUDE.md at the project root (if present)' (CLAUDE.md is CLI-only per docs).Cursor Docs: Rules - Cursor Docs: Using Agent in CLI
    Reads AGENTS.md
    cursor.com/docs/rules: 'Cursor supports AGENTS.md in the project root and subdirectories.'Cursor Docs: Rules
    AGENTS.md details
    cursor.com/docs/rules AGENTS.md section; cursor.com/docs/cli/using Rules section.Cursor Docs: Rules - Cursor Docs: Using Agent in CLI
    User-level file
    cursor.com/docs/rules: User Rules are 'global preferences defined in Customize -> Rules', a settings UI, not a documented file path.Cursor Docs: Rules
    Nested files
    cursor.com/docs/rules: 'You can place AGENTS.md files in any subdirectory of your project, and they will be automatically applied when working with files in that directory or its children.'Cursor Docs: Rules
    Imports
    cursor.com/docs/rules: file mentions like @service-template.ts tell Agent where to look; 'The file's contents are not inlined into the prompt', so no include syntax is documented.Cursor Docs: Rules
    Rules directory
    cursor.com/docs/rules: 'Stored in .cursor/rules, version-controlled and scoped to your codebase.'Cursor Docs: Rules
    How files combine
    cursor.com/docs/rules: 'Rules are applied in this order: Team Rules -> Project Rules -> User Rules ... earlier sources take precedence'; nested AGENTS.md 'more specific instructions taking precedence'.Cursor Docs: Rules

  • Windsurf (Devin Desktop)

    .devin/rules/*.md

    The .devin/ directory is preferred and takes precedence over the legacy .windsurf/ fallback; system-level (Enterprise) rules are merged with workspace and global rules without overriding user-defined rules.

    AGENTS.md
    Yes
    User-level
    ~/.codeium/windsurf/memories/global_rules.md
    Nested
    Yes

    Sources

    Where each value comes from
    Files it reads
    docs.devin.ai/desktop/cascade/memories Rules table: Global ~/.codeium/windsurf/memories/global_rules.md; Workspace .devin/rules/*.md (preferred) or .windsurf/rules/*.md (fallback); 'The legacy single-file .windsurfrules at the workspace root is also still read'; AGENTS.md in any directory. docs.devin.ai/desktop/cascade/agents-md: 'Both AGENTS.md and agents.md are recognized'. (docs.windsurf.com redirects to docs.devin.ai.)Devin Docs (Windsurf): Cascade Memories and Rules - Devin Docs (Windsurf): AGENTS.md - Devin Docs: Devin CLI Rules and AGENTS.md
    Reads AGENTS.md
    docs.devin.ai/desktop/cascade/agents-md: 'Devin Desktop automatically discovers it and feeds it into the same Rules engine'.Devin Docs (Windsurf): AGENTS.md
    AGENTS.md details
    docs.devin.ai/desktop/cascade/agents-md How It Works; 'The Devin Local agent reads AGENTS.md through the Devin CLI rules system'; docs.devin.ai/cli/extensibility/rules Supported File Names and Controlling Imports.Devin Docs (Windsurf): AGENTS.md - Devin Docs: Devin CLI Rules and AGENTS.md
    User-level file
    docs.devin.ai/desktop/cascade/memories: Global scope ~/.codeium/windsurf/memories/global_rules.md, single file, always on, limited to 6,000 characters.Devin Docs (Windsurf): Cascade Memories and Rules
    Nested files
    docs.devin.ai/desktop/cascade/agents-md: subdirectory AGENTS.md treated as glob rule <directory>/**; memories page: .devin/rules in any sub-directory and parent directories up to the git root.Devin Docs (Windsurf): Cascade Memories and Rules - Devin Docs (Windsurf): AGENTS.md - Devin Docs: Devin CLI Rules and AGENTS.md
    Imports
    No import or include syntax stated on the Desktop rules or AGENTS.md pages.
    Rules directory
    docs.devin.ai/desktop/cascade/memories: 'When you create a new rule, it will be saved in the .devin/rules directory'; .windsurf/rules is the legacy fallback.Devin Docs (Windsurf): Cascade Memories and Rules - Devin Docs: Devin CLI Rules and AGENTS.md
    How files combine
    docs.devin.ai/desktop/cascade/memories: 'The .devin/ directory is the preferred location and takes precedence'; 'System-level rules are merged with workspace and global rules ... without overriding user-defined rules.'Devin Docs (Windsurf): Cascade Memories and Rules - Devin Docs: Devin CLI Rules and AGENTS.md

  • Zed

    .rules

    Zed loads the first matching project file in its priority list (.rules first, GEMINI.md last), and project instructions override personal AGENTS.md when they conflict.

    AGENTS.md
    Yes
    User-level
    ~/.config/zed/AGENTS.md
    Nested
    Not stated

    Sources

    Where each value comes from
    Files it reads
    zed.dev/docs/ai/instructions: 'Zed uses the first matching file in this list: .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md'; personal file ~/.config/zed/AGENTS.md.Zed Docs: Agent Instructions
    Reads AGENTS.md
    zed.dev/docs/ai/instructions: 'Zed supports AGENTS.md as the primary instruction file for personal and project-level agent guidance.'Zed Docs: Agent Instructions
    AGENTS.md details
    zed.dev/docs/ai/instructions file list and agent table ('External Agents and Terminal Threads may read their own native instruction files directly. Do not assume Zed's instruction loader controls those agents').Zed Docs: Agent Instructions
    User-level file
    zed.dev/docs/ai/instructions: 'Create or edit: ~/.config/zed/AGENTS.md'; 'On Windows, the equivalent file is under %APPDATA%\Zed\AGENTS.md.'Zed Docs: Agent Instructions
    Nested files
    Not stated on the official instructions page (the old /docs/ai/rules URL returns 404).
    Imports
    Not stated on the official instructions page.
    Rules directory
    zed.dev/docs/ai/instructions: 'Rules have been replaced by Skills and Instructions'; no rules directory documented.Zed Docs: Agent Instructions
    How files combine
    zed.dev/docs/ai/instructions: 'first matching file in this list'; 'Project instructions override personal AGENTS.md when they conflict.'Zed Docs: Agent Instructions

  • Cline

    .clinerules/

    Workspace and global rules are combined, and workspace rules take precedence when they conflict with global rules.

    AGENTS.md
    Yes
    User-level
    ~/Documents/Cline/Rules (global rules directory; also ~/.cline/rules, ~/Cline/Rules and ~/.agents/AGENTS.md)
    Nested
    Not stated

    Sources

    Where each value comes from
    Files it reads
    docs.cline.bot/customization/cline-rules Supported Rule Types table: Cline Rules .clinerules/, .cline/rules/; Cursor Rules .cursorrules; Windsurf Rules .windsurfrules; AGENTS.md AGENTS.md, ~/.agents/AGENTS.md.Cline Docs: Rules
    Reads AGENTS.md
    docs.cline.bot/getting-started/config: 'In a project, Cline also reads ... AGENTS.md at the project root ... Globally, it also reads ~/.agents/AGENTS.md'.Cline Docs: Config
    AGENTS.md details
    docs.cline.bot/customization/cline-rules: 'All detected rule types appear in the Rules panel, where you can toggle them individually.'Cline Docs: Rules
    User-level file
    docs.cline.bot/customization/cline-rules Global Rules Directory: macOS/Linux ~/Documents/Cline/Rules, Windows Documents\Cline\Rules; 'Cline also searches ~/.cline/rules and ~/Cline/Rules'.Cline Docs: Rules
    Nested files
    Not stated; docs only describe rules at the project root (.clinerules/ or .cline/rules/) and AGENTS.md 'at the project root'.
    Imports
    Not stated on the official rules or config pages.
    Rules directory
    docs.cline.bot/customization/cline-rules: 'Workspace rules go in .clinerules/ or .cline/rules/ at your project root'; 'The VS Code Rules panel still creates new workspace rules in .clinerules/.'Cline Docs: Rules
    How files combine
    docs.cline.bot/customization/cline-rules: 'When both workspace and global rules exist, Cline combines them. Workspace rules take precedence when they conflict with global rules.'Cline Docs: Rules

  • Kiro

    .kiro/steering/

    When global and workspace steering conflict, Kiro prioritizes the workspace steering instructions.

    AGENTS.md
    Yes
    User-level
    ~/.kiro/steering/
    Nested
    Yes

    Sources

    Where each value comes from
    Files it reads
    kiro.dev/docs/steering: Workspace steering .kiro/steering/, Global steering ~/.kiro/steering/, and the Agents.md section.Kiro Docs: Steering
    Reads AGENTS.md
    kiro.dev/docs/steering: 'Kiro supports providing steering directives via the AGENTS.md standard.'Kiro Docs: Steering
    AGENTS.md details
    kiro.dev/docs/steering: 'AGENTS.md files do not support inclusion modes and are always included'; 'add AGENTS.md files to the global steering file location (~/.kiro/steering/), or to the root folder of your workspace'; Steering with custom agents section.Kiro Docs: Steering
    User-level file
    kiro.dev/docs/steering: 'Global steering files reside in your home directory under ~/.kiro/steering/, and apply to all workspaces.'Kiro Docs: Steering
    Nested files
    kiro.dev/docs/steering: 'AGENTS.md files are also discovered in subdirectories throughout your workspace.'Kiro Docs: Steering
    Imports
    kiro.dev/docs/steering File references: #[[file:<relative_file_name>]]; IDE and CLI V3 also support #[[file:<relative_file_name>:<start>-<end>]] and #[[folder:<relative_folder_name>]].Kiro Docs: Steering
    Rules directory
    kiro.dev/docs/steering: 'Workspace steering files reside in your project root folder under .kiro/steering/'.Kiro Docs: Steering
    How files combine
    kiro.dev/docs/steering: 'In case of conflicting instructions between global and workspace steering, Kiro will prioritize the workspace steering instructions.'Kiro Docs: Steering

  • opencode

    AGENTS.md

    Local files are found by traversing up from the current directory (AGENTS.md, CLAUDE.md), then the global ~/.config/opencode/AGENTS.md, then ~/.claude/CLAUDE.md unless disabled; the first matching file wins in each category, and files listed in opencode.json "instructions" are combined with AGENTS.md.

    AGENTS.md
    Yes
    User-level
    ~/.config/opencode/AGENTS.md
    Nested
    Not stated

    Sources

    Where each value comes from
    Files it reads
    https://opencode.ai/docs/rules/ (Types; Claude Code Compatibility)opencode docs: Rules
    Reads AGENTS.md
    https://opencode.ai/docs/rules/ ("You can provide custom instructions to opencode by creating an AGENTS.md file")opencode docs: Rules
    AGENTS.md details
    https://opencode.ai/docs/rules/ (Precedence; Claude Code Compatibility env var comments; Custom Instructions)opencode docs: Rules
    User-level file
    https://opencode.ai/docs/rules/ (Global: ~/.config/opencode/AGENTS.md)opencode docs: Rules
    Nested files
    Not stated: docs describe traversing up from the current directory only, not loading subdirectory files
    Imports
    https://opencode.ai/docs/rules/ (Referencing External Files: "opencode doesn't automatically parse file references in AGENTS.md"; use the opencode.json instructions field instead)opencode docs: Rules
    Rules directory
    Not stated: no rules directory documented; the instructions field accepts globs such as ".cursor/rules/*.md"
    How files combine
    https://opencode.ai/docs/rules/ (Precedence; "All instruction files are combined with your AGENTS.md files")opencode docs: Rules

  • Amp

    AGENTS.md

    AGENTS.md files in the cwd (or workspace roots) and parent directories up to $HOME are always included, subtree AGENTS.md files are included when the agent reads a file in that subtree, system-wide and $HOME/.config files are always included if present, and workspace guidance is included before personal and repository guidance.

    AGENTS.md
    Yes
    User-level
    $HOME/.config/amp/AGENTS.md
    Nested
    Yes

    Sources

    Where each value comes from
    Files it reads
    https://ampcode.com/docs/customize/agents-md (file table; AGENT.md/CLAUDE.md fallback)Amp docs: AGENTS.md
    Reads AGENTS.md
    https://ampcode.com/docs/customize/agents-md ("Amp looks in AGENTS.md files for guidance")Amp docs: AGENTS.md
    AGENTS.md details
    https://ampcode.com/docs/customize/agents-md (fallback paragraph; Ignoring Guidance Files)Amp docs: AGENTS.md
    User-level file
    https://ampcode.com/docs/customize/agents-md (file table: $HOME/.config/amp/AGENTS.md and $HOME/.config/AGENTS.md)Amp docs: AGENTS.md
    Nested files
    https://ampcode.com/docs/customize/agents-md ("Subtree AGENTS.md files are included when the agent reads a file in the subtree")Amp docs: AGENTS.md
    Imports
    https://ampcode.com/docs/customize/agents-md (Writing AGENTS.md Files; Granular Guidance)Amp docs: AGENTS.md
    Rules directory
    Not stated: no rules directory documented
    How files combine
    https://ampcode.com/docs/customize/agents-md (inclusion list; workspace guidance paragraph)Amp docs: AGENTS.md

  • Qwen Code

    QWEN.md

    The global ~/.qwen/QWEN.md loads first, then the configured context file in the current working directory and each parent up to the project root (.git) or home, with more specific files overriding or supplementing general ones; .qwen/QWEN.local.md loads after the shared project QWEN.md, and all found files are concatenated into the system prompt.

    AGENTS.md
    Yes
    User-level
    ~/.qwen/QWEN.md
    Nested
    Not stated

    Sources

    Where each value comes from
    Files it reads
    https://qwenlm.github.io/qwen-code-docs/en/users/features/memory/ (Where to create QWEN.md table; AGENTS.md sentence)Qwen Code docs: Memory
    Reads AGENTS.md
    https://qwenlm.github.io/qwen-code-docs/en/users/features/memory/ ("If your repository already has an AGENTS.md file for other AI tools, Qwen reads that too.")Qwen Code docs: Memory
    AGENTS.md details
    https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/ (context.fileName; example settings)Qwen Code docs: Settings (Context Files)
    User-level file
    https://qwenlm.github.io/qwen-code-docs/en/users/features/memory/ (~/.qwen/QWEN.md)Qwen Code docs: Memory
    Nested files
    Not stated: settings page documents searching the cwd and parent directories only, not subdirectories
    Imports
    https://qwenlm.github.io/qwen-code-docs/en/users/features/memory/ (Reference other files)Qwen Code docs: Memory
    Rules directory
    https://qwenlm.github.io/qwen-code-docs/en/users/features/rules/ ("Rules live in .qwen/rules/"; also ~/.qwen/rules/)Qwen Code docs: Rules
    How files combine
    https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/ (Hierarchical Loading and Precedence) and https://qwenlm.github.io/qwen-code-docs/en/users/features/memory/ (QWEN.local.md loads after)Qwen Code docs: Memory - Qwen Code docs: Settings (Context Files)

  • goose

    AGENTS.md

    Global and local hints are both used and local hints win on conflict; at session start goose loads configured context files from the working directory up to the repository root, loads nested hint files as it accesses subdirectories (combined from project root down to the current directory), and all found files are combined into the context.

    AGENTS.md
    Yes
    User-level
    ~/.config/goose/.goosehints
    Nested
    Yes

    Sources

    Where each value comes from
    Files it reads
    https://goose-docs.ai/docs/guides/context-engineering/using-goosehints/ (Creating Your Hints File; Custom Context Files: "goose looks for each configured filename in both global (~/.config/goose/) and local project locations", default ["AGENTS.md", ".goosehints"])goose docs: Providing Hints to goose
    Reads AGENTS.md
    https://goose-docs.ai/docs/guides/context-engineering/using-goosehints/ ("goose looks for AGENTS.md then .goosehints files by default")goose docs: Providing Hints to goose
    AGENTS.md details
    https://goose-docs.ai/docs/guides/context-engineering/using-goosehints/ (Configuration; Developer extension required)goose docs: Providing Hints to goose
    User-level file
    https://goose-docs.ai/docs/guides/context-engineering/using-goosehints/ ("Global hints are stored in ~/.config/goose/.goosehints")goose docs: Providing Hints to goose
    Nested files
    https://goose-docs.ai/docs/guides/context-engineering/using-goosehints/ (Nested .goosehints Files)goose docs: Providing Hints to goose
    Imports
    https://goose-docs.ai/docs/guides/context-engineering/using-goosehints/ (examples; Organize with @-mentions)goose docs: Providing Hints to goose
    Rules directory
    Not stated: no rules directory documented
    How files combine
    https://goose-docs.ai/docs/guides/context-engineering/using-goosehints/ (Creating Your Hints File; Nested .goosehints Files; Custom Context Files)goose docs: Providing Hints to goose

FAQ

Which coding agents read AGENTS.md?

13 of 14 coding agents read AGENTS.md out of the box and Gemini CLI reads it once you name it in a setting. Out of the box: Claude Code, OpenAI Codex CLI, GitHub Copilot, GitHub Copilot CLI, Cursor, Windsurf, Zed, Cline, Kiro, opencode, Amp, Qwen Code and goose.

Does Cursor read AGENTS.md?

Yes. Cursor reads AGENTS.md. Native, no setting needed. AGENTS.md is a plain markdown alternative to .cursor/rules, supported in the project root and in subdirectories. CLAUDE.md is documented only for the Cursor CLI, which reads AGENTS.md and CLAUDE.md at the project root and applies them as rules alongside .cursor/rules.

Does Claude Code read AGENTS.md?

Yes. Claude Code reads AGENTS.md. Native, controlled by the Project instructions setting. Default value claude-md-or-agents-md reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it; claude-md-and-agents-md reads both (each directory's CLAUDE.md first, AGENTS.md after). Set via /config or pluginConfigs under cc-plugin-agents-md@builtin (option instructionFiles). Requires v2.1.277 or later; where unavailable, put an @AGENTS.md import in a CLAUDE.md. AGENTS.local.md, AGENTS.override.md and anything under .agents/ are not read.

Does Gemini CLI read AGENTS.md?

Only once configured. Not by default (default context file name is GEMINI.md). Documented via the context.fileName property in settings.json, which accepts a name or list of names, for example ["AGENTS.md", "CONTEXT.md", "GEMINI.md"].

Does GitHub Copilot read AGENTS.md?

Yes. GitHub Copilot reads AGENTS.md. Native. Copilot cloud agent reads AGENTS.md (or a single CLAUDE.md or GEMINI.md at the repository root); VS Code Copilot sessions list .github/copilot-instructions.md or AGENTS.md as recommended project instructions. For the VS Code Local harness, chat.useAgentsMdFile toggles AGENTS.md support and chat.useNestedAgentsMdFiles (disabled by default) controls nested AGENTS.md files.

Does Windsurf read AGENTS.md?

Yes. Windsurf reads AGENTS.md. Native, no setting needed. AGENTS.md (or agents.md, case insensitive) is fed into the same Rules engine: root file is always-on, subdirectory files become glob rules scoped to <directory>/**. The default Devin Local agent reads AGENTS.md through the Devin CLI rules system, whose docs also list AGENTS.local.md, AGENT.md, .windsurfrules and CLAUDE.md, and allow disabling via "read_config_from": {"agents_standard": false}.

Does OpenAI Codex CLI read AGENTS.md?

Yes. OpenAI Codex CLI reads AGENTS.md. Native default. In each directory Codex checks AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames (set in ~/.codex/config.toml), and includes at most one file per directory. Empty files are skipped and the combined size is capped by project_doc_max_bytes (32 KiB by default).

Where does Claude Code look for CLAUDE.md?

Claude Code's docs list these files: CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, AGENTS.md, .claude/AGENTS.md. The user-level file is ~/.claude/CLAUDE.md. Files in subdirectories are read too. Files are concatenated rather than overriding each other, loaded from broadest to most specific (managed policy, user, project, local) and ordered from the filesystem root down to the working directory, with CLAUDE.local.md appended after CLAUDE.md in each directory and subdirectory files loaded on demand.

Where does Gemini CLI look for GEMINI.md?

Gemini CLI's docs list these files: GEMINI.md. The user-level file is ~/.gemini/GEMINI.md. Files in subdirectories are read too. The CLI loads the global ~/.gemini/GEMINI.md, then GEMINI.md files in the configured workspace directories and their parent directories, then just-in-time GEMINI.md files found when a tool accesses a file or directory, and concatenates all found files and sends them with every prompt.

Where does OpenAI Codex CLI look for AGENTS.md?

OpenAI Codex CLI's docs list these files: AGENTS.md, AGENTS.override.md. The user-level file is ~/.codex/AGENTS.md. Files in subdirectories are read too. Codex reads the global file in the Codex home first (AGENTS.override.md if present, otherwise AGENTS.md), then walks from the project root down to the current working directory taking one file per directory, and concatenates them so files closer to the current directory appear later and override earlier guidance.

Which instruction files can import other files?

7 of 14 tools document a way to pull another file into their instructions: Claude Code (@path/to/import), Gemini CLI (@file.md), GitHub Copilot CLI (@ followed by a relative path), Kiro (#[[file:<relative_file_name>]]), Amp, Qwen Code and goose. The Imports column shows each tool's syntax as its docs give it; the rest either do not inline referenced files or do not say.

Which coding agents use a rules directory?

Claude Code (.claude/rules/), GitHub Copilot (.github/instructions), GitHub Copilot CLI (.github/instructions), Cursor (.cursor/rules), Windsurf (.devin/rules), Cline (.clinerules/), Kiro (.kiro/steering) and Qwen Code (.qwen/rules/).

Method

How to read this matrix

Values come from each tool's docs, read on . Agents change how they load context often; check the linked source before you rely on a detail. Tools whose docs name no instruction file and say nothing about AGENTS.md are left out rather than shown as a row of blanks.

Official docs only
Each value was read from the tool's own documentation and re-checked independently. No forums, roundups or third-party claims, including the AGENTS.md site's own list of supporting tools.
Not stated means not stated
When the docs do not say whether a tool reads nested files, the matrix says Not stated rather than guessing from behaviour. None documented means the docs name no user-level file, import syntax or rules directory.
Opt-in is not default
A tool marked Opt-in can read AGENTS.md only after you name it in a setting. Yes means it reads the file with no configuration, though a tool may still prefer its own file when both exist.

Newsletter

Know when your tools change

One email per week. New coding agent releases, the config and context changes they ship, and what they mean for how you work.

Keep exploring

Coding agent CLI reference

Every slash command, flag, setting and config file for eight coding agents, from official docs.

MCP client support matrix

Which coding tools support MCP tools, resources, prompts, transports and OAuth.

How to write a CLAUDE.md

What belongs in an instruction file, what to cut, and how to share it with other agents.