ruff-linting

ruff のリント

包括的なルールに対応し、自動修正機能も備えた非常に高速な Python リンターとして ruff check を使うための専門知識です。

このスキルを使う場面

次の場合にこのスキルを使います…	代わりに特化した関連スキルを使う場合…
ruff check を実行する、ルールセットを選ぶ、またはリント違反を自動修正する	コードスタイルを統一するために ruff format を実行する場合は、ruff-formatting を使います
pyproject.toml で [tool.ruff.lint] のルールやファイルごとの無視設定を構成する	スタック全体の観点から ruff と型チェッカーやフォーマッターを比較する場合は、python-code-quality を使います
ruff をエディター、pre-commit、CI/CD、Docker、またはビルドシステムに組み込む	以下のCI/CD 統合にある簡易例を参照してください。エディター／CI／Docker／移行の詳しい手順は REFERENCE.md を参照してください
Flake8/pylint/isort/pyupgrade から ruff の統合ルールセットに移行する	コードスタイルを統一するために ruff format を実行する場合は、ruff-formatting を使います

主な特長

ruff の利点

• 非常に高速です（Flake8 の 10～100 倍）
• パフォーマンスを重視して Rust で書かれています
• 複数のツール（Flake8、pylint、isort、pyupgrade など）を置き換えます
• 多くのルールに自動修正機能があります
• 既存の設定と互換性があります
• 800 を超える組み込みルールがあります

基本的な使い方

シンプルなリント

# Lint current directory
ruff check

# Lint specific files or directories
ruff check path/to/file.py
ruff check src/ tests/

# IMPORTANT: Pass directory as parameter to stay in repo root
# ✅ Good
ruff check services/orchestrator

# ❌ Bad
cd services/orchestrator && ruff check

自動修正

# Show what would be fixed (diff preview)
ruff check --diff

# Apply safe automatic fixes
ruff check --fix

# Fix specific files
ruff check --fix src/main.py

# Fix with preview (see changes before applying)
ruff check --diff services/orchestrator
ruff check --fix services/orchestrator

出力形式

# Default output
ruff check

# Show statistics
ruff check --statistics

# JSON output for tooling
ruff check --output-format json

# GitHub Actions annotations
ruff check --output-format github

# GitLab Code Quality report
ruff check --output-format gitlab

# Concise output
ruff check --output-format concise

ルールの選択

よく使われるルールコード

コード	説明	ルールの例
E	pycodestyle のエラー	E501（行が長すぎる）
F	Pyflakes	F401（未使用のインポート）
W	pycodestyle の警告	W605（無効なエスケープ）
B	flake8-bugbear	B006（変更可能なデフォルト値）
I	isort	I001（インポートの順序が不適切）
UP	pyupgrade	UP006（非推奨の型）
SIM	flake8-simplify	SIM102（ネストした if）
D	pydocstyle	D100（docstring がない）
N	pep8-naming	N806（変数名の規則違反）
S	flake8-bandit（セキュリティ）	S101（assert の使用）
C4	flake8-comprehensions	C400（不要なジェネレーター）

ルールの選択

# Select specific rules at runtime
ruff check --select E,F,B,I

# Extend default selection
ruff check --extend-select UP,SIM

# Ignore specific rules
ruff check --ignore E501,E402

# Show which rules would apply
ruff rule --all

# Explain a specific rule
ruff rule F401

ルールの検索

# List all available rules
ruff rule --all

# Search for rules by pattern
ruff rule --all | grep "import"

# Get detailed rule explanation
ruff rule F401
# Output: unused-import (F401)
#   Derived from the Pyflakes linter.
#   Checks for unused imports.

# List all linters
ruff linter

# JSON output for automation
ruff rule F401 --output-format json

設定

pyproject.toml

[tool.ruff]
# Line length limit (same as Black)
line-length = 88

# Target Python version
target-version = "py311"

# Exclude directories
exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
]

[tool.ruff.lint]
# Enable specific rule sets
select = [
    "E",   # pycodestyle errors
    "F",   # Pyflakes
    "B",   # flake8-bugbear
    "I",   # isort
    "UP",  # pyupgrade
    "SIM", # flake8-simplify
]

# Disable specific rules
ignore = [
    "E501",  # Line too long (handled by formatter)
    "B008",  # Function calls in argument defaults
]

# Allow automatic fixes
fixable = ["ALL"]
unfixable = ["B"]  # Don't auto-fix bugbear rules

# Per-file ignores
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401", "E402"]
"tests/**/*.py" = ["S101"]  # Allow assert in tests

ruff.toml（単独ファイル）

# Same options as pyproject.toml but without [tool.ruff] prefix
line-length = 100
target-version = "py39"

[lint]
select = ["E", "F", "B"]
ignore = ["E501"]

[lint.isort]
known-first-party = ["myapp"]
force-single-line = true

高度な使い方

ファイルごとの設定の上書き、対象を絞ったルールチェック、変更ファイルのみを対象にする方法、並列実行のパターンについては、references/command-recipes.md を参照してください。

CI/CD 統合

簡易例 — GitHub Actions で PR に注釈を付けながらリントします。

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3
        with:
          args: 'check --output-format github'

簡易例 — pre-commit フック：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.0
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format

統合の詳しい手順については、REFERENCE.md を参照してください。エディターの設定（VS Code、Neovim、Zed、Helix）、高度な pre-commit 設定、GitLab/CircleCI/Jenkins、Make/Just/Task/tox、Docker、LSP サーバー設定、Flake8/Black/pylint からの移行ガイドを掲載しています。

よくあるパターン

特定の問題の検出、段階的な導入、リファクタリングのサポートに関する手順は、references/command-recipes.md を参照してください。

プラグインの設定

プラグインごとの [tool.ruff.lint.<plugin>] 設定（isort、flake8-quotes、pydocstyle、pylint）については、references/plugin-configuration.md を参照してください。

ベストプラクティス

ruff check を使用する場面

• コード品質の確保
• コミット前の検証
• CI/CD パイプライン
• リファクタリングの支援
• セキュリティスキャン
• インポートの整理

重要：ディレクトリのパラメーター

• ✅ 必ずディレクトリをパラメーターとして渡します：ruff check services/orchestrator
• ❌ 決してcdを使いません：cd services/orchestrator && ruff check
• 理由：並列実行、より明確な出力、ツールとの互換性

ルール選択の方針

1. 最小構成から始めます：select = ["E", "F"]（エラー＋pyflakes）
2. bugbear を追加します：select = ["E", "F", "B"]
3. インポートルールを追加します：select = ["E", "F", "B", "I"]
4. pyupgrade を追加します：select = ["E", "F", "B", "I", "UP"]
5. セキュリティルールを検討します：select = ["E", "F", "B", "I", "UP", "S"]

修正可能なルールと修正不可能なルール

• 判断が不確かなルールには unfixable を指定し、手動で確認します
• よくある修正不可能なルール：B（bugbear）、F（pyflakes F401）
• 安全なルールの修正は ruff に任せます：I（isort）、UP（pyupgrade）

避けるべきよくある間違い

• ディレクトリのパラメーターを渡さずに cd を使う
• すべてのルールをすぐに有効にする（段階的に導入します）
• --fix の前に --diff を使わない
• ルールの説明を確認しない（ruff rule <code>）
• 特殊なケースに対するファイルごとの無視設定を構成しない

クイックリファレンス

必須コマンド

# Basic operations
ruff check                          # Lint current directory
ruff check path/to/dir              # Lint specific directory
ruff check --diff                   # Show fix preview
ruff check --fix                    # Apply fixes

# Rule management
ruff rule --all                     # List all rules
ruff rule F401                      # Explain rule F401
ruff linter                         # List all linters

# Output formats
ruff check --statistics             # Show violation counts
ruff check --output-format json     # JSON output
ruff check --output-format github   # GitHub Actions format

# Selection
ruff check --select E,F,B          # Select rules
ruff check --ignore E501           # Ignore rules
ruff check --extend-select UP      # Extend selection

設定の優先順位

1. コマンドライン引数（最優先）
2. 現在のディレクトリにある ruff.toml
3. 現在のディレクトリにある pyproject.toml
4. 親ディレクトリの設定（再帰的に適用）
5. ユーザー設定：~/.config/ruff/ruff.toml

よくあるルールの組み合わせ

# Minimal safety
ruff check --select E,F

# Good default
ruff check --select E,F,B,I

# Comprehensive
ruff check --select E,F,B,I,UP,SIM

# Security-focused
ruff check --select E,F,B,S

# Docstring enforcement
ruff check --select D --config '[lint.pydocstyle]\nconvention = "google"'

これにより、ruff check は高速で包括的な Python コードのリンティングに最適なツールとなります。