python-uv: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. It only holds agent-specific rules and the minimum commands; everything else is in docs/ (see Documentation Map).

Project Overview

A Python development environment template using uv (package manager), Ruff (linter/formatter), and ty (type checker). It also ships a reusable tools/ package (Logger, Settings, Timer).

Essential Commands

uv sync                                     # Install dependencies
uv add <package>                            # Add a dependency (--dev for dev dependencies); never use pip
uv run nox -s fmt -- --ruff --sqruff        # Format (without flags, nothing runs)
uv run nox -s lint -- --ruff --sqruff --ty  # Lint and type check (without flags, nothing runs)
uv run nox -s test                          # Tests with coverage (75% minimum)
uv run pre-commit run --all-files           # All pre-commit hooks

Run all of the above before opening a PR. Other options: Task Automation with nox.

Rules for Claude Code

Code and tests

• Follow Code Standards: type hints and docstrings on public APIs, line length 88.
• Name test files test__*.py (double underscore) and mirror tools/ in tests/. Coverage must stay at 75% or above (branch coverage included).
• When adding a utility to tools/, add or update its page in docs/guides/tools/.

Documentation

• Each topic has exactly one source of truth under docs/ (see Documentation Map). Edit only that page.
• Never copy documentation content into README.md, CONTRIBUTING.md, or this file; link to the docs/ page instead.
• Configuration pages include the real config files with --8<-- snippets; do not paste config contents into docs.
• After changing docs, run uv run mkdocs build --strict. Register new pages in the nav of mkdocs.yml.