What is the ZERO noqa policy and why does Ruff enforce it?

ZERO noqa means you should not mask issues with # noqa. Ruff provides proper fixes or configurations to address problems and reduce technical debt.

How do I configure Ruff for a FastAPI project?

Configure [tool.ruff] in pyproject.toml (target-version, line-length, src), enable ALL rules, and use per-file-ignores for tests or migrations as needed.

How do I migrate from other linters like black/isort/flake8/pylint?

Ruff replaces these tools: use ruff format for formatting, ruff check for linting, and remove old configs and dependencies; gradually convert configs and adjust rules as needed.

Ruff Patterns

Scanned

npx machina-cli add skill ruslan-korneev/python-backend-claude-plugins/ruff-patterns --openclaw

Files (1)

SKILL.md

3.4 KB

Ruff Patterns

Knowledge about the ruff linter and patterns for solving errors. ZERO noqa policy — always look for the proper solution.

Triggers

Use this skill when the user:

Asks "how to configure ruff"
Gets a ruff error and wants to understand how to fix it
Wants to migrate from black/isort/flake8/pylint
Asks about a specific rule (E501, F401, etc.)

Main Principle: NEVER USE NOQA

Every ruff error has a proper solution. Using # noqa is:

Hiding the problem, not solving it
Technical debt
A potential source of bugs

Instead of noqa:

Fix the code properly
Configure per-file-ignores for specific cases (tests, migrations)
Disable the rule globally if it doesn't fit the project

More details: ${CLAUDE_PLUGIN_ROOT}/skills/ruff-patterns/references/why-no-noqa.md

Quick Start

Installation

uv add ruff --dev

Basic Usage

# Check
ruff check .

# Format
ruff format .

# Auto-fix safe errors
ruff check --fix .

# Auto-fix all errors (including potentially unsafe)
ruff check --fix --unsafe-fixes .

Recommended Configuration

For FastAPI Projects

[tool.ruff]
target-version = "py312"
line-length = 120
src = ["src"]

[tool.ruff.lint]
select = ["ALL"]
ignore = [
    "D",       # docstrings
    "ANN101",  # self annotation
    "ANN102",  # cls annotation
    "FBT003",  # boolean positional arg
    "PLR0913", # too many arguments
    "S101",    # assert (allowed in tests via per-file-ignores)
    "COM812",  # trailing comma conflict
    "ISC001",  # implicit string concat conflict
]

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101", "PLR2004"]
"alembic/versions/*.py" = ["ALL"]
"__init__.py" = ["F401"]

[tool.ruff.format]
quote-style = "double"

Full example: ${CLAUDE_PLUGIN_ROOT}/skills/ruff-patterns/examples/fastapi-pyproject.toml

Solutions for Popular Errors

Detailed solution database: ${CLAUDE_PLUGIN_ROOT}/skills/ruff-patterns/references/rule-solutions.md

Quick Reference

Code	Problem	Solution
E501	Line too long	Use parentheses for line breaks
F401	Unused import	Remove or add to `__all__`
F841	Unused variable	Use `_` or remove
B008	Function call in default	`None` + check
PLR0913	Too many arguments	Dataclass/Pydantic model
S101	Assert in code	Explicit check + raise
UP007	Outdated Union	Use `X \| Y`

Migration from Other Linters

From black + isort + flake8

Ruff completely replaces these tools:

ruff format = black
ruff check --select I = isort
ruff check = flake8 + plugins

# Remove old dependencies
uv remove black isort flake8 flake8-bugbear flake8-comprehensions

# Add ruff
uv add ruff --dev

# Remove old configs
rm .flake8 .isort.cfg
# Remove [tool.black], [tool.isort] sections from pyproject.toml

From pylint

Ruff covers most pylint rules through PL* groups:

PLC: Convention
PLE: Error
PLR: Refactor
PLW: Warning

CI/CD Integration

GitHub Actions

- name: Lint with ruff
  run: |
    ruff check --output-format=github .
    ruff format --check .

Pre-commit

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

Plugin Commands

/lint:check [path] — check code
/lint:explain <error> — error explanation + solution
/lint:config [preset] — configure ruff for the project

Source

git clone https://github.com/ruslan-korneev/python-backend-claude-plugins/blob/master/plugins/python/skills/ruff-patterns/SKILL.md

View on GitHub

Overview

Ruff Patterns teaches how to use the Ruff linter to fix errors without relying on # noqa. It emphasizes a ZERO noqa policy and proper solutions, including per-file-ignores for edge cases. The guide covers setup, common errors, migrations from other linters, and CI/CD integration.

How This Skill Works

Ruff analyzes Python code against its rule set. Instead of masking issues with noqa, you fix the root cause or configure per-file-ignores or global rules. You can run ruff check for linting and ruff format for formatting, and use --fix to auto-correct safe errors.

When to Use It

You want to know how to configure Ruff for a project.
You’ve encountered a Ruff error and need guidance on fixing it.
You’re migrating from Black, isort, Flake8, or Pylint to Ruff.
You’re curious about a specific rule like E501 or F401 and its solution.
You’re integrating Ruff into CI/CD or a pre-commit workflow.

Quick Start

Step 1: uv add ruff --dev
Step 2: ruff check .
Step 3: ruff check --fix .

Best Practices

Never use # noqa; fix the code or use proper configuration.
Use per-file-ignores for known exceptions (tests, migrations) instead of global ignores.
Configure Ruff via pyproject.toml with [tool.ruff], lint, and format sections.
Use ruff check for linting and ruff format for formatting; apply --fix for safe fixes.
Consult the rule-solutions database and migrate gradually from other linters.

Example Use Cases

FastAPI project configured with a pyproject.toml: target-version = py312, line-length = 120, src = ["src"].
Per-file-ignores: "tests/**/*.py" = ["S101", "PLR2004"] and "alembic/versions/*.py" = ["ALL"], plus "__init__.py" = ["F401"].
Run linting and auto-fix: ruff check . and ruff check --fix .
Migrate from Black/isort/flake8/pylint by removing old deps and configs, then adding Ruff.
CI integration: GitHub Actions steps for ruff check and ruff format in the pipeline.

Frequently Asked Questions

Add this skill to your agents