Codex AGENTS.md: Write and Verify Repository Instructions

Codex can make a technically sensible change that still violates your repository’s rules. It might rename a public field, choose the wrong test command or edit generated files that should have been rebuilt. Repeating “follow our conventions” rarely resolves the underlying problem: the conventions are either missing, ambiguous or outside the instruction scope used by the task.

An AGENTS.md file gives those recurring decisions a visible home. This guide shows how to write useful instructions, check which ones apply and verify the resulting change. The examples describe a fictional repository, not a claim that a particular prompt guarantees correct behaviour.

Begin with the failure you want to prevent

Write down one mistake that would make a change unacceptable. For an API, that could be returning a different error shape. For an Android app, it could be adding a permission without reviewing the Play policy implications. A useful instruction names the protected behaviour and tells the agent what to do instead.

Compare “write production-quality code” with “keep the existing JSON error fields because the mobile client reads them; add a regression test when changing error handling.” The second version gives the reviewer something to inspect. It also explains why an apparently helpful refactor may be wrong.

Keep facts about the project separate from permission to act. Knowing a deployment command exists does not mean a coding task should run it. An instruction file can identify the command while requiring explicit approval before a production deployment.

Place shared rules at the root and local rules near their code

The official OpenAI documentation describes global guidance and project guidance discovered along the path to the current working directory. A nearer project file can refine earlier guidance. An AGENTS.override.md file can take precedence over AGENTS.md in the same directory. Check that discovery chain before assuming a rule is being ignored.

For example, this repository separates a web client from a Python service:

example-project/
  AGENTS.md
  web/
    AGENTS.md
    package.json
  services/
    api/
      AGENTS.md
      tests/

The root file should contain the agreements that apply everywhere. The API file can describe its error contract and tests. Keep web build commands out of the API instructions unless the change genuinely affects both components.

Do not assume a root-scoped task automatically includes every nested instruction file. OpenAI’s documented discovery follows the working-directory path. For a task confined to the API, start in that directory or explicitly direct the agent to inspect its applicable guidance before editing.

A small instruction file with observable requirements

Save an instruction file as plain UTF-8 text. Here is an original example for the fictional repository root:

# Project working agreements

Read the existing implementation before changing behaviour.
Preserve unrelated local edits and existing public URLs.
Do not commit credentials or put customer data in diagnostic output.

For a bug fix, reproduce the failing behaviour or explain why reproduction
is unavailable. Prefer a regression test that fails before the fix.

Do not edit generated assets directly. Find their source and rebuild them.
If the build process is unavailable, report that limitation.

Before finishing, report the changed files and checks actually run.
State skipped checks and their reason. A proposed command is not a test result.

Production deployment requires explicit approval for the current change.

That file does not pretend to know a test command the repository has not defined. Add real commands only after checking the project configuration. An obsolete command copied into an instruction file can cause the agent to spend its effort fixing the wrong environment.

A local services/api/AGENTS.md could add a rule such as:

# API-specific requirements

Preserve the existing JSON error response contract.
The Android client depends on the current field names.

When changing error handling, add a test for the response body and status.
Do not expose exception traces or credentials in client-facing responses.

Use the test command documented in this service's README.
If the README disagrees with the current configuration, identify the conflict
before updating either file.

The final instruction avoids treating the README as infallible. Documentation drifts. The agent should compare evidence and explain the discrepancy rather than quietly rewriting a command until something turns green.

Verify instruction discovery before requesting a large edit

Start with a read-only check from the intended directory. If the Codex CLI is installed, this command asks it to explain scope without editing:

codex --cd services/api "Summarize the instruction files that apply here. Identify the protected API behaviour and the documented test command. Do not edit files or run deployment commands."

Compare the response with the actual files. If it mentions the web instructions while missing the API rule, inspect the working directory, a same-directory override and any configured fallback names. An empty instruction file is another reason a file may contribute nothing useful.

OpenAI also documents a size limit for combined project guidance. If rules are being truncated, shortening duplicated material is usually a better first move than turning the root file into a larger manual. Put specialist detail beside the component that needs it and link to supporting material where appropriate.

After changing guidance, verify it in a new run. Do not assume a conversation already in progress has rebuilt its initial instruction chain. The command above invokes your configured Codex environment; it has not been benchmarked here against a paid model account.

Make the coding request testable as well

The instruction file carries recurring agreements. The task prompt should describe the current defect. Give the observed behaviour, expected result and protected scope. Include relevant evidence without pasting secrets or an entire production database.

Fix the API error response for an unknown task ID.
Observed: the endpoint returns an HTML error page.
Expected: the existing JSON error contract and an appropriate HTTP status.
Inspect the route and error middleware first.
Add a regression test for this case.
Do not rename response fields or change other endpoints.
Report the test command, its result and anything you could not verify.

This is an example of a bounded task, not a diagnosis of your service. Replace the observed failure with one you have actually reproduced. The official prompting guidance provides further advice on giving Codex useful task context.

Inspect the diff after the change. Run the relevant test in the correct environment and check that it asserts the behaviour you care about. A passing test that only checks whether a function exists will not protect an API response contract.

Keep review rules specific enough to catch a real defect

For repositories using Codex review, OpenAI documents custom review rules in AGENTS.md. A useful review rule explains which behaviour to flag, rather than asking for a vague standard such as “review everything carefully.” See Custom Code Review rules for Codex.

For the example API, a review rule might ask the reviewer to flag any change that sends internal exception details to a client. The supporting test should exercise a server failure and inspect the returned body. A comment in the instruction file cannot enforce that boundary by itself.

Review repeated failures over time. If the same misunderstanding recurs, improve the smallest relevant rule and retain the regression test. Adding another page of general advice makes the important requirement harder to find.

Keep access controls outside the prose. Repository instructions are not a security sandbox, and a sentence saying “never leak secrets” cannot replace restricted credentials or deployment permissions. Grant only the tools and data the task needs.

For broader work on evaluating AI outputs and designing bounded tasks, use the production prompt-engineering course. The next practical step is to choose one recurring mistake in your own repository, write a rule that names it, and prove that a test would catch it.