name: uv-tdd
description: A development process for Python applications that uses TDD to iterate on a new project based around uv. Use when Claude needs to create a new Python project, write Python code with tests, or work on Python development using test-driven development practices with the uv package manager.

uv-tdd skill

A development process for Python applications that uses TDD to iterate on a new project based around uv.

Create a project with this command:

mkdir name-of-project
cd name-of-project
uv init
git init (if not already in a git repo)

This creates an initial pyproject.toml file

Add dependencies using:

uv add httpx

Always start by adding a dev dependency of pytest like this:

uv add pytest --dev

Then add a starting test:

mkdir tests
echo 'def test_add():
    assert 1 + 1 == 2' > tests/test_add.py

Then run the tests like this:

uv run pytest

Always run Python code like this:

uv run python -c "..."

Always create a README.md for the project, which starts with just the project name as a heading plus a short description.

Start by creating a spec.md file with a detailed specification that includes markdown TODO lists. Update the spec and those TODOs as you progress, including adding new ones and checking off previous ones.

Practice TDD. For every change start by writing a test (grouped sensible in test files with other related tests) and then use uv run pytest -k name_of_test to watch it fail. Then implement the change and watch the test pass. Update the TODOs and add or update relevant documentation in the README, then commit the implementation and tests and documentation as a single commit.

Use and reuse pytest fixtures where appropriate, including for temporary files used for the duration of the test run. Use pytest.mark.parameterized to avoid duplicated test code.

Delete that test_add.py file once you have implemented your first real test. Do not include that test_add.py file in any of your commits.

Commit often, in sensible chunks. If a remote is configured then push after every commit.