ruff-recursive-fix

Ruff による再帰的修正

概要

このスキルを使用して、制御された反復的なワークフローで Ruff によるコード品質を確保します。 以下をサポートします。

• 特定のフォルダーへの対象範囲の限定（任意）。
• pyproject.toml のプロジェクト既定設定の使用。
• 柔軟な Ruff の実行方法（uv、直接の ruff、python -m ruff、または同等の方法）。
• 実行ごとのルール上書き（--select、--ignore、--extend-select、--extend-ignore、任意）。
• 安全な自動修正を実行した後、安全でない自動修正を実行。
• 各修正パス後の差分レビュー。
• 指摘事項が解消されるか、判断が必要になるまで再帰的に繰り返す。
• 抑制が妥当な場合に限り、インラインの # noqa を慎重に使用する。

入力

実行前に、次の入力を収集します。

• target_path（任意）：チェックするフォルダーまたはファイル。空の場合はリポジトリ全体が対象です。
• ruff_runner（任意）：Ruff コマンドの明示的なプレフィックス（例：uv run、ruff、python -m ruff、pipx run ruff）。
• rules_select（任意）：適用するルールコードをカンマ区切りで指定します。
• rules_ignore（任意）：無視するルールコードをカンマ区切りで指定します。
• extend_select（任意）：設定済みの既定ルールを置き換えずに追加するルール。
• extend_ignore（任意）：設定済みの既定ルールを置き換えずに追加する無視対象ルール。
• allow_unsafe_fixes（既定値：true）：Ruff の安全でない修正を実行するかどうか。
• ask_on_ambiguity（既定値：true）：複数の妥当な選択肢がある場合、必ずユーザーに確認します。

コマンドの構築

入力に基づいて Ruff コマンドを構築します。

0. Ruff ランナーの解決

コマンドを構築する前に、再利用可能な ruff_cmd プレフィックスを決定します。

解決順序：

1. ruff_runner が指定されている場合は、そのまま使用します。
2. それ以外で、uv が利用可能で、Ruff が uv で管理されている場合は、uv run ruff を使用します。
3. それ以外で、ruff が PATH 上で利用可能な場合は、ruff を使用します。
4. それ以外で、Python が利用可能で、その環境に Ruff がインストールされている場合は、python -m ruff を使用します。
5. それ以外の場合は、インストール済みの Ruff を実行するプロジェクト固有の同等の方法（例：pipx run ruff）を使用するか、停止してユーザーに確認します。

ワークフロー内のすべての check および format コマンドで、同じ解決済みの ruff_cmd を使用します。

基本コマンド：

<ruff_cmd> check

フォーマッターコマンド：

<ruff_cmd> format

対象を任意で指定する場合：

<ruff_cmd> format <target_path>

対象を追加する場合：

<ruff_cmd> check <target_path>

必要に応じて任意の上書きを追加します。

--select <codes>
--ignore <codes>
--extend-select <codes>
--extend-ignore <codes>

例：

# Full project with defaults from pyproject.toml
ruff check

# One folder with defaults
python -m ruff check src/models

# Override to skip docs and TODO-like rules for this run
uv run ruff check src --extend-ignore D,TD

# Check only selected rules in a folder
ruff check src/data --select F,E9,I

ワークフロー

1. ベースライン分析

1. 選択した対象範囲とオプションを指定して、<ruff_cmd> check を実行します。
2. 指摘事項を種類ごとに分類します。
   • 安全に自動修正可能。
   • 安全でないが自動修正可能。
   • 自動修正不可。
3. 指摘事項が残っていなければ終了します。

2. 安全な自動修正

1. 同じ対象範囲とオプションを指定し、--fix を使って Ruff を実行します。
2. 意味的な正しさとスタイルの一貫性に注意して、生成された差分を慎重にレビューします。
3. 同じ対象範囲に対して <ruff_cmd> format を実行します。
4. <ruff_cmd> check を再実行し、残りの指摘事項を確認します。

3. 安全でない自動修正

指摘事項が残っており、allow_unsafe_fixes=true の場合にのみ実行します。

1. 同じ対象範囲とオプションを指定し、--fix --unsafe-fixes を使って Ruff を実行します。
2. 挙動に影響する編集を優先し、生成された差分を慎重にレビューします。
3. 同じ対象範囲に対して <ruff_cmd> format を実行します。
4. <ruff_cmd> check を再実行します。

4. 手動での修正

指摘事項が残っている場合：

1. 明確で安全な修正方法がある場合は、コードを直接修正します。
2. 編集は最小限かつ局所的にとどめます。
3. 同じ対象範囲に対して <ruff_cmd> format を実行します。
4. <ruff_cmd> check を再実行します。

5. 曖昧さへの対応方針

いずれかの手順で複数の妥当な解決策がある場合は、作業を続ける前に必ずユーザーに確認します。 同等の選択肢から、黙って一つを選んではいけません。

6. 抑制の判断（# noqa）

次のすべての条件を満たす場合に限り、抑制を使用します。

• そのルールが、必要な挙動、公開 API、フレームワークの規約、または可読性の目標と衝突する。
• リファクタリングに見合う価値が、そのルールにはない。
• 抑制の範囲が狭く、具体的である（可能な場合は単一行で、明示的なコードを指定する）。

ガイドライン：

• 広範な # noqa より、# noqa: <RULE> を優先します。
• すぐには分からない抑制には、簡潔な理由コメントを追加します。
• 妥当な結果が二つ以上ある場合は、どの選択肢を優先するか必ずユーザーに確認します。

7. 再帰ループと停止基準

次のいずれかの結果になるまで、手順 2〜6 を繰り返します。

• <ruff_cmd> check が問題なしを返します。
• 残りの指摘に、アーキテクチャまたは製品に関する判断が必要です。
• 残りの指摘が、根拠を文書化したうえで意図的に抑制されています。
• ループを繰り返しても進展がありません。

各ループの反復では、次の <ruff_cmd> check の前に必ず <ruff_cmd> format を実行してください。

進展がないと判断した場合：

1. 対応できないルールと影響を受けるファイルを要約します。
2. 有効な選択肢とトレードオフを提示します。
3. ユーザーに選択を求めます。

品質ゲート

完了を宣言する前に、次を確認します。

• 選択したスコープ／オプションで、Ruff に予期しない指摘がないこと。
• すべての自動修正の差分が、正確であることを確認済みであること。
• 明確な根拠なしに抑制を追加していないこと。
• 動作に影響する可能性がある安全でない修正について、ユーザーに注意を促していること。
• すべての反復で Ruff のフォーマットを実行していること。

出力仕様

実行の最後に、次を報告します。

• 使用したスコープと Ruff のオプション。
• 実行した反復回数。
• 修正した指摘の概要。
• 手動で修正した項目の一覧。
• 根拠とともに抑制した項目の一覧。
• 残りの指摘がある場合は、その内容と必要なユーザーの判断。

プロンプトの例

• 「既定の設定で、リポジトリ全体に ruff-recursive-fix を実行してください。」
• 「src/models のみに ruff-recursive-fix を実行し、DOC ルールを無視してください。」
• 「テストに select F,E9,I を指定して、安全でない修正を行わずに ruff-recursive-fix を実行してください。」
• 「src/data に ruff-recursive-fix を実行し、noqa の追加前に確認してください。」