Skip to main content
Technology & EngineeringPython Patterns30 lines

Adopt Ruff for Python Linting and Formatting

Use Ruff in a controlled migration with explicit configuration, rule parity, and reproducible check-only CI.

Quick Summary8 lines
Identify supported Python versions, package roots, checked files, and lint and format commands currently required by CI. Record whether the old setup uses Flake8 plugins, isort, Black or another tool. Select a Ruff version the repository can pin, and map which rules and formatting behavior must carry over. Make a minimal fixture for a rule that catches an actual project error and one intentional exception.

## Key Points

- [Ruff configuration](https://docs.astral.sh/ruff/configuration/)
- [Ruff official repository](https://github.com/astral-sh/ruff)
skilldb get python-patterns-skills/python-lintingFull skill: 30 lines
Paste into your CLAUDE.md or agent config

Adopt Ruff for Python Linting and Formatting

Capture the current lint contract

Identify supported Python versions, package roots, checked files, and lint and format commands currently required by CI. Record whether the old setup uses Flake8 plugins, isort, Black or another tool. Select a Ruff version the repository can pin, and map which rules and formatting behavior must carry over. Make a minimal fixture for a rule that catches an actual project error and one intentional exception.

Use the existing configuration file layout where appropriate. In pyproject.toml, verify the documented Ruff sections for overall options, lint selection and formatter settings. Set or verify target-version for the code that will actually run. If nested packages have separate configuration, check how Ruff chooses the relevant file and whether inheritance is explicit. Test generated sources, test files and migrations under the intended include and exclude rules.

Separate diagnosis and changes

Begin with ruff check for diagnostics and ruff format --check if the project adopts the formatter. Run those exact commands from the CI working directory on known paths. Do not assume that selecting a rule family enables every old plugin behavior. Compare important findings by code, file and cause. Keep a complementary rule or test for requirements Ruff does not cover.

Apply fixes separately from introducing a required gate. Start with an isolated set of files, review the diff, and run the affected tests. Treat unsafe fixes as a distinct reviewed decision. An automatic edit can change semantics even when the check passes. Keep broad file reformatting separate when preserving useful history or minimizing review churn matters.

Verify the gate from a clean checkout

Use check-only CI and the same pinned version as local development. Test a known violation and a file that should remain excluded. Verify the lint command exits nonzero on the violation and returns cleanly after it is resolved. Confirm formatting failure is separately observable, so a formatter cannot silently update checked files during CI. Record the working directory and resolved settings when a nested package behaves differently.

Hand off the config, enabled rules, known deviations, fixture output and the old checks that remain required. If changing the formatter as well as the linter, verify that the editor integration and CI agree on the same version and file scope.

References

Install this skill directly: skilldb add python-patterns-skills

Get CLI access →