Build an AGENTS.md your Python coding agent will follow

A coding agent is an AI assistant that runs inside your project, reads your files, edits them, and runs commands on your behalf. Claude Code, Codex CLI, and the agent mode in Cursor are the three most-used ones in 2026. They all read the same kind of file at the root of your repository: a plain Markdown document called AGENTS.md. The file has no required schema. Whatever you put in it is what the agent sees at the start of every conversation, and what it keeps in mind for every follow-up turn.

The reason the file matters is the alternative. Without context, an agent asked to add two endpoints to a FastAPI app (a Python web framework optimized for JSON APIs) will guess. It will guess your Python version, your dependency manager, your style, and your test framework. Most of the time at least one guess is wrong, and you spend two or three rounds correcting the agent before the code is something you would have written yourself.

With an AGENTS.md in place, the same prompt produces clean, idiomatic output on the first try. The file is the cheapest single change you can make to an AI-assisted workflow that shifts the output in your direction.

A worked example: cars API with and without an AGENTS.md

To make the contrast concrete, the Real Python tutorial walks through a small FastAPI service that serves a cars.json file with ten car records. Two endpoints exist: GET /cars returns all cars, GET /cars/{car_id} returns one car or 404. The starting main.py is roughly forty lines: load the JSON, build a FastAPI() instance, define the two routes.

The tutorial asks an agent, with no context file, to add two more endpoints: one to create a car and one to delete one. The prompt is six lines. The result, in the tutorial’s transcript, is a 60-line diff that:

• Imports pydantic for request validation, but the rest of the project uses raw dicts
• Persists new cars by writing back to cars.json with Path.write_text() rather than appending to an in-memory list, breaking the next read
• Uses HTTPException with a status code of 400 for missing records, when the rest of the file consistently uses 404
• Adds no tests, despite the project having a tests/ directory the agent did not look for

Three of those four issues come from the agent guessing. The agent does not know what conventions the file already follows.

Re-running the same prompt after dropping a 60-line AGENTS.md at the project root produces the same two endpoints in 35 lines, in idiomatic style, with the test file updated to match.

What goes in the file

There is no required schema, but the parts that actually drive output quality fall into four categories.

• Project framing. Two or three sentences on what the project is, what stack it uses, and which files are the entry points. The agent uses this to decide which parts of the codebase to read first. A project that is “a FastAPI service backed by a JSON file” prompts different searches than “a Flask app backed by Postgres.”
• Versions and tooling. The Python version, the package manager (uv, Poetry, pip-tools, plain pip), the linter and formatter (ruff, black, mypy), and the test runner (pytest, unittest). Pinning these stops the agent from defaulting to whatever it was last trained on, which is usually one or two versions behind.
• Conventions and quality gates. Coding style preferences (type hints on public functions, no print statements, f-strings over .format()), error-handling patterns, and the commands that must pass before a change is acceptable. Examples: ruff check . && mypy . and pytest -x. The agent can run these itself and fix the issues it introduced.
• Ignore rules and boundaries. Files the agent should not touch (generated code, vendored dependencies, large data files), directories the agent should treat as read-only (anything in migrations/ or scripts/), and the parts of the codebase that are owned by a human reviewer rather than the agent. This is the part that prevents the agent from “helpfully” rewriting a 2000-line migration script.

The four categories fit comfortably in 60 to 120 lines. Anything longer and you have a different problem: the agent’s context window (the limited amount of text it can keep in mind at once) is finite, and a 500-line AGENTS.md will crowd out the actual code you want the agent to think about.

What the agent actually does with the file

When a coding agent session starts, it reads AGENTS.md from the current working directory (or the nearest enclosing one) and adds the contents to its initial context window. The context window is the prompt the model sees, including the system prompt, the conversation so far, and the contents of any files the agent has read or edited during the session. Every subsequent prompt in the same session includes the file’s contents, because the context window persists across turns.

This is why pinning style and tooling has outsized value. The agent will use your pinned Python version for type hints, your pinned linter for the diff it produces, your pinned test runner to verify its own work. You do not need to prompt it to “use pytest” or “remember to run ruff”; the file carries that instruction forward.

The file is not magic. The agent does not always follow it. If your AGENTS.md says “use type hints on public functions” and the prompt asks for a one-liner script, the agent may skip the type hints. Treat the file as a strong default, not a hard constraint.

The four mistakes people make with AGENTS.md

Most of the AGENTS.md files you will find in the wild have at least one of these issues.

• Too vague. “Write clean Python code” is not actionable. The agent already tries to write clean code. What it needs to know is your specific definition of clean, which functions get docstrings, which imports go first, whether you use Optional[X] or X | None.
• Too long. A 500-line AGENTS.md crowds out the actual code from the context window. The agent will start ignoring parts of the file to make room. Cut anything that is generic advice about Python, anything that is about a project the agent will not work on, anything that duplicates what the linter already enforces.
• Includes secrets. Pinning API keys, tokens, or internal hostnames in AGENTS.md puts them in every agent session, every prompt, and every log of the conversation. The file is meant to be committed to version control. Treat it as public.
• Forgets to update. A stale AGENTS.md is worse than no file, because the agent trusts it. A project that migrated from Poetry to uv six months ago and never updated the file will have the agent default back to Poetry every time. Add a CI check (a small test script run on every code change) that runs the agent on a sample prompt and asserts the output uses the current tooling.

Trade-offs

An AGENTS.md is not free. It costs the time to write it well, the time to keep it current, and a few hundred tokens of context on every conversation. The token cost is real but small: a 100-line file is roughly 2,000 tokens, which most agents in 2026 can afford without complaint.

The other cost is the agent’s trust. A well-written file produces clean output on the first try. A stale or contradictory file produces confident nonsense, because the agent believes what you told it. Treat the file as a high-impact surface: small edits to it shift the agent’s behavior more than any other change to your project.

For a Python project of any size, the calculation is straightforward. Two hours of writing the file buys you back in saved re-prompting within a week of regular use, and the file compounds as more developers on the team use the agent.

If you only do one thing after reading this, open your project root, create AGENTS.md, and write the four sections above. The agent will behave better on the next prompt you give it.