AGENTS.md examples: Python, Java, monorepo, and Codex overrides
Copy-paste AGENTS.md examples for a Python service, a Java Spring Boot app, and a monorepo, plus Codex override files and the rules for which file wins.
Most AGENTS.md files describe the project. The useful ones give orders: the exact command to run the tests, the directory never to edit, the format every pull request title must follow. An agent can read your code; it can't read your team's habits.
This post gives three copy-paste examples and the rules for how agents combine several files, based on agents.md and OpenAI's AGENTS.md guide for Codex, checked on 16 November 2026. For a full TypeScript example and what to leave out, see AGENTS.md vs CLAUDE.md.
What goes in
The agents.md site lists popular sections: project overview, build and test commands, code style guidelines, testing instructions, and security considerations. It adds that anything you'd tell a new teammate belongs there too, such as commit and PR guidelines, security gotchas, large datasets, and deployment steps.
Two of its answers are worth knowing before you write:
- The agent runs the commands you list. It will try to run relevant checks and fix failures before finishing. So write exact commands, not descriptions.
- The file is living documentation. Update it when a command or rule changes.
Example 1: a Python service
# AGENTS.md
## Setup
- Python 3.12, managed with uv. Install: `uv sync --all-extras`
- Copy .env.example to .env. Tests need Postgres: `docker compose up -d db`
## Commands
- Tests: `uv run pytest -x`. One test: `uv run pytest tests/test_orders.py -k refund`
- Lint and types: `uv run ruff check . && uv run mypy src` before every commit
- Migrations: `uv run alembic revision --autogenerate -m "<message>"`, then review the file
## Code style
- Type hints on every public function.
- Money is integer cents (`int`), never `float`.
- Raise domain errors from src/errors.py; don't return None for failures.
## Boundaries
- Never edit files in migrations/versions/ after they are merged.
- Never log request bodies or fields marked PII in src/models.py.
## Pull requests
- Title: `<area>: <summary>`, e.g. `billing: refund partial captures`
- Run lint, types, and tests before opening. Paste the test result in the description.
Example 2: a Java Spring Boot app
# AGENTS.md
## Setup
- Java 21, Gradle wrapper. Build: `./gradlew build`
- Local dependencies: `docker compose up -d postgres redis`
## Commands
- Unit tests: `./gradlew test`. One class: `./gradlew test --tests "*OrderServiceTest"`
- Integration tests: `./gradlew integrationTest` (needs Docker running)
- Format: `./gradlew spotlessApply` before every commit
## Code style
- Constructor injection only; no field `@Autowired`.
- Controllers stay thin. Business logic lives in `*Service` classes.
- DTOs are Java records in the `api` package. Never expose JPA entities from controllers.
## Boundaries
- Flyway migrations in src/main/resources/db/migration are append-only. Add a new version.
- Don't change public API paths under /api/v1 without a deprecation note in CHANGELOG.md.
## Pull requests
- Run `./gradlew build` locally. CI runs the same plus integration tests.
Example 3: a monorepo
Put shared rules at the root and package rules in each package. Agents read the nearest file, so the closest one takes precedence.
Root AGENTS.md:
# AGENTS.md
## Repo
- pnpm workspaces with Turborepo. Install at the root: `pnpm install`
- Find a package: `pnpm dlx turbo run where <package>`
## Commands
- One package: `pnpm turbo run test lint typecheck --filter <package>`
- Everything (CI): `pnpm turbo run test lint typecheck`
## Pull requests
- One package per PR when possible.
- Changes to packages/shared need a reviewer from each team that uses it.
apps/api/AGENTS.md:
# AGENTS.md (apps/api)
- Dev server: `pnpm --filter @acme/api dev` on port 4000. Needs `docker compose up -d db`.
- Errors use problem+json through httpError() in src/errors.ts.
- The audit_events table is append-only. Corrections are new rows.
Don't repeat root rules in package files; say only what is different. If a package genuinely overrides a root rule, say so explicitly.
How several files combine
| Situation | What happens |
|---|---|
| Several AGENTS.md files on the path | The closest file to the edited code wins (agents.md) |
| You give a conflicting instruction in chat | The chat instruction wins |
| Codex | Concatenates files from the git root down to your directory; closer files come later and override |
| Codex size limit | 32 KiB for the combined chain by default (project_doc_max_bytes) |
| Codex override files | AGENTS.override.md is checked before AGENTS.md in each directory |
| Claude Code | Reads AGENTS.md when there's no CLAUDE.md; a CLAUDE.md can import it with @AGENTS.md |
Codex: overrides and fallbacks
Codex adds two extras (Codex guide):
- Overrides.
~/.codex/AGENTS.override.mdreplaces your global~/.codex/AGENTS.mdwhen it exists, and anAGENTS.override.mdin a directory is read before that directory's AGENTS.md. Useful for a temporary personal instruction you don't want to commit. - Fallback names.
project_doc_fallback_filenamesin~/.codex/config.tomllets Codex read other file names, such asCLAUDE.md, where no AGENTS.md exists.
To check what Codex loaded, its guide suggests asking it: codex --ask-for-approval never "Summarize the current instructions."
Keep it current
The fastest way an AGENTS.md goes wrong is a command that changed and a file that didn't. Update it in the same pull request that changes the command. And keep decisions that change often, such as which API version is being retired, out of it, or give each one a date and a link to where it was decided.
Where Lockstep fits
Lockstep keeps those changing decisions out of AGENTS.md and in one shared record. Decisions are captured from PRDs, Slack, and pull requests and become binding when their owner approves them. Claude Code is briefed on the ones that apply at the start of each session, and any MCP agent can query the record. Codex isn't supported yet, so Codex users get no automatic briefing.
See how it works.
Sources checked 16 November 2026
- https://agents.md
- https://learn.chatgpt.com/docs/agent-configuration/agents-md
- https://code.claude.com/docs/en/memory
Related reading
For the TypeScript example and what to leave out, see AGENTS.md vs CLAUDE.md. For Claude Code's file, see CLAUDE.md examples. For Codex memory, see Codex memory, and how to share it with Claude Code. For GitHub Copilot's own instruction files, see AGENTS.md vs copilot-instructions.md. For what stays in the README, see AGENTS.md vs README.md.
Frequently asked questions
- What should an AGENTS.md file contain?
- The agents.md site lists popular sections: project overview, build and test commands, code style guidelines, testing instructions, and security considerations, plus anything you'd tell a new teammate, such as PR guidelines or deployment steps. Keep commands exact so the agent can run them.
- Which AGENTS.md wins when there are several?
- Per the agents.md site, the AGENTS.md closest to the edited file wins, and explicit instructions in chat override everything. Codex concatenates files from the git root down to the current directory, so files closer to where you work come later and take precedence.
- Will the agent run the test commands in AGENTS.md?
- Yes, if you list them. The agents.md site says the agent will try to run relevant programmatic checks and fix failures before finishing the task.
- What is AGENTS.override.md?
- A Codex file. In each directory, Codex checks AGENTS.override.md before AGENTS.md, and globally it reads ~/.codex/AGENTS.override.md instead of ~/.codex/AGENTS.md when it exists. Use it for temporary or personal overrides. Claude Code does not read it.
- How long should AGENTS.md be?
- Short enough to stay current. Codex caps the combined instruction chain at 32 KiB by default, and Anthropic recommends under 200 lines for Claude Code's instruction files. Long files cost context and get followed less reliably.
Keep reading