Skip to content
Open the dashboard
Documentation

CLAUDE.md, Cursor rules and Copilot instructions: one source for all of them

Engineering leadsDevelopers7 min read

A team using Claude Code, Cursor and GitHub Copilot keeps four instruction files: AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc and .github/copilot-instructions.md. Each tool reads its own, each is edited by whoever noticed a problem that week, and within a quarter they disagree. The only arrangement that stays correct is one source of standards from which all four are generated, and a check in CI that fails when a generated file is stale.

File Read by Scoping Format
AGENTS.md Codex, Cursor, Copilot, Claude Code (when no CLAUDE.md) Nearest file in the tree Plain Markdown
CLAUDE.md Claude Code Root plus subdirectories; @path imports Plain Markdown
.cursor/rules/*.mdc Cursor Per file, by globs, description or alwaysApply in the frontmatter Markdown with YAML frontmatter
.github/copilot-instructions.md and .github/instructions/*.instructions.md Copilot coding agent, code review, Chat Repository-wide, or per path with applyTo Markdown, frontmatter for the per-path files

The formats differ in one way that matters: Cursor and Copilot can scope a rule to a set of files, AGENTS.md and CLAUDE.md cannot. A rule like “handlers in src/api/handlers never import the database” belongs in a scoped file for the tools that support it and in the general file for the tools that do not.

  • Someone fixes a wrong instruction in CLAUDE.md and forgets the Cursor rule.
  • A new rule is added to copilot-instructions.md because Copilot was the agent that broke it; the other three never hear of it.
  • A rule is deleted in one file because it was wrong, and survives in the others for a year.
  • Nobody reviews changes to these files with the care given to code, because they are “just docs”.

None of this is carelessness. Four hand-maintained copies of one thing always diverge.

Keep the standards in one place, in a form a tool can read, and generate the four files from it. Each standard says what the rule is, why, how to comply, which files it applies to, and how serious a break is. The generator writes:

  • the general rules into AGENTS.md;
  • a CLAUDE.md that imports AGENTS.md (one line, so Claude Code reads the same text);
  • a .cursor/rules/groundrule.mdc with the general rules and one .mdc per group of path-scoped rules, with the right globs;
  • a .github/copilot-instructions.md block and one .instructions.md per path group, with applyTo.

Your own content in AGENTS.md, CLAUDE.md and copilot-instructions.md stays; the generator owns a marked block, not the file.

This is npx @groundrule/cli sync. The standards live in .groundrule/standards/*.yaml, or in a shared rulebook when the repository is connected to a workspace. Agent instruction files documents every file and the exact block.

Generation alone is not enough; someone will edit a generated file by hand. Two things close the loop:

  1. npx @groundrule/cli sync --check fails when any generated file differs from what the standards would produce. Run it in CI on every pull request; the GitHub Action does by default.
  2. The same standards are checked on the code, not only taught to the agent. A rule that says “no axios” is also a deterministic check that fails the pull request if axios is imported, whichever agent or person wrote it. See How to enforce coding standards on AI-generated code in CI.

If the four files already exist, do not retype them. npx @groundrule/cli scan --upload reads the instructions in AGENTS.md, CLAUDE.md, Cursor and Copilot files and turns them into proposals you accept or reject, with the file each one came from; see Scans. Accepted proposals become standards, and the next sync rewrites the four files from them.