CLAUDE.md, Cursor rules and Copilot instructions: one source for all of them
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.
The four files
Section titled “The four files”| 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.
How drift happens
Section titled “How drift happens”- Someone fixes a wrong instruction in
CLAUDE.mdand forgets the Cursor rule. - A new rule is added to
copilot-instructions.mdbecause 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.
One source
Section titled “One source”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.mdthat importsAGENTS.md(one line, so Claude Code reads the same text); - a
.cursor/rules/groundrule.mdcwith the general rules and one.mdcper group of path-scoped rules, with the rightglobs; - a
.github/copilot-instructions.mdblock and one.instructions.mdper path group, withapplyTo.
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.
The check that keeps it true
Section titled “The check that keeps it true”Generation alone is not enough; someone will edit a generated file by hand. Two things close the loop:
npx @groundrule/cli sync --checkfails 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.- 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 ifaxiosis imported, whichever agent or person wrote it. See How to enforce coding standards on AI-generated code in CI.
Start from what you have
Section titled “Start from what you have”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.