name: quality-fixer description: 自动应用安全的质量修复，包括格式化（Black、isort）、代码检查（Ruff自动修复）和解决格式化工具冲突。当质量检查失败或提交代码前使用。

质量修复应用器

⚠️ 强制要求：首先阅读项目文档

在应用质量修复之前，您必须阅读并理解以下项目文档：

核心项目文档

README.md - 项目概述、功能和入门指南
AI_DOCS/project-context.md - 技术栈、架构、开发工作流
AI_DOCS/code-conventions.md - 代码风格、格式化、最佳实践
AI_DOCS/tdd-workflow.md - TDD流程、测试标准、覆盖率要求

会话上下文（如果可用）

.ai-context/ACTIVE_TASKS.md - 当前任务和优先级
.ai-context/CONVENTIONS.md - 项目特定约定
.ai-context/RECENT_DECISIONS.md - 最近的架构决策
.ai-context/LAST_SESSION_SUMMARY.md - 上一会话摘要

附加AI文档

AI_DOCS/ai-tools.md - 会话管理工作流
AI_DOCS/ai-skills.md - 其他可用专业技能/代理

为什么这很重要

工具配置：了解配置了哪些格式化器和检查器
代码标准：应用符合项目约定的修复
安全规则：知道哪些自动修复是安全的vs需要手动审查
集成：与其他质量工具协调（Black、Ruff、isort）

阅读这些文件后，继续下面的质量修复任务。

概述

自动对Python代码应用安全的质量修复，解决格式化问题、代码检查问题和格式化工具冲突。

何时使用

编写代码后，运行make check之前
当make lint或make format报告可修复问题时
解决Black与Ruff格式化器冲突时
提交代码前确保质量门通过
当您想应用所有安全的自动修复时

此技能修复的内容

✅ 格式化问题

Black代码格式化
isort导入排序
行长度调整
空白字符规范化

✅ 代码检查问题（安全自动修复）

移除未使用的导入
移除未使用的变量（安全时）
F字符串转换
可简化的if语句
列表/字典推导式改进

✅ 类型提示问题（安全情况）

为无返回函数添加-> None
添加明显的类型提示（str、int、bool字面量）
修复存根签名中的省略号

✅ 格式化器冲突

Black与Ruff的分歧
长字符串的消息变量提取
换行调整

使用示例

修复项目中的所有问题

# 运行全面的质量修复
apply quality fixes to the entire project

操作：

运行make format（Black + isort）
运行带--fix标志的Ruff
检查并解决格式化器冲突
报告修复内容

修复特定文件

# 修复单个文件
fix quality issues in src/python_modern_template/validators.py

操作：

格式化特定文件
对该文件应用Ruff修复
验证未引入冲突
显示更改差异

仅解决格式化器冲突

# 专注于冲突
resolve Black and Ruff formatter conflicts

操作：

运行两个格式化器
识别它们存在分歧的行
应用冲突解决策略
验证两者都满意

预览模式（空运行）

# 查看将修复什么而不实际应用
preview quality fixes for src/

操作：

在空运行模式下运行所有检查
显示将更改的内容
应用前请求确认

分步流程

步骤1：运行格式化

# 应用Black格式化
make format

# 这会运行：
# - black src/ tests/
# - isort src/ tests/

修复内容：

代码风格（间距、缩进、引号）
导入组织和分组
行长度合规性（88个字符）

步骤2：应用Ruff自动修复

# 运行带自动修复的Ruff
uv run ruff check --fix src/ tests/

# 安全修复包括：
# - 移除未使用的导入
# - 移除未使用的变量（安全时）
# - F字符串转换
# - 简化表达式

修复内容：

导入清理
代码简化
现代Python惯用法

步骤3：检测格式化器冲突

# 检查Black和Ruff是否一致
make format && make lint

常见冲突：

超过行长度的长字符串字面量
需要换行的复杂表达式
注释放置差异

步骤4：解决冲突

策略1：提取消息变量

# 之前（冲突 - 太长）
logger.error("This is a very long error message that exceeds the line length limit")

# 之后（已解决）
msg = "This is a very long error message that exceeds the line length limit"
logger.error(msg)

策略2：使用括号换行

# 之前（冲突）
result = some_function(arg1, arg2, arg3, arg4, arg5, arg6)

# 之后（已解决）
result = some_function(
    arg1, arg2, arg3, arg4, arg5, arg6
)

策略3：拆分长字符串

# 之前（冲突）
text = "This is a very long string that should be split across multiple lines for readability"

# 之后（已解决）
text = (
    "This is a very long string that should be "
    "split across multiple lines for readability"
)

步骤5：验证修复

# 运行完整质量检查
make check

必须通过：

✅ 格式化（Black + isort）
✅ 代码检查（Ruff + Pylint + mypy）
✅ 测试（pytest）
✅ 安全（Bandit）

冲突解决策略

识别冲突

运行两个工具并比较：

# 应用Black
black src/python_modern_template/module.py

# 检查Ruff
ruff check src/python_modern_template/module.py

# 如果Ruff仍然抱怨格式化，则存在冲突

解决决策树

长字符串字面量 → 提取到变量或跨行拆分
复杂表达式 → 添加括号和换行
长函数调用 → 将参数拆分为多行
注释放置 → 将注释移到行上方
类型注解复杂性 → 拆分为多行并适当缩进

示例：解决长字符串冲突

问题：

# Black这样格式化：
raise ValueError("The email address provided is not valid because it does not contain the required @ symbol")

# Ruff抱怨：E501 行太长（92 > 88）

解决方案：

# 提取消息变量
error_msg = (
    "The email address provided is not valid because it "
    "does not contain the required @ symbol"
)
raise ValueError(error_msg)

# Black和Ruff都满意！

此技能不修复的内容

❌ 复杂逻辑问题

算法问题
业务逻辑错误
设计缺陷

❌ 非明显类型提示

复杂泛型类型
需要领域知识的联合类型
自定义类型别名

❌ 文档字符串内容

会格式化文档字符串
不会编写缺失的文档字符串
不会改进文档字符串质量

❌ 测试失败

仅修复代码风格
不修复失败的测试
不添加缺失的测试

❌ 破坏性更改

仅应用安全的非破坏性修复
不会移除使用的变量
不会改变语义

输出格式

应用修复后，提供报告：

## 已应用的质量修复

**修改的文件：** X
**总更改：** X行

### 格式化修复
- ✅ 对X个文件应用了Black格式化
- ✅ 对X个文件使用isort排序了导入
- ✅ 修复了X行的行长度问题

### 代码检查修复
- ✅ 移除了X个未使用的导入
- ✅ 转换了X个字符串为f-字符串
- ✅ 简化了X个表达式
- ✅ 修复了X个Ruff问题

### 已解决的冲突
- ✅ 提取了X个消息变量
- ✅ 拆分了X个长字符串
- ✅ 重新格式化了X个函数调用

### 质量检查结果
```bash
make check

[显示输出]

更改的文件

src/python_modern_template/module1.py (+12, -8)
src/python_modern_template/module2.py (+5, -3)
tests/test_module.py (+3, -2)

后续步骤

使用git diff审查更改
运行测试确保无破坏性更改：make test
如果满意则提交更改


## 安全功能

### 空运行模式

始终可用于预览：

```bash
# 格式化预览
black --check --diff src/

# Ruff预览
ruff check --fix --diff src/

Git集成

提交前验证更改：

# 查看更改内容
git diff

# 暂存特定更改
git add -p

备份策略

对于大型修复，首先创建提交：

# 提交当前状态
git commit -m "Before quality fixes"

# 应用修复
[quality-fixer运行]

# 审查更改
git diff HEAD~1

# 如果需要撤销
git reset --hard HEAD~1

与项目工具集成

Makefile集成

# 仅格式化
make format

# 仅代码检查（带修复）
make lint

# 完整检查（无自动修复）
make check

预提交集成

添加到.pre-commit-config.yaml：

- repo: local
  hooks:
    - id: quality-fixer
      name: Quality Fixer
      entry: python .claude/skills/quality-fixer/scripts/auto_fix.py
      language: system
      types: [python]

CI集成

使用--check模式在CI中运行：

# CI应该验证，而不是修复
make check

# 如果失败，开发人员运行：
[quality-fixer在本地修复]

高级功能

选择性修复

仅修复特定类型的问题：

# 仅格式化
[quality-fixer] --format-only

# 仅导入清理
[quality-fixer] --imports-only

# 仅冲突
[quality-fixer] --conflicts-only

忽略模式

遵守pyproject.toml中的配置：

[tool.ruff.lint]
ignore = ["E501"]  # 在特定情况下不自动修复行长度

[tool.black]
extend-exclude = '''
/(
  | generated
)/
'''

自定义规则

定义项目特定的修复：

# .claude/skills/quality-fixer/scripts/custom_rules.py

def fix_common_typos(code: str) -> str:
    """修复项目特定的常见错误。"""
    fixes = {
        "recieve": "receive",
        "seperator": "separator",
    }
    for typo, correction in fixes.items():
        code = code.replace(typo, correction)
    return code

最佳实践

提交前运行 - 提交前始终清理代码
审查更改 - 不要盲目接受所有修复，使用git diff
修复后测试 - 运行make test确保无破坏性更改
迭代修复 - 从格式化开始，然后是代码检查，最后是冲突
理解更改 - 从应用的修复中学习以避免未来问题

常见场景

场景1：提交前

# 1. 应用修复
[quality-fixer]

# 2. 审查更改
git diff

# 3. 测试
make test

# 4. 提交
git add .
git commit -m "feat: add new feature"

场景2：代码审查后

# 代码审查者说："修复格式化和代码检查"

# 1. 应用修复
[quality-fixer]

# 2. 验证所有问题已解决
make check

# 3. 推送
git push

场景3：CI失败

# CI报告质量问题

# 1. 拉取最新
git pull

# 2. 应用修复
[quality-fixer]

# 3. 本地验证
make check

# 4. 推送修复
git commit -am "fix: resolve quality issues"
git push

故障排除

“Black和Ruff在修复后仍然冲突”

解决方案： 手动审查冲突行并应用高级策略：

将复杂表达式提取到变量
重构代码以获得更好的格式化
对不可避免的情况谨慎使用# noqa注释

“自动修复破坏了我的测试”

解决方案：

使用git checkout -- <file>恢复
使用git diff审查更改内容
更有选择性地应用修复
报告不安全的修复（不应应用）

“Pylint仍然报告问题”

注意： 此技能仅应用可自动修复的问题。Pylint通常需要手动修复：

未使用的参数 → 使用_前缀或移除
参数过多 → 重构函数
过于复杂 → 简化逻辑

记住

质量修复是工具，不是良好代码的替代品：

从一开始就编写干净的代码
理解格式化器为何要求更改
从应用的修复中学习
不要依赖自动修复处理所有事情

此技能帮助您高效维护代码质量，但良好的编码实践仍然至关重要！