# 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](https://pydevtools.com/handbook/explanation/codex-complete-guide.md) 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](https://pydevtools.com/handbook/reference/uv.md), [Ruff](https://pydevtools.com/handbook/reference/ruff.md), [pytest](https://pydevtools.com/handbook/reference/pytest.md), and [Pyrefly](https://pydevtools.com/handbook/reference/pyrefly.md). Remove or replace any command that your project does not use.

## Write the repository guide

Create `AGENTS.md` at the Git repository root:

```markdown {filename="AGENTS.md"}
# 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.

> [!NOTE]
> Anthropic has not yet enabled `AGENTS.md` support for Claude Code sessions that use Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

## Let Codex reuse CLAUDE.md

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

```toml {filename="~/.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:

```bash
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:

```bash
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.