What Is AGENTS.md? A Beginner’s Guide to Project Rules in Codex CLI

Do you find yourself telling Codex CLI the same things every time you ask it to modify code—“use pnpm, not npm,” or “run the tests when you are done”?

Your package manager, test procedure, protected directories, and dependency policy usually remain the same even when the task changes. Instead of repeating those instructions in every prompt, you can store them in an AGENTS.md file. Codex reads that file before it starts working and uses the contents as persistent project guidance.

This guide focuses on three practical outcomes. By the end, you will be able to:

1. Explain what AGENTS.md is for
2. Add a minimal file to your own project
3. Check whether Codex CLI loaded it

What is AGENTS.md?

AGENTS.md is a Markdown file that tells coding agents such as Codex about a project’s structure, development rules, commands, restrictions, and definition of done. OpenAI’s documentation describes it as something like a README for agents.

Before starting work, Codex searches for instruction files and adds the instructions it finds to the context alongside your task-specific prompt. You therefore do not need to repeat rules such as these every time:

• Use TypeScript for new source files
• Use pnpm instead of npm
• Run tests after changing application code
• Do not add production dependencies without permission
• Report the changes and verification results at the end

An effective AGENTS.md is short, specific, and phrased so Codex can act on or verify its instructions.

How it differs from README.md

This does not mean Codex cannot read README.md. Codex can inspect a README and other documentation when relevant. The important distinction is that Codex automatically discovers AGENTS.md as a project instruction file and includes it in its working context.

How it differs from a regular prompt

A regular prompt describes the task you want completed now. AGENTS.md contains rules that should apply repeatedly across tasks in the same project.

For example, this belongs in a prompt:

Add a button to the login screen that toggles password visibility.

These instructions belong in AGENTS.md:

- Follow the existing patterns in `src/features/`.
- Do not add production dependencies without asking.
- Run `pnpm test` after changing application code.

In short, the prompt says what to change; AGENTS.md says how to work and what to verify.

Why use AGENTS.md?

Stop repeating setup instructions

Within a project, the package manager and test commands generally do not change from one task to the next. Putting them in AGENTS.md removes the need for a long preamble in every request.

It also reduces omissions. You are less likely to forget the lint instruction on one task or the dependency policy on another.

Reduce assumptions

Codex can inspect repository files and infer much of the technical setup, but source code does not always reveal team-specific rules.

• Use pnpm, not npm
• Start Docker Compose before integration tests
• Never edit generated files directly
• Update the relevant documentation when a public API changes
• Ask before changing the database schema

Writing these rules down reduces the amount of work Codex has to base on general conventions or guesses.

Share one set of rules with the team

If you commit the root AGENTS.md to Git, everyone using Codex in that repository can work from the same instructions. Test procedures and restrictions no longer live only in one person’s prompt history.

Where should AGENTS.md go?

For your first setup, one AGENTS.md file at the root of the Git repository is enough.

my-app/
├── AGENTS.md
├── README.md
├── package.json
├── src/
└── tests/

After checking global guidance, Codex searches for project instructions along the path from the project root to the current working directory. It combines the files from root to leaf, so instructions closer to the working directory are applied later.

That behavior is useful in monorepos, but you do not need a complex hierarchy on day one. Start with one accurate root file and split it only when a concrete need appears.

Put personal defaults in ~/.codex/AGENTS.md

Personal working preferences that should apply across all projects can live in the Codex home directory:

~/.codex/AGENTS.md

For example:

# Personal preferences

- Explain important design decisions.
- Keep changes focused on the requested task.
- Report commands that failed.

Do not keep team-wide technical rules only in your personal file, because other contributors will not receive them. Repository decisions such as using pnpm or running a particular test command belong in the project file.

You can add files in subdirectories

If one part of a repository needs extra guidance, add another AGENTS.md within that directory.

my-repository/
├── AGENTS.md
└── services/
    └── payment/
        └── AGENTS.md

The root file might define common rules, while services/payment/AGENTS.md provides payment-service test procedures.

Codex also supports AGENTS.override.md when instructions at the same level must explicitly replace regular guidance. Beginners should first focus on keeping one root AGENTS.md accurate.

Write a minimal AGENTS.md

Start with just five rules

Save the following file at your project root:

# Project rules

## Development

- Use TypeScript for new source files.
- Use `pnpm` instead of `npm`.

## Verification

- Run `pnpm test` after changing application code.
- Run `pnpm lint` before completing the task.

## Restrictions

- Do not add production dependencies without asking.

You do not have to write the file in English. Use whichever language your team can maintain clearly.

Specify languages and tools

- Use TypeScript for new source files.
- Use `pnpm` instead of `npm`.

These lines settle two choices: the language for new files and the package manager. Do not rely on Codex to infer a decision correctly if choosing the wrong option would cause trouble.

At the same time, do not impose technology that the repository does not use. If the project contains only JavaScript and no TypeScript migration is planned, omit the first rule.

Define verification commands

- Run `pnpm test` after changing application code.
- Run `pnpm lint` before completing the task.

These rules make the definition of done explicit. Changing the code is not the final step; Codex should run the relevant checks too.

State when a command should run, not only which command to use. If documentation-only changes do not require the test suite, limiting the rule to application-code changes makes it more useful.

State what Codex must not do on its own

- Do not add production dependencies without asking.

You can require confirmation before high-impact operations such as adding dependencies, changing a database schema, modifying a public API, or touching generated files.

Avoid vague rules such as “do not make large changes.” Name the operation instead:

- Ask before adding a production dependency or changing the database schema.
- Do not edit files in `src/generated/` directly.

Add a short repository map if useful

A small map can point Codex toward the most important locations:

## Repository structure

- `src/components/`: UI components
- `src/features/`: Feature-specific logic
- `src/lib/`: Shared utilities
- `tests/`: Automated tests

You do not need to list every directory. Prioritize locations with non-obvious roles and existing patterns that new work should follow.

How to create AGENTS.md

Create it manually

Move to the project root and create an empty file:

cd path/to/my-app
touch AGENTS.md

Open it in your editor and add rules the project actually uses:

code AGENTS.md

Your first version can contain only the package manager, test command, lint command, and important restrictions. Check that every command you list really exists in package.json or the project’s task configuration.

Generate a starting point with /init

When an interactive Codex CLI session is running in the target directory, the /init command can generate an AGENTS.md scaffold there:

/init

Treat the result as a draft, not a finished policy. Compare it with the project’s actual build, test, and review process, then correct inaccurate commands and remove unnecessary text.

Verify that Codex loaded the file

After creating the file, ask Codex to summarize the rules from the project root:

codex "Summarize the project rules you must follow in this repository."

Inside an interactive session, you can ask:

List the project rules currently loaded for this session.

If Codex loaded the sample correctly, its answer should include roughly these points:

- Use TypeScript for new source files
- Use pnpm instead of npm
- Run tests after changing application code
- Run lint before completing the task
- Do not add production dependencies without permission

Codex builds its instruction chain when it runs, usually at the beginning of an interactive CLI session. If a newly created or edited file does not take effect, verify that it is inside the intended repository, start Codex from the correct directory, and begin a new session.

What belongs in AGENTS.md?

When you are unsure what to include, organize the file around five categories:

It is also useful to define the final report:

- At the end, summarize changed files and verification results.
- Report any checks that could not be run and explain why.

Do not try to make the first version perfect

AGENTS.md is not a complete architecture specification. It is a place for concrete, verifiable rules that Codex should follow repeatedly.

Start small. Add a rule when Codex repeats the same mistake or when the team adopts a new shared convention. Accuracy matters more than length: the file must reflect the repository as it exists today.

If a topic needs extensive background, point to the authoritative document instead of duplicating it:

- Read `docs/architecture.md` before changing module boundaries.

Common beginner mistakes

Writing only vague guidance

These instructions do not provide an observable completion condition:

- Write good code.
- Follow best practices.
- Be careful.

Replace them with actions Codex can perform or verify:

- Run `pnpm test` and `pnpm lint` before completing the task.
- Follow the existing patterns in `src/features/`.

Pasting an entire design document

Duplicating extensive background material makes inconsistencies with the source document more likely. Keep the operational essentials in AGENTS.md and point to the authoritative documentation when necessary.

Listing commands that do not exist

Writing pnpm test does not create a test script. Check package.json, your task runner, and CI configuration, then document a command that can actually run.

Creating the file and never maintaining it

When the package manager, directory layout, or CI checks change, update AGENTS.md as well. Whenever a change modifies the development workflow, check whether the agent instructions also need updating.

Summary

AGENTS.md is a Markdown file for persistent project guidance in Codex CLI. Start with one file at the repository root and document a small set of real commands, verification steps, and restrictions.

# Project rules

- Follow the existing project structure.
- Use the package manager already configured in this repository.
- Run the relevant tests after changing code.
- Do not add dependencies without asking.
- Summarize the changes and verification results.

After saving it, run this command from the project root:

codex "Summarize the project rules currently in effect."

If the response contains the rules you expected, your first AGENTS.md is working. From there, expand it gradually whenever Codex encounters a recurring ambiguity or your team adopts a new concrete rule.