Codex in a Minute: AGENTS.md

In one sentence

AGENTS.md is a project guide written for coding agents so they can follow your repo’s real workflow.

Why it matters

Codex and similar tools perform better when the repository explains itself. Humans already keep README files for people. Agents need the operational subset: commands, constraints, and definition of done.

How it works

Keep an AGENTS.md (sometimes alongside other agent instruction files) that answers:

• how to install and run the project;
• which checks must pass;
• what not to touch;
• how to structure commits or PRs;
• where deeper docs live.

Prefer commands that copy-paste cleanly. Prefer rules that prevent common mistakes in this repo. Official Codex behavior and discovery rules should be confirmed in current OpenAI docs when you set this up.

Example

# Agent guide

## Setup
npm ci

## Verify
npm test && npm run lint

## Constraints
- Static export site: do not add runtime API routes for production features.
- Do not invent product claims in marketing copy.

Agentic coding use

AGENTS.md is shared infrastructure for any agent that lands in the repo—Codex today, another tool tomorrow. It reduces prompt repetition and makes agent failures diagnosable: either the instructions were wrong, or the agent ignored them.

Watch out

Do not maintain three conflicting instruction files with different test commands. Pick a source of truth and link out. Conflict between AGENTS.md, README, and chat prompts is a common agent failure mode.