Instruction files

AGENTS.md, CLAUDE.md and copilot-instructions.md in one repo: who reads what

A repo with a .claude folder, a .github folder and maybe a .cursor folder. Each tool reads its own file. The question is which one reads which, and how to avoid writing every rule three times.

Checked against the VS Code, Claude Code, Cursor and Gemini CLI docs on 21 November 2026.

The short answer

The folders .claude and .github can sit side by side. They do not interfere. The risk is in the content: the same rule written twice drifts apart, and each tool silently follows its own copy.

AGENTS.md is described in the VS Code docs as a cross-agent format, not a Codex-only file. That makes it the natural shared source.

Who reads what

ToolReadsNote
Claude CodeCLAUDE.md or .claude/CLAUDE.md, CLAUDE.local.md, .claude/rules/*.mdReads AGENTS.md only if there is no CLAUDE.md in the working directory or above (v2.1.277 or later).
GitHub Copilot in VS Code.github/copilot-instructions.md or AGENTS.md, plus .github/instructions/*.instructions.mdTargeted files carry an applyTo pattern in their frontmatter. VS Code also lists CLAUDE.md for its Claude harness.
Cursor.cursor/rules/*.mdc and AGENTS.mdA plain .md file in .cursor/rules is ignored. AGENTS.md works in the root and in subfolders.
CodexAGENTS.mdLoads the files along the path from the repository root to the working directory.
Gemini CLIGEMINI.mdAdd AGENTS.md to context.fileName in settings.json to read it too.

The AGENTS.md site lists more tools that read the file, among them Cursor, Codex, Gemini CLI and VS Code. In nested files the closest one to the edited file wins, and a prompt you type in the chat overrides all files.

Keep one source

  1. Write the shared rules once in AGENTS.md in the repository root: build and test commands, conventions, architecture notes.
  2. Claude Code: add a CLAUDE.md that imports it. The import pulls the file in, and anything below it is Claude-only:
    CLAUDE.md
    @AGENTS.md
    
    ## Claude Code
    
    Use plan mode for changes that touch more than three files.
    The Claude Code docs say the import never makes Claude read AGENTS.md twice.
  3. Cursor and Codex: nothing to do. Both read AGENTS.md.
  4. Gemini CLI: either keep a small GEMINI.md, or let it read the shared file:
    ~/.gemini/settings.json
    {
      "context": {
        "fileName": ["AGENTS.md", "GEMINI.md"]
      }
    }

A symlink (ln -s AGENTS.md CLAUDE.md) also works for Claude Code. Two limits from its docs: its Edit and Write tools refuse to write through a symlink and edit the target instead, and on Windows a committed symlink can arrive as a plain text file unless core.symlinks is enabled. The import avoids both.

Copilot: instructions and AGENTS.md

The VS Code docs name two always-on files for Copilot: .github/copilot-instructions.md or AGENTS.md. For rules that apply to some files only, use .github/instructions/*.instructions.md with an applyTo pattern in the frontmatter. The pattern is relative to the workspace root, not to the instructions folder.

If AGENTS.md already holds the shared rules, keep copilot-instructions.md short and point to it. The docs do not say that Copilot follows such a pointer on its own, so treat it as a hint for readers and keep the Copilot-only rules in that file:

.github/copilot-instructions.md
See AGENTS.md in the repository root for the project rules.
Rules below apply to Copilot only.

Claude Code has the matching split: .claude/rules/*.md with a paths field, where Copilot uses applyTo. Both are for rules scoped to files.

What does not work

  • The same rule in two files with different wording. The VS Code docs: "Don't rely on a universal precedence order: combination rules differ by harness." They advise keeping shared requirements consistent. Delete the duplicate.
  • A CLAUDE.md that only says "read AGENTS.md" in words. Claude sees the file only if it decides to open it. Use @AGENTS.md.
  • A personal CLAUDE.local.md next to an AGENTS.md-only repo. It counts as a CLAUDE.md, so Claude Code stops reading AGENTS.md. Its docs offer the setting claude-md-and-agents-md for this, or the import.
  • Plain markdown in .cursor/rules. Cursor ignores files without the .mdc extension.

Instruction files also have a size cost and a limit on what a rule can do. See CLAUDE.md too long for what to move out of the file.

With cachly

Rule files hold what you write down. Lessons from fixes, with the cause and the dead ends, grow faster than a file should. cachly keeps those in a memory that all these tools read, next to your rule files. The walk-through is in one memory for Claude Code, Cursor and Copilot. If MCP tools do not show up in VS Code, see the checklist.

Frequently asked questions

Can I keep both .claude and .github folders?

Yes. They do not collide: .claude/ holds Claude Code's rules and settings, .github/ holds Copilot's instructions and hooks. What collides is the content. If the same rule sits in both places with different wording, each tool follows its own copy.

Which file wins when two disagree?

There is no answer that holds across tools. The VS Code docs say not to rely on a universal precedence order, because combination rules differ by harness. Remove the duplicate instead of ranking it.

Should I symlink CLAUDE.md to AGENTS.md?

On macOS and Linux it works. If anyone on the team uses Windows, use the @AGENTS.md import instead: the Claude Code docs say a committed symlink can be checked out there as a one-line text file.

Sources

All read on 21 November 2026.

More: CLAUDE.md too long · Cursor Memories removed · All docs