AGENTS.md for Python
A complete, production-ready AGENTS.md example for Python projects — token-optimized to 309 tokens, ready to drop into your repo. Plus a free generator that tailors it to your exact stack in 3 questions.
What is AGENTS.md?
AGENTS.md is a machine-readable specification file that tells AI coding assistants (Claude Code, Cursor, GitHub Copilot, Windsurf) exactly how to work in your codebase — the real commands to run, the permission boundaries, and code style rules they must follow. Unlike documentation written for humans, AGENTS.md is optimised for agents: every line prevents a concrete mistake.
AGENTS.md example for Python
Here is a complete AGENTS.md for a Python project, optimized to 309tokens using MDPilot's 5-pass optimizer:
# Agent role declaration
I am a Python developer assistant, helping with coding tasks in this project.
# Environment setup
To get started, create a virtual environment with `python -m venv .venv`, then activate it with `source .venv/bin/activate` on Linux/macOS or `.venv\Scripts\activate` on Windows.
Install requirements with `pip install -r requirements.txt` or `pip install -e .` for an editable install, and `pip install -r dev-requirements.txt` for development tools.
# File-scoped build/test commands
Run tests with `pytest` and check formatting with `black .` and `ruff .`.
Build the project with `python -m build`.
# Code style rules
Adhere to PEP 8 conventions with type hints checked by `mypy`.
Formatting is done with `black` and `ruff`, and code quality is checked with `flake8`.
# Key project paths
Project root: .
Source code: src/
Tests: tests/
# Permission boundaries
Allowed: Editing files in src/ and tests/.
Approve: Changes to pyproject.toml, requirements.txt, and dev-requirements.txt.
Never: Modifications to .gitignore, .venv/, or other system files.
# PR format
Pull requests should include a brief description of changes, and follow conventional commit messages with a type, brief description, and body.Why Python projects need AGENTS.md
Python developers often struggle with maintaining consistent coding standards and setting up their development environments. The AGENTS.md file helps alleviate this pain by providing a clear set of instructions for coding assistants, ensuring that all code contributions adhere to PEP 8 conventions and pass checks by tools like mypy and black. Additionally, the file helps with virtual environment setup using `python -m venv`, making it easier to manage dependencies with pip. By following the guidelines in AGENTS.md, developers can avoid common mistakes, such as incorrect type hints or inconsistent formatting.
Generate your own AGENTS.md for Python
Answer 3 questions about your project and MDPilot generates a AGENTS.md grounded in your exact stack — real commands, real paths, no hallucinated scripts.
Generate AGENTS.md free →Frequently asked questions
What is AGENTS.md?
AGENTS.md is an open standard for AI coding assistant instructions, providing a set of guidelines for maintaining consistency and quality in Python projects.
How do I set up my Python environment according to AGENTS.md?
Create a virtual environment with `python -m venv .venv`, then activate it and install requirements with `pip install -r requirements.txt` or `pip install -e .` for an editable install.
What formatting tools should I use in my Python project?
Use `black` and `ruff` for formatting, and `mypy` for type hint checks to adhere to PEP 8 conventions.
Where should I place the AGENTS.md file in my Python project?
Place the AGENTS.md file at the root of your project, alongside other key files like pyproject.toml and requirements.txt.