Why does Copilot ignore copilot-instructions.md?

How do I check whether Copilot used my instructions?

Before you rewrite a line, find out whether Copilot saw it. Each surface has its own check:

• Copilot Chat (GitHub.com and VS Code): expand the References list at the top of the answer and look for .github/copilot-instructions.md. VS Code's docs are careful about what that proves: it checks inclusion, not compliance.
• VS Code, in detail: the Chat Debug view shows the request that was sent, including which instruction files were attached. Turn logging on before you reproduce the problem.
• Copilot CLI: /instructions lists the instruction files the session found and whether each one loaded.
• Code review: Copilot reads instructions from the head branch of the pull request, the one with your changes. So you can edit the file in the same pull request and request a new review to test it.

Why is Copilot not reading copilot-instructions.md?

• You are looking at inline suggestions. The grey text that appears as you type does not use custom instructions. VS Code's docs say so directly. Instructions reach Chat, agent mode, the cloud agent, the CLI and code review, each in its own way.
• That surface does not read that file. The support matrix differs by product. Copilot Chat on GitHub.com reads repository-wide and organization instructions but not .github/instructions/*.instructions.md: on GitHub.com, path-specific files reach only the cloud agent and code review. Code review in VS Code and Visual Studio reads only the repository-wide file. In Eclipse, code review reads none.
• A setting is off. In VS Code, github.copilot.chat.codeGeneration.useInstructionFiles controls copilot-instructions.md, chat.includeApplyingInstructions controls matching .instructions.md files, and chat.useAgentsMdFile controls the root AGENTS.md. On GitHub.com, a repository admin can turn off “Use custom instructions when reviewing pull requests” under Settings, Copilot, Code review.
• The applyTo never matches. There is no default pattern. The glob is relative to the repository root, not to .github/instructions/, so applyTo: "*.ts" matches only TypeScript files at the root; you want "**/*.ts". In VS Code, a file with neither applyTo nor a description is only attached when you add it by hand.
• It is a nested AGENTS.md. VS Code reads the one at the workspace root. Discovering nested files is experimental and off by default, behind chat.useNestedAgentsMdFiles. The cloud agent does read AGENTS.md anywhere in the repository; how each agent handles these files is in AGENTS.md vs CLAUDE.md.
• Your Copilot CLI is old. Two loading bugs were fixed this year. Before v1.0.36 the CLI skipped every instruction file under .github/ when that folder was gitignored, with nothing in the logs (#1981). The user-level ~/.copilot/copilot-instructions.md was listed but not loaded (#2179, #1827). Both are closed as fixed. Update before you debug further.

Why does Copilot ignore instructions it loaded?

Because they are text in the prompt, and the model weighs them against everything else it was given. VS Code's docs say it plainly: instructions guide the model and do not guarantee compliance. GitHub's code review docs add that Copilot will not catch every problem. A rule that holds in most sessions can still lose to a long task.

Conflicts make it worse. GitHub gives Copilot every set of relevant instructions at once: personal first in priority, then repository, then organization, plus every path-specific file that matches. Two files that disagree both reach the model. Copilot's own system instructions count too. In #3552 (open), a repository rule said never to commit on its own; the CLI committed anyway, and its explanation pointed to a commit trailer in its system instructions. The user put the rule's hit rate at about 95% by their own estimate.

The fix for a conflict is to delete one side. A third line explaining which one wins is one more thing to weigh. For vague rules, the same docs suggest clarifying one rule, repeating the task in a new chat, and comparing what changed.

Causes, checks, and fixes

How do I make Copilot always follow a rule?

Move it out of the prompt. Copilot CLI and the cloud agent run hooks from .github/hooks/*.json in the repository. A preToolUse hook runs before each tool call and can refuse it by printing JSON with permissionDecision: "deny" and a reason. If any hook denies, the call is blocked:

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "./.github/hooks/no-commit.sh",
        "timeoutSec": 30
      }
    ]
  }
}

A hook that crashes or exits non-zero also denies; a hook that times out lets the call through. The cloud agent runs a subset of the events. The full contract is in GitHub's hooks reference. Inline suggestions and Chat on GitHub.com have no hooks, so for those the backstop is the same as for people: a linter, a formatter and CI.

Everything else stays prose, and prose works best short and concrete: “Run pnpm test before committing”, not “test your changes”, with nothing a linter already enforces. Check your rule files runs that test on yours. The same problem in other agents is covered in why Claude ignores CLAUDE.md and why Codex ignores AGENTS.md.

Where Harbor fits

Several causes above come from one design: a set of files per product, each read by some surfaces and not others, where nothing tells you which rule reached the model. Harbor serves Copilot the decisions your team made, picking the ones that apply to the task. harbor init installs it for Copilot CLI and VS Code's agent mode (the cloud agent is not supported yet), and any MCP client can search the same facts. Answers cite the facts they used, and Harbor counts, per fact, how often it was served and how often it was cited. A cite is evidence that a rule was used, not proof that it was obeyed; the method is in served vs cited.