Ruff Recursive Fix

概要

このスキルを使用して、制御された反復的なワークフローで Ruff による code quality を強制します。 以下の機能をサポートしています:

• 特定フォルダへのスコープ制限（オプション）。
• pyproject.toml からのデフォルトプロジェクト設定。
• 柔軟な Ruff 呼び出し（uv、直接 ruff、python -m ruff、またはそれに相当するもの）。
• 実行時のルール上書き（--select、--ignore、--extend-select、--extend-ignore）（オプション）。
• 安全から順に自動修正、その後不安全な自動修正。
• 各修正パス後の Diff レビュー。
• 発見事項が解決または決定が必要になるまでの再帰的な反復。
• 抑制が正当化される場合のみの慎重なインライン # 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 の unsafe fixes を実行するかどうか。
• ask_on_ambiguity（デフォルト: true）: 複数の有効な選択肢が存在する場合、常にユーザーに確認します。

コマンド構築

入力から Ruff コマンドを構築します。

0. Ruff Runner の解決

ワークフロー全体で再利用可能な 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>

例:

# pyproject.toml からのデフォルトを使用した全プロジェクト
ruff check

# デフォルトを使用した 1 フォルダ
python -m ruff check src/models

# この実行でドキュメントと TODO 関連ルールをスキップするため上書き
uv run ruff check src --extend-ignore D,TD

# フォルダ内の選択されたルールのみをチェック
ruff check src/data --select F,E9,I

ワークフロー

1. ベースライン分析

1. 選択されたスコープとオプションで <ruff_cmd> check を実行します。
2. 発見事項をタイプ別に分類します:
   • 自動修正可能（安全）。
   • 自動修正可能（不安全）。
   • 自動修正不可。
3. 発見事項が残っていない場合は停止します。

2. 安全な自動修正パス

1. 同じスコープ/オプションで --fix を使用して Ruff を実行します。
2. 結果の Diff をセマンティック正確さとスタイル一貫性について慎重にレビューします。
3. 同じスコープで <ruff_cmd> format を実行します。
4. <ruff_cmd> check を再実行して、残りの発見事項を更新します。

3. 不安全な自動修正パス

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

1. 同じスコープ/オプションで --fix --unsafe-fixes を使用して Ruff を実行します。
2. 結果の Diff を慎重にレビューし、動作に敏感な編集を優先します。
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> を優先します。
• 自明でない抑制に対しては簡潔な理由コメントを追加します。
• 2 つ以上の有効な結果が存在する場合、常にユーザーにどのオプションを優先するか確認します。

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

次の結果の 1 つになるまでステップ 2 〜 6 を繰り返します:

• <ruff_cmd> check がクリーンを返します。
• 残りの発見事項にはアーキテクチャ/プロダクト決定が必要です。
• 残りの発見事項は文書化された根拠とともに意図的に抑制されます。
• 反復ループが進捗しません。

各ループの反復は次の <ruff_cmd> check の前に <ruff_cmd> format を含める必要があります。

進捗が検出されない場合:

1. ブロックされたルールと影響を受けたファイルを要約します。
2. 有効なオプションとトレードオフを提示します。
3. ユーザーに選択するよう求めます。

品質ゲート

完了を宣言する前に:

• Ruff は選択されたスコープ/オプションに対して予期しない発見事項を返しません。
• すべての自動修正 Diff は正確性についてレビューされます。
• 明示的な正当化なく抑制は追加されません。
• 可能性のある動作影響を持つ unsafe fix はユーザーにハイライトされます。
• Ruff フォーマットは各反復で実行されます。

出力契約

実行終了時に以下を報告します:

• 使用されたスコープと Ruff オプション。
• 実行された反復回数。
• 修正された発見事項の要約。
• 手動修正の一覧。
• 根拠付き抑制の一覧。
• 残りの発見事項（あれば）と必要なユーザー決定。

推奨プロンプト開始句

• "Run ruff-recursive-fix on the whole repo with default config."
• "Run ruff-recursive-fix only on src/models, ignore DOC rules."
• "Run ruff-recursive-fix on tests with select F,E9,I and no unsafe fixes."
• "Run ruff-recursive-fix on src/data and ask me before adding any noqa."