How AI Agents Work

The Instruction Hierarchy: Scope, Interpretation and Technical Control

How to tell apart which instructions an agent actually loaded, how conflicts between loaded instructions are resolved in a specific product, and which…

Chapter 28How AI Agents Work

Documentation checked on 26 September 2026.

Picture a task: change a button in a single widget. The project's root instruction file says that interactive elements in the web interface must use the shared component library. An instruction in a subdirectory explains that the widget has to run in an embedded environment where that library is not available. An agent can honour both texts, provided it understands where each one applies. The same kind of situation turns dangerous when the task asks to drop a table in the live database, while the team only allows a migration to be prepared for people to review.

These examples require you to separate three questions: which instructions did the system actually load; how should the agent act if the loaded instructions conflict; and what technically prevents a forbidden action from being carried out? Answering one of these questions does not answer the other two.

This unit builds on the agent's working environment (how AI coding agents work), limited context (context as a limited resource), sources of truth, handing work over and the repository as a knowledge system. Here, "agent" means a specific product on a specific working surface, not any language model in general. The examples are invented; none describes a real company, production database or hidden policy.

Three different mechanisms

Loading determines what the agent saw

A file can exist in the repository and still not make it into the context of the current run. That happens, for example, when:

  • the product does not support the file's name;
  • the file is not in a directory the product checks;
  • the work was started from the wrong working directory;
  • the system loads the instruction only after the file it is attached to is opened;
  • another configuration mechanism replaced or excluded the file;
  • the agent is running in a version or environment where the feature is not yet available.

So the phrase "it's in the repository" proves only that it is on disk. It does not prove that the instruction was active during the work. Conversely, an instruction may have been loaded, yet the agent may have misunderstood its meaning or failed to follow it.

Precedence determines how a contradiction in the text is resolved

When two applicable rules are incompatible, you have to establish whether the documentation of that specific product describes a loading order or a rule for combining them. One file may, for example, refine a broader rule for a particular path. But "loaded later" is not a synonym for "always has the highest authority", and the order of files does not replace the limits on access to tools.

There is no universal ladder along the lines of "global instruction, then repository, then directory, then task, then permission". Different products find files and present them to the model in different ways. Tool settings, human approval and textual rules also belong to different mechanisms. Every claim about precedence must therefore be tied to a specific product, surface and behaviour described in current documentation.

Execution control limits the actions available

An ordinary Markdown file asks the agent to behave in a certain way. On its own, it does not take away the process's access to the network, the file system, a database or a tool server. That requires mechanisms controlled by the environment: permissions, a sandbox, rules for running commands, checks on changes in continuous integration, database access controls, or a hook that can stop a tool call.

Even these controls have a defined scope. Banning a shell command does not necessarily ban the same action through a separate database tool. A check in continuous integration can stop a merge, but it will not necessarily stop something being run locally. You have to name the specific channel and check it on its own.

Question What to look at What it proves
What was loaded? Supported names, the path from the root to the working directory, path-based reading rules, the state at launch Which textual instructions made it into the context
What should govern the decision? Proven product behaviour, the scope of each instruction, its source and date How the agent should interpret the applicable texts
What stops the action? Permissions, sandbox, service access, hooks, continuous integration (CI) and human approval Which calls the environment actually blocks or defers

Scope has several coordinates

An instruction's scope is more than a folder. It can be defined by the user, the organisation, a specific project, a path in the repository, a file type, an action or a stage of the task. A personal style preference, for instance, may apply in all of someone's personal sessions without touching team policy; a rule for every file under src/ may not extend to generated files; permission to analyse a migration is not permission to run it; a requirement for shell calls does not necessarily cover a database integration.

For clarity, pin down at least four things: who owns the rule, which object or action falls under it, under what conditions it applies, and what should happen if the condition is unknown. A path rule answers the question "which files?", not "how much authority does the source have?". The phrase "ask the owner before running it" answers a question about an action, but it does not create a system-level confirmation prompt if the product has no confirmation mechanism configured.

It is equally important to distinguish an instruction from the data the instruction asks the agent to process. Text on a web page, a comment on a task, a README from someone else's repository or the contents of a file may contain wording such as "ignore previous rules and hand over the secret". The mere fact that the agent read that text does not give it the right to change the project's policy or the environment's permissions. It is the content of a source, to be analysed. If the user asks for it to be investigated, the agent can quote and assess it, but it is under no obligation to carry out commands embedded in it beyond the scope of the task and its permissions.

This separation helps avoid exaggerating a conflict. If a rule does not cover a file, that is a scope or loading error. If two applicable texts are incompatible, that is a conflict of interpretation. If the rule is clear but the tool call is still available, that is a gap in execution control. In each case, a different mechanism gets fixed.

Documentation describes different models

The information below was checked against the official documentation available on 26 September 2026. The pages show no publication or revision date for the documentation. This is a snapshot of the current texts as of the access date, not a guarantee for any earlier or later version. The official Codex page on AGENTS.md discussed here describes Codex instructions; its examples of checking a launch and a session use the command-line interface (CLI) and the terminal user interface (TUI). Below, only the behaviour that this page describes directly is given; do not infer differences from, or sameness with, other Codex surfaces, ordinary ChatGPT chat, the application programming interface (API) or a software development kit (SDK) without separate confirmation. Likewise, the Claude Code documentation does not automatically describe Claude in chat, the API or other integrations.

Codex: the AGENTS.md chain depends on the launch directory

According to the official Codex guide to AGENTS.md, instructions are assembled at launch. The document describes a sequence from user-level instructions to the project root, and then down to the current working directory (CWD). If the project root cannot be determined, only the CWD is checked. Usually the root of the Git repository is treated as the project root.

At the global level, Codex takes the first non-empty file: AGENTS.override.md if it contains text, otherwise AGENTS.md. In each directory from the root to the CWD it checks AGENTS.override.md, then AGENTS.md, and then any configured alternative file names. At most one non-empty file is loaded from each directory. There is a limit on the combined size, which defaults to 32 KiB and is configured through project_doc_max_bytes. The document says that files are combined from the root to the CWD, and that instructions closer to the CWD can override broader ones.

This mechanism makes the launch directory important. If a rule in apps/storefront/AGENTS.md is meant to apply to work in that directory, launching from the root and launching with apps/storefront as the CWD are not interchangeable. Editing an instruction file after launch is also no evidence that the text was updated in context that has already been assembled: the guide describes building the chain at launch and recommends restarting Codex after making changes.

Codex has other mechanisms that should not be merged into a single "hierarchy". The .codex/config.toml configuration file sets environment parameters; it does not add another level to the AGENTS.md text. The Codex configuration basics documentation describes a separate order for resolving settings: command-line arguments take precedence over files; project configurations are read from the root to the CWD, with the closest one taking precedence, and they apply only to trusted projects. That order concerns configuration values, not which Markdown guidance should persuade the model. The Codex Rules page marks rules as an experimental feature for commands that can be run outside the sandbox; rules are loaded from the active configuration directory, and local project rules depend on the .codex directory being trusted. This restriction on commands is not a precedence mechanism for Markdown instructions.

Separately, the Codex documentation on approvals and security distinguishes the sandbox mode from the approval policy. The sandbox defines the technical capabilities of the command environment; the policy defines when the product must ask for permission. These parameters mean something only for the environment and channels they apply to. If an action can be carried out through another connected tool, that tool's own access and controls have to be considered separately.

Claude Code: memory, path rules and permission policy are not the same thing

The official Claude Code documentation on memory states that CLAUDE.md files give Claude context but are not enforcement configuration. CLAUDE.md and CLAUDE.local.md files in the working directory and its parent directories are read at the start of the session; the documentation describes them being assembled from the root down to the current directory. Instructions from subdirectories may be loaded later, when Claude reads files there. A file in .claude/rules/ without a paths scope is loaded as a general rule, while a rule with a paths field in YAML (YAML Ain't Markup Language) is activated for the matching files. A memory file can also import another file through @path.

Claude Code supports reading AGENTS.md directly from version 2.1.277. In the default claude-md-or-agents-md configuration, AGENTS.md is read when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or its ancestors. If claude-md-and-agents-md is selected, both types of file are read: first CLAUDE.md for the relevant directory, then AGENTS.md. Direct reading is unavailable in some sessions if the agents-md module is disabled, and before version 2.1.281 some sessions, including those via Amazon Bedrock or with telemetry disabled, read only CLAUDE.md. The first session after upgrading from 2.1.276 or an earlier version may also fail to read AGENTS.md. In that case the documentation advises importing it from CLAUDE.md. So the fact that "there is an AGENTS.md" does not yet guarantee that Claude Code read it; check the version, the Project instructions mode and the actual context.

User rules and project rules do not form a simple ladder either. The current memory page warns explicitly that both sets can end up in context, and that when they contradict each other Claude may follow either one; they should be kept consistent. The loading order here cannot be turned into a general promise that "the closer file wins" in every situation.

For tool restrictions, Claude Code documents permissions and hooks separately. In the permission policy, a deny rule blocks a call, ask requests confirmation, and allow permits the call without a manual prompt, within the rules. The order between rules is deny, then ask, then allow. For multiple hook decisions, the documented order is deny, defer, ask, allow. A PreToolUse hook can evaluate a call before it is executed. Its allow decision skips the normal permission prompt, but matching deny and ask rules still apply: deny blocks the call, and ask keeps confirmation mandatory. For AskUserQuestion and ExitPlanMode, updatedInput must be passed together with allow; MCP tools with requiresUserInteraction and connector tools under an organisational ask rule may still require interaction. In auto mode, some actions cannot be approved by a hook decision alone. A command hook that times out continues to the normal permission check; it does not automatically block the call. These mechanisms work only for the hooks, events and tools that are configured; a rule for one tool does not create control over another channel. A sandbox likewise operates within its own environment, not over every external route. Text in CLAUDE.md is no substitute for a hook or for access control, and MCP (Model Context Protocol) and other integrations must be checked separately.

The order of text is not a right to act

The words "higher" and "lower" are often misleading. In the file system, a file may genuinely be closer to the target; in the documentation, it may come later than another file; but none of that determines whether a specific action may be carried out. The order in which context is assembled answers a technical question about how the product passes text to the model. A precedence rule answers the question of how the product describes a conflict. An access policy answers the question of whether a tool or environment will allow the operation to run. The three answers may coincide, but they are not one statement.

For example, a local requirement for one directory can legitimately refine a general recommendation for the whole repository. It cannot give the agent secret credentials it does not have, and it cannot cancel a network control. Likewise, a confirmation in the agent's window can permit a call only within the configured rights; it does not prove that the operation complies with data-retention obligations. If the rules do not give an unambiguous answer, particularly for deleting data or making external changes, the ambiguity should be passed to the responsible owner rather than settled by guessing about "levels".

The Claude Code settings page sets out a separate order, in the same way, for the values of JSON settings: organisation-managed settings, launch arguments, local project settings, shared project settings, personal settings. Some lists are merged, and certain security parameters have special rules. That is an order for configuration keys, not for textual memory instructions.

Do not call a global instruction the most authoritative one unless the documentation of that particular product confirms it. For Codex, the current AGENTS.md page directly describes how files are assembled and the role of closer instructions in the chain. For Claude Code, the memory page describes how the different types of file are loaded and warns that conflicting user and project rules may be interpreted unpredictably. These are specific, different promises, not one shared standard. Separately managed access parameters can have stricter properties: Anthropic documents that permission-settings rules are enforced by the client, whereas CLAUDE.md is behavioural guidance. It does not follow from this difference that any corporate instruction file automatically blocks an action.

A short record for working through a conflict

When instructions look incompatible, write a short decision record. It helps show exactly where the problem lies, and it gives a person enough context that they do not have to repeat the diagnosis.

  • Session: the product and surface name, the visible version, the working directory, the moment of launch.
  • Sources: the path to each file, its name, owner, review date and evidence that the product loaded it.
  • Scope: which files, actions and conditions each rule covers; whether their scopes overlap.
  • Content: the exact wording of each requirement and the specific part of the task it concerns.
  • Options: what can be done within the shared permitted area; which option requires an exception or a human decision.
  • Control: which permission, hook, service access or external check should prevent the unwanted action, and for which tool exactly it works.

Then classify what you have observed. If one rule did not load, that is not yet a conflict between two texts. If the rules concern different directories or different stages of the work, they may be compatible. If a local requirement clearly narrows a general one for precisely this case, apply what they have in common, and apply the exception only within its declared scope. If both texts have the same scope but demand mutually exclusive actions, rely only on the documented rule of that particular product; where no such rule exists, ask the owner. If the problem is about access rather than text, do not confuse the model's agreement with technical permission.

The result of the diagnosis must be observable: either the agent carried out a bounded action and can show the file or the check, or it stopped and clearly named what is unknown, the decision needed and who is responsible. Not having done something must not be dressed up as success. Neither the agent's confident explanation nor the fact that a tool allows a command is evidence that the policy was applied correctly.

Example 1: a general rule and a local exception for a widget

Situation. An invented monorepo contains a shop and a widget embedded on partner pages. The root requirement: web interfaces use the Button component from the @studio/ui package, so that focus states, accessibility and styling stay consistent. The widget in apps/availability-widget/src/embed/ runs inside a restricted iframe, where that package is unavailable because of how the build is architected. An exception has been approved for this narrow directory: use a plain HTML button element with type="button", a visible label, a disabled state and a keyboard interaction test. The exception does not extend to other pages or to other components of the widget.

The root AGENTS.md can contain the general rule for Codex; the file apps/availability-widget/src/embed/AGENTS.override.md sets the exception only for work in the embedded-interface directory. In Claude Code, the project CLAUDE.md can be combined with .claude/rules/embed-controls.md, whose YAML header contains a paths field with the value apps/availability-widget/src/embed/**/*, while the text states the same constraints of the exception. These are two configuration variants for different products, not one file that both products will read the same way.

Before implementation there are three real options. The first is to use the shared component everywhere, which would violate the confirmed constraint of the iframe build. The second is to switch to a native button across the whole web application, which would needlessly weaken the general rule. The third is to check the exact scope of the exception and apply it only to the embedded file. The third option keeps the broader rule for the rest of the surface and does not invent new policy.

To make the check reproducible, the team can name the paths explicitly: the root AGENTS.md contains the @studio/ui requirement, and the local apps/availability-widget/src/embed/AGENTS.override.md sets the exception for that directory only. In Claude Code, the path-scoped rule file contains only the instruction for that same pattern, and the project CLAUDE.md remains a short general rule. Do not copy one universal file between tools until you have checked that each product recognises its name and scope.

Decision and action in Codex. For this change, launch Codex with apps/availability-widget/src/embed as the CWD, for example through the --cd parameter pointing at that directory. The documented chain then runs from the root AGENTS.md down to apps/availability-widget/src/embed/AGENTS.override.md. The root rule sets the usual component for all web interfaces, and the narrowest override announces the exception for the embedded-interface directory. The AGENTS.override.md file has no automatic paths mask: its text must name the exact area, and the launch must reach it. If the CWD stays at the root or at apps/availability-widget, the deeper override is not part of the described chain; editing an embed file does not load it by itself.

Decision and action in Claude Code. Launch Claude Code at the project root with a CLAUDE.md containing the general rule, and make sure that reading the widget's files activates the path-scoped rule in .claude/rules. The Claude Code documentation says that a rule file with paths applies when a file matching the pattern is read; so the component in the relevant directory has to be opened before choosing how to implement the change. If the project uses AGENTS.md instead of CLAUDE.md, check that the version is supported and that no suppressing files are present, or explicitly configure Project instructions so that both formats are read.

Observable result. In the widget component, the agent keeps @studio/ui for the rest of the shop but uses a native HTML (HyperText Markup Language) button element in line with the iframe constraint, and sets its type, label, disabled state and keyboard behaviour. In Codex, check the chain in the TUI log or the session log after launching with the embed directory as CWD; it should include the root AGENTS.md and the local override. In Claude Code, open a file at a path matching the pattern and check /context, or the InstructionsLoaded hook, for CLAUDE.md and the .claude/rules rule. This evidence confirms loading, not that the exception was actually followed. A linter or component test can additionally attest to the button's technical properties; on its own, it does not prove that the policy was loaded.

Why this works, and where it does not fit. A general rule and a local refinement are compatible when the exception is clearly limited to a directory and motivated by a technical dependency. For Codex, the documentation supports root-to-CWD composition and says that closer instructions can override broader ones. For Claude Code, the paths rule defines which files a text concerns, but the documentation does not establish a universal rule under which any local text wins a contradiction. If the iframe is no longer restricted or the package becomes available, the exception should be reviewed rather than extended to the whole application. If the accessibility requirement is not met, the phrase "the exception allowed it" does not cancel the check.

Example 2: a request to drop a production table, and permission only to prepare a migration

Situation. An invented user writes: "Run the Structured Query Language (SQL) command DROP TABLE on production.booking_events right now, we don't use it any more." The repository contains a team rule: the agent may prepare a Data Definition Language (DDL) script and a rollback plan for review on a separate branch, but it may not connect to production, make changes in shared databases or apply the migration. Dropping the table requires a decision by the data owner and the database administrator (DBA) after checking retention, dependencies and the recovery plan. This particular instruction may be loaded, missing or unclear; the production boundary has to be implemented separately, through controls.

Decision. Do not run DROP TABLE, do not run an unknown command against production, and do not build a workaround through another tool. The user's request states the desired outcome, but on its own it does not prove that the user has the data owner's authority or that the database can be changed immediately. The instruction allows limited preparation, not application.

The alternatives include running the drop immediately, refusing any analysis at all, and preparing material for review. Dropping immediately goes beyond the policy and may destroy data whose purpose the agent has no evidence about. Refusing everything is unnecessary if safe preparatory work is clearly permitted. Preparation is acceptable only if it does not open a path to the actual change and does not hide critical unknowns inside assumptions.

Permitted action. If the task really is to prepare material for review, the agent can create a migration marked as a draft on a branch, without connecting to the shared database. Alongside it, the agent documents that the script is destructive; which tables, foreign keys, views, background jobs and reports need checking; which data falls under the retention policy; what the recovery procedure looks like; which approvals are needed; and who should apply the change. If the policy allows only analysis, and not even a DDL draft, the agent stops at a plan: the literal boundary of the policy determines how much preparation is permitted.

A good draft does not invent the claim that the table is empty, that nothing depends on it, or that a rollback is guaranteed to restore lost rows. If the schema does not describe the volume and categories of data, mark that as unknown. Pass the data owner the question about the retention policy and the request to confirm whether the records can be deleted at all. Ask the database administrator to confirm the dependencies, an available backup instance, the test plan and the procedure for running the change. The human decision here is not a formal tick-box: it settles facts, authority and risk that the agent's textual instruction cannot establish.

Observable result. The branch contains material for human review; the work log states explicitly that no connection was made to the database and the command was not run. The data owner and the DBA decide whether the table is obsolete, whether retention requirements have been met, when decommissioning is possible, and who is authorised to approve running it. Only after that does the responsible operator apply the change through a separate agreed process.

Why text is not enough. In this scenario, assume that the agent's working environment has no production credentials, the network blocks outbound access to that server, and the pull request check in continuous integration (CI) flags migrations containing DROP TABLE for mandatory approval by the database administrator (DBA). These are given conditions of the example, not built-in properties of Codex or Claude Code. If the environment has some other route to the database, the controls must cover that route specifically: shell access, an MCP connection, an administrative API and separate credentials. A textual prohibition is useful for the agent's decision, but it does not replace the database role, the network boundary, the command policy or the CI approval.

Where this does not fit. For a local test instance with synthetic data, a team may allow a down migration to be run, if the local instructions and the environment's permissions explicitly cover it. That does not prove the same step is safe in production. Likewise, an "auto-approve" mode in the interface does not change the data owner's authority and is not permission for an irreversible operation.

Example 3: the agent did not find the instruction file because it is misnamed and in the wrong place

Situation. A developer asks for a change to the checkout process. The work is launched with apps/checkout as the CWD. The repository contains docs/agents/AGENT.md with useful notes about orders. The developer expects the agent to apply them and asks why a different error format appeared in the result.

Diagnosis. Start not from the assumption that "the model ignores the rules", but from the discovery mechanism of the specific product.

  • For Codex, the default expected names are AGENTS.md or AGENTS.override.md, not the singular AGENT.md. In addition, docs/agents/ is not a parent directory of apps/checkout; the search path from the root to the CWD does not pass through the sibling docs directory. The file is left out of the standard chain for both reasons. It could be made available through a supported alternative file name in the Codex configuration, but an alternative name does not change the scope rule: the directory has to be on the route along which the product looks for it.
  • For Claude Code, AGENT.md is not a standard name either. If the instructions concern checkout, placing them in docs/agents does not make them automatically active while working in apps/checkout. Even an AGENTS.md in a different tree is not a checkout instruction just because it is a file in the repository. For Claude Code to load AGENTS.md automatically, check the version (direct support from 2.1.277), the working path and the conditions concerning CLAUDE.md being present. Alternatively, use CLAUDE.md as a supported memory source, or a .claude/rules rule with an exact paths pattern.

Repair. First clarify whether the notes are meant to govern the whole repository, only the checkout code, or only the documentation. If they are checkout policy, move the content to apps/checkout/AGENTS.md, for the Codex chain and for Claude Code where its conditions are met. If the team relies on CLAUDE.md, add one to the relevant directory, or create a path-scoped rule that limits the instruction to the files it concerns. If docs/agents/AGENT.md is a reference document, leave it as reference material and put a short index with a link to it in a file that actually gets loaded. Do not mechanically rename the file: the same text might be policy, an example or a historical note.

If the documentation is kept only for the record, do not move it into an active file without checking with its author: that could accidentally turn outdated advice into current policy. If different surfaces use different formats, it is best to have a short shared policy as the source of meaning and separate thin files for each agent's loading mechanics. Diagnosis can then show whether the path broke or one product failed to read the format, instead of leaving the team with two diverging sets of rules.

Verification and result. Start a new session in the right directory, because the list of instructions may have been assembled at launch. For Codex, check the project directory, the CWD, and the standard and configured alternative names. According to the official guide, the actual chain can be checked in the text TUI log, enabled with the parameter codex -c log_dir=./.codex-log, or in the session-*.jsonl session log if session logging is enabled. Asking the agent which sources it believes it has loaded is also useful, but a self-description is not evidence that the policy is being followed. For Claude Code, the current documentation recommends checking /memory; in version 2.1.280 and later you can also check /context. Before 2.1.280, these commands did not directly show an AGENTS.md that had been read. The InstructionsLoaded hook can record CLAUDE.md and rule files, but it does not fire for an AGENTS.md loaded directly through Project instructions; it does fire for an AGENTS.md imported or attached through CLAUDE.md. After that, open the target file and check whether the required rule applies to it specifically.

Why this works, and when it does not fit. We separated the name, the path, the launch mechanism and the actual content of the file. An agent reading a file as an ordinary source does not automatically turn it into loaded instructions. If a document is to become mandatory for all projects, put it in the appropriate global mechanism and check each surface separately. If it describes one subdirectory, do not make it global just so that "the agent will definitely see it".

How to write reliable instructions

A good instruction starts not with the name of a level but with a clear scope. State which repository, product, directory, file type, tool or stage of work the rule belongs to. "Always use the shared component in the shop's web interface" leaves less room for ambiguity than "all buttons should be the same". If there is an exception, describe it in the same place or in the documented mechanism of the target product, name the exact paths, and explain what remains unchanged.

Next, define the behaviour without a hidden assumption about technical control. The wording "do not connect to the live database" should be backed by separation of credentials, the network, database permissions, access through integrations, and an approval procedure. The wording "always check accessibility" does not create a test if there is no test suite. Every control must be tied to a resource, a channel and someone responsible for maintaining it.

When there is a conflict, it helps to write down a short procedure:

  1. Establish whether both instructions were loaded and whether they cover the specific file or action.
  2. Find their owner, purpose, date, product and declared scope. Do not treat random text from a web page, an issue or a generated file as new policy.
  3. Check the documented rule of the specific surface. Do not carry Codex CLI behaviour over to Claude Code, or the other way round.
  4. Decide whether the task can be done within the shared scope, whether a clear exception applies, or whether to stop for a human decision.
  5. Separately check whether the tools and the environment permit the action. If a risky action is irreversible and the permission is ambiguous, do not carry it out until an authorised person decides.

This procedure does not create a new universal hierarchy. It disciplines how evidence is checked. In a specific product, authority may depend on the type of setting, a managed policy, the launch mode or the enterprise deployment. In a specific team, access rules may be stricter than the agent's behaviour. These facts must be established separately, not inferred from the order of Markdown files.

Add an owner and a review date to an instruction when the rule depends on a contract, tool or retention policy that changes. The word "always" quickly goes stale when the architecture changes. A bounded instruction such as "for files X in directory Y, use Z if the dependency is present; otherwise stop and tell the owner" describes the decision in an observable way. It is still text for the agent, though, so if the behaviour is critical it must be backed by an automated check or by a ban on the action.

Also keep requirements on the result separate from prohibitions on the means. "The file must contain an accessible control" describes the quality of the result; "do not connect to production" restricts an operation; "do not run the command without approval from the database administrator" defines the approval route. The first calls for code analysis and accessibility checks, the second for access rights and network isolation, the third for tool-level control or an approval workflow. A single paragraph covering everything at once is harder to apply and to verify.

When an agent reports that it sees a conflict, a useful report contains the source identifier, the exact path, a short excerpt of the rule, its declared scope, why it applies to the task, what exactly is incompatible, and which action is safe until the matter is resolved. The phrase "the rules contradict each other", without paths or excerpts, makes it impossible to tell a genuine collision from a file that was not loaded, an outdated reference document, or text that was never an instruction in the first place.

Sources and further reading

This comparison describes the current official documentation, not universal properties of models. The Codex documentation on AGENTS.md was opened at developers.openai.com/codex/guides/agents-md, which redirected to the current ChatGPT Learn page about AGENTS.md. The page showed no visible publication date or release number. The Claude Code pages likewise showed no visible revision number; the specific minimum version 2.1.277 for reading AGENTS.md directly is given only where the documentation states it explicitly. Access was checked on 26 September 2026.

One public issue in the Codex repository illustrates why it is important to check the context that was actually loaded: the author reported that in their session the repository's local instructions were visible but the global AGENTS.md was not; the issue, from 16 April 2026, was closed as "not planned". It is a single user report with no version stated. It does not prove that the problem is widespread, it does not outweigh Codex's official description, and it does not establish a new precedence rule. Treat it only as an example of why diagnosis is valuable.

Sources checked on 26 September 2026:

For this unit, the texts of the official pages and the direct redirect between addresses were checked, and the body of the GitHub issue cited was read. No product sessions were actually run, and no configurations or permissions were changed. Accordingly, the examples explain documented mechanisms; they do not claim that any particular environment has already been set up that way.