ruff-recursive-fix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ruff Recursive Fix

Ruff递归修复

Overview

概述

Use this skill to enforce code quality with Ruff in a controlled, iterative workflow. It supports:

Optional scope limitation to a specific folder.
Default project settings from
```
pyproject.toml
```
.
Flexible Ruff invocation (
```
uv
```
, direct
```
ruff
```
,
```
python -m ruff
```
, or equivalent).

Optional per-run rule overrides (

--select

--ignore

--extend-select

--extend-ignore

Automatic safe then unsafe autofixes.
Diff review after each fix pass.
Recursive repetition until findings are resolved or require a decision.
Judicious use of inline
```
# noqa
```
only when suppression is justified.

使用此技能通过可控的迭代工作流用Ruff保障代码质量。它支持以下能力：

可选限制为指定文件夹范围
读取
```
pyproject.toml
```
中的默认项目配置
灵活的Ruff调用方式（
```
uv
```
、直接调用
```
ruff
```
、
```
python -m ruff
```
或等价方式）
可选单次运行的规则覆盖（
```
--select
```
、
```
--ignore
```
、
```
--extend-select
```
、
```
--extend-ignore
```
）
先自动应用安全修复，再应用不安全修复
每轮修复后查看差异
递归重复流程直到问题解决或需要人工决策
仅当有合理的屏蔽理由时才谨慎使用行内
```
# noqa
```

Inputs

输入

Collect these inputs before running:

```
target_path
```
(optional): folder or file to check. Empty means whole repository.
```
ruff_runner
```
(optional): explicit Ruff command prefix (for example
```
uv run
```
,
```
ruff
```
,
```
python -m ruff
```
,
```
pipx run ruff
```
).
```
rules_select
```
(optional): comma-separated rule codes to enforce.
```
rules_ignore
```
(optional): comma-separated rule codes to ignore.
```
extend_select
```
(optional): extra rules to add without replacing configured defaults.
```
extend_ignore
```
(optional): extra ignored rules without replacing configured defaults.
```
allow_unsafe_fixes
```
(default: true): whether to run Ruff unsafe fixes.
```
ask_on_ambiguity
```
(default: true): always ask the user when multiple valid choices exist.

运行前收集以下输入：

```
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）：存在多个有效选择时始终询问用户

Command Construction

命令构建

Build Ruff commands from inputs.

根据输入构建Ruff命令。

0. Resolve Ruff Runner

0. 确定Ruff运行器

Determine a reusable

ruff_cmd

prefix before building commands.

Resolution order:

If
```
ruff_runner
```
is provided, use it as-is.
Else if
```
uv
```
is available and Ruff is managed through
```
uv
```
, use
```
uv run ruff
```
.
Else if
```
ruff
```
is available on
```
PATH
```
, use
```
ruff
```
.
Else if Python is available and Ruff is installed in that environment, use
```
python -m ruff
```
.
Else use any project-specific equivalent that invokes installed Ruff (for example
```
pipx run ruff
```
), or stop and ask the user.

Use the same resolved

ruff_cmd

for all

check

and

format

commands in the workflow.

Base command:

bash

<ruff_cmd> check

Formatter command:

bash

<ruff_cmd> format

With optional target:

bash

<ruff_cmd> format <target_path>

Add optional target:

bash

<ruff_cmd> check <target_path>

Add optional overrides as needed:

bash

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

Examples:

bash

undefined

在构建命令前确定可复用的

ruff_cmd

前缀。

解析顺序：

如果提供了
```
ruff_runner
```
，直接使用
否则如果有可用的
```
uv
```
且Ruff通过
```
uv
```
管理，使用
```
uv run ruff
```
否则如果
```
PATH
```
中存在
```
ruff
```
，使用
```
ruff
```
否则如果有可用的Python且对应环境中安装了Ruff，使用
```
python -m ruff
```
否则使用任何项目特有的等价调用已安装Ruff的方式（例如
```
pipx run ruff
```
），或停止流程询问用户

工作流中所有

check

和

format

命令都使用同一个解析得到的

ruff_cmd

。

基础命令：

bash

<ruff_cmd> check

格式化命令：

bash

<ruff_cmd> format

带可选目标路径的格式化命令：

bash

<ruff_cmd> format <target_path>

添加可选目标路径的检查命令：

bash

<ruff_cmd> check <target_path>

按需添加可选规则覆盖参数：

bash

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

示例：

bash

undefined

Full project with defaults from pyproject.toml

使用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

本次运行跳过文档和类TODO规则

uv run ruff check src --extend-ignore D,TD

Check only selected rules in a folder

仅检查指定文件夹下的选定规则

ruff check src/data --select F,E9,I

undefined

ruff check src/data --select F,E9,I

undefined

Workflow

工作流

1. Baseline Analysis

1. 基线分析

Run
```
<ruff_cmd> check
```
with the selected scope and options.
Classify findings by type:
- Autofixable safe.
- Autofixable unsafe.
- Not autofixable.
If no findings remain, stop.

使用选定的范围和选项运行
```
<ruff_cmd> check
```
按类型分类问题：
- 可自动修复的安全问题
- 可自动修复的不安全问题
- 不可自动修复的问题
如果没有剩余问题，停止流程

2. Safe Autofix Pass

2. 安全自动修复轮次

Run Ruff with
```
--fix
```
using the same scope/options.
Review resulting diff carefully for semantic correctness and style consistency.
Run
```
<ruff_cmd> format
```
on the same scope.
Re-run
```
<ruff_cmd> check
```
to refresh remaining findings.

使用相同的范围/选项运行带
```
--fix
```
参数的Ruff
仔细审查生成的差异，确保语义正确和风格一致
在相同范围运行
```
<ruff_cmd> format
```
重新运行
```
<ruff_cmd> check
```
刷新剩余问题列表

3. Unsafe Autofix Pass

3. 不安全自动修复轮次

Run only if findings remain and

allow_unsafe_fixes=true

Run Ruff with
```
--fix --unsafe-fixes
```
using the same scope/options.
Review resulting diff carefully, prioritizing behavior-sensitive edits.
Run
```
<ruff_cmd> format
```
on the same scope.
Re-run
```
<ruff_cmd> check
```
.

仅当仍有剩余问题且

allow_unsafe_fixes=true

时运行。

使用相同的范围/选项运行带
```
--fix --unsafe-fixes
```
参数的Ruff
仔细审查生成的差异，优先关注影响行为的编辑
在相同范围运行
```
<ruff_cmd> format
```
重新运行
```
<ruff_cmd> check
```
刷新剩余问题列表

4. Manual Remediation Pass

4. 人工修复轮次

For remaining findings:

Fix directly in code when there is a clear, safe correction.
Keep edits minimal and local.
Run
```
<ruff_cmd> format
```
on the same scope.
Re-run
```
<ruff_cmd> check
```
.

针对剩余问题：

当有清晰安全的修正方案时直接在代码中修复
保持编辑最小化且局部化
在相同范围运行
```
<ruff_cmd> format
```
重新运行
```
<ruff_cmd> check
```
刷新剩余问题列表

5. Ambiguity Policy

5. 歧义处理策略

If there are multiple valid solutions at any step, always ask the user before proceeding. Do not choose silently between equivalent options.

任何步骤存在多个有效解决方案时，继续前必须询问用户，不要在等价选项间静默选择。

6. Suppression Decision (

# noqa

)

6. 屏蔽决策（

# noqa

）

Use suppression only when all conditions are true:

The rule conflicts with required behavior, public API, framework conventions, or readability goals.
Refactoring would be disproportionate to the value of the rule.
The suppression is narrow and specific (single line, explicit code when possible).

Guidelines:

Prefer
```
# noqa: <RULE>
```
over broad
```
# noqa
```
.
Add a brief reason comment for non-obvious suppressions.
If two or more valid outcomes exist, always ask the user which option to prefer.

仅当所有条件都满足时才使用规则屏蔽：

规则与所需行为、公共API、框架约定或可读性目标冲突
重构的成本远高于遵守规则带来的价值
屏蔽范围窄且明确（尽可能是单行、显式指定规则码）

使用准则：

优先使用
```
# noqa: <RULE>
```
而非宽泛的
```
# noqa
```
对于不明显的屏蔽添加简短的理由注释
如果存在两个及以上有效结果，询问用户偏好哪个选项

7. Recursive Loop and Stop Criteria

7. 递归循环和停止条件

Repeat steps 2 to 6 until one of these outcomes:

```
<ruff_cmd> check
```
returns clean.
Remaining findings require architectural/product decisions.
Remaining findings are intentionally suppressed with documented rationale.
Repeated loop makes no progress.

Each loop iteration must include

<ruff_cmd> format

before the next

<ruff_cmd> check

When no progress is detected:

Summarize blocked rules and affected files.
Present valid options and trade-offs.
Ask the user to choose.

重复步骤2到6直到出现以下任一结果：

```
<ruff_cmd> check
```
返回无问题
剩余问题需要架构/产品决策
剩余问题已通过有文档说明的理由主动屏蔽
重复循环无进展

每次循环迭代在下次

<ruff_cmd> check

前必须执行

<ruff_cmd> format

。

当检测到无进展时：

汇总阻塞的规则和受影响的文件
展示有效选项和权衡
请用户选择

Quality Gates

质量门禁

Before declaring completion:

Ruff returns no unexpected findings for the chosen scope/options.
All autofix diffs are reviewed for correctness.
No suppression is added without explicit justification.
Any unsafe fix with possible behavioral impact is highlighted to the user.
Ruff formatting is executed in every iteration.

在宣布完成前：

Ruff对选定的范围/选项没有返回意外问题
所有自动修复的差异都已审查确认正确性
没有无明确理由的屏蔽添加
任何可能影响行为的不安全修复都已向用户高亮说明
每次迭代都执行了Ruff格式化

Output Contract

输出约定

At the end of execution, report:

Scope and Ruff options used.
Number of iterations performed.
Summary of fixed findings.
List of manual fixes.
List of suppressions with rationale.
Remaining findings, if any, and required user decisions.

执行结束后，报告以下内容：

使用的范围和Ruff选项
执行的迭代次数
已修复问题的汇总
手动修复列表
带理由的屏蔽列表
剩余问题（如果有）及所需的用户决策

Suggested Prompt Starters

建议的Prompt示例

"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."

"对整个仓库使用默认配置运行ruff-recursive-fix。"
"仅对src/models运行ruff-recursive-fix，忽略DOC规则。"
"对测试用例运行ruff-recursive-fix，选择F、E9、I规则，不使用不安全修复。"
"对src/data运行ruff-recursive-fix，添加任何noqa前先询问我。"

ruff-recursive-fix

Original

Translation

Ruff Recursive Fix

Ruff递归修复

Overview

概述

Inputs

输入

Command Construction

命令构建

0. Resolve Ruff Runner

0. 确定Ruff运行器

Full project with defaults from pyproject.toml

使用pyproject.toml默认配置检查整个项目

One folder with defaults

使用默认配置检查单个文件夹

Override to skip docs and TODO-like rules for this run

本次运行跳过文档和类TODO规则

Check only selected rules in a folder

仅检查指定文件夹下的选定规则

Workflow

工作流

1. Baseline Analysis

1. 基线分析

2. Safe Autofix Pass

2. 安全自动修复轮次

3. Unsafe Autofix Pass

3. 不安全自动修复轮次

4. Manual Remediation Pass

4. 人工修复轮次

5. Ambiguity Policy

5. 歧义处理策略

6. Suppression Decision (# noqa)

6. 屏蔽决策（# noqa）

7. Recursive Loop and Stop Criteria

7. 递归循环和停止条件

Quality Gates

质量门禁

Output Contract

输出约定

Suggested Prompt Starters

建议的Prompt示例

6. Suppression Decision (
`# noqa`
)

6. 屏蔽决策（
`# noqa`
）