Instruction Precedence for Coding Agent Repositories

Last reviewed: 2026-07-14

Direct answer

When repository instructions conflict, resolve them by the agent that is actually doing the work, then by that agent’s documented loading order, then by the narrowest file scope that applies to the files being changed. Do not assume that AGENTS.md, CLAUDE.md, and GitHub Copilot custom instructions are interchangeable just because they contain similar rules.

A practical precedence workflow is:

Identify the active coding agent and list the instruction files that agent documents as readable.
Record which file is global, repository-wide, path-specific, or local-only.
Prefer the active agent’s documented order over a team convention when the two disagree.
When two applicable files are both loaded, apply the narrower or later-loaded instruction only to the files it governs.
If the conflict changes security, deployment, secrets, billing, or irreversible repository state, stop and ask for a written decision before continuing.

Smoke-test workflow:

Setup assumptions: the repository has at least one shared instruction file and one agent-specific instruction file; the operator can inspect repository files but does not need credentials.
Happy-path request plan: ask the active agent to summarize the instruction files it loaded, then compare the answer with the documented discovery order for that tool.
Error-path check: create a harmless contradiction in a scratch branch or disposable fixture, such as two different formatting preferences, and confirm the agent follows the narrower documented rule for the matching path.
Minimum assertions: the active agent names the expected instruction source, applies the expected scope, and does not treat another tool’s file as higher priority unless that tool’s documentation says it should.
Pass/fail logging fields: agent_name, repo_path, instruction_files_checked, conflict_type, expected_precedence, observed_behavior, result, follow_up_owner.
Do not assert: hidden platform prompts, private account settings, unobserved memory state, model availability, or behavior for a different coding agent.

Sanitized log template:

agent_name: "<AGENT_NAME>"
repo_path: "<REPOSITORY_PATH>"
instruction_files_checked: ["<FILE_PATH>", "<FILE_PATH>"]
conflict_type: "<SCOPE_OR_RULE_CONFLICT>"
expected_precedence: "<DOCUMENTED_EXPECTATION>"
observed_behavior: "<SHORT_OBSERVATION>"
result: "pass|fail|inconclusive"
follow_up_owner: "<ROLE_OR_TEAM>"

For related repository context work, see How to Write Repository Instructions for Coding Agents .

Who this is for

This guide is for maintainers who run more than one coding agent against the same repository: for example, Codex for terminal or cloud work, Claude Code for long repository sessions, and GitHub Copilot for pull request or agent workflows. It is also useful when a repository has inherited several instruction formats and nobody is sure which one should be treated as authoritative.

Key takeaways

Codex documents an AGENTS.md discovery chain that includes global guidance, project guidance, and directory-level overrides.
Claude Code documents CLAUDE.md as its project instruction mechanism, and says repositories that already use AGENTS.md can import it from CLAUDE.md.
GitHub Copilot documents repository-wide, path-specific, and agent instruction files, including AGENTS.md behavior for Copilot agents.
A team-owned precedence note should name the active agent, the files it reads, and the conflict policy for security-sensitive work.
A passing check proves only the observed repository and agent configuration, not every tool version or private account setting.

Failure modes

Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.

Sources checked

OpenAI Codex AGENTS.md guidance - accessed 2026-07-14; purpose: verify repository instruction-file context for coding agents.
Claude Code memory documentation - accessed 2026-07-14; purpose: verify project memory and instruction-file context for agent workflows.
GitHub Copilot repository instructions documentation - accessed 2026-07-14; purpose: verify repository instruction guidance.

Contract details to verify

Area	What to verify	Source URL	Accessed	Safe candidate wording
Codex file discovery	Which `AGENTS.md` files Codex reads and how later, closer files affect earlier guidance.	https://developers.openai.com/codex/guides/agents-md	2026-07-14	“Codex uses its documented `AGENTS.md` discovery order; closer project files can override earlier guidance.”
Claude Code instruction files	Whether Claude Code reads `CLAUDE.md`, and how teams can connect it to `AGENTS.md`.	https://code.claude.com/docs/en/memory	2026-07-14	“Claude Code uses `CLAUDE.md`; a repository can import `AGENTS.md` into that file when teams want shared guidance.”
GitHub Copilot instruction types	Which repository-wide, path-specific, and agent instruction files Copilot documents.	https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions	2026-07-14	“Copilot can use repository custom instructions, path-specific instructions, and agent instruction files according to GitHub’s documented rules.”
Conflict handling	Whether the tool docs define the exact conflict your repository has.	https://developers.openai.com/codex/guides/agents-md	2026-07-14	“If the exact conflict is not documented, record a team decision instead of guessing.”

Reader next step

Compare the workflow against Start with CometAPI .

FAQ

Should every coding agent use the same instruction file?

Not always. A shared file can reduce drift, but each tool documents different loading behavior. Use a shared source only when the active tool supports it directly or through an explicit import.

Is `AGENTS.md` always higher priority than `CLAUDE.md`?

No. Priority depends on the active tool. Codex documents AGENTS.md discovery. Claude Code documents CLAUDE.md and describes importing AGENTS.md when a repository already uses it.

What should a team do when two instruction files disagree?

First decide which tool is running. Then apply that tool’s documented scope and order. If the conflict affects security, deployment, secrets, or account state, stop and capture a written decision before making changes.

Can a smoke test prove how every agent will behave?

No. It can only verify the observed repository setup, tool, and request path. Keep the result scoped to what was actually checked.