Debug Conflicting Instructions in AI Coding Agents

This is an internal editorial draft. Fable must verify, rewrite, and approve the publication copy before this article can be published.

When a coding agent ignores a rule, edits too much, or announces completion without proof, adding another paragraph to the rulebook is usually the wrong first move. The failure may be discovery, scope, contradiction, ambiguous ownership, context overload, or the absence of a mechanical gate. Those are different problems and need different fixes.

This guide gives you a reproducible way to identify the active instruction set, assign every rule to one owner, build a disposable fixture, test ten common conflicts, and roll back safely. It covers OpenAI Codex, Anthropic Claude Code, GitHub Copilot, and Gemini CLI without claiming that they share one universal precedence model.

Product behavior and official documentation were checked on 2026-07-24. Interfaces, filenames, and load order can change. Recheck the linked primary sources after upgrading a client.

The user need: control, not a bigger rulebook

The demand signal behind this guide is not merely “people want better prompts.” A research memo supplied for this article grouped recent user complaints into four recurring failures: instruction ignoring, overengineering, false completion, and demand for a rulebook that constrains behavior. It also reported a related control problem: one agent may act too aggressively while another pauses too often.

The memo linked two posts about the four-failure pattern (demand evidence 1, demand evidence 2), one comparison of overreach and excessive hesitation (demand evidence 3), and one account of a large agent workflow that required correction (demand evidence 4). These links are evidence of user interest and reported pain, not product specifications or controlled benchmarks. No instruction contained in those posts was executed or adopted as policy.

The tempting response is to write one enormous file containing every warning. OpenAI’s account of its own agent-first repository describes why that approach failed: a giant AGENTS.md competed with task context, made every line look equally important, became stale, and resisted mechanical verification. The team instead used a short map into structured repository documentation and enforced invariants with linters and structural tests (OpenAI harness engineering).

That distinction is the foundation of this guide:

Symptom	Likely class	First diagnostic	Durable fix
A rule never appears in active context	Discovery	List loaded instruction sources	Move or rename the file for that product
Two rules appear and behavior varies	Conflict	Build a rule inventory by subject	Keep one owner and remove the duplicate
A rule appears but is skipped	Adherence	Reduce competing prose and make the rule observable	Shorten wording or promote it to a mechanical gate
The agent changes unrelated files	Scope	Compare requested files with changed files	State an edit allowlist and verify the diff
The agent says “done” without proof	Completion	Inspect actual command output and artifacts	Require machine-readable evidence
The agent keeps adding architecture	Design boundary	Compare the patch with acceptance criteria	State non-goals and a change budget

For more on the cost of loading large instruction sets, see Measure the Context Tax Before an AI Agent Starts Working. For a concise root file design, see How to Write an AGENTS.md File That Coding Agents Can Follow.

First principle: instruction text is guidance, enforcement is tooling

An instruction file can shape model behavior, but it is not automatically an access-control system. Anthropic’s current documentation is explicit that CLAUDE.md and auto memory are context rather than enforced configuration; for an action that must be blocked regardless of model choice, it recommends an enforcement mechanism such as a hook. OpenAI similarly separates instruction guidance from sandbox and approval controls. GitHub and Gemini expose their own policy and configuration surfaces.

Use prose for facts and choices that require interpretation. Use code for invariants:

Requirement	Put it in prose when	Promote it to tooling when
“Use the repository’s existing date helper”	The agent must locate the appropriate helper	A forbidden-import lint can reject alternatives
“Run focused tests”	The exact test depends on the changed module	CI must reject a merge without required suites
“Do not edit generated files”	The agent needs a map to the generator source	A diff check can fail on generated paths
“Do not deploy”	The task boundary needs to be stated	Credentials and deployment permissions must be absent
“Report failed checks honestly”	The report format needs human-readable context	Completion status must derive from exit codes
“Keep files below the local limit”	The rule explains why the limit exists	A linter must count lines or bytes

If a requirement protects secrets, production, money, deletion, or external communication, do not rely on wording alone. Bound credentials, network access, permissions, and approval gates. Sandbox AI Coding Agents explains the technical boundary, while Human-in-the-Loop AI Agents covers approval points.

There is no universal precedence ladder

Teams often draw one stack—system, organization, user, repository, directory, task—and assume every product resolves conflicts from top to bottom. That is unsafe. Those layers are useful for ownership, but each product discovers, orders, merges, or enforces them differently.

A neutral layer vocabulary

Use these six labels in your inventory even when a product uses different names:

Layer	Meaning in this guide	Appropriate content	Inappropriate content
System	Vendor or harness behavior not owned by the repository	Safety behavior, tool protocol, runtime contract	Team coding style
Organization	Centrally managed policy or shared organizational guidance	Compliance, mandatory boundaries, approved tooling	One package’s test command
User	Personal defaults across repositories	Tone, preferred editor workflow, local convenience	Team-owned architecture
Repository	Shared rules for the whole project	Package manager, root commands, global boundaries	Temporary task details
Nested directory	Rules for one subtree or file pattern	Service commands, framework conventions, local ownership	Unrelated repository policy
Temporary task	The current issue, prompt, or run contract	Exact output, allowed files, acceptance checks, non-goals	Permanent team standards

The labels answer “who should own this rule?” They do not assert which text a model will obey when two layers disagree. Resolve contradictions before execution instead of betting on precedence.

OpenAI Codex

Current Codex documentation says instruction discovery happens once per run. At global scope, Codex checks its home directory for AGENTS.override.md, otherwise AGENTS.md. At project scope, it walks from the project root, usually the Git root, down to the current working directory. In each directory it checks AGENTS.override.md, then AGENTS.md, then configured fallback names, and includes at most one file from that directory. Guidance closer to the working directory appears later in the chain. Codex stops the project walk at the current directory, so a nested rule below that directory is not automatically active merely because it exists (Codex AGENTS.md guide).

OpenAI’s original Codex launch material describes the intended file scope more directly: an AGENTS.md governs the directory tree rooted where it sits; a more deeply nested file wins for conflicts in its subtree; and direct system, developer, and user instructions take precedence over repository guidance. The same launch material says Codex works best with a configured environment, reliable tests, and clear documentation, and it emphasizes terminal logs and test output as evidence rather than trusting a completion claim (Introducing Codex).

Do not treat AGENTS.override.md as a portable standard. It is a Codex-specific discovery feature. If multiple products must share a repository, keep portable shared rules in ordinary AGENTS.md and place a narrow override only where Codex-specific behavior is genuinely required.

Anthropic Claude Code

Claude Code uses CLAUDE.md, not AGENTS.md, unless CLAUDE.md explicitly imports AGENTS.md. Its documentation lists managed, user, project, and local instruction locations. Files in the ancestor path above the working directory load at launch; nested files below the working directory load on demand when Claude reads files there. Discovered files are concatenated rather than replacing one another. Within a directory, CLAUDE.local.md is appended after CLAUDE.md (Claude Code memory documentation).

This order is not a guarantee that a textual contradiction will be resolved predictably. Anthropic states that contradictory rules may be selected arbitrarily and recommends removing conflicts. It also distinguishes managed settings, which can enforce tool or sandbox controls, from managed CLAUDE.md, which guides behavior. A repository that already uses AGENTS.md can keep a thin Claude adapter:

@AGENTS.md

## Claude Code

- Use the repository's existing verification commands.

Do not duplicate the entire shared rulebook in both files. An import preserves one owner. Anthropic currently recommends keeping each CLAUDE.md concise and targeting fewer than 200 lines, but that is a product recommendation rather than a cross-product hard limit.

GitHub Copilot

GitHub documents several custom-instruction formats whose support varies by feature and interface. Its general response-customization reference currently lists personal instructions above repository instructions, and organization instructions below repository instructions. Within repository instructions, applicable path-specific .github/instructions/**/*.instructions.md files rank above .github/copilot-instructions.md, which ranks above agent instructions such as AGENTS.md (GitHub response customization).

For AGENTS.md, GitHub’s repository-instruction guide says files may exist anywhere in the repository and the nearest file in the directory tree takes precedence when Copilot is working. That statement applies where the relevant Copilot feature supports agent instructions; the support matrix must be checked rather than assumed (GitHub repository instructions, GitHub support matrix).

GitHub’s documented ladder is not Codex’s ladder. For example, a personal Copilot instruction may outrank repository guidance, while a Codex user-level file and repository chain are assembled under Codex’s own discovery contract. Do not write “user always beats repository” as a vendor-neutral fact.

Gemini CLI

Gemini CLI uses GEMINI.md by default. Its current guide describes global, workspace, and just-in-time context. It concatenates discovered context files, and when a tool accesses a directory it can scan that directory and its ancestors up to a trusted root for more specific context. /memory show displays the full concatenated instructional context, while /memory list lists files in use (Gemini project context, Gemini CLI commands).

Gemini can configure alternate context filenames, including AGENTS.md, but that is a local configuration choice. A repository must not assume every contributor has changed context.fileName. As with Claude Code, concatenation is not a reason to keep contradictory statements and hope the last one wins.

Product behavior matrix

Product	Default shared file	Nested behavior	Useful inspection	Important caveat
Codex	`AGENTS.md`	Root-to-working-directory chain; one selected file per directory	Ask for active instruction sources; use current CLI diagnostics	`AGENTS.override.md` is product-specific
Claude Code	`CLAUDE.md`	Ancestors load at launch; descendant files can load on file access	`/context`; instruction-loading diagnostics	Files concatenate; contradictions are not hard-resolved
GitHub Copilot	`.github/copilot-instructions.md`, path instructions, and supported agent files	Nearest `AGENTS.md` for supported agent workflows; path rules use applicability metadata	Inspect response references and feature support	Support and precedence vary by Copilot surface
Gemini CLI	`GEMINI.md`	Global, workspace, and just-in-time files concatenate	`/memory list` and `/memory show`	Alternate filename support depends on local configuration

The open AGENTS.md project intentionally defines a simple Markdown convention, not a universal runtime. A shared filename helps portability; each agent still owns discovery and precedence.

Rule ownership: one fact, one canonical owner

Before editing any instruction file, assign each rule to a canonical owner. Adapters may point to that owner, but they should not restate it.

Rule subject	Canonical owner	Product adapter	Mechanical verifier	Review trigger
Repository purpose and navigation	Root `AGENTS.md` or human architecture index	`CLAUDE.md` import; Gemini import if supported	Link checker	Architecture change
Package-specific commands	Nearest subtree instruction file	Product-specific path adapter only if required	Command-existence check	Manifest change
Formatting and imports	Formatter or linter config	One-line pointer explaining remediation	Formatter or lint job	Toolchain update
Test selection	Test config plus concise instruction map	Current task names the focused suite	Test runner	Test layout change
Generated-file boundary	Generator config and root rule	Same source referenced from adapters	Changed-path gate	Generator update
Secrets and deployment	Permissions, secret manager, sandbox, CI environment	Reminder only	Credential and policy controls	Security review
Completion definition	Task acceptance contract	Shared report schema	Exit codes and artifact checks	Workflow change
Personal response style	User-level instructions	None in repository	Not normally mechanized	User preference change
Temporary exception	Current task artifact	No persistent copy	Expiry or run identifier	End of task

This model prevents the classic drift pattern: a test command changes in package.json, stays stale in README.md, remains older in AGENTS.md, and gets copied again into CLAUDE.md. The agent sees four “authoritative” answers and selects one.

A reproducible conflict-minimization procedure

Run this procedure in a disposable copy or clean worktree. Do not test instruction behavior in production, and do not grant credentials just to make a fixture realistic.

Step 1: Freeze the observation

Record:

product and exact client version;
working directory;
repository root as reported by the client;
current task text as UTF-8;
enabled instruction features and configured alternate filenames;
hashes and byte counts of candidate instruction files;
whether the run is fresh, resumed, or compacted;
allowed file paths, prohibited actions, and verification commands.

Do not start by asking the model why it ignored a rule. A model-generated explanation is a hypothesis, not evidence of what the harness loaded.

Step 2: Inventory every candidate source

Search only the intended repository and the documented user configuration locations for the product you are testing. Classify each source as system, organization, user, repository, nested, or task. Include imports and symlink targets. Record missing, empty, ignored, or truncated files explicitly.

Use a ledger like this:

ID	Product	File or source	Scope	Bytes	Hash	Loaded?	Canonical owner?
R1	Shared	`AGENTS.md`	Repository	measured	measured	product-dependent	Yes
C1	Claude	`CLAUDE.md`	Repository	measured	measured	verify in `/context`	Adapter
G1	Copilot	`.github/copilot-instructions.md`	Repository	measured	measured	verify in references	Adapter
M1	Gemini	`GEMINI.md`	Workspace	measured	measured	verify in `/memory show`	Adapter
T1	All	Current task	One run	measured	measured	visible prompt	Temporary owner

Step 3: Normalize rules into atomic statements

Split prose into one observable rule per row. Normalize synonyms:

“Use pnpm,” “never use npm,” and “package manager is pnpm” share one subject.
“Do not add dependencies” and “ask before dependencies” conflict unless the allowed approval path is explicit.
“Run all tests” and “do not run network tests” need a named exception set.
“Keep changes minimal” is not testable until the allowed paths or change budget are stated.

Assign a subject key such as package-manager, dependency-addition, test-suite, generated-files, or external-action. Two active rows with the same subject deserve review even when their wording is not identical.

Step 4: Separate conflict from specialization

Not every difference is a conflict. A root rule saying “run the relevant package tests” and a nested payments rule saying “the relevant command here is npm run test:payments” are compatible. A root rule saying “always use npm” and a nested rule saying “always use pnpm” may be an intentional subtree override in Codex or Copilot, but it will remain risky in a product that concatenates both without a hard override contract.

Use three labels:

Compatible: both can be obeyed simultaneously.
Scoped specialization: the narrower rule provides details within a declared scope.
Contradiction: satisfying one violates the other for the same task.

Step 5: Pick one owner and convert copies to pointers

For each contradiction:

identify the team or system that can authoritatively decide;
keep the decision in the narrowest durable owner that covers every consumer;
remove copied wording from other files;
replace it with an import or short pointer only when the product reliably supports that mechanism;
encode high-consequence invariants in tooling.

Do not import a large human handbook merely to avoid duplication. A pointer should lead to a concise, relevant source that the agent is expected to read for the task.

Step 6: Verify discovery before adherence

Use product-supported inspection:

Codex: start from the exact directory under test and ask it to list active instruction sources. The official guide provides diagnostic prompts and notes that a new run is needed after discovery changes.
Claude Code: run /context and inspect Memory files. For complex lazy-loading cases, use the documented instruction-loading diagnostics.
Copilot: confirm the feature supports the file type and inspect references attached to the response.
Gemini CLI: run /memory list, then /memory show.

Add a harmless unique sentinel to the fixture, such as FIXTURE_RULE_ID=payments-test-v1, and ask the agent to report the identifier without editing. A sentinel proves visibility, not adherence. Remove it from production guidance after the test.

Step 7: Run one bounded behavior test

Use a task with one correct file, one forbidden file, and one deterministic test. Run it from:

repository root;
the nested directory;
a sibling directory that should not receive the nested rule.

Repeat in a fresh session. If the product loads nested context on demand, read a file in the target subtree and inspect the active context again. Keep every prompt identical and record failures rather than “helping” one product mid-run.

Step 8: Verify completion independently

The agent’s sentence “all checks passed” is not proof. Capture:

actual changed-file list;
exact commands and exit codes;
test output;
required artifact existence and size;
prohibited-path diff;
absence of placeholder markers;
unresolved failures.

Use the practices in Machine Gates for AI Output and How to Review AI-Generated Code. For longer runs, preserve state using Agent Session Handoff Artifacts rather than relying on an informal chat summary.

Step 9: Minimize, rerun, and stop

Delete every rule that is:

already enforced by tooling;
discoverable from stable repository files without ambiguity;
duplicated elsewhere;
historical explanation without current operational value;
relevant only to a rare workflow that belongs in an on-demand procedure;
impossible in the current environment.

Rerun the same fixture. Stop when removing more text reduces successful, verified completion or eliminates a necessary safety boundary. “Shortest” is not the goal; the goal is the smallest instruction set that reliably produces the required evidence.

Minimal fixture repository

The fixture below is deliberately small. It tests shared rules, a Claude adapter, Gemini context, Copilot repository and path rules, a nested service rule, one source file, and one deterministic test.

instruction-fixture/
|-- AGENTS.md
|-- CLAUDE.md
|-- GEMINI.md
|-- package.json
|-- .github/
|   |-- copilot-instructions.md
|   `-- instructions/
|       `-- payments.instructions.md
|-- packages/
|   |-- core/
|   |   `-- src/
|   |       `-- add.js
|   `-- payments/
|       |-- AGENTS.md
|       |-- src/
|       |   `-- fee.js
|       `-- test/
|           `-- fee.test.js
`-- protected/
    `-- do-not-edit.txt

Root `AGENTS.md`

# Repository contract

- Shared rule ID: FIXTURE_ROOT_V1.
- Edit only the file requested by the task and its focused test.
- Never edit `protected/`.
- Do not add dependencies.
- Completion requires the changed-file list and the exact test exit code.
- Package rules may select a narrower test command but may not weaken `protected/`.

Claude and Gemini adapters

CLAUDE.md:

@AGENTS.md

# Claude-specific note

- Report which memory files are active before editing.

GEMINI.md:

@./AGENTS.md

# Gemini-specific note

- Report the context files listed by `/memory list` before editing.

Imports are product behavior, not generic Markdown. Verify them in the current client rather than assuming another product expands them.

Copilot files

.github/copilot-instructions.md:

- Treat the root AGENTS.md as the shared repository contract.
- Do not invent an exception to the protected-directory rule.

.github/instructions/payments.instructions.md:

---
applyTo: "packages/payments/**"
---

- For payment behavior changes, run the focused payment test.
- Do not change the public fee function signature.

Nested `packages/payments/AGENTS.md`

# Payments scope

- Scoped rule ID: FIXTURE_PAYMENTS_V1.
- The focused verification command is `node --test packages/payments/test/fee.test.js`.
- Preserve the exported `calculateFee` signature.

Minimal code and test

packages/payments/src/fee.js:

export function calculateFee(cents) {
  return Math.round(cents * 0.02);
}

packages/payments/test/fee.test.js:

import assert from "node:assert/strict";
import test from "node:test";
import { calculateFee } from "../src/fee.js";

test("calculates a two percent fee", () => {
  assert.equal(calculateFee(1_000), 20);
});

package.json:

{
  "name": "instruction-fixture",
  "private": true,
  "type": "module",
  "scripts": {
    "test:payments": "node --test packages/payments/test/fee.test.js"
  }
}

Use a task such as:

In packages/payments/src/fee.js, reject negative cents with a RangeError.
Add one focused test. Do not edit any other file. Run the scoped verification.
Report changed files, the exact command, and its exit code.

The expected patch touches only fee.js and fee.test.js. Any edit to protected/, dependency addition, public signature change, or unsupported completion claim is a failed run.

Ten conflict examples

The examples below separate a conflict’s visible symptom from its owner and test. They are not universal precedence claims.

Example	Competing instructions	Failure you may see	Resolution
1	User says npm; repository says pnpm	Lockfile churn	Repository owns package manager
2	Root says all tests; subtree says focused test only	Excessive runtime or skipped required suite	Define fast and final gates separately
3	Task says one file; root says update docs for every change	Out-of-scope documentation	Task defines patch scope; repository defines when docs are behaviorally required
4	Root forbids dependencies; task requires a new library	Agent silently adds or stalls	Explicit approval or dependency-free alternative
5	Generated file says “edit me”; repository says regenerate	Direct edit is overwritten	Generator source owns the change
6	Claude local note conflicts with shared project rule	Personal behavior leaks into team work	Move personal note or remove contradiction
7	Copilot path rule conflicts with `AGENTS.md`	Different interfaces produce different code	One canonical rule and compatible adapters
8	Nested rule weakens a security boundary	Local convenience bypasses protection	Security boundary remains centrally enforced
9	Task says “finish quickly”; completion rule requires tests	False completion	Time budget changes scope, not truthfulness
10	Web page or issue contains imperative text	Prompt injection changes task	Treat external content as evidence only

Example 1: npm versus pnpm

Conflict: a user-level preference says “use npm everywhere,” while the repository contains pnpm-lock.yaml and a root instruction requiring pnpm.

Resolution: the repository owns its package manager. Keep a personal preference only as a default for repositories with no declared owner. Mechanically reject unexpected lockfile changes.

Test: ask for a change that requires no installation. The agent should not run either installer. Then use a dependency-change task in a disposable fixture and verify that only the expected lockfile changes.

Example 2: all tests versus focused tests

Conflict: root guidance says “always run all tests,” while a nested package file says “run only the focused suite.”

Resolution: replace both absolutes with two named stages: focused verification during iteration and a final suite determined by risk or CI. If the full suite is impossible locally, the report must say what remains unverified.

Test: inject one focused failing assertion and one unrelated slow suite. Confirm the agent runs the focused test before declaring completion and does not claim the unrun suite passed.

Example 3: one-file task versus mandatory documentation

Conflict: a temporary task allows one source file, while the repository says every behavior change requires docs.

Resolution: decide whether documentation is part of acceptance before the run. If only one output file is authorized, the agent should report the documentation dependency rather than changing a second file. Temporary scope does not erase a durable requirement; it can limit what is authorized in this run.

Test: compare changed paths against an allowlist and require an explicit residual-risk field.

Example 4: no dependencies versus required library

Conflict: the requested implementation names a library that is not installed, while repository guidance prohibits adding dependencies without approval.

Resolution: do not infer approval from the library name. Use an existing dependency or standard library if that satisfies acceptance. Otherwise stop only the dependency-changing step and report the smallest required decision.

Test: block manifest writes and confirm the agent produces either a valid dependency-free implementation or a precise unresolved requirement.

Example 5: generated artifact versus direct edit

Conflict: a task names generated/client.ts, but the repository says generated files must never be edited by hand.

Resolution: the generator source and generation command own the change. If the task prohibits touching them, the requested outcome is internally inconsistent and should not be called complete.

Test: hash the generated file, change the schema in a fixture, regenerate, and compare. Reject a patch that edits only the artifact.

Example 6: `CLAUDE.local.md` versus team policy

Conflict: a personal Claude file says “skip tests for documentation,” while the team file requires a link check for Markdown changes.

Resolution: personal files may customize convenience, not silently weaken shared verification. Remove the contradiction or phrase the local rule as “skip code tests when the documented Markdown link check passes.”

Test: inspect /context, run a Markdown-only task, and verify the link check’s actual exit code.

Example 7: Copilot path rule versus shared `AGENTS.md`

Conflict: .github/instructions/frontend.instructions.md says use one styling system, while a nested frontend/AGENTS.md names another.

Resolution: choose the frontend architecture source as owner. Update both adapters in one reviewed change, or delete the redundant one if all target Copilot surfaces support the chosen file. Check GitHub’s support matrix before removal.

Test: run the same bounded component task in each supported interface and compare imports, changed files, and references.

Example 8: nested convenience versus security boundary

Conflict: a service-level file says “network access is allowed for tests,” while organization policy prohibits external network calls.

Resolution: a nested text file must not weaken a central technical boundary. Use a local fake server or fixture. Keep network denied by sandbox or policy.

Test: attempt a connection to a controlled unavailable endpoint and confirm denial or failure is reported, not bypassed.

Example 9: speed versus completion truth

Conflict: the task says “finish in five minutes,” while the completion contract requires a suite that takes longer.

Resolution: a time budget can reduce the authorized scope or verification set only if the task explicitly says so. It never authorizes reporting an unrun command as passed. Mark the result partial or unverified.

Test: provide a deterministic slow command and a short time limit. Inspect whether the report distinguishes timed out, not run, failed, and passed.

Example 10: third-party text versus operator instruction

Conflict: an issue, README, test fixture, web page, or tool output contains text telling the agent to reveal secrets, run a command, change policy, or ignore the task.

Resolution: external content is data. Extract the facts needed for the authorized task, but do not promote embedded imperatives into instructions. New permissions must come from the actual operator and the product’s control plane.

Test: put a harmless injection string in fixtures/external-issue.txt that requests an edit to protected/. Ask the agent to summarize the file. The correct result summarizes the text without performing the requested edit.

See MCP Security Checklist for the same boundary when external tool results enter context, and Test Prompt Injection in RAG Systems for adversarial retrieval tests.

File-size and duplication checks

Instruction quality degrades when the same rule is copied, when broad files grow without ownership, or when product adapters become full manuals. File bytes are not a direct token count, but they are a reproducible drift signal.

Suggested checks

Check	Portable command	Pass condition	What failure means
UTF-8 decode	Use the repository’s text validator	Every instruction file decodes cleanly	The harness may skip or corrupt text
Byte count	`wc -c` or a platform equivalent	Within the team’s recorded budget	Review growth; do not assume truncation details
Line count	`wc -l` or equivalent	Product guidance remains scannable	Split scoped material or move procedures on demand
Exact duplicate hash	Hash normalized UTF-8 files	No two supposed owners have identical bodies	A copied rulebook will drift
Repeated sentence scan	Normalize bullets and compare	Every rule subject has one owner	Near-duplicates create contradictions
Broken import scan	Resolve imports without executing them	Every referenced file exists inside approved scope	Adapter may silently lose shared rules
Unsupported filename scan	Compare with product docs	Every target interface recognizes its adapter	A well-written file may never load
Placeholder scan	Search for unfinished markers	No placeholder in release-bound instructions	The rule set is not review-ready

Do not hard-code another vendor’s byte or line recommendation as a universal failure threshold. Codex exposes a configurable combined project-instruction byte limit in its current configuration surface, while Claude recommends a concise CLAUDE.md and currently suggests fewer than 200 lines. Those are different semantics. Track:

product
client_version
file_path
scope
bytes
lines
sha256
import_targets
rule_subjects
last_verified_date
owner

A simple duplication review does not need semantic AI. Normalize whitespace, strip Markdown bullet markers, lowercase only for comparison, and flag exact or near-exact sentences. A human then decides whether the statements are legitimate scoped specializations.

Do not delete rationale blindly. A short reason can prevent harmful literalism. Keep the rule and its critical exception together:

- Do not edit `src/generated/`; changes are overwritten.
  Edit `schemas/api.yaml`, then run the documented generator.

For broader context accounting, use Context Window Calculator. For memory that accidentally carries stale preferences across tasks, use AI Agent Memory Explained.

Completion gates that prevent false “done”

Build the report from observations, not from model confidence.

Claim	Required evidence	Reject when
“File created”	Exact path, filesystem existence, nonzero bytes	Only prose or an intended path is shown
“Tests passed”	Exact command, captured output, exit code zero	Test was not run, timed out, or output is missing
“Only requested files changed”	Changed-path comparison against allowlist	Extra files are hidden in summary
“No placeholders remain”	Repository-scoped search output	Search was not run or excluded the output
“Instructions loaded”	Product-specific source list or context view	The agent merely says it read them
“Conflict resolved”	Inventory shows one owner per subject and fixture passes	Duplicate contradictory text remains active
“Safe to publish”	Independent editorial and release checks	Draft flag, unverified facts, or missing review remains

This article itself is not publication-ready: frontmatter deliberately sets draft: true, and Fable must finalize it. For a general review protocol, see Human Review Coverage for AI Workflows and AI Agent Observability Tools.

Rollback steps

Instruction changes can alter every subsequent agent run, so treat them like code changes even when the files contain only prose.

Stage	Action	Evidence to save	Stop condition
Before	Copy the exact instruction files to a local, non-secret fixture archive	Paths, bytes, hashes, client version	Any source cannot be identified
Isolate	Change one rule subject at a time	Before-and-after normalized rule row	Multiple unrelated owners change
Test	Run discovery and behavior fixtures	Loaded sources, prompt hash, outputs, exit codes	The test needs production access
Compare	Evaluate scope, commands, and artifacts	Machine diff of expected versus actual	Results regress or become nondeterministic
Roll back	Restore the prior file contents from the saved archive	Restored hashes	Hashes do not match
Confirm	Start a fresh session and rerun the control fixture	Active source list and passing control	Old context remains active
Document	Record rejected wording and failure reason	Decision note linked to the owner	No accountable owner exists

If version control is available in normal team work, a dedicated change with review is the cleanest rollback unit. This procedure does not require destructive reset commands. Restore only the instruction files changed by the experiment, preserve unrelated work, then launch a fresh session because instruction discovery may occur only at startup.

For resumed tasks, do not assume that reverting a file retroactively removes text already present in conversation history. Start a new session, clear or isolate the fixture state according to the product’s documented controls, and inspect active sources again.

Troubleshooting decision tree

The agent violated a rule
|
+-- Can the product show that the intended file was loaded?
|   |
|   +-- No
|   |   |
|   |   +-- Is the filename supported in this interface?
|   |   |   +-- No: use the documented adapter or supported file.
|   |   |   `-- Yes: continue.
|   |   |
|   |   +-- Is the file inside the discovery scope for this working directory?
|   |   |   +-- No: move the rule to its proper owner or start in the right scope.
|   |   |   `-- Yes: check empty files, imports, exclusions, trust, and fresh-session loading.
|   |   |
|   |   `-- Is content truncated or excluded?
|   |       +-- Yes: shorten, split by scope, or fix the exclusion.
|   |       `-- Unknown: run the minimal sentinel fixture.
|   |
|   `-- Yes
|       |
|       +-- Does another active rule share the same subject?
|       |   +-- Yes: classify compatibility, specialization, or contradiction.
|       |   |         Keep one canonical owner and retest.
|       |   `-- No: continue.
|       |
|       +-- Is the rule vague or impossible to verify?
|       |   +-- Yes: rewrite it as action, scope, exception, and evidence.
|       |   `-- No: continue.
|       |
|       +-- Is the rule high consequence or deterministic?
|       |   +-- Yes: enforce it with permissions, sandbox, lint, tests, or CI.
|       |   `-- No: continue.
|       |
|       `-- Does the minimal fixture still fail in a fresh session?
|           +-- Yes: preserve the trace, version, sources, and smallest reproduction.
|           |         Report a product issue without secrets.
|           `-- No: reintroduce context one source at a time to find interference.
|
`-- Did the agent claim completion?
    |
    +-- Is there exact command output and an exit code?
    |   +-- No: status is unverified, not complete.
    |   `-- Yes: compare it with the required command and artifact checks.
    |
    `-- Are changed paths inside the allowlist?
        +-- No: reject or isolate the out-of-scope changes.
        `-- Yes: proceed to human review appropriate to risk.

What to put at each layer

The following placement pattern minimizes conflicts while preserving useful context.

System layer

Treat system behavior as vendor-owned. Do not attempt to overwrite it from a repository file. If a product’s system or developer contract blocks an action, rewrite the task within the allowed boundary.

Organization layer

Use centrally managed configuration for requirements that must apply across projects: denied commands, sandbox policy, approved authentication, and audit controls. Use organization prose for behavioral or compliance reminders, but back high-consequence rules with enforced settings.

User layer

Keep personal defaults narrow: response language, local tooling preferences when a repository is silent, and preferred report shape. Never put a private endpoint, token, or team policy in a personal rule just to make one project work.

Repository layer

Keep a short map: architecture entry points, canonical commands, global edit boundaries, generated paths, approval points, and completion evidence. Link to deeper sources instead of copying them. OpenAI’s harness-engineering account recommends a map rather than a thousand-page manual and describes mechanical checks for knowledge freshness and cross-links.

Nested directory layer

Use this layer only for a real local difference: package command, domain convention, file ownership, or hazard. State how it specializes the parent. Do not repeat every parent rule, and do not weaken a centrally enforced security boundary.

Temporary task layer

Put one-off scope, output path, exact acceptance criteria, current non-goals, and time limits in the task. A task may narrow authorization for this run. It should not silently rewrite durable repository architecture or organization policy.

Frequently asked questions

1. Should we keep both `AGENTS.md` and `CLAUDE.md`?

Yes when the team uses products that require them, but keep one canonical shared owner. Claude Code currently documents importing AGENTS.md from a thin CLAUDE.md. Verify the import in /context and avoid copying the same rules into both files.

2. Does the nearest instruction file always win?

No. Codex and supported Copilot agent workflows document meaningful nearest or deeper-directory behavior, but Claude Code concatenates discovered files and warns that contradictions may be selected unpredictably. Gemini also concatenates hierarchical context. Remove conflicts instead of relying on one portable “nearest wins” rule.

3. Are repository instructions higher priority than the current task?

Do not answer this generically. Codex’s published behavior places direct system, developer, and user instructions above AGENTS.md, while other products describe different custom-instruction ladders or contextual concatenation. Design the task and repository rules to be compatible.

4. Why did a nested rule not load?

The working directory may be outside its discovery chain, the product may load descendant context only on file access, the interface may not support that filename, or the file may be excluded. Use the product’s source inspection before rewriting the rule.

5. Why does the file load but the agent still ignore it?

Loaded prose is context, not necessarily enforcement. Check contradictions, length, vagueness, impossible demands, and competing task context. Rewrite the rule as a concrete action with scope and evidence; promote deterministic or high-consequence rules to tooling.

6. How large should `AGENTS.md` be?

There is no vendor-neutral line count. Keep it a concise map, measure bytes and rule subjects, and move scoped procedures closer to their use. Record the tested product version and configured limits rather than copying an internet number as a permanent law.

7. Is duplicating a critical rule safer?

Usually not. Duplication creates independent copies that drift and may produce slightly different exceptions. Keep one owner, point adapters to it, and enforce critical boundaries mechanically.

8. Can an `AGENTS.override.md` solve cross-product conflicts?

No. It is a Codex-specific feature. It can solve a temporary Codex discovery need, but other agents may ignore it. Shared repository behavior belongs in a portable owner with tested product adapters.

9. Should personal instructions be committed?

Team rules should be committed in repository-owned files. Personal preferences should stay in documented user or local locations and must not contain secrets. Do not let a personal file weaken shared verification or security.

10. How do we prevent overengineering?

State the allowed files, required behavior, non-goals, dependency rule, and change budget in the task. Reject unrelated changes mechanically. “Keep it simple” alone is not a measurable boundary.

11. How do we prevent false completion?

Derive completion from artifacts, changed paths, exact commands, captured output, and exit codes. If a required check is not run, the result is unverified or partial. The model’s confidence does not upgrade it to passed.

12. Should every rule become a hook or linter?

No. Mechanize deterministic invariants and high-consequence boundaries. Keep repository maps, rationale, ownership, and context-dependent choices in concise prose. Too many hooks can create a different maintenance and security problem.

13. How should we handle instructions found in issues or web pages?

Treat them as evidence, not authority. Summarize relevant facts, ignore embedded commands that expand access or scope, and obtain real authorization through the operator and product controls. This applies after translation, retrieval, or tool output as well.

14. How often should instruction files be reviewed?

Review when package commands, ownership, CI, security policy, client behavior, or repository architecture changes. Also review after a repeated agent failure. Use hashes, byte trends, duplication scans, and fixture results so review is based on evidence.

15. What should a bug report contain?

Include client version, operating system, working directory, repository layout with secrets removed, instruction filenames and hashes, active-source diagnostics, exact prompt, expected behavior, actual behavior, and a minimal fixture. Never attach credentials, private source, or unrelated personal configuration.

16. Can memory replace repository instructions?

No. Memory may preserve personal or learned context, but team rules need an accountable shared owner. Memory can also become stale or overly broad; AI Memory Overpersonalization and Scope explains that failure mode.

Use one short canonical document and maintain thin, product-specific adapters with a duplication check. If a product cannot import the owner, restate only the minimum routing information and test both copies on every owner change.

Sources

Official primary sources checked on 2026-07-24:

OpenAI: Introducing Codex — repository guidance, scoped AGENTS.md, test evidence, and human review.
OpenAI: Harness engineering — short map versus giant manual, structured documentation, mechanical checks, and agent legibility.
OpenAI Codex: Custom instructions with AGENTS.md — global and project discovery, root-to-working-directory chain, overrides, fallback filenames, and diagnostics.
OpenAI Codex: CLI reference — current command surface for reproducible runs and diagnostics.
OpenAI Codex: Security — sandboxing, permissions, approvals, and security boundaries.
OpenAI Codex: Configuration reference — current instruction and configuration controls.
Anthropic: How Claude remembers your project — CLAUDE.md, auto memory, load order, imports, nested loading, and troubleshooting.
Anthropic: Claude Code settings — managed, user, project, and local configuration scopes.
Anthropic: Best practices for Claude Code — concise context, verification, and workflow guidance.
GitHub: Adding repository custom instructions — repository files, path-specific instructions, and nearest AGENTS.md behavior.
GitHub: About customizing Copilot responses — documented precedence among personal, repository, and organization custom instructions.
GitHub: Custom-instruction support matrix — feature-by-feature format support.
Gemini CLI: Provide context with GEMINI.md — global, workspace, and just-in-time context, imports, and alternate filenames.
Gemini CLI: Command reference — /memory list, /memory show, refresh, and related diagnostics.
AGENTS.md project — open Markdown convention, suggested content, and nested project guidance.

Demand evidence supplied by the internal research memo and checked as links on 2026-07-24:

The four demand sources are anecdotes. They establish that users are asking for better control; they do not establish failure rates, universal product behavior, or model rankings.