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 archived Roo Code
  7. Per-tool guides

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 (archived; historical).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 the Windsurf desktop app became Devin Desktop (Cognition); docs moved to docs.devin.ai/desktop/…. Windsurf remains the JetBrains plugin name and in backward-compatible paths. Devin Local is the primary local agent, while Cascade remained documented on 2026-08-01 and still owns Memories and Workflows; no final shutdown date was verified. 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 checked 2026-08-01: v0.53.1.

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

Cline and archived 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 (archived) used .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 loaded AGENTS.md (or AGENT.md as fallback) from the workspace root by default. This is migration reference only: Roo's repository was archived on 2026-05-15 and points users to the maintained Zoo Code successor. Verify Zoo's current rule paths before carrying an old Roo configuration forward.

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, and Cline 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.

Drop AGENTS.md at the repo root; these tools pick it up. Roo Code also read it, but Roo is archived; use the maintained Zoo Code successor and verify its current rule behavior.

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.

Per-tool guides

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.