Python Project Tooling
Respect established projects
Inspect pyproject.toml, lockfiles, CI, contributor docs, and existing commands. Continue using configured tools silently. Do not introduce uv, Ruff, ty, pytest, or a new build backend merely to replace working equivalents unless the user requests a migration.
For a request to format, lint, or type-check explicitly named files, use the
repository's configured commands and scope them to those files when the tool
supports it. If the requested check has no configured tool, report that gap
instead of adding a tool or pretending another command covers it. Review any
automatic changes, then re-run the relevant checks without fix flags for clean
evidence.
New or deliberately modernized projects
- Ask for the supported Python version when it is not specified; offer Python 3.14 as the default.
- Prefer uv for environments, dependencies, locking, and command execution.
- Prefer Ruff for formatting and linting, ty for static type checking, and pytest for tests.
- Put canonical configuration in
pyproject.toml; keep CI and contributor commands aligned with it.
- Choose a build backend appropriate to the package. Do not add packaging machinery to an application that is not distributed.
- Commit a lockfile when reproducibility is part of the repository's policy.
Change safely
- Separate a tool migration from unrelated feature work.
- Pin only where reproducibility or compatibility requires it; preserve useful lower and upper bounds.
- Verify lock consistency, clean-environment installation, lint, format check, type check, tests, and package build as applicable.
- For publishing, prefer trusted publishing and a dry run or test index before a production release.
1---2name: python-project-tooling3description: Configure and maintain Python projects, dependencies, packaging, environments, linting, formatting, type checking, testing, builds, and publishing. Use for pyproject.toml, an existing repository toolchain, or repository-level Python tooling work, not for a standalone script.4---56# Python Project Tooling78## Respect established projects910Inspect `pyproject.toml`, lockfiles, CI, contributor docs, and existing commands. Continue using configured tools silently. Do not introduce uv, Ruff, ty, pytest, or a new build backend merely to replace working equivalents unless the user requests a migration.1112For a request to format, lint, or type-check explicitly named files, use the13repository's configured commands and scope them to those files when the tool14supports it. If the requested check has no configured tool, report that gap15instead of adding a tool or pretending another command covers it. Review any16automatic changes, then re-run the relevant checks without fix flags for clean17evidence.1819## New or deliberately modernized projects20211. Ask for the supported Python version when it is not specified; offer Python 3.14 as the default.222. Prefer uv for environments, dependencies, locking, and command execution.233. Prefer Ruff for formatting and linting, ty for static type checking, and pytest for tests.244. Put canonical configuration in `pyproject.toml`; keep CI and contributor commands aligned with it.255. Choose a build backend appropriate to the package. Do not add packaging machinery to an application that is not distributed.266. Commit a lockfile when reproducibility is part of the repository's policy.2728## Change safely2930- Separate a tool migration from unrelated feature work.31- Pin only where reproducibility or compatibility requires it; preserve useful lower and upper bounds.32- Verify lock consistency, clean-environment installation, lint, format check, type check, tests, and package build as applicable.33- For publishing, prefer trusted publishing and a dry run or test index before a production release.
cjthompson