AI Native Notes
Back to GPT Codex
GPT CodexBeginner4 min read

Codex Instructions — Make AGENTS.md Actually Useful

Use layered AGENTS.md files, `/init`, and config basics so Codex behaves consistently across repositories and tasks.

agents-mdconfigurationworkflowverification

Official References: AGENTS.md Guide · Config Basics · CLI Slash Commands · Best Practices

Curriculum path

  1. Codex Getting Started — install, sign in, first task
  2. Codex Instructions — instruction chain, /init, and config basics ← You are here
  3. Codex Sandboxing — permissions, approvals, and cloud environments
  4. Codex Task Design — scope, prompts, and task breakdown
  5. Codex Skills — package repeated workflows
  6. Codex MCP — connect external context
  7. Codex Reviews and Automations — review, worktrees, and unattended runs

Official docs used in this guide

Why this surface matters so much

If everything lives in the prompt, you keep re-explaining the same project context over and over. Codex works better when you split concerns:

  • today’s task in the prompt
  • long-lived repo rules in AGENTS.md
  • runtime defaults in config

That is the real point of the instruction chain.

How Codex discovers instructions

The AGENTS guide says Codex builds an instruction chain before it starts work.

In practice, that means:

  1. ~/.codex/AGENTS.override.md or ~/.codex/AGENTS.md
  2. project-level files from repo root down to your current directory
  3. nearer files apply later, so they override earlier guidance

A good mental model is:

  • home-level file = personal defaults
  • repo root file = team standards
  • nested file = local exception for one area

/init gives you a starting point, not a finished document

The slash command docs describe /init as a way to generate an AGENTS.md scaffold in the current directory. That is useful, but the scaffold is generic by design.

After /init, you usually still need to add:

  • real verification commands
  • protected paths
  • the project’s source of truth
  • rules around dependencies, migrations, and generated files

What belongs where?

Surface Put this there Do not put this there
AGENTS.md coding rules, architecture hints, test commands, guardrails one-off requests for the current task
config.toml model, approval policy, sandbox mode business logic or code style policy
Prompt current goal, constraints, done conditions permanent repo policy

Once you separate those three, prompts get shorter and Codex gets more predictable.

The minimum useful AGENTS.md structure

In real projects, four sections carry most of the value.

1. Project context

## Project context
- Next.js 16 App Router app
- Documents live in content/{locale}/{tool}/*.mdx
- UI components live under src/components/

2. Working agreements

## Working agreements
- Prefer small diffs
- Do not add dependencies without approval
- Reuse existing patterns first

3. Verification

## Verification
- npm run lint
- npm run build
- Do not claim completion if checks fail

4. Do not

## Do not
- Edit generated files directly
- Commit secrets
- Change public APIs casually

Only use nested AGENTS when rules truly differ

Nested AGENTS.md files are powerful, but too many create confusion. The right question is simple:

Does this folder actually need different rules?

Good examples:

  • apps/web/AGENTS.md for rendering and UI rules
  • infra/AGENTS.md for deployment boundaries

Bad example:

  • repeating the repo-root file almost verbatim in every subdirectory

Config knobs worth touching first

Config basics highlights the most common defaults people change:

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

The important point is not the exact model name forever. It is that your team chooses explicit defaults instead of rediscovering them every session.

Use prompts like issues, not like vague requests

Even with good instructions, a vague task still produces shaky results. That is why Codex best practices recommend issue-shaped prompts.

The simplest structure is:

  • Goal
  • Context
  • Constraints
  • Done when

That alone removes a lot of guessing.

Common mistakes

1. Putting every rule in the prompt

This creates repetition and inconsistent behavior.

2. Writing AGENTS.md like a giant project history file

Execution rules matter more than narrative background.

3. Listing verification commands that do not actually work

That misleads both Codex and humans.

4. Adding too many nested AGENTS files

More overrides means more surprise.

Short version

  • Use /init to draft the file
  • put durable repo rules in AGENTS.md
  • put runtime defaults in config
  • keep today’s request in the prompt

That split is one of the biggest upgrades you can make to Codex quality.

Connected Guides