Step-by-Step Playbook: Roll Out VS Code's New AGENTS.md + CLAUDE.md Stack Without Prompt Drift

VS Code's custom-instructions docs were updated on July 15, 2026 with a much clearer explanation of how instruction files now stack:

project-wide .github/copilot-instructions.md
one or more AGENTS.md files
optional CLAUDE.md compatibility
scoped *.instructions.md files
optional organization-level instructions

If your team already uses more than one coding agent, that sounds great until everyone starts stuffing the same rules into three files and then wondering why prompts drift. The playbook below keeps the setup boring on purpose.

Step 1: Start with one always-on file, not three

If you only change one thing this week, make it a single workspace-level instructions file. VS Code still recommends beginning with .github/copilot-instructions.md for project-wide standards. That gives you one obvious place for rules that really should apply everywhere: framework choices, testing requirements, naming conventions, and "never do this" guidance.

Keep it short. If a rule is already enforced by linting or formatting, leave it out. The new docs are blunt about that: instruction files work better when they explain non-obvious preferences and the reasoning behind them.

A good first file looks more like this than a manifesto:

- Use Server Components by default in app routes.
- Put network calls behind shared data helpers.
- Add tests for branching business logic.
- Avoid date libraries unless the repo already depends on one.

Step 2: Add `AGENTS.md` only if you actually run multiple agents

The new VS Code docs make AGENTS.md useful for teams that switch between multiple AI coding tools and want one shared instruction source. That's the real value: not more rules, but fewer duplicated rules.

If your repo already has a strong .github/copilot-instructions.md, don't clone it line for line into AGENTS.md. Put only the cross-agent rules there, then let Copilot-specific guidance stay in the Copilot file.

The lazy split is:

AGENTS.md: rules every coding agent should follow
.github/copilot-instructions.md: Copilot-specific workflow preferences
everything else: stay out until a real conflict appears

Step 3: Use nested `AGENTS.md` files only for real monorepo boundaries

VS Code now has an experimental chat.useNestedAgentsMdFiles setting that recursively finds subfolder AGENTS.md files. That's useful, but it is also the fastest path to invisible instruction conflicts if you enable it too early.

Turn it on when the repo already has genuine boundary lines, like:

apps/web and apps/api with different runtime constraints
a mobile app that needs a different testing policy than the backend
generated code folders that need strict do-not-edit guidance

Don't turn it on just because you can. If a repo is small enough that one senior engineer can explain the rules in a minute, one root file is still cheaper.

Step 4: Use `CLAUDE.md` as a compatibility bridge, not a second policy document

One of the genuinely useful July changes is that VS Code now detects CLAUDE.md files too, including root, .claude/CLAUDE.md, home-directory, and local-only variants. That matters if your team moves between VS Code, Claude Code, and other Claude-based tools during the same week.

The mistake to avoid is treating CLAUDE.md like a parallel source of truth. Keep it as a bridge file for shared instructions, or point it at the same conventions your repo already uses. Duplicating policy in both files buys you drift, not portability.

Step 5: Put narrow rules in `*.instructions.md`, not in the root files

Scoped instruction files are still the cleanest answer for framework- or folder-specific behavior. If only your migrations folder needs special handling, or only your React surfaces need accessibility rules, keep those rules attached to matching files instead of promoting them to global policy.

That's especially important now that VS Code can combine more instruction sources. Global files should answer "how this repo works." Scoped files should answer "how this slice works."

Step 6: Debug instruction problems before rewriting the files

Two recent VS Code additions help here. The custom-instructions docs point to diagnostics so you can see which files were loaded and whether pattern matching failed. VS Code 1.127 also added /troubleshoot for agent sessions, including cases where custom instructions seem to be ignored.

Use that before you start rewriting prompts. Most bad outcomes come from one of four boring causes:

The file is in the wrong location.
The glob pattern doesn't match the file being edited.
The setting for AGENTS.md or CLAUDE.md support is off.
Two files say similar things with different wording.

Step 7: Keep organization-level instructions thin

VS Code now supports organization-level instruction discovery too. That's useful for compliance rules, security requirements, or shared delivery conventions across repos. It is not a great place for framework trivia or repo-specific style debates.

The priority order matters: personal instructions win, repository instructions sit above organization instructions, and conflicting guidance will follow that stack. So keep org-level content broad and stable, then let repositories stay opinionated where they need to.

The Monday-Morning Setup

If you want the shortest rollout that still scales, do this:

Create or clean up .github/copilot-instructions.md.
Add a root AGENTS.md only if multiple coding agents are normal in the repo.
Enable nested AGENTS.md only for monorepos with real boundaries.
Add CLAUDE.md only when cross-tool compatibility is a real need.
Push special-case rules into *.instructions.md.
Use diagnostics and /troubleshoot before changing the policy again.

That is enough structure to get consistency without turning your prompt layer into another configuration system.

References

Image credit: ["Visual Studio Code Editor"](https://www.flickr.com/photos/12882975@N00/37032450042) by kenming Wang, licensed [CC BY-SA 2.0](https://creativecommons.org/licenses/by-sa/2.0/).