GitHub Copilot Ignoring Your Instructions? Diagnose the File, Scope, and Session

Short answer. “Copilot is ignoring my instructions” is five different problems that look the same from the chat window. In the order they are usually found: the file was never discovered (wrong name, wrong place, or a type this client does not read); the environment is still running on the old copy — in Copilot CLI, edits are not picked up by a running session; a path-specific file’s applyTo does not match the file you are editing; the file was read and the rule is not one a model can act on; or two files in scope disagree. Each has a check that produces evidence, and the checks are cheap. Start with discovery, because everything after it assumes the file was read.

The diagnostic guide below turns your environment, file type and symptom into an ordered checklist. It runs in this page and asks for nothing about your repository.

Facts about what each client reads were taken from GitHub’s documentation on 16 September 2026 and are linked where they are used. They change; if a statement here and your client’s own documentation disagree, the client’s is current.

Diagnostic guide

Three answers, one checklist. This does not read your files or run Copilot; it orders the checks and names what you still have to look at.

Is the file discovered?

Nothing else matters until this is settled, and it is the check most people skip because the file is right there in the editor. Being open in your editor is not the same as being read by Copilot.

Name and location, exactly. The repository-wide file is .github/copilot-instructions.md: the .github directory at the repository root, a hyphen, the .md extension. Path-specific files live in .github/instructions/ — subdirectories are allowed — and must end in .instructions.md. Agent files are AGENTS.md, which may be anywhere in the tree, or a single CLAUDE.md or GEMINI.md at the root. A copilot_instructions.md, a file at the root without .github/, or a .instructions.md file outside that directory is not an instruction file; it is a Markdown file.

A type this client reads. GitHub’s support reference lists, per client, which instruction types Copilot Chat uses, and the lists are not the same. The table below reproduces the Chat rows. The two that surprise people: Copilot Chat on GitHub.com reads personal, repository-wide and organization instructions — path-specific files and AGENTS.md are read there by the cloud agent and code review, not Chat — and Copilot Chat in Eclipse reads only the repository-wide file.

Evidence that it was read. Every environment gives you one.

• VS Code, Visual Studio, JetBrains, Xcode, Eclipse: expand the references at the top of a Chat response. GitHub’s documentation says the instruction file is added as a reference whenever it is used. VS Code’s own troubleshooting advice is the same — “verify the References section in the chat response” — and adds three settings to check if it is missing: chat.includeApplyingInstructions for pattern-based files, chat.includeReferencedInstructions, and chat.useAgentsMdFile for AGENTS.md (chat.useClaudeMdFile is the equivalent for CLAUDE.md).
• JetBrains also has a Customizations editor — the settings icon in the Chat panel — that lists the workspace and personal instructions the IDE sees.
• GitHub.com: start a conversation with the repository attached, ask anything, expand the references.
• Copilot CLI: run /instructions. It lists every instruction file the session discovered and lets you enable or disable each. A file absent from that list was not read, and no amount of rewording will change that.

Illustrative, not a real transcript — the shape of a /instructions listing:

> /instructions
Instruction files discovered for this session:
  [x] ~/.copilot/copilot-instructions.md
  [x] .github/copilot-instructions.md
  [x] .github/instructions/api.instructions.md   (applyTo: src/api/**)
  [ ] AGENTS.md   (disabled)

If the file is listed, discovery is not your problem and you can skip to whether it is followed. If it is not, the cause is in this section or the next one.

Does your environment need a fresh session?

This is the whole cause more often than seems reasonable, and it is specific to one environment.

Copilot CLI does not reload instruction files in a running session. GitHub’s CLI documentation is explicit: changes to custom instruction files “are not immediately available for use in active CLI sessions.” To apply an edit, exit the session and either resume it — copilot --continue — or start a new one. Then run /instructions again. If you have been editing the file and re-asking in the same session, every test you ran was against the old copy, and the file may have been right for the last twenty minutes.

Illustrative sequence, not a recorded one:

$ copilot
> /instructions          # file is missing or stale
> /exit
$ copilot --continue
> /instructions          # the new file is listed

Everywhere else, GitHub states the instructions are available “as soon as you save the file.” If a response after the edit still does not reference the file, look for the ordinary reasons a saved file is not the one being read: an unsaved buffer, a different branch or worktree, a workspace opened at a subdirectory so .github/ is not at the workspace root, or — on GitHub.com — a conversation that does not have the repository attached.

Is a path-specific file matching?

A path-specific file applies only where its applyTo glob matches the file Copilot is working on. This produces the symptom “it works in some files and not others”, which is not Copilot being inconsistent; it is the pattern doing what it says.

Check three things. First, that the frontmatter exists and is the first thing in the file:

---
applyTo: "src/api/**/*.ts"
---
Every handler in this directory validates its input with the shared schema
helper before touching the database.

Second, that the glob matches the full relative path of the file you are editing. src/*.ts does not match src/api/handlers/user.ts; src/**/*.ts does. Multiple patterns are comma-separated. Third — VS Code specifically — that the file has an applyTo at all: VS Code’s documentation says a .instructions.md file without one “is not applied automatically”, though it can still be attached to a request by hand.

When both a path-specific file and the repository-wide file apply, GitHub states that “the instructions from both files are used.” A rule that holds in one directory and not another is therefore usually a path-specific file you did not know was there, adding to or contradicting the repository-wide one in that directory. List .github/instructions/ before assuming anything.

Nested AGENTS.md files produce the same symptom by a different mechanism. GitHub’s repository-instructions documentation says that when Copilot is working, “the nearest AGENTS.md file in the directory tree will take precedence.” In VS Code, nested files are behind chat.useNestedAgentsMdFiles, marked experimental. If a subdirectory has its own AGENTS.md, that is the one applying there.

Copilot CLI reads path-specific files the same way — “included only when their applyTo value matches a file that Copilot CLI is working with” — but treats the rest differently, which the conflict section covers.

Discovered is not followed

The file is in the references list, or /instructions shows it, and the output still does not do what the rule says. Now, and only now, the file’s contents are the question.

Test one rule you can verify. Move the real file aside and replace it with a single rule that has a right and a wrong answer — a mandatory comment at the top of every generated function, a forbidden import, a specific rounding rule — and ask for something the rule must affect. If the one-rule file works, your original file is the problem, and the way to find the failing part is to add rules back a few at a time. If the one-rule file does not work with the file listed as used, collect that exact request and response; it is the evidence any further troubleshooting needs.

Illustrative one-rule file:

Every function you generate begins with a comment line reading
`// reviewed: no` so that reviewers can find unreviewed code.

Then ask for any function. Either the comment is there or it is not.

Check the rule is something a model can act on. Instructions to be “careful”, “follow best practices” or “write clean code” change nothing you can observe, because nothing observable follows from them. A followable rule has a condition and an effect: when X, do Y. The copilot-instructions lesson is built around writing exactly that kind of rule. Length matters too: VS Code’s guidance is to keep instructions “concise and focused”, and a long file of general advice is the most common shape of “discovered but not followed.”

Check whether the model had a stronger signal. Instructions are added to the request; they do not override the code that is open, the selection, or the prompt itself. A rule that says “use tabs” in a file that uses spaces, with a prompt that asks to “match the surrounding style”, has been contradicted by two things closer to the task. This is not a fault; it is the reason the next section exists.

Are instructions conflicting?

More than one set of instructions can apply to one request: personal, repository-wide, path-specific, agent files and organization instructions. Each was written on a different day for a different reason, and a rule in one can contradict a rule in another.

GitHub.com and the IDEs. GitHub’s documentation states an order — “Personal instructions take the highest priority. Repository instructions come next, and then organization instructions are prioritized last” — and then, in the same note, that “all sets of relevant instructions are provided to Copilot.” Read both halves. The order is a statement about priority, not a promise that a lower-priority contradiction is discarded; the model still sees it. GitHub’s own advice is to avoid providing conflicting instructions, and that is the fix: find every file in scope, read them side by side, and remove the contradiction rather than relying on the order to settle it.

Copilot CLI. Different, and worth quoting because it is often misdescribed. The CLI “combines their instructions”, removes duplicate copies of identical files, “but does not define a general precedence order between these files.” There is no nearest-wins, no personal-beats-repository, no ranking. Two contradictory rules in two discovered files are both in the prompt. Resolve it in the files, or use /instructions to disable one for the session and see what changes. copilot --no-custom-instructions disables loading altogether, which is the fastest way to prove whether any instruction file is the cause of a behaviour.

excludeAgent. A path-specific file can carry excludeAgent: "code-review" or excludeAgent: "cloud-agent" in its frontmatter, which withholds it from that feature deliberately. If the symptom is “code review ignores this file” and nothing else does, this is the one-line cause.

What each environment reads

The Copilot Chat rows from GitHub’s support reference, read on 16 September 2026. Cloud agent and code review have their own rows on that page; on GitHub.com, in particular, they read path-specific and agent files that Chat does not. Check the reference for the feature you are using, not only the client.

GitHub.com’s Chat row also lists organization instructions; VS Code reads them when github.copilot.chat.organizationInstructions.enabled is set, per VS Code’s documentation. The IDE compatibility tool tracks the wider feature matrix per editor.

The checks in one table

Frequently asked questions

Does a longer, more detailed instruction file work better? Usually worse. Short, specific, followable rules are what the one-rule test rewards, and “concise and focused” is the documented advice. Detail that a model cannot act on is noise the real rules have to compete with.

Can I see the exact prompt Copilot sent, including my instructions? Not as a documented feature in these clients. What you can see is whether the file was referenced (IDEs, GitHub.com) or discovered (/instructions in the CLI). Treat that as the boundary of what you can prove.

I have AGENTS.md and .github/copilot-instructions.md. Which wins? In the CLI, neither: they are combined with no precedence. On GitHub.com and in the IDEs, GitHub documents priority between personal, repository and organization instructions, and nearest-wins between nested AGENTS.md files, while stating all relevant sets are provided. If they disagree, fix the disagreement.

Does the file apply to code completions? The support reference lists instruction types for Chat, cloud agent and code review. If your symptom is in inline completions, you are testing a feature the reference does not list for instruction files, and the one-rule test should be run in Chat instead.

Why does it work on my machine and not a colleague’s? Different client, different rows of the table; or a personal instruction on one account; or /instructions disabled a file in one session; or, in VS Code, a setting such as chat.useAgentsMdFile differs. Compare the references list on both machines for the same request.

Is there a size limit? GitHub’s drafting guidance for repository instructions suggests keeping them short — the prompt it provides for generating a file asks for no more than two pages — but that is guidance for writing, not a documented hard limit this article can state. Length is a followability problem before it is a limit problem.

Recap and next step

Discovery first: the exact name and place, a type this client reads, and the references list or /instructions as proof. Then the session, if you are in the CLI. Then scope: applyTo against the full path, and nearest AGENTS.md. Only then the rule itself — one verifiable rule at a time — and finally the other files in scope, combined in the CLI and prioritised everywhere else.

If you have worked through this and want the fastest route to a file that demonstrably changes an answer, the first-instruction-file session builds a minimal one from a verifiable rule, checks discovery, and tests it — about twenty-five minutes, from the copilot-instructions and CLI custom instructions lessons. For path-specific files and applyTo patterns, the custom instructions lesson goes further than this article needed to.