python-lint
Purpose
Configure Ruff as the single linter and formatter for a Python package — replacing
Black, Flake8 (+ plugins), isort, and pyupgrade — with an explicit rule set in
pyproject.toml, then drive ruff check and ruff format --check to a clean exit.
Covers fresh setup, migration from the legacy stack, rule tuning, and fixing lint or
format failures. Every command below runs in the user's package repository.
When NOT to use
- Type errors / mypy / pyright / ty — Ruff performs no type inference;
ANN
rules only police annotation style. The python-typing skill, if installed,
owns this.
- Pre-commit wiring (
.pre-commit-config.yaml, hook rev pinning, staged-file
runs) — the python-precommit skill. This skill only defines what Ruff should do.
- CI workflow YAML (GitHub Actions jobs, matrices, caching) — the python-ci
skill. This skill supplies the commands a CI job should run, not the workflow.
- Formatting YAML / JSON / TOML / Markdown prose — Ruff formats Python
(including, since 0.16, Python code fences inside Markdown) and nothing else,
by deliberate maintainer decision
(astral-sh/ruff#10738);
the python-precommit skill covers non-Python files.
- Running Ruff automatically on agent edits (Claude Code hooks) — the
agent-guardrails skill.
Workflow
1. Inspect before touching anything
ls .flake8 .isort.cfg setup.cfg tox.ini ruff.toml .ruff.toml 2>/dev/null
grep -nE '^\[tool\.(ruff|black|isort)|^\[flake8\]|^\[isort\]' pyproject.toml setup.cfg tox.ini 2>/dev/null
grep -n 'requires-python' pyproject.toml
Pick the path: fresh setup (steps 2–3), migration off Black/Flake8/isort (step 5),
tuning an existing config (step 4), or fixing a red lint gate (step 6).
2. Install a pinned Ruff
uv add --dev "ruff==0.16.6" # example pin — check the latest release and pin that
# one-off, no project change:
uvx --from 'ruff==0.16.6' ruff check .
No-uv fallback (once, applies to every command below): python -m pip install 'ruff==0.16.6' and drop the uv run prefix.
Why pin — formatter output and the rule catalog change between minor releases:
0.15 shipped a "2026 style guide" that changed lambda and empty-line formatting
(astral.sh/blog/ruff-v0.15.0), and 0.16
(2026-07-23) grew the default rule set from 59 to 413 rules while dropping 18
E/F codes from it, so an unconfigured repo's findings changed overnight
(astral.sh/blog/ruff-v0.16.0). An unpinned
Ruff makes local, teammate, and CI runs disagree — the top reported lint-workflow
failure. Optionally enforce the pin in config with
required-version = "0.16.6" under [tool.ruff]. Note that uv format
(experimental since uv 0.8.13) runs a Ruff it bundles itself, so its version can
differ from the project's pin — keep ruff in dev dependencies as the source of
truth and treat uv format as a convenience wrapper.
3. Write the config (fresh setup)
All Ruff config lives in pyproject.toml. Keep exactly one config file — a
ruff.toml next to a [tool.ruff] section is a recipe for confusion. Starter:
[tool.ruff]
target-version = "py311" # lowest Python you support; gates UP rewrites
line-length = 88
extend-exclude = ["migrations"] # generated code, if any
[tool.ruff.lint]
select = [
"E", "W", # pycodestyle
"F", # pyflakes
"I", # isort (import sorting)
"UP", # pyupgrade
"B", # flake8-bugbear
"C4", # flake8-comprehensions
"SIM", # flake8-simplify
"RUF", # Ruff-specific rules
]
ignore = ["E501"] # line length is the formatter's job
[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101"] # assert is fine in tests (relevant once S is on)
"__init__.py" = ["F401"] # re-exports
[tool.ruff.lint.isort]
known-first-party = ["yourpackage"]
[tool.ruff.format]
quote-style = "double"
docstring-code-format = true # formats Python snippets inside docstrings
Non-obvious decisions baked into this block:
- Never rely on Ruff's default rule set. Before 0.16 it was
E4/E7/E9
F (59 rules, less than a Flake8+plugins stack); since 0.16 it is 413 rules across
B, UP, SIM, PL and more, with 18 former E/F defaults removed — a repo
without select gets a different gate on every upgrade. select replaces
the default set, so an explicit list freezes it; select = ["E4", "E7", "E9", "F"] reproduces the pre-0.16 baseline if a team wants exactly that.
ignore = ["E501"] whenever the formatter is enabled — ruff format already
wraps at line-length; linting it too double-reports on lines the formatter
cannot break (URLs, long strings).target-version gates UP (pyupgrade) rewrites. If unset, Ruff falls back
to project.requires-python; if that is also absent it assumes py310, and
autofixes can emit syntax that crashes older supported runtimes.- Avoid
select = ["ALL"] — it silently enables every new rule on every Ruff
upgrade, breaking checks unpredictably. Official guidance is to start narrow and
grow one category at a time
(docs.astral.sh/ruff/linter/).
Deeper rule catalog, tier strategy, and sub-table options (isort, pydocstyle,
bugbear): references/rule-selection.md.
4. Tune an existing config
- Noise in one area (tests, scripts, notebooks) → scope it with
[tool.ruff.lint.per-file-ignores]; never delete the rule from select globally
because tests complain. Common: "tests/**/*.py" = ["S101", "PLR2004"],
"scripts/*" = ["T201"].
- A single intentional violation →
# noqa: <CODE> with the specific code and a
short reason. Bare # noqa hides every rule on the line.
- Codes from non-Ruff tools in
# noqa comments (custom Flake8 plugin) →
declare external = ["XX"] in [tool.ruff.lint], or RUF100 strips those
comments on the next --fix.
- Widen coverage one prefix at a time (
"S", "PT", "PTH", …), run
uv run ruff check . after each addition, and fix or scope before adding more.
- Sanity-check the result:
python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root .
(read-only; flags E501 double-reporting, ALL, formatter-conflicting rules,
leftover legacy configs, missing target-version).
5. Migrate from Black / Flake8 / isort
Full mapping tables (commands, config keys, Flake8-plugin→prefix) and the
large-legacy-codebase strategy: references/migration.md. The sequence:
- Translate config first.
[tool.black] → [tool.ruff] + [tool.ruff.format],
[tool.isort]/.isort.cfg → [tool.ruff.lint.isort] (kebab-case keys),
.flake8 → select/ignore/per-file-ignores. Ruff never reads
[tool.black] or .flake8 — anything not translated is silently lost.
- Check plugin parity. For each Flake8 plugin in use, confirm a Ruff prefix
exists (table in the reference). A business-critical plugin with no equivalent
→ hybrid: keep Flake8 scoped to that plugin, add its codes to
external = [...].
- One-time cleanup as its own reviewed commit, before any gate is switched:
uv run ruff check . --fix && uv run ruff format .
Review the diff — Ruff's formatter is close to Black on large codebases but not
byte-identical; deviations are documented at
docs.astral.sh/ruff/formatter/black/.
For a large reformat, record the commit in .git-blame-ignore-revs.
- Retire the old stack in the same PR: remove black/flake8/isort (and their
plugins) from dev dependencies; delete
.flake8, .isort.cfg, [tool.black],
[tool.isort]. Two active formatters will fight over the same lines
(astral-sh/ruff#1307).
- Tell the user to repoint whatever invoked the old tools — pre-commit hooks
(python-precommit skill) and CI jobs (python-ci skill). Provide only the
commands:
ruff check . and ruff format --check ..
An existing Black+Flake8 setup that works and hurts nobody is a valid reason to
not migrate — churn has cost. Migrate when there is friction (speed, config
sprawl, plugin abandonment), not for fashion.
6. Fix lint / format failures
uv run ruff check . --fix # 1. autofix what's safe
uv run ruff format . # 2. THEN format — fixes can leave code needing reformat
uv run ruff check . # 3. see what's left; --fix exiting clean != zero violations
Order matters: --fix rewrites imports/comprehensions that then need reformatting.
For what remains:
- Fix the code. Reach for suppressions only when the violation is intentional, and
then the narrowest one: specific
# noqa: <CODE> > per-file-ignores > global
ignore. Never make a red gate green by deleting rules from select.
- Some fixes are deliberately held back as unsafe (could change behavior). Review
them explicitly with
uv run ruff check . --fix --unsafe-fixes --diff before
applying.
- In GitHub Actions logs,
uv run ruff check . --output-format=github emits
file/line annotations on the PR (the workflow YAML itself is python-ci
territory).
7. Verify done
uv run ruff check . && uv run ruff format --check . && echo LINT-OK
python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root .
Output spec
Done means all of:
pyproject.toml has [tool.ruff] with an explicit select, E501 ignored
while the formatter is in use, and a resolved target-version (or
requires-python).- Ruff pinned in dev dependencies (and optionally
required-version in config).
uv run ruff check . and uv run ruff format --check . both exit 0.- No leftover
.flake8 / .isort.cfg / [tool.black] / [tool.isort], and no
black/flake8/isort in dev dependencies (unless the documented hybrid pattern).
- Migrations: the mechanical reformat isolated in its own commit; suppressions
carry rule codes and reasons.
scripts/check_ruff_config.py reports 0 errors.
Failure modes & gotchas
| Symptom |
Cause |
Fix |
| Ruff installed but finds too little (pre-0.16) or floods CI after an upgrade (0.16+) |
Running on the default rule set, which changed from E+F to 413 rules in 0.16 |
Write an explicit select (step 3) — it replaces the defaults, so upgrades stop moving the gate |
| E501 violations the formatter refuses to fix |
Linter and formatter both own line length |
ignore = ["E501"]; the formatter wraps what it can |
| Routine Ruff upgrade suddenly fails checks |
select = ["ALL"] auto-enables new rules |
Explicit select; pin the Ruff version |
| Formatter and linter fight (commas, quotes, indentation) |
COM812/COM819, Q000–Q004, D203/D206/D300, W191, E111/E114/E117 (and ISC002 without ISC001 + allow-multiline = false) conflict with ruff format |
Drop them from select/add to ignore — see conflicting rules |
--fix deletes # noqa: XY123 comments |
RUF100 treats unknown codes as unused suppressions |
external = ["XY"] in [tool.ruff.lint] |
| Autofix emits syntax that breaks the oldest supported Python |
No target-version / requires-python → py310 assumed |
Set target-version to the real minimum |
| Excluded files still linted when paths are passed one-by-one |
Explicit file args bypass exclude (ruff#9585) |
Use per-file-ignores for must-hold rules; hook-layer wiring belongs to python-precommit |
ruff check --fix exits clean, CI still red |
Only safe fixes auto-apply; the rest still report |
Re-run plain check; fix manually or review --unsafe-fixes --diff |
| Files keep flip-flopping between formats |
Black (or an IDE Black plugin) still active alongside Ruff |
One formatter only — remove Black, update editor settings |
Old .flake8 / [tool.black] settings "stopped working" |
Ruff never reads them |
Translate into [tool.ruff], then delete the originals |
| Passes locally, fails elsewhere |
Version drift across dev/CI/hooks |
Same pinned version everywhere; required-version makes mismatch a hard error |
| Expected Ruff to format YAML/Markdown/TOML |
Python-only by design; since 0.16 Python code fences in Markdown are formatted by default (opt out with fmt: off comments or extend-exclude) |
python-precommit skill covers non-Python formatting; scope Prettier/mdformat so they do not fight Ruff on fenced Python |
| First CI run after adding Ruff fails hard |
No local cleanup pass before wiring the gate |
Run step 6 locally, commit, then gate |
ruff check green but diffs look unformatted |
Lint and format are separate concerns — check doesn't verify formatting |
Always run both gates (step 7) |
Bundled resources
references/rule-selection.md — rule-prefix→origin map, tiered adoption
strategy, select vs extend-select vs ALL trade-offs, per-file-ignore
conventions, isort/pydocstyle/bugbear sub-tables, fix-safety knobs.references/migration.md — old-command→Ruff mapping, Black/isort/Flake8 config
key translation, Flake8-plugin→prefix table, custom-plugin hybrid, incremental
adoption for large legacy codebases.scripts/check_ruff_config.py — read-only config sanity checker; exits non-zero
on findings. Run python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root <repo>
(--strict to fail on warnings too).
1---2name: python-lint3description: Sets up and tunes Ruff linting and formatting for a Python package — pyproject [tool.ruff] rule selection, Black/Flake8/isort migration — and fixes lint or format failures. Use when the user says 'set up linting', 'add ruff', 'fix lint errors', 'configure the formatter'. Not for type errors, non-Python file formatting, pre-commit wiring, or CI workflows.4license: MIT5---67# python-lint89## Purpose1011Configure Ruff as the single linter and formatter for a Python package — replacing12Black, Flake8 (+ plugins), isort, and pyupgrade — with an explicit rule set in13`pyproject.toml`, then drive `ruff check` and `ruff format --check` to a clean exit.14Covers fresh setup, migration from the legacy stack, rule tuning, and fixing lint or15format failures. Every command below runs in the user's package repository.1617## When NOT to use1819- **Type errors / mypy / pyright / ty** — Ruff performs no type inference; `ANN`20 rules only police annotation *style*. The python-typing skill, if installed,21 owns this.22- **Pre-commit wiring** (`.pre-commit-config.yaml`, hook rev pinning, staged-file23 runs) — the python-precommit skill. This skill only defines what Ruff should do.24- **CI workflow YAML** (GitHub Actions jobs, matrices, caching) — the python-ci25 skill. This skill supplies the commands a CI job should run, not the workflow.26- **Formatting YAML / JSON / TOML / Markdown prose** — Ruff formats Python27 (including, since 0.16, Python code fences inside Markdown) and nothing else,28 by deliberate maintainer decision29 ([astral-sh/ruff#10738](https://github.com/astral-sh/ruff/issues/10738));30 the python-precommit skill covers non-Python files.31- **Running Ruff automatically on agent edits** (Claude Code hooks) — the32 agent-guardrails skill.3334## Workflow3536### 1. Inspect before touching anything3738```bash39ls .flake8 .isort.cfg setup.cfg tox.ini ruff.toml .ruff.toml 2>/dev/null40grep -nE '^\[tool\.(ruff|black|isort)|^\[flake8\]|^\[isort\]' pyproject.toml setup.cfg tox.ini 2>/dev/null41grep -n 'requires-python' pyproject.toml42```4344Pick the path: fresh setup (steps 2–3), migration off Black/Flake8/isort (step 5),45tuning an existing config (step 4), or fixing a red lint gate (step 6).4647### 2. Install a pinned Ruff4849```bash50uv add --dev "ruff==0.16.6" # example pin — check the latest release and pin that51# one-off, no project change:52uvx --from 'ruff==0.16.6' ruff check .53```5455No-uv fallback (once, applies to every command below): `python -m pip install56'ruff==0.16.6'` and drop the `uv run` prefix.5758Why pin — formatter output and the rule catalog change between minor releases:590.15 shipped a "2026 style guide" that changed lambda and empty-line formatting60([astral.sh/blog/ruff-v0.15.0](https://astral.sh/blog/ruff-v0.15.0)), and 0.1661(2026-07-23) grew the **default** rule set from 59 to 413 rules while dropping 1862`E`/`F` codes from it, so an unconfigured repo's findings changed overnight63([astral.sh/blog/ruff-v0.16.0](https://astral.sh/blog/ruff-v0.16.0)). An unpinned64Ruff makes local, teammate, and CI runs disagree — the top reported lint-workflow65failure. Optionally enforce the pin in config with66`required-version = "0.16.6"` under `[tool.ruff]`. Note that `uv format`67(experimental since uv 0.8.13) runs a Ruff it bundles itself, so its version can68differ from the project's pin — keep `ruff` in dev dependencies as the source of69truth and treat `uv format` as a convenience wrapper.7071### 3. Write the config (fresh setup)7273All Ruff config lives in `pyproject.toml`. Keep exactly one config file — a74`ruff.toml` next to a `[tool.ruff]` section is a recipe for confusion. Starter:7576```toml77[tool.ruff]78target-version = "py311" # lowest Python you support; gates UP rewrites79line-length = 8880extend-exclude = ["migrations"] # generated code, if any8182[tool.ruff.lint]83select = [84 "E", "W", # pycodestyle85 "F", # pyflakes86 "I", # isort (import sorting)87 "UP", # pyupgrade88 "B", # flake8-bugbear89 "C4", # flake8-comprehensions90 "SIM", # flake8-simplify91 "RUF", # Ruff-specific rules92]93ignore = ["E501"] # line length is the formatter's job9495[tool.ruff.lint.per-file-ignores]96"tests/**/*.py" = ["S101"] # assert is fine in tests (relevant once S is on)97"__init__.py" = ["F401"] # re-exports9899[tool.ruff.lint.isort]100known-first-party = ["yourpackage"]101102[tool.ruff.format]103quote-style = "double"104docstring-code-format = true # formats Python snippets inside docstrings105```106107Non-obvious decisions baked into this block:108109- **Never rely on Ruff's default rule set.** Before 0.16 it was `E4`/`E7`/`E9`110 + `F` (59 rules, less than a Flake8+plugins stack); since 0.16 it is 413 rules across111 `B`, `UP`, `SIM`, `PL` and more, with 18 former `E`/`F` defaults removed — a repo112 without `select` gets a different gate on every upgrade. `select` **replaces**113 the default set, so an explicit list freezes it; `select = ["E4", "E7", "E9",114 "F"]` reproduces the pre-0.16 baseline if a team wants exactly that.115- **`ignore = ["E501"]` whenever the formatter is enabled** — `ruff format` already116 wraps at `line-length`; linting it too double-reports on lines the formatter117 cannot break (URLs, long strings).118- **`target-version` gates `UP` (pyupgrade) rewrites.** If unset, Ruff falls back119 to `project.requires-python`; if that is also absent it assumes py310, and120 autofixes can emit syntax that crashes older supported runtimes.121- Avoid `select = ["ALL"]` — it silently enables every new rule on every Ruff122 upgrade, breaking checks unpredictably. Official guidance is to start narrow and123 grow one category at a time124 ([docs.astral.sh/ruff/linter/](https://docs.astral.sh/ruff/linter/)).125126Deeper rule catalog, tier strategy, and sub-table options (isort, pydocstyle,127bugbear): `references/rule-selection.md`.128129### 4. Tune an existing config130131- Noise in one area (tests, scripts, notebooks) → scope it with132 `[tool.ruff.lint.per-file-ignores]`; never delete the rule from `select` globally133 because tests complain. Common: `"tests/**/*.py" = ["S101", "PLR2004"]`,134 `"scripts/*" = ["T201"]`.135- A single intentional violation → `# noqa: <CODE>` with the specific code and a136 short reason. Bare `# noqa` hides every rule on the line.137- Codes from non-Ruff tools in `# noqa` comments (custom Flake8 plugin) →138 declare `external = ["XX"]` in `[tool.ruff.lint]`, or `RUF100` strips those139 comments on the next `--fix`.140- Widen coverage one prefix at a time (`"S"`, `"PT"`, `"PTH"`, …), run141 `uv run ruff check .` after each addition, and fix or scope before adding more.142- Sanity-check the result: `python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root .`143 (read-only; flags E501 double-reporting, `ALL`, formatter-conflicting rules,144 leftover legacy configs, missing target-version).145146### 5. Migrate from Black / Flake8 / isort147148Full mapping tables (commands, config keys, Flake8-plugin→prefix) and the149large-legacy-codebase strategy: `references/migration.md`. The sequence:1501511. **Translate config first.** `[tool.black]` → `[tool.ruff]` + `[tool.ruff.format]`,152 `[tool.isort]`/`.isort.cfg` → `[tool.ruff.lint.isort]` (kebab-case keys),153 `.flake8` → `select`/`ignore`/`per-file-ignores`. Ruff never reads154 `[tool.black]` or `.flake8` — anything not translated is silently lost.1552. **Check plugin parity.** For each Flake8 plugin in use, confirm a Ruff prefix156 exists (table in the reference). A business-critical plugin with no equivalent157 → hybrid: keep Flake8 scoped to that plugin, add its codes to158 `external = [...]`.1593. **One-time cleanup as its own reviewed commit**, before any gate is switched:160 ```bash161 uv run ruff check . --fix && uv run ruff format .162 ```163 Review the diff — Ruff's formatter is close to Black on large codebases but not164 byte-identical; deviations are documented at165 [docs.astral.sh/ruff/formatter/black/](https://docs.astral.sh/ruff/formatter/black/).166 For a large reformat, record the commit in `.git-blame-ignore-revs`.1674. **Retire the old stack in the same PR**: remove black/flake8/isort (and their168 plugins) from dev dependencies; delete `.flake8`, `.isort.cfg`, `[tool.black]`,169 `[tool.isort]`. Two active formatters will fight over the same lines170 ([astral-sh/ruff#1307](https://github.com/astral-sh/ruff/issues/1307)).1715. **Tell the user to repoint whatever invoked the old tools** — pre-commit hooks172 (python-precommit skill) and CI jobs (python-ci skill). Provide only the173 commands: `ruff check .` and `ruff format --check .`.174175An existing Black+Flake8 setup that works and hurts nobody is a valid reason to176not migrate — churn has cost. Migrate when there is friction (speed, config177sprawl, plugin abandonment), not for fashion.178179### 6. Fix lint / format failures180181```bash182uv run ruff check . --fix # 1. autofix what's safe183uv run ruff format . # 2. THEN format — fixes can leave code needing reformat184uv run ruff check . # 3. see what's left; --fix exiting clean != zero violations185```186187Order matters: `--fix` rewrites imports/comprehensions that then need reformatting.188For what remains:189190- Fix the code. Reach for suppressions only when the violation is intentional, and191 then the narrowest one: specific `# noqa: <CODE>` > per-file-ignores > global192 `ignore`. Never make a red gate green by deleting rules from `select`.193- Some fixes are deliberately held back as unsafe (could change behavior). Review194 them explicitly with `uv run ruff check . --fix --unsafe-fixes --diff` before195 applying.196- In GitHub Actions logs, `uv run ruff check . --output-format=github` emits197 file/line annotations on the PR (the workflow YAML itself is python-ci198 territory).199200### 7. Verify done201202```bash203uv run ruff check . && uv run ruff format --check . && echo LINT-OK204python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root .205```206207## Output spec208209Done means all of:210211- `pyproject.toml` has `[tool.ruff]` with an explicit `select`, `E501` ignored212 while the formatter is in use, and a resolved `target-version` (or213 `requires-python`).214- Ruff pinned in dev dependencies (and optionally `required-version` in config).215- `uv run ruff check .` and `uv run ruff format --check .` both exit 0.216- No leftover `.flake8` / `.isort.cfg` / `[tool.black]` / `[tool.isort]`, and no217 black/flake8/isort in dev dependencies (unless the documented hybrid pattern).218- Migrations: the mechanical reformat isolated in its own commit; suppressions219 carry rule codes and reasons.220- `scripts/check_ruff_config.py` reports 0 errors.221222## Failure modes & gotchas223224| Symptom | Cause | Fix |225| --- | --- | --- |226| Ruff installed but finds too little (pre-0.16) or floods CI after an upgrade (0.16+) | Running on the default rule set, which changed from `E`+`F` to 413 rules in 0.16 | Write an explicit `select` (step 3) — it replaces the defaults, so upgrades stop moving the gate |227| E501 violations the formatter refuses to fix | Linter and formatter both own line length | `ignore = ["E501"]`; the formatter wraps what it can |228| Routine Ruff upgrade suddenly fails checks | `select = ["ALL"]` auto-enables new rules | Explicit `select`; pin the Ruff version |229| Formatter and linter fight (commas, quotes, indentation) | `COM812`/`COM819`, `Q000`–`Q004`, `D203`/`D206`/`D300`, `W191`, `E111`/`E114`/`E117` (and `ISC002` without `ISC001` + `allow-multiline = false`) conflict with `ruff format` | Drop them from `select`/add to `ignore` — see [conflicting rules](https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules) |230| `--fix` deletes `# noqa: XY123` comments | `RUF100` treats unknown codes as unused suppressions | `external = ["XY"]` in `[tool.ruff.lint]` |231| Autofix emits syntax that breaks the oldest supported Python | No `target-version` / `requires-python` → py310 assumed | Set `target-version` to the real minimum |232| Excluded files still linted when paths are passed one-by-one | Explicit file args bypass `exclude` ([ruff#9585](https://github.com/astral-sh/ruff/issues/9585)) | Use per-file-ignores for must-hold rules; hook-layer wiring belongs to python-precommit |233| `ruff check --fix` exits clean, CI still red | Only *safe* fixes auto-apply; the rest still report | Re-run plain `check`; fix manually or review `--unsafe-fixes --diff` |234| Files keep flip-flopping between formats | Black (or an IDE Black plugin) still active alongside Ruff | One formatter only — remove Black, update editor settings |235| Old `.flake8` / `[tool.black]` settings "stopped working" | Ruff never reads them | Translate into `[tool.ruff]`, then delete the originals |236| Passes locally, fails elsewhere | Version drift across dev/CI/hooks | Same pinned version everywhere; `required-version` makes mismatch a hard error |237| Expected Ruff to format YAML/Markdown/TOML | Python-only by design; since 0.16 Python *code fences* in Markdown are formatted by default (opt out with `fmt: off` comments or `extend-exclude`) | python-precommit skill covers non-Python formatting; scope Prettier/mdformat so they do not fight Ruff on fenced Python |238| First CI run after adding Ruff fails hard | No local cleanup pass before wiring the gate | Run step 6 locally, commit, then gate |239| `ruff check` green but diffs look unformatted | Lint and format are separate concerns — `check` doesn't verify formatting | Always run both gates (step 7) |240241## Bundled resources242243- `references/rule-selection.md` — rule-prefix→origin map, tiered adoption244 strategy, `select` vs `extend-select` vs `ALL` trade-offs, per-file-ignore245 conventions, isort/pydocstyle/bugbear sub-tables, fix-safety knobs.246- `references/migration.md` — old-command→Ruff mapping, Black/isort/Flake8 config247 key translation, Flake8-plugin→prefix table, custom-plugin hybrid, incremental248 adoption for large legacy codebases.249- `scripts/check_ruff_config.py` — read-only config sanity checker; exits non-zero250 on findings. Run `python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root <repo>`251 (`--strict` to fail on warnings too).
Paldom