BrainStack

Reference · 8 min read · Updated 2026-10-20

GEMINI.md vs CLAUDE.md vs AGENTS.md vs Cursor rules vs Copilot instructions

Which rules file each AI coding tool reads, where to put it, and how to keep one source of truth when you use more than one tool.

Every AI coding tool wants a rules file, and they all picked different names. The good news: the content is basically the same Markdown everywhere. This guide covers where each one goes and how to avoid maintaining five copies.

AI tools update quickly and file conventions keep evolving. This is accurate to the best of our knowledge as of 2026-10-20, but always check your tool's official docs for the latest details.

Quick reference

ToolProject fileNotes
AGENTS.md agents (e.g. OpenAI Codex)AGENTS.md in the repo rootAn open convention meant to work across tools. Nested AGENTS.md files in subfolders can add folder-specific instructions.
Claude CodeCLAUDE.md in the repo rootAlso supports a user-level file for all projects and files in subfolders. Its /init command can draft one from your codebase.
Gemini CLIGEMINI.md in the repo rootAlso supports a global file in your home config folder and files in subfolders. The context file name is configurable.
Cursor.cursor/rules/*.mdcEach rule file has a small frontmatter header controlling when it applies. The older single .cursorrules file is legacy.
GitHub Copilot.github/copilot-instructions.mdRepository-wide instructions. Copilot also supports more targeted instruction files; see GitHub's docs.

Other Gemini-based agents (Google's Antigravity, for example) also work with project rules. One real project we studied kept its core rules in GEMINI.md and topic rules in .agents/rules/*.md. Check your tool's docs for the exact folders it loads automatically.

The Cursor .mdc header

Cursor rule files are Markdown with a YAML frontmatter block on top:

---
description: "Core project rules"
globs:
alwaysApply: true
---

# Project rules
- ...
  • alwaysApply: true: included in every request. Use this for your main brain file.
  • globs: file patterns (like src/**/*.ts) that attach the rule when matching files are involved. Good for scoped rules.
  • description: helps the agent decide when to pull in a rule that isn't always applied.

Global, project, and folder levels

Most tools support layers, from broadest to narrowest:

  1. User or global: your personal preferences for every project ("I use Windows and PowerShell", "explain things simply"). Lives in your home folder or the tool's settings, not in the repo.
  2. Project: the brain file in the repo root. Shared with anyone (and any AI) working on the project.
  3. Folder: extra rules for one part of the codebase, such as a server/ folder with different conventions.

Keep project facts in the project file so they travel with the repo, and personal taste in the global one.

Using more than one tool? Keep one source of truth

Plenty of people use two or three AI tools on the same repo. Copy-pasting the same rules into five files guarantees they drift apart. Better options:

  1. One main file, thin pointers. Put everything in AGENTS.md. In the other files, write one line: "Follow all instructions in AGENTS.md." Some tools also support importing another file directly (Claude Code, for example, supports @path imports in CLAUDE.md).
  2. Configure the file name where the tool allows it. Some tools let you point them at AGENTS.md instead of their default name, and several now read AGENTS.md natively.
  3. Generate them all from the same answers. The Brain File Generator outputs every format from one form, so you can regenerate when rules change.
About symlinks: linking CLAUDE.md to AGENTS.md works on macOS and Linux, but symlinks in git can misbehave on Windows unless they're enabled. Pointer files are the safer cross-platform choice.

What to write in it

The file name matters much less than what's inside. If you haven't written one yet, start with what a brain file is, then pick the guide for your project type.