How to Write AGENTS.md for a Python Project

A repository-level AGENTS.md tells coding agents how to work in your Python project before they read a task. Codex and Claude Code can both read it, so one file can share commands and boundaries across the two tools.

Prerequisites

• Codex or Claude Code installed and authenticated
• An existing Python project
• The commands your project uses to install dependencies and run checks

The template uses uv, Ruff, pytest, and Pyrefly. Remove or replace any command that your project does not use.

Write the repository guide

Create AGENTS.md at the Git repository root:

# Repository guide

## Project structure

- Application code lives in `src/`.
- Tests live in `tests/` and mirror the package layout.
- Treat `uv.lock` as generated output. Update it with uv, not by hand.

## Python workflow

- Use `uv add` and `uv remove` for dependencies. Do not use pip.
- Run Python commands and tools with `uv run`.
- Read `pyproject.toml` before changing dependencies or tool settings.

## Quality checks

- Run tests with `uv run pytest`.
- Run linting with `uv run ruff check .`.
- Check formatting with `uv run ruff format --check .`.
- Run type checking with `uv run pyrefly check`.

## Change boundaries

- Ask before adding a production dependency.
- Do not edit generated files or secrets.
- Keep changes limited to the requested task.

Keep rules concrete. “Write clean code” gives Codex no testable action; “run uv run ruff check . after editing Python” names the trigger and the command.

Do not put passwords, API keys, or other secrets in AGENTS.md. Coding agents load the file into their instruction context.

Configure Codex scopes

Put preferences that should follow you across repositories in ~/.codex/AGENTS.md. Put shared build commands, repository structure, and contribution rules in the project’s AGENTS.md.

Codex loads the global file first, then project files from the repository root down to the current working directory. Guidance closer to the working directory appears later and takes precedence when rules conflict.

Use AGENTS.override.md for a temporary replacement at one directory level. When both files exist in the same directory, Codex reads the override and ignores that directory’s AGENTS.md.

Add narrower rules near specialized code

Add a nested AGENTS.md when one part of the repository needs different commands. For example, docs/AGENTS.md can require a documentation build while the root file keeps the Python test commands.

Codex only discovers nested files between the repository root and its current working directory. Start Codex in docs/, or pass --cd docs, when you want docs/AGENTS.md to join the instruction chain.

Keep the root file useful on its own. A nested file should add or replace only the rules that differ for that subtree.

Use the file with Claude Code

By default, Claude Code reads AGENTS.md only when the project has no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md between the project root and the working directory.

Open /config in Claude Code and change Project instructions when you want to load both CLAUDE.md and AGENTS.md, or to use only CLAUDE.md. Claude Code can also load nested AGENTS.md files as it reads text files in those directories, but its discovery behavior is not identical to Codex’s.

Let Codex reuse CLAUDE.md

If the repository already maintains CLAUDE.md or another guidance file, add its name to ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

At each project directory, Codex checks AGENTS.override.md, then AGENTS.md, then the configured fallback names. It reads at most one non-empty instruction file from that directory, so CLAUDE.md is ignored there when AGENTS.md exists.

Restart Codex after changing the configuration or an instruction file. Codex rebuilds the instruction chain when a run starts, not while a session is already open.

Verify Codex instructions

From the repository root, ask Codex to report its instruction chain:

codex --ask-for-approval never "List the instruction files you loaded in precedence order, then summarize the active rules."

Expect the response to name your global file when one exists, followed by the repository’s AGENTS.md.

If the project has docs/AGENTS.md, verify the nested scope separately:

codex --cd docs --ask-for-approval never "List the instruction files you loaded in precedence order, then summarize the active rules."

The second response should list the global file, the root file, and docs/AGENTS.md in that order. If a file is missing, check for an AGENTS.override.md, confirm that the file is not empty, and restart the session from the intended directory.

For Claude Code, open /config and confirm the Project instructions mode first. Then ask Claude Code to list the instruction files it loaded. If it omits AGENTS.md, check whether the default mode found a project CLAUDE.md or whether the session uses Bedrock, Vertex AI, or Foundry.

Back guidance with automated checks

Treat AGENTS.md as guidance, not enforcement. Keep formatters, tests, and type checks in CI or pre-commit so a missed instruction still produces a failing check. Use each tool’s permissions and sandbox settings for access controls instead of relying on a sentence in the file.