# Teaching LLMs Python Best Practices


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](https://pydevtools.com/handbook/reference/uv.md).

<blockquote class="twitter-tweet"><p lang="en" dir="ltr">how is it, that despite every frontier LLM being insanely python maxxed they rarely use virtural envs, and even adding rules like &quot;we are using uv, do everything with uv&quot; they ignore it and think the system python is broken. like, every time. that&#39;s actually an accomplishment</p>&mdash; Shannon Sands (@max_paperclips) <a href="https://twitter.com/max_paperclips/status/1991637788295590016?ref_src=twsrc%5Etfw">November 20, 2025</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

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](https://pydevtools.com/llms.txt) following the [llms.txt](https://llmstxt.org/) 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](https://pydevtools.com/handbook/explanation/modern-python-project-setup-guide-for-ai-assistants.md) 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](https://pydevtools.com/handbook/explanation/modern-python-project-setup-guide-for-ai-assistants.md), 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

```bash
# AI often defaults to outdated patterns
python script.py
pip install package
```

### With handbook context

```bash
# AI follows modern practices
uv run python script.py
uv add package
```

## Integrating Handbook Resources

Projects can reference handbook content in several ways:

### In project documentation (README.md, CONTRIBUTING.md)

```markdown
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

```markdown
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.txt
```

### Through active guidance mechanisms

For example [hooks](https://pydevtools.com/blog/claude-code-hooks-for-uv.md) and [interceptors](https://pydevtools.com/blog/interceptors.md) 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](https://pydevtools.com/feedback/index.md).

## Learn More

- [Modern Python Project Setup Guide for AI Assistants](https://pydevtools.com/handbook/explanation/modern-python-project-setup-guide-for-ai-assistants.md)
- [Claude Code Hooks for uv](https://pydevtools.com/blog/claude-code-hooks-for-uv.md)
- [Use interceptors to teach Claude Code to use uv](https://pydevtools.com/blog/interceptors.md)
- [How to configure Claude Code to use uv](https://pydevtools.com/handbook/how-to/how-to-configure-claude-code-to-use-uv.md)
- [llms.txt specification](https://llmstxt.org/)
- [AGENTS.md documentation](https://agents.md/)