Title: How to Write an AGENTS.md File for a Python Project – Real Python
Open Graph Title: How to Write an AGENTS.md File for a Python Project – Real Python
Description: Learn how to write an AGENTS.md file so your AI coding agent produces idiomatic Python code that fits your project on the first try.
Open Graph Description: Learn how to write an AGENTS.md file so your AI coding agent produces idiomatic Python code that fits your project on the first try.
Mail addresses
?subject=Python article for you&body=How to Write an AGENTS.md File for a Python Project on Real Python
https://realpython.com/agents-md/
Opengraph URL: https://realpython.com/agents-md/
X: @realpython
Domain: realpython.com
{
"@context": "http://schema.org",
"@type": "Article",
"headline": "How to Write an AGENTS.md File for a Python Project",
"image": {
"@type": "ImageObject",
"url": "https://files.realpython.com/media/How-to-Write-an-AGENTS.md-File-for-a-Python-Project_Watermarked.48cd85ac2760.jpg",
"width": 1920,
"height": 1080
},
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://realpython.com/agents-md/",
"lastReviewed": "2026-08-24",
"author": {
"@type": "Person",
"name": "Leodanis Pozo Ramos",
"image": "https://realpython.com/cdn-cgi/image/width=862,height=862,fit=crop,gravity=auto,format=auto/https://files.realpython.com/media/Perfil_final1.9f896bc212f6.jpg",
"url": "https://realpython.com/team/lpozoramos/",
"affiliation": {
"@type": "Organization",
"@id": "https://realpython.com/#organization",
"name": "Real Python",
"url": "https://realpython.com",
"logo": "https://realpython.com/static/real-python-logo-square-512.157ae6bf64ed.png"
}
},
"reviewedBy": [
{
"@type": "Person",
"name": "Aldren Santos",
"image": "https://realpython.com/cdn-cgi/image/width=500,height=500,fit=crop,gravity=auto,format=auto/https://files.realpython.com/media/Aldren_Santos_Real_Python.6b0861d8b841.png",
"url": "https://realpython.com/team/asantos/",
"affiliation": {
"@type": "Organization",
"@id": "https://realpython.com/#organization",
"name": "Real Python",
"url": "https://realpython.com",
"logo": "https://realpython.com/static/real-python-logo-square-512.157ae6bf64ed.png"
}
},
{
"@type": "Person",
"name": "Brenda Weleschuk",
"image": "https://realpython.com/cdn-cgi/image/width=320,height=320,fit=crop,gravity=auto,format=auto/https://files.realpython.com/media/IMG_3324_1.50b309355fc1.jpg",
"url": "https://realpython.com/team/bweleschuk/",
"affiliation": {
"@type": "Organization",
"@id": "https://realpython.com/#organization",
"name": "Real Python",
"url": "https://realpython.com",
"logo": "https://realpython.com/static/real-python-logo-square-512.157ae6bf64ed.png"
}
},
{
"@type": "Person",
"name": "Bartosz Zaczy\u0144ski",
"image": "https://realpython.com/cdn-cgi/image/width=1694,height=1694,fit=crop,gravity=auto,format=auto/https://files.realpython.com/media/coders_lab_2109368.259b1599fbee.jpg",
"url": "https://realpython.com/team/bzaczynski/",
"affiliation": {
"@type": "Organization",
"@id": "https://realpython.com/#organization",
"name": "Real Python",
"url": "https://realpython.com",
"logo": "https://realpython.com/static/real-python-logo-square-512.157ae6bf64ed.png"
}
},
{
"@type": "Person",
"name": "Martin Breuss",
"image": "https://realpython.com/cdn-cgi/image/width=456,height=456,fit=crop,gravity=auto,format=auto/https://files.realpython.com/media/martin_breuss_python_square.efb2b07faf9f.jpg",
"url": "https://realpython.com/team/mbreuss/",
"affiliation": {
"@type": "Organization",
"@id": "https://realpython.com/#organization",
"name": "Real Python",
"url": "https://realpython.com",
"logo": "https://realpython.com/static/real-python-logo-square-512.157ae6bf64ed.png"
}
},
{
"@type": "Person",
"name": "Stephen Gruppetta",
"image": "https://realpython.com/cdn-cgi/image/width=400,height=400,fit=crop,gravity=auto,format=auto/https://files.realpython.com/media/Stephen_inside_2_BW_2_square_crop_2_low_res_2_copy.4a7e2d8bc19c.png",
"url": "https://realpython.com/team/sgruppetta/",
"affiliation": {
"@type": "Organization",
"@id": "https://realpython.com/#organization",
"name": "Real Python",
"url": "https://realpython.com",
"logo": "https://realpython.com/static/real-python-logo-square-512.157ae6bf64ed.png"
}
}
]
},
"datePublished": "2026-08-24T14:00:00+00:00",
"dateModified": "2026-08-24T14:00:00+00:00",
"publisher": {
"@type": "Organization",
"@id": "https://realpython.com/#organization",
"name": "Real Python",
"url": "https://realpython.com",
"logo": {
"@type": "ImageObject",
"url": "https://realpython.com/static/real-python-logo-square-512.157ae6bf64ed.png",
"width": 512,
"height": 512
},
"description": "Real Python is a leading provider of online Python education and one of the largest language-specific online communities for software developers. It publishes high-quality learning resources, such as tutorials, books, and courses to an audience of millions of developers, data scientists, and machine learning engineers each month.",
"slogan": "Become a Python Expert",
"email": "info@realpython.com",
"sameAs": [
"https://github.com/realpython",
"https://www.youtube.com/realpython",
"https://twitter.com/realpython",
"https://x.com/realpython",
"https://www.linkedin.com/company/realpython-com/",
"https://www.facebook.com/learnrealpython",
"https://www.instagram.com/realpython",
"https://www.tiktok.com/@realpython.com"
]
},
"author": {
"@type": "Person",
"name": "Leodanis Pozo Ramos",
"image": "https://realpython.com/cdn-cgi/image/width=862,height=862,fit=crop,gravity=auto,format=auto/https://files.realpython.com/media/Perfil_final1.9f896bc212f6.jpg",
"url": "https://realpython.com/team/lpozoramos/",
"affiliation": {
"@type": "Organization",
"@id": "https://realpython.com/#organization",
"name": "Real Python",
"url": "https://realpython.com",
"logo": "https://realpython.com/static/real-python-logo-square-512.157ae6bf64ed.png"
}
},
"description": "Learn how to write an AGENTS.md file so your AI coding agent produces idiomatic Python code that fits your project on the first try.",
"hasPart": {
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What is an AGENTS.md file?",
"acceptedAnswer": {
"@type": "Answer",
"text": "\u003cp\u003eAn \u003ccode\u003eAGENTS.md\u003c/code\u003e file is a Markdown file at your project root that AI coding agents read automatically and load into their \u003ca href=\"/ref/ai-coding-glossary/context-window/\" class=\"ref-link\"\u003econtext window\u003c/a\u003e. It holds project context like your Python version, dependency manager, conventions, and constraints so the agent produces code that fits your project.\u003c/p\u003e"
}
},
{
"@type": "Question",
"name": "Where do you put an AGENTS.md file?",
"acceptedAnswer": {
"@type": "Answer",
"text": "\u003cp\u003ePut \u003ccode\u003eAGENTS.md\u003c/code\u003e in your project root, where agents look for it by default.\u003c/p\u003e"
}
},
{
"@type": "Question",
"name": "What is the difference between AGENTS.md and CLAUDE.md?",
"acceptedAnswer": {
"@type": "Answer",
"text": "\u003cp\u003e\u003ccode\u003eAGENTS.md\u003c/code\u003e is an open format that many agents read, while \u003ca href=\"https://realpython.com/python-claude-md/\"\u003e\u003ccode\u003eCLAUDE.md\u003c/code\u003e\u003c/a\u003e is specific to \u003ca href=\"/ref/ai-coding-tools/claude-code/\" class=\"ref-link\"\u003eClaude Code\u003c/a\u003e. They do the same job, and a \u003ccode\u003eCLAUDE.md\u003c/code\u003e can pull in your shared instructions with a single \u003ccode\u003e@AGENTS.md\u003c/code\u003e import so you keep one source of truth.\u003c/p\u003e"
}
},
{
"@type": "Question",
"name": "What should an AGENTS.md file include?",
"acceptedAnswer": {
"@type": "Answer",
"text": "\u003cp\u003eA useful \u003ccode\u003eAGENTS.md\u003c/code\u003e covers your project domain, setup and run commands, coding conventions, project structure, quality gates, constraints, and ignore rules. Keeping each section short matters more than covering everything, since long files dilute individual rules.\u003c/p\u003e"
}
},
{
"@type": "Question",
"name": "Do all AI coding agents support AGENTS.md?",
"acceptedAnswer": {
"@type": "Answer",
"text": "\u003cp\u003eMany do, including Codex, Cursor, and GitHub Copilot, with more than twenty agents reading the format. Claude Code uses \u003ccode\u003eCLAUDE.md\u003c/code\u003e, but it can import an \u003ccode\u003eAGENTS.md\u003c/code\u003e so you still get one shared file.\u003c/p\u003e"
}
}
]
}
}| author | Real Python |
| theme-color | #18354c |
| color-scheme | light dark |
| twitter:card | summary_large_image |
| twitter:image | https://files.realpython.com/media/How-to-Write-an-AGENTS.md-File-for-a-Python-Project_Watermarked.48cd85ac2760.jpg |
| og:image | https://files.realpython.com/media/How-to-Write-an-AGENTS.md-File-for-a-Python-Project_Watermarked.48cd85ac2760.jpg |
| twitter:creator | @realpython |
| og:type | article |
| og:site_name | Real Python |
| apple-mobile-web-app-title | Real Python |
Links:
Viewport: width=device-width, initial-scale=1, shrink-to-fit=no, viewport-fit=cover
Robots: max-image-preview:large
