IDE rules files (Cursor rules, Copilot instructions)

Why you'd careThe problem it solves

An agent does something you did not ask for and cannot find the source of. It refuses to write raw SQL. It insists on a test file naming scheme nobody remembers choosing. You search the repo for the phrase and find it in .cursor/rules/db.mdc, written eleven months ago by someone who has left, with alwaysApply: true at the top. It has been prepended to every request that developer's editor made since. Nobody on Claude Code has ever seen it, which is why two people on the same repo get different behaviour and each assumes the other is imagining things. These files are the installed base. They predate skills, most teams already have them, and they do not announce themselves.

ConceptWhat it is

IDE rules files are per-tool instruction files stored in the repository and loaded by one editor's agent. Two families dominate.

Cursor's project rules are .mdc files under .cursor/rules/, each with frontmatter carrying description, globs and alwaysApply. Those three keys produce four activation modes: always on; auto-attached when the globs match a file in play; agent-requested, where only the description is shown and the model chooses; and manual, where a human references the rule explicitly. The older root-level .cursorrules file still works in places but is the deprecated form. Cursor also has user rules that live in application settings rather than the repo — invisible to everyone else on the team, which is its own class of mystery.

GitHub Copilot's are Markdown too: .github/copilot-instructions.md for repository-wide guidance, plus per-path files under .github/instructions/ ending in .instructions.md, whose frontmatter carries an applyTo glob. Copilot's prompt files, under .github/prompts/, are a different mechanism — invocable, not ambient.

Where the boundary sits: these are conditional context, nothing more. They inject text. They add no capability, bundle no scripts, and have no progressive disclosure — a rule is either fully in the prompt or fully absent. All of the filenames, extensions and frontmatter keys above were read from both vendors' current documentation on 2026-07-25, which reverses an earlier draft that flagged this entry as unverified recall.

How it worksThe mechanics

Cursor first. One rule, one file, frontmatter deciding when it fires:

.cursor/rules/
  api-conventions.mdc
  db.mdc

# --- api-conventions.mdc ---
---
description: How to add an endpoint to the worker API
globs: packages/worker/src/routes/**
alwaysApply: false
---
- Every route registers itself in routes/index.ts.
- Validate the body with the shared zod schema, not by hand.

Read the frontmatter as a truth table. alwaysApply: true means the body is in every request, and the globs are then irrelevant. alwaysApply: false with globs means it attaches when a matching file is in play. Description alone means the model is shown a one-line summary and decides — the same economics as a skill's description field, and the same failure mode when the description is vague. Nothing set means manual reference only.

Copilot's shape is close but not the same:

.github/
  copilot-instructions.md          # repository-wide, no frontmatter
  instructions/
    tests.instructions.md

# --- tests.instructions.md ---
---
applyTo: "**/*.test.ts"
---
Use vitest. Do not import from jest.
Colocate the test beside the file under test.

The consequential difference is that Copilot's per-path files gate on a glob only. There is no model-decides mode and no always-on flag — scope is expressed entirely through applyTo, and applyTo with a match-everything glob is how you get the always-on behaviour.

Two operational facts. First, these files stack: a repo with Cursor rules, a Copilot instructions file and an AGENTS.md will have several tools reading several overlapping documents, and the tool does not tell you which fired. Second, Claude Code reads none of them. A team migrating to skills without deleting the rules ends up running two policies at once, split by which editor each person opened.

At a glanceSee it

How a Cursor rule and a Copilot instructions file decide to fire, silently, alongside your skill.

Where it runsSurfaces and availability

This is still the least portable layer in the catalogue, and the four "Yes" rows are not four ecosystems: they are Cursor plus three faces of Copilot, and even those three disagree with each other — JetBrains takes one file, Visual Studio and VS Code take path-scoped ones. If a rule genuinely matters for correctness, it should not live only here. Move the always-true parts to AGENTS.md and the conditional parts to a skill, then keep the rule file as a thin pointer — or delete it. Claude Code's /init will read your existing Cursor and Copilot rule files once during that migration, which makes the port cheaper than it looks.

ExampleIn the real world

A team standardises on a query builder and bans raw SQL strings. Someone encodes it in .cursor/rules/db.mdc with alwaysApply: true. For the Cursor half of the team it works perfectly for a year.

Then the team adopts skills, and a new db-migrations skill is written for Claude Code. It says the same thing, plus a checklist for reviewing a generated migration. Nobody deletes the rule, because nobody remembers it exists.

Now three behaviours are in play. Cursor users get the rule on every request, whether or not they are near the database. Claude Code users get the skill, but only when the description matches what they typed — so a session that starts "fix this failing test" and drifts into a schema change may never load it. And a Copilot user, whose .github/instructions/ directory nobody updated, gets nothing at all and writes raw SQL that passes review because the reviewer's agent did not flag it either.

The fix is a five-minute grep at the start, not a policy afterwards. List every instruction file in the repo, decide for each one whether it is always-true or conditional, put the always-true ones in AGENTS.md and the conditional ones in a skill, and leave the vendor files as short pointers so the next person finds the real source.

Not thisWhat it is often confused with

• Not a skilla rule is one file of text that is either injected or not. There is no body loaded on demand, no bundled script, no reference directory. If you need the agent to run something, a rule cannot carry it.
• Not AGENTS.mdthese are vendor-specific paths read by one editor each; AGENTS.md is the cross-vendor file. Many tools now read both, which is how a repo ends up sending the same paragraph twice.
• Not prompt filesCopilot's .github/prompts/ entries and Cursor's commands are user-invoked. Rules are ambient. Confusing the two is why people expect a rule to fire on demand and it never does.
• Not enforcementa rule is a suggestion in a context window. A lint rule, a pre-commit hook or a CI check is enforcement, and only the latter survives a model that decided differently.
• Not visible to the teamCursor's user rules live in application settings, not the repository. If your explanation for a behaviour is "it must be a rule" and the repo is clean, look there.

LimitsWhen not to reach for it

• The convention should hold for everyone.Anything correctness-relevant goes in AGENTS.md or CI, not in one editor's rules directory where half the team never sees it.
• The rule is 200 lines and always applies.You are paying that on every request in that editor. Scope it with globs, or turn it into a skill with a description that earns its load.
• You are trying to grant a capability.No amount of instruction text lets an agent reach a database it has no tool for. That is an MCP server or a function tool.
• You are migrating to skills.Do not bulk-delete the rules first. Find out who is still on Cursor or Copilot, port the content, then remove — in that order.
• The behaviour must be identical across the team.These files guarantee the opposite. Pick the layer every one of your harnesses reads and put the rule there.

RelatedGo deeper