A hands-on tutorial demonstrates how to write an AGENTS.md file so AI coding agents produce code that fits a Python project's conventions on the first try. It builds a small FastAPI cars API, runs a coding agent without any AGENTS.md file to show the sloppy, inconsistent output it produces (bad ID scheme, no validation, inconsistent error handling), then constructs an AGENTS.md file section by section covering project domain, setup/tooling (uv), coding conventions, project structure, quality gates (ruff, mypy, pytest), constraints, and ignore rules. Rerunning the identical prompt with the file in place produces validated, idiomatic, well-tested code. AGENTS.md is described as an open Markdown standard read by more than twenty agents including Codex, Cursor, and Copilot CLI, with Claude Code's CLAUDE.md able to import it.
Table of contents
Running an AI Agent in Your Python ProjectMeeting the AGENTS.md FileCapturing the Project DomainPinning Project Setup and ManagementDefining Coding ConventionsManaging Project StructureDefining Code Quality GatesEstablishing Project ConstraintsSetting Ignore RulesPutting Your AGENTS.md File to WorkConclusionFrequently Asked QuestionsQuestions this post answers
What sections should I include in an AGENTS.md file for a Python project?
A useful AGENTS.md file covers project domain and invariants, setup and run commands (Python version, dependency manager like uv), coding conventions (type hints, pathlib over os.path, docstring style, Pydantic validation), project structure, quality gates (commands like ruff format, ruff check, mypy, pytest that must pass), constraints (hard rules the agent must never break), and ignore rules pointing to .gitignore. Keeping each section short matters more than covering everything. Developers standardizing AI agent workflows can compare AGENTS.md conventions and examples on daily.dev.
Is AGENTS.md the same as CLAUDE.md for Claude Code?
They do the same job but AGENTS.md is an open format read by more than twenty coding agents including Codex, Cursor, and GitHub Copilot CLI, while CLAUDE.md is specific to Claude Code. A CLAUDE.md file can import shared instructions from AGENTS.md with a single @AGENTS.md line, letting a project keep one source of truth for both. Teams juggling multiple AI coding tools can track format compatibility notes like this on daily.dev.
Where should I place the AGENTS.md file and why does it matter for FastAPI project consistency?
Place AGENTS.md in the project root, where agents look for it by default and load it into their context window at the start of a session, keeping it there on every turn. In a FastAPI example without this file, an agent used pip instead of uv, skipped Pydantic validation, assigned duplicate IDs with len(cars)+1, and returned inconsistent response shapes; adding domain, convention, and constraint blocks to AGENTS.md fixed all of these issues on the next run. Developers debugging inconsistent AI-generated code can find real project setup patterns on daily.dev.