Teaching LLMs Python Best Practices with the Handbook
Large language models possess extensive Python knowledge from training data, yet they consistently struggle with modern tooling practices. Despite being trained on massive amounts of Python code, frontier models often default to outdated patterns like direct python or pip commands instead of using virtual environments and modern tools like uv.
how is it, that despite every frontier LLM being insanely python maxxed they rarely use virtural envs, and even adding rules like "we are using uv, do everything with uv" they ignore it and think the system python is broken. like, every time. that's actually an accomplishment
— Shannon Sands (@max_paperclips) November 20, 2025
This gap between Python knowledge and practical tooling expertise creates friction when AI assistants help with real-world development tasks. LLMs know Python syntax and libraries extensively, but modern development practices like dependency isolation and project structure require explicit guidance.
Teaching LLMs Through Context
The Python Developer Tooling Handbook addresses this challenge by providing structured resources specifically designed for AI consumption:
llms.txt Format
The handbook exposes a machine-readable summary at pydevtools.com/llms.txt following the llms.txt specification. This lightweight format provides LLMs with quick context about modern Python tooling practices and where to find detailed information.
AI Assistant Guide
The Modern Python Project Setup Guide for AI Assistants provides comprehensive, structured instructions specifically formatted for AI consumption.
The guide explicitly states patterns like “use uv run for dev dependencies” and “never mix pip and uv in the same project” in a format optimized for AI understanding.
A Markdown formatted version of this is also available, making it easy for consumption by models.
How This Helps in Practice
When AI assistants access these resources through context windows or retrieval systems, they receive explicit guidance that compensates for gaps in training data:
Without handbook context
# AI often defaults to outdated patterns
python script.py
pip install packageWith handbook context
# AI follows modern practices
uv run python script.py
uv add packageIntegrating Handbook Resources
Projects can reference handbook content in several ways:
In project documentation (README.md, CONTRIBUTING.md)
This project follows modern Python practices as outlined in the
Python Developer Tooling Handbook's AI Assistant Guide:
https://pydevtools.com/handbook/explanation/modern-python-project-setup-guide-for-ai-assistants/In AGENTS.md, CLAUDE.md, or similar AI instructions
Follow the Python Developer Tooling Handbook's recommendations:
- Use uv for all dependency management
- Reference: https://pydevtools.com/handbook/explanation/modern-python-project-setup-guide-for-ai-assistants.md
- For more information: https://pydevtools.com/llms.txtThrough active guidance mechanisms
For example hooks and interceptors are technical solutions to enforce modern tool use.
In model training
AI labs are welcome to use these resources to train their models to improve their knowledge of Python. Feel free to contact me to discuss.