The Workshop · 11 min mission

Rules Files Across Tools: AGENTS.md and the Rest

Keep one source of truth for agent rules across every IDE coding tool you use.

AGENTS.mdrules filesCLAUDE.mdcross-toolide-agentsFact-checked 2026-06-15
On this page
  1. Nesting and precedence
  2. Cursor
  3. GitHub Copilot
  4. Windsurf is now Devin Desktop
  5. Gemini CLI
  6. Cline and Roo Code
  7. Deeper dives in the cosmos

This guide maps which rules/memory file each coding agent reads, and how to keep one canonical briefing across all of them. After reading it you can put your project rules in a single AGENTS.md, let native readers consume it directly, and add a two-line bridge for the two tools (Claude Code, Gemini CLI) that need one.

ToolPrimary native fileReads AGENTS.md?Notable structured / legacy files
Cross-tool standardAGENTS.md (root + nested)It *is* the standardStewarded by Agentic AI Foundation / Linux Foundation
Cursor.cursor/rules/*.mdcYes (root + nested)Legacy .cursorrules no longer documented
GitHub Copilot.github/copilot-instructions.mdYes — plus CLAUDE.md & GEMINI.md.github/instructions/*.instructions.md (applyTo, excludeAgent)
VS Code Copilot.github/copilot-instructions.mdYes (chat.useAgentsMdFile)Reads CLAUDE.md via chat.useClaudeMdFile; .instructions.md
Windsurf / Devin Desktop.devin/rules/*.mdYes (root always-on; nested auto-scoped)Legacy .windsurf/rules/, .windsurfrules, global_rules.md
Claude CodeCLAUDE.md (+ .claude/rules/)No — bridge via @AGENTS.md or symlinkCLAUDE.local.md; managed-policy CLAUDE.md
Gemini CLIGEMINI.mdOnly if added to context.fileName~/.gemini/GEMINI.md global file
Cline.clinerules/Yes (root + ~/.agents/AGENTS.md)Legacy single .clinerules file
Roo Code.roo/rules/Yes (roo-cline.useAgentRules).roorules, AGENTS.local.md (v3.47.0)
Which tool reads which file, as of 2026-06-15. "Native AGENTS.md" = read with no extra config. Every claim traces to the tool’s official docs (see sources).

Nesting and precedence

A packages/api/AGENTS.md refines or overrides the root file when the agent works inside packages/api; chat prompts beat both. Most native readers honor "more specific takes precedence." The exception is Claude Code, which concatenates ancestor files (root down to the working directory) instead of letting the closest one override.

Cursor

Cursor reads AGENTS.md at the root and in nested subdirectories ("more specific instructions take precedence"). On top of that, Project Rules live in .cursor/rules/ as .mdc files (Markdown + YAML frontmatter), organizable into subdirectories like .cursor/rules/frontend/components.mdc. Four rule sources exist — Project, User, Team, and AGENTS.md — with precedence Team Rules → Project Rules → User Rules.

ModeFrontmatterWhen it loads
Always ApplyalwaysApply: trueInjected into every chat session
Apply Intelligentlydescription set, no globsThe agent decides when it is relevant
Apply to Specific Filesglobs pattern setWhen a matching file is in context
Apply Manuallynone of the aboveOnly when you mention @rule-name
Cursor’s four rule activation modes, selected by three frontmatter fields (`alwaysApply`, `description`, `globs`).

GitHub Copilot

Repository-wide instructions live in a single .github/copilot-instructions.md (natural-language Markdown) at the repo root. For finer scope, .github/instructions/NAME.instructions.md files carry frontmatter: applyTo: "glob/pattern" scopes a file (e.g. applyTo: "app/models/**/*.rb"), and excludeAgent: "code-review" or excludeAgent: "coding-agent" hides it from a specific agent. With no excludeAgent, all agents use the file. Copilot also reads AGENTS.md (root primary, nested = additional for their subtree) plus CLAUDE.md and GEMINI.md at the repo root per the support matrix. AGENTS.md support for the coding agent shipped 2025-08-28.

Windsurf is now Devin Desktop

On 2026-06-02 Windsurf became Devin Desktop (Cognition); docs moved to docs.devin.ai/desktop/…. Cascade is now the legacy agent (successor "Devin Local," rewritten in Rust), usable through 2026-07-01; the "Windsurf" name persists in directory paths for backward compatibility. Workspace rules are .devin/rules/*.md (preferred, takes precedence), with .windsurf/rules/*.md as fallback and the single-file .windsurfrules at root still read. The global file is ~/.codeium/windsurf/memories/global_rules.md. It offers trigger: frontmatter modes — always_on, model_decision, glob, manual — and reads AGENTS.md into the same rules engine: a root AGENTS.md becomes an always-on rule; a subdirectory one is auto-scoped with the glob <directory>/**.

Bridge Claude Code to a shared AGENTS.md

  1. Import AGENTS.md from CLAUDE.md

    Put @AGENTS.md as the first line of a short CLAUDE.md. Claude expands the shared file into context at launch. Imports are recursive up to 4 hops; they do not reduce context (the imported file still loads).

  2. Add only Claude-specific notes below it

    Everything not in the shared brief — plan-mode rules, skills, path-scoped notes — goes under the import so nothing duplicates AGENTS.md.

  3. Or symlink when there is no Claude-specific content

    Run ln -s AGENTS.md CLAUDE.md. Works everywhere except Windows without admin or Developer Mode — use the @AGENTS.md import there.

  4. Or let /init pull it in

    Running /init in a repo that already has AGENTS.md reads it into the generated CLAUDE.md, and also pulls from .cursorrules, .devin/rules/, and .windsurfrules.

CLAUDE.md — the bridge pattern (one source of truth)
markdown
@AGENTS.md
 
## Claude Code
Use plan mode for changes under `src/billing/`.
Prefer the /review-pr skill before opening a PR.

Gemini CLI

Gemini CLI's default context filename is GEMINI.md. It loads hierarchically — global ~/.gemini/GEMINI.md, then project and ancestor directories, then just-in-time as tools touch files — and concatenates everything it finds with each prompt. It supports @file.md imports and the /memory show / /memory reload commands. It does not read AGENTS.md by default; add it to the context.fileName key in settings.json (accepts a single name or an array). Latest stable: v0.45.0 (2026-06-03).

~/.gemini/settings.json — teach Gemini CLI to read AGENTS.md too
json
{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

Cline and Roo Code

Cline uses a .clinerules/ directory: it processes every .md and .txt file inside and combines them, with optional numeric prefixes (01-coding.md) as ordering aids. Global rules live in ~/Documents/Cline/Rules; conditional rules use paths: frontmatter. It reads both a project-root AGENTS.md and a cross-tool global ~/.agents/AGENTS.md.

Roo Code uses .roo/rules/ (recursive, appended to the system prompt in alphabetical filename order), with the single-file .roorules as legacy fallback and .roo/rules-{modeSlug}/ for mode-specific rules. It loads AGENTS.md (or AGENT.md as fallback) from the workspace root by default — disable with the VS Code setting "roo-cline.useAgentRules": false. As of v3.47.0 (2026-02-05) it also supports AGENTS.local.md for personal, un-committed overrides, auto-added to .gitignore.

Wire one source of truth across your stack

  1. Make AGENTS.md canonical

    Write the project overview, build/test/lint commands, setup gotchas, and hard constraints once in AGENTS.md at the repo root. Keep it lean — plain Markdown, no required structure.

  2. Let the native readers just read it

    Cursor, Copilot, Windsurf/Devin, Cline, and Roo Code need nothing more. For a monorepo, add nested AGENTS.md files in subprojects where closest-file-wins should refine the root.

  3. Bridge Claude Code

    Add a short CLAUDE.md whose first line is @AGENTS.md, then list only Claude-specific notes below it.

  4. Bridge Gemini CLI

    In ~/.gemini/settings.json, set context.fileName to an array including "AGENTS.md". Gemini CLI concatenates it with any GEMINI.md it finds.

  5. Reserve structured rules for scoped concerns

    Keep .cursor/rules/*.mdc, .github/instructions/*.instructions.md, .devin/rules/, and .claude/rules/ for narrow needs — path globs, modes, lifecycle. The broad briefing stays in the single AGENTS.md.

Reads AGENTS.md natively vs. needs a bridge

Native — nothing extra needed

Cursor (root + nested), GitHub Copilot (coding agent + VS Code via chat.useAgentsMdFile), Windsurf / Devin, Cline, Roo Code.

Drop AGENTS.md at the repo root; these tools pick it up. Add nested files for monorepo subtrees where the closest file should win.

Needs a thin shim

Claude Code → a short CLAUDE.md containing @AGENTS.md (or ln -s AGENTS.md CLAUDE.md on non-Windows).

Gemini CLI → add AGENTS.md to context.fileName in ~/.gemini/settings.json (or @AGENTS.md import into GEMINI.md).

one repo, every agent reading the same brief
… scroll to run this session
AGENTS.md is canonical. Native readers consume it directly; CLAUDE.md imports it; Gemini CLI is pointed at it via settings.json. No file holds a second copy.

Knowledge check

You keep your briefing in AGENTS.md at the repo root. Cursor and Copilot read it, but Claude Code ignores it entirely. What is the supported fix?

Translate one rule set into every tool

Write your rules once, ship them everywhere

Every coding agent reads its rules from a different file with its own conventions. Write your project rules once below — then switch tabs to get each tool's native format, ready to copy.

./AGENTS.md
# AGENTS.md
## Project overview
Acme Dashboard
## Conventions
- Use TypeScript strict mode — no `any`, no implicit returns
- Run the full test suite before opening a pull request
- Never commit secrets; .env stays out of version control
- Prefer small, focused modules over sprawling files
- Match the existing code style; let the formatter decide the rest
Write your project rules once and see them rendered in each tool’s native convention — AGENTS.md, .cursor/rules, copilot-instructions.md, CLAUDE.md, GEMINI.md — then copy each.

Deeper dives in the cosmos

This is the cross-tool overview. For the structured-rules systems, see Cursor: rules and context. For each native file in depth: Claude Code's CLAUDE.md, Codex and the AGENTS.md standard, and Gemini CLI's GEMINI.md.

Reach the end and this star joins your charted sky.