AGENTS.md · Python

AGENTS.md and CLAUDE.md examples for Python

Of 486 actively developed open-source products built with Python, 240 (49%) keep instruction files for coding agents: AGENTS.md in 178, CLAUDE.md in 153. The typical file is 909 words, and most cover commands to build, run and test (79%) and pointers to other docs (71%).

Real files to read

From the best-known open-source Python products whose file is a real one (not a pointer to another), 200 to 4,000 words, covering at least three of the usual topics, written mainly in Python. Each opens on GitHub.

Project	File	Stars	Words	Covers
NousResearch/hermes-agent	`AGENTS.md`	252,829	1,572	CommandsTestingDoc pointersStructure
Significant-Gravitas/AutoGPT	`AGENTS.md`	187,527	943	CommandsTestingDoc pointersStructureCode styleGit
home-assistant/core	`AGENTS.md`	91,392	843	CommandsTestingDoc pointersGit
bytedance/deer-flow	`AGENTS.md`	83,703	1,785	CommandsTestingDoc pointersCode style
usestrix/strix	`AGENTS.md`	67,972	991	CommandsTestingDoc pointers
wshobson/agents	`AGENTS.md`	40,427	804	CommandsTestingDoc pointers
getzep/graphiti	`AGENTS.md`	31,654	865	CommandsTestingStructureCode styleGit
langbot-app/LangBot	`AGENTS.md`	18,107	600	CommandsTestingDoc pointers
rocketride-org/rocketride-server	`AGENTS.md`	17,804	768	CommandsTestingDoc pointersStructureCode styleGit
MODSetter/SurfSense	`AGENTS.md`	16,374	1,263	CommandsTestingDoc pointersStructureGit
yusufkaraaslan/Skill_Seekers	`AGENTS.md`	15,133	1,917	CommandsTestingStructureCode styleGit
NVIDIA/TensorRT-LLM	`AGENTS.md`	14,794	1,546	CommandsTestingDoc pointersStructureGit

What Python projects put in them

Share of the 213 files that cover each topic, against all 641 files we read.

Commands to build, run and test79% vs 78%

Pointers to other docs71% vs 68%

Testing68% vs 67%

Project structure58% vs 58%

Code style46% vs 51%

Git, commits and pull requests46% vs 46%

How they talk to the agent: 81% say “never” or “do not” somewhere (all files: 80%), 23% shout a rule in capitals like IMPORTANT or MUST (24%), and 19% tell it to ask before some changes (20%).

The tools they name

Package managersuv (79 files), npm (32 files), pnpm (27 files)

Tests and linterspytest (99), Ruff (26), Vitest (17), Playwright (16), ESLint (15), Prettier (13)

Named more than in files generallypytest (99), FastAPI (54), Pydantic (31), Ruff (26)

A starting AGENTS.md for Python

The sections these files cover most, the package manager and checks Python projects name most, and the stack Python makers' products chose most often. Fill in the <placeholders>.

# AGENTS.md

<What this product does and who it is for, in a sentence or two.>

## Stack


## Commands

- Install: `uv sync`
- Run locally: `<command>`
- Test: `uv run pytest`
- Lint: `uv run ruff check .`

## Testing

Run `uv run pytest` before calling a change done, and add a test with each fix or feature.

## Project structure

- `<folder>/`: <what lives there>
- More in <docs/…>

## Conventions

- <Naming, patterns and style the code does not show>
- Commits and pull requests: <your rules>

## Boundaries

- Ask before: <changes you want to approve first>
- Never: <files or actions that are off-limits>

<!-- Started from https://howmakersbuild.com/agents-md/python — point CLAUDE.md here with a line: @AGENTS.md -->

uv: named in 79 of 213 instruction files from open-source projects built with Python.
pytest: named in 99 of 213 instruction files from open-source projects built with Python.
Ruff: named in 26 of 213 instruction files from open-source projects built with Python.

Make one for your own stack →

Questions

What should an AGENTS.md for a Python project include?

In 213 files from open-source Python products: commands to build, run and test (79%), pointers to other docs (71%), testing (68%), project structure (58%), code style (46%), git, commits and pull requests (46%). The package manager they name most is uv (79 files).

AGENTS.md or CLAUDE.md?

Among these Python products, 178 keep an AGENTS.md and 153 a CLAUDE.md. Across every product we checked, 320 keep both, and in 170 of those the CLAUDE.md only points to the AGENTS.md (a symlink or a line like @AGENTS.md), so there's one file to maintain. Codex, Cursor, Copilot and others read AGENTS.md; Claude Code reads CLAUDE.md.

How long is a typical Python AGENTS.md?

The median is 909 words in these 213 files; across all 641 files we read, half are between 425 and 1,665 words.

How this is counted: the GitHub repos of open-source products built with Python, pushed to in the 180 days before 2026-10-12. We read each repo's AGENTS.md, CLAUDE.md and other agent files; what's published here is counts and links, not their text. All files, by the numbers.