ruff-formatting

ruff Formatting

ruff format を Black と互換性のある超高速な Python コードフォーマッターとして使うための専門知識です。

このスキルを使う場面

次のような場合にこのスキルを使います	次のような場合は代わりに別のツールを使います
Python ファイルをフォーマットするとき	コードの問題をリントするとき（ruff check を使用）
CI でフォーマット準拠を確認するとき	型チェックをするとき（basedpyright を使用）
Black から移行するとき	デッドコードを検出するとき（vulture/deadcode を使用）
保存時のフォーマットを設定するとき	テストを実行するとき（pytest を使用）

主な専門知識

ruff format の利点

• Black より 10～30 倍高速
• そのまま置き換えられる Black 互換ツール（99.9％互換）
• パフォーマンスに優れた Rust 製
• Black の設定オプションに対応
• フォーマットチェックと差分プレビューに対応
• .gitignore を自動的に尊重

基本的な使い方

シンプルなフォーマット

# Format current directory
ruff format

# Format specific files or directories
ruff format path/to/file.py
ruff format src/ tests/

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

フォーマットのチェック

# Check if files are formatted (exit code 1 if not)
ruff format --check

# Show diff without modifying files
ruff format --diff

# Check specific files
ruff format --check src/ tests/

# Preview changes before applying
ruff format --diff services/orchestrator
ruff format services/orchestrator  # Apply after review

対象を指定したフォーマット

# Format only Python files
ruff format src/**/*.py

# Format excluding tests
ruff format --exclude tests/

# Format only changed files (git)
git diff --name-only --diff-filter=d | grep '\.py$' | xargs ruff format

# Format files in specific directory
ruff format src/core/ src/utils/

設定

pyproject.toml

[tool.ruff]
line-length = 88
target-version = "py39"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"
docstring-code-format = true
docstring-code-line-length = "dynamic"
exclude = [
    "*.pyi",
    "**/__pycache__",
    "**/node_modules",
    ".venv",
]

ruff.toml（単独）

line-length = 88

[format]
quote-style = "single"
indent-style = "space"
skip-magic-trailing-comma = false
docstring-code-format = true

Black との互換性

[tool.ruff]
line-length = 88
indent-width = 4
target-version = "py39"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

フォーマットのワークフロー

1. プレビュー：ruff format --diff（変更を確認）
2. チェック：ruff format --check（CI で検証）
3. 適用：ruff format（ファイルを変更）
4. 検証：ruff format --check（結果を確認）

ベストプラクティス

• ディレクトリのパラメーターを直接渡します：ruff format src/
• まず --diff で変更をプレビューします
• プロジェクトごとにフォーマッターを 1 つ使います（ruff format は Black に置き換わります）
• pyproject.toml で生成ファイルを除外します
• pre-commit の設定をフォーマッターの選択と一致させます
• ドキュメントを改善するには docstring-code-format を有効にします

エージェント向けの最適化

コンテキスト	コマンド
ディレクトリをフォーマット	ruff format src/
フォーマットをチェック	ruff format --check
差分を表示	ruff format --diff
CI チェックと差分表示	ruff format --check --diff
フォーマットとリント	ruff format && ruff check
変更されたファイルをフォーマット	git diff --name-only --diff-filter=d | grep '\.py$' | xargs ruff format

クイックリファレンス

基本コマンド

ruff format                         # Format current directory
ruff format path/to/dir             # Format specific directory
ruff format --check                 # Check if formatted
ruff format --diff                  # Show formatting changes
ruff format file1.py file2.py       # Format specific files
ruff format --exclude tests/        # Exclude directory
ruff format --line-length 100       # Override line length

フォーマットとチェック

コマンド	目的	終了コード	ファイルの変更
ruff format	ファイルをフォーマット	0	はい
ruff format --check	フォーマットを検証	フォーマットされていない場合は 1	いいえ
ruff format --diff	変更を表示	0	いいえ
ruff format --check --diff	検証して表示	フォーマットされていない場合は 1	いいえ

設定のクイックスタート

最小構成（Black 互換）

[tool.ruff]
line-length = 88

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

推奨

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
docstring-code-format = true
line-ending = "auto"
exclude = [
    "*.pyi",
    "migrations/**/*.py",
]

詳しい例、高度なパターン、統合ガイド、移行チェックリストについては、REFERENCE.md を参照してください。