October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsSlow PC?RecommendedPC slow today? Run a repair scan before it gets worseResolve common Windows issues and optimize system performance.Scan NowOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
World desk4 min

What to Do When AGENTS.md Instructions Conflict

There is no universal AGENTS.md precedence rule. Learn how to check the active harness, apply its documented behavior, and resolve conflicts it leaves ambiguous.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

When AGENTS.md instructions conflict, first identify which agent harness and session type is running: there is no universal precedence rule. Codex documents a specific hierarchy; GitHub Copilot CLI combines applicable instructions without defining a general winner; VS Code warns that discovery and merging vary by harness. Follow a documented rule for the tool you are using, and if none exists, reconcile the files or ask their owner to clarify.

Why the answer depends on the agent

AGENTS.md is not governed by one cross-tool standard. Codex, GitHub Copilot CLI, Copilot on GitHub, and VS Code can discover and combine instruction files differently. Even within VS Code, behavior can depend on whether the session uses the Local agent or an Agent Host harness. Before deciding which instruction wins, establish the exact tool and session type.

As an Amazon Associate I earn from qualifying purchases.

For VS Code, nested AGENTS.md discovery by the Local agent is experimental and disabled by default unless enabled with chat.useNestedAgentsMdFiles. Agent Host sessions follow the selected harness’s rules. See VS Code’s custom-instructions documentation.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

How the main tools handle conflicting instructions

Tool or feature Documented behavior What to do when instructions conflict
Codex Combines project instruction files from repository root down to the current working directory; closer project files override earlier project guidance when they conflict. Direct system, developer, or user prompt instructions take precedence over AGENTS.md. Use Codex’s documented scope and ordering, while honoring higher-priority direct prompt instructions.
GitHub Copilot CLI Combines applicable user-level and repository instruction files, but does not specify a general precedence order among them. Do not infer a winner from file location or order. Resolve the contradiction in the instructions or ask their owner.
Copilot on GitHub For Copilot working on GitHub, the nearest AGENTS.md takes precedence; repository-wide and matching path-specific instructions can also apply. Apply this behavior only to that GitHub feature, not automatically to other Copilot sessions.
VS Code Discovery and merge behavior can differ by session type and harness. VS Code advises against relying on file order or a universal precedence rule. Confirm the active session type and selected harness; use that harness’s documented behavior.

For Codex’s published precedence statements and current configuration details, consult OpenAI’s Introducing Codex and AGENTS.md configuration guide. For Copilot CLI and Copilot on GitHub, see the relevant CLI instructions documentation and GitHub repository-instructions documentation.

Resolve the conflict step by step

  1. Identify the harness and session

    Record whether you are using Codex CLI, GitHub Copilot CLI, Copilot on GitHub, or a VS Code Local or Agent Host session. Do not treat one product’s behavior as a rule for another.

  2. Check which files the harness can discover

    Map the instructions that apply to the task: global or user-level files, repository-root files, nested files along the working path, and any path-specific instruction files. A file that exists but is not discovered cannot resolve the active session’s behavior.

    In Codex, check the global Codex home and each project directory from repository root through the current working directory. Codex checks AGENTS.override.md before AGENTS.md at each directory, and may use configured fallback filenames. It stops at the current directory rather than searching deeper unrelated folders. The configuration guide specifies a default combined project-instructions limit of 32 KiB, so content beyond the configured limit may not be included.

    Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

    Copilot CLI searches standard locations including repository root, the current working directory, intermediate directories, and directories nested along the path of a file it is working on. Matching *.instructions.md files apply when their applyTo pattern matches. Check the CLI documentation for the applicable locations and patterns.

  3. Apply only a documented precedence rule

    In Codex, project instructions are concatenated from root to the current directory, and closer project guidance overrides earlier project guidance when they conflict. OpenAI’s published Codex system-message text also states that direct system, developer, or user instructions take precedence over AGENTS.md.

    For Copilot CLI, the documentation says applicable instruction files are combined but does not establish a general precedence order. For VS Code, do not use file order as a substitute for a documented rule. Copilot on GitHub’s nearest-file behavior is specific to that feature.

  4. Remove ambiguity if no winner is defined

    Edit the relevant instructions so they agree, or ask the person responsible for them which behavior is intended. If a rule should apply only to one area, scope it with a mechanism the selected harness supports, such as an applicable path-specific instruction file. VS Code recommends keeping user, repository, and organization requirements consistent.

    Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  5. Verify discovery and behavior

    Confirm which files were loaded, then test a representative task to see whether the intended rule is followed. For Codex, the documentation suggests asking it to report its instruction sources and auditing session logs when needed. In Copilot CLI, use /instructions to view discovered files and enable or disable individual ones. VS Code notes that confirming a file was discovered does not prove the agent followed it; a representative task checks that separately.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Codex details that can explain a surprising result

  • One selected file per directory: At each project directory Codex includes at most one instruction file, preferring AGENTS.override.md, then AGENTS.md, then configured fallback filenames. In the global scope, a non-empty AGENTS.override.md replaces AGENTS.md; only the first non-empty file is used at that level.
  • Instructions are assembled at startup: Codex builds its instruction chain when it starts; in a TUI this usually happens once per launched session. After changing the working directory or instructions, start a fresh run or session if the active set may be stale.
  • Scope ends at the working directory: Codex does not search into deeper, unrelated directories. A more deeply nested file matters only when the task’s working path brings it into scope.

Keep the evidence and expectations in proportion

Official documentation explains how these tools discover and handle instructions, but it does not establish how frequently AGENTS.md conflicts occur or measure their effects. The practical answer is therefore tool-specific: inspect the active instruction set, apply only a documented precedence rule, and clarify conflicts the harness leaves unresolved.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
Windows Errors? Fix Them Before They SpreadFree repair scan
Crashes, No Sound, or Screen Glitches?Free driver scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.