A Practical Guide to AGENTS.md: Writing Instructions for Codex

AI helped draft and revise the Chinese original, then translate and adapt it into English.

Why should Codex users know about AGENTS.md?

If you use Codex to build projects, or do a lot of vibe coding, some of these problems may sound familiar:

1. You're a product manager who wants to discuss the user experience and possible solutions, but the AI keeps getting into technical details.
2. You only want to talk through an idea, but the AI starts changing code. By the time you realize it's going in the wrong direction, there's work to undo.
3. Your project already has a module that does the job, but the AI builds another one. The project gets messier with every change.
4. You just told it not to change a particular part of the project. In the next chat, you have to say it all again.
5. You ask it to change a button, and it also changes the nearby text and layout.
6. Your project already has shared components, styles, and coding conventions, but the AI's changes don't follow them.
7. You've already agreed on the product positioning and business rules, but the AI changes those details while editing a page.
8. The AI says the work is done. You open the result, find problems, and realize it never checked its changes.
9. Every new task starts with another explanation of the project structure, how to run it, and what to watch out for.

Part of the problem is that the rules you want the AI to follow haven't been provided clearly and consistently. And we can't always remember to explain everything, at the right time, in every conversation.

If you've used Claude Code, you can think of AGENTS.md as a file with a similar purpose to CLAUDE.md.

At their core, CLAUDE.md and AGENTS.md serve the same purpose: they record ongoing collaboration requirements and project knowledge so an AI coding assistant can load them into its context while it works. Both tools' official documentation describes using these files for project conventions, workflows, and personal preferences.

Put simply, they're instruction manuals for the AI. They tell it:

1. How to work with you.
2. What rules the project follows.
3. What it shouldn't change without asking.

How do you write an AGENTS.md file?

1. Group the problems into categories

Let's start by grouping the problems above:

Problem	Category
1. You want to discuss the user experience and possible solutions, but the AI keeps explaining technical details.	Your background and communication preferences
2. You're only discussing an idea, but the AI starts changing code.	The workflow for discussion and implementation
3. The functionality already exists, but the AI builds it again.	Existing modules and reuse requirements
4. You have to repeat the same restrictions in every new chat.	Ongoing agreements and restrictions on changes
5. You ask for a button change, but other things get changed too.	Scope of changes
6. The components, styles, and code don't follow the project's conventions.	Development conventions
7. The AI changes product positioning or business rules you've already agreed on.	Product positioning and business rules
8. It says the work is done without checking the result.	Completion criteria and verification requirements
9. You have to keep explaining the project structure and how to run it.	Project structure and setup instructions

If we then group these requirements by where they apply, we get two broad categories:

1. Personal preferences and collaboration requirements: your background, communication preferences, how you move from discussion to implementation, and general expectations about scope and delivery. You usually want the AI to work with you this way even when you switch projects.
2. Project context and conventions: this project's structure and setup, existing modules and reuse requirements, development conventions, product positioning, business rules, and specific restrictions and verification steps.

Some problems involve both. For example, "Check your changes and tell me if you haven't" is a general requirement. "Here is how to check changes in this project" is a project convention.

Codex supports managing these instructions at both the global and project levels.

Here are the main points from the official AGENTS.md documentation, summarized:

• Global: The Codex home directory defaults to ~/.codex. You can change it with CODEX_HOME. Codex prefers AGENTS.override.md; otherwise, it uses AGENTS.md.
• Project: Codex checks each directory along the path from the project root to the current working directory. In each directory, it prefers AGENTS.override.md, then AGENTS.md. You can also configure fallback filenames. Codex uses at most one file per directory.
• Combined instructions: Codex combines the files in order: global, project root, then deeper directories along the path. If instructions conflict, those closer to the current working directory take priority.

Put simply, Codex loads the applicable global and project instructions into its context to guide its work.

Use the global file for general requirements, and the project file for that project's context and rules. Instructions that don't conflict work together. Where they do conflict, the more specific project instructions take priority.

Following this approach, we can write two AGENTS.md files:

1. Global AGENTS.md: stored at ~/.codex/AGENTS.md by default, for personal preferences and collaboration requirements that apply across projects.
2. Project AGENTS.md: stored in the project root, for that project's context and conventions.

You don't have to write both. Start with the instructions you actually need.

2. What goes in a global AGENTS.md?

Location: ~/.codex/AGENTS.md by default.

Content: requirements that still apply when you switch projects, such as your background, communication preferences, discussion and implementation workflow, and general expectations about scope and delivery.

Example: Here's a short global AGENTS.md for a product manager. Adjust it to match your background and how you like to work.

# How to work with me

- I'm a product manager. Prioritize user problems, product ideas, the user
  experience, and final copy in our discussions.
- When discussing a technical approach, explain why you recommend it, its impact,
  and the tradeoffs. Explain code details when needed.
- When I ask for opinions, analysis, or a discussion of possible solutions,
  discuss first. Change files when I explicitly ask you to implement and the
  goal and scope are clear.
- Only change what the current task involves. If you need to expand the scope,
  explain why and confirm with me first.
- When you're done, tell me what users will see, what you verified, and what
  remains unresolved.

3. What goes in a project AGENTS.md?

Location: the project root.

Content: the project's background and specific requirements, such as its structure and how to run it, existing modules and reuse requirements, development conventions, product positioning, business rules, and specific restrictions and verification steps.

Example: Here's a short project AGENTS.md. Replace the text in square brackets with your project's actual details.

# Project conventions

- This project is [project description], mainly for [target users].
- Main features live in [directory], and shared components live in [directory].
  Check the existing implementation before developing a feature, and prefer
  reusing existing modules and components.
- Reuse the project's existing components and follow its styles and naming
  conventions.
- Use [document path] as the source of truth for product positioning and business
  rules. When editing pages, don't change agreed pricing, plan benefits, or
  business workflows without approval.
- Start the project locally with [command]. Run checks and tests with [commands].
- After changing [feature], verify [the relevant user flow].

4. Optional: AGENTS.override.md

What it does: provides an instruction file that takes priority. Within the same directory, Codex reads AGENTS.override.md instead of that directory's AGENTS.md.

When it can be useful:

1. Temporarily changing your global requirements. Put the instructions you want to use for a while in ~/.codex/AGENTS.override.md. Keep the original AGENTS.md so you can return to it later.
2. Giving a module its own requirements. For example, your payments module might need a different way to run tests. You can create an AGENTS.override.md in the payments directory. Starting a chat with that directory as the working directory brings those instructions into context.

Things to keep in mind:

• Only one file is loaded per directory. If there are instructions in the original AGENTS.md that you still need, include them in the override file too.
• Instructions from other levels still load. An override in the payments directory doesn't clear the global and project instructions. Where they conflict, the instructions closer to the current working directory take priority.
• It doesn't expire automatically. If you're using it temporarily, move it out of the directory or rename it when you're done, then start a new chat.
• You don't need an AGENTS.md first. You can use an override file even if there's no regular AGENTS.md in that directory. You can also put a subdirectory's specific instructions in a regular AGENTS.md. What makes the override different is its priority within the same directory.

If you're just getting started, write the global and project instructions you need first. Use an override when there's a reason to.

Optional reading: How AGENTS.md works

1. When does Codex read AGENTS.md?

When you start a new chat in a project and begin a task, Codex automatically loads the applicable AGENTS.md instructions.

If you update one of these instruction files during a chat, you can ask Codex to read it again, or start a new chat to load the updated instructions.

2. How does Codex find AGENTS.md?

Codex looks for global instructions first, then checks the directories along the path from the project root to the current working directory.

For example, if you start a chat with the project's payments directory as the working directory, the order is:

Global instructions -> Project root instructions -> Payments directory instructions

If any directories in between have instruction files, Codex loads those too. The search stops at the current working directory.

3. If both files are in the same directory, which one does Codex read?

Codex prefers AGENTS.override.md. If there isn't a usable override file, it reads AGENTS.md. Empty files are skipped.

4. How do you check after creating or updating a file?

Save the file, start a new chat in the project, and check whether the instructions have loaded. You can ask:

List the paths of the instruction files loaded for this chat, and summarize the main requirements from each.

Check the paths and summaries, then try a small task. For example, if you wrote "Don't change code while we're discussing an approach," see whether Codex follows that instruction. Along with checking what it says it loaded, check what it actually does.

References

1. My own experience with nearly a year of regular vibe coding.

2. Official AGENTS.md documentation

The main reference for this guide. Covers file locations, loading order, overrides, and ways to check which instructions are loaded.

1. Rethinking skills and prompts for GPT-6 Astra

Explains how to remove outdated instructions, provide context for the task at hand, and make collaboration boundaries clear. Some recommendations are specific to GPT-6 Astra.

1. Official Projects and chats documentation

Explains the working directory used for new chats in the desktop app and where Codex automatically looks for AGENTS.md.

1. Official Claude Code documentation

Explains what CLAUDE.md is for and how it stores collaboration requirements and project conventions.