code-linting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Linting Skill

代码检查技能

Unified linting workflow for Python (ruff) and JavaScript (Biome).

Python（ruff）与JavaScript（Biome）的统一代码检查工作流。

Operator Context

操作上下文

This skill operates as an operator for code quality enforcement, configuring Claude's behavior for consistent linting and formatting across Python and JavaScript codebases.

本技能作为代码质量管控的操作工具，配置Claude的行为，以实现Python和JavaScript代码库间一致的代码检查与格式化。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md files before execution. Project-specific linting rules override defaults.
Over-Engineering Prevention: Only run requested linters and fixes. Don't add custom rules, configuration changes, or additional tooling without explicit request.
Show complete linter output: NEVER summarize as "no issues found" - display actual command output
Run both Python and JS linting: When project has both languages, lint both (unless user specifies otherwise)
Use project-specific configs: Always use pyproject.toml/biome.json settings, never override
Preserve line width settings: Respect the line width configured in project tools

CLAUDE.md 合规性：执行前读取并遵循仓库中的CLAUDE.md文件。项目特定的代码检查规则优先级高于默认规则。
避免过度设计：仅运行请求的代码检查工具与修复操作。未经明确请求，不得添加自定义规则、修改配置或引入额外工具。
显示完整的代码检查工具输出：绝对不要总结为「未发现问题」——必须显示实际的命令输出
同时运行Python与JS代码检查：若项目包含两种语言，则同时检查（除非用户明确指定）
使用项目特定配置：始终使用pyproject.toml/biome.json中的设置，绝不覆盖
保留行宽设置：遵循项目工具中配置的行宽要求

Default Behaviors (ON unless disabled)

默认行为（启用状态，除非手动禁用）

Communication Style: Report facts without self-congratulation. Show command output rather than describing it. Be concise but informative.
Temporary File Cleanup: Remove any temporary lint report files or cache files created during execution at task completion.
Auto-fix safe issues: Apply
```
--fix
```
flag for formatting and import ordering issues
Check before commit: Verify code passes linting before suggesting commit
Report all categories: Show errors, warnings, and style issues together
Suggest manual fixes: For issues that can't be auto-fixed, explain how to resolve

沟通风格：仅报告事实，不添加自我夸赞内容。直接显示命令输出，而非描述输出内容。简洁且信息完整。
临时文件清理：任务完成后，删除执行过程中创建的所有临时检查报告文件或缓存文件
自动修复安全问题：对格式化与导入排序问题使用
```
--fix
```
参数
提交前检查：在建议提交前，验证代码是否通过检查
报告所有类别：同时显示错误、警告与风格问题
建议手动修复：对于无法自动修复的问题，说明解决方法

Optional Behaviors (OFF unless enabled)

可选行为（禁用状态，除非手动启用）

Strict mode: Treat warnings as errors (fail on any issue)
Single language only: Lint only Python or only JavaScript when requested
Format only: Skip linting, only run formatting
Ignore specific rules: Disable particular lint rules for edge cases

严格模式：将警告视为错误（存在任何问题即判定失败）
仅单语言检查：根据请求仅检查Python或JavaScript
仅格式化：跳过代码检查，仅运行格式化操作
忽略特定规则：在特殊场景下禁用特定的代码检查规则

What This Skill CAN Do

本技能可执行的操作

Run ruff check/format for Python codebases
Run Biome check/format for JavaScript/TypeScript codebases
Auto-fix safe issues (import ordering, formatting)
Show complete linter output for review
Use project-specific configurations (pyproject.toml, biome.json)

为Python代码库运行ruff检查/格式化
为JavaScript/TypeScript代码库运行Biome检查/格式化
自动修复安全问题（导入排序、格式化）
显示完整的代码检查工具输出以供评审
使用项目特定配置（pyproject.toml、biome.json）

What This Skill CANNOT Do

本技能不可执行的操作

Override project linter configurations without explicit request
Summarize linter output (must show full command output)
Run linters for languages other than Python and JavaScript/TypeScript
Fix complex logic issues (only style/formatting/import issues)
Skip reading linter output before applying auto-fixes

未经明确请求，不得覆盖项目的代码检查工具配置
不得总结代码检查工具输出（必须显示完整的命令输出）
不得为Python与JavaScript/TypeScript之外的语言运行代码检查工具
无法修复复杂逻辑问题（仅支持风格/格式化/导入问题）
在应用自动修复前，不得跳过读取代码检查工具输出的步骤

Error Handling

错误处理

Error: "ruff not found"

错误：「ruff not found」

Cause: Virtual environment not activated or ruff not installed Solution:

Use virtual environment path:
```
./venv/bin/ruff
```
or
```
./env/bin/ruff
```
Or install globally:
```
pip install ruff
```
Or use pipx:
```
pipx run ruff check .
```

原因：虚拟环境未激活或ruff未安装 解决方案：

使用虚拟环境路径：
```
./venv/bin/ruff
```
或
```
./env/bin/ruff
```
或全局安装：
```
pip install ruff
```
或使用pipx：
```
pipx run ruff check .
```

Error: "biome not found"

错误：「biome not found」

Cause: Biome not installed in project Solution: Run

npx @biomejs/biome

to use npx-based execution

原因：项目中未安装Biome 解决方案：运行

npx @biomejs/biome

使用基于npx的执行方式

Error: "Configuration file not found"

错误：「Configuration file not found」

Cause: Running from wrong directory Solution: cd to project root where pyproject.toml/biome.json exist

原因：从错误目录执行命令 解决方案：切换到包含pyproject.toml/biome.json的项目根目录

Quick Reference

快速参考

Python (ruff)

Python（ruff）

bash

undefined

bash

undefined

Navigate to your project

导航到你的项目

cd /path/to/your/project

Check for issues (use project's venv if available)

检查问题（如有可用的项目venv则使用）

ruff check .

or with virtual env: ./venv/bin/ruff check .

或使用虚拟环境：./venv/bin/ruff check .

Auto-fix issues

自动修复问题

ruff check --fix .

Format code

格式化代码

ruff format .

Check formatting only (no changes)

仅检查格式化（不修改代码）

ruff format --check .

undefined

ruff format --check .

undefined

JavaScript (Biome)

JavaScript（Biome）

bash

undefined

bash

undefined

Navigate to your project

导航到你的项目

cd /path/to/your/project

Check for issues

检查问题

npx @biomejs/biome check src/

Auto-fix issues

自动修复问题

npx @biomejs/biome check --write src/

Format only

仅格式化

npx @biomejs/biome format --write src/

undefined

npx @biomejs/biome format --write src/

undefined

Combined Commands (if Makefile configured)

组合命令（若配置了Makefile）

bash

make lint       # Check both Python and JS
make lint-fix   # Fix both Python and JS

bash

make lint       # 检查Python与JS
make lint-fix   # 修复Python与JS的问题

Configuration Files

配置文件

Tool	Config	Typical Line Width
ruff	pyproject.toml	88-120
biome	biome.json	80-120

工具	配置文件	典型行宽
ruff	pyproject.toml	88-120
biome	biome.json	80-120

Common Fixes

常见修复

Python

Unused import (F401): Remove or use the import
Import order (I001): Run
```
ruff check --fix
```
Line too long (E501): Break into multiple lines or adjust line-length config

未使用的导入（F401）：移除或使用该导入
导入顺序（I001）：运行
```
ruff check --fix
```
行过长（E501）：拆分为多行或调整行宽配置

JavaScript

noVar: Replace
```
var
```
with
```
let
```
/
```
const
```
useConst: Use
```
const
```
for unchanging values
noDoubleEquals: Use
```
===
```
instead of
```
==
```

noVar：将
```
var
```
替换为
```
let
```
/
```
const
```
useConst：对不变的值使用
```
const
```
noDoubleEquals：使用
```
===
```
替代
```
==
```

Anti-Patterns

反模式

Anti-Pattern 1: Running Linter Without Reading Output

反模式1：未读取输出就运行代码检查工具

What it looks like:

bash

$ ruff check .
$ # Immediately running --fix without reviewing issues
$ ruff check --fix .

Why it's wrong:

May auto-fix issues that need manual review
Misses understanding of what violations exist
Can introduce unintended changes (e.g., removing imports still needed)

Do this instead:

Read the complete linter output first
Understand what violations exist and their severity
Decide which fixes are safe to automate
Apply targeted fixes or manual corrections

表现：

bash

$ ruff check .
$ # 未查看问题就立即运行--fix
$ ruff check --fix .

问题所在：

可能会自动修复需要手动评审的问题
无法了解存在哪些违规情况
可能引入意外变更（例如移除仍需要的导入）

正确做法：

先读取完整的代码检查工具输出
了解存在哪些违规情况及其严重程度
决定哪些修复可以安全地自动化
应用针对性修复或手动修正

Anti-Pattern 2: Applying Auto-Fixes Blindly

反模式2：盲目应用自动修复

What it looks like:

bash

$ ruff check --fix .

表现：

bash

$ ruff check --fix .

All files changed

所有文件都被修改

$ git add . && git commit -m "lint fixes"

Didn't review what changed

未查看修改内容


**Why it's wrong:**
- Auto-fixes might remove imports you still need
- Could reformat code in ways that reduce readability for specific cases
- May introduce subtle bugs (e.g., changing variable shadowing)

**Do this instead:**
1. Run `ruff check --fix .`
2. Review the diff: `git diff`
3. Verify changes are correct and safe
4. Revert any problematic auto-fixes
5. Then commit with understanding of what changed


**问题所在**：
- 自动修复可能会移除你仍需要的导入
- 可能会以降低特定场景下可读性的方式重新格式化代码
- 可能引入细微的bug（例如改变变量遮蔽情况）

**正确做法**：
1. 运行 `ruff check --fix .`
2. 查看差异：`git diff`
3. 验证修改是否正确且安全
4. 撤销任何有问题的自动修复
5. 确认修改内容后再提交

Anti-Pattern 3: Summarizing Linter Output

反模式3：总结代码检查工具输出

What it looks like:

User: "Lint the code"
Assistant: "I ran the linter and found 3 issues. All fixed!"

Why it's wrong:

User can't see what violations existed
Can't verify fixes were appropriate
Hides important details about code quality

Do this instead: Show complete command output:

bash

$ ruff check .
src/main.py:10:1: F401 [*] `os` imported but unused
src/utils.py:25:80: E501 Line too long (95 > 88 characters)
Found 2 errors.
[*] 1 fixable with the --fix flag

$ ruff check --fix .
Fixed 1 error:
src/main.py:10:1: F401 Removed unused import `os`

表现：

用户：「检查代码」
助手：「我运行了代码检查工具，发现3个问题。已全部修复！」

问题所在：

用户无法看到具体存在哪些违规情况
无法验证修复是否合适
隐藏了关于代码质量的重要细节

正确做法：显示完整的命令输出：

bash

$ ruff check .
src/main.py:10:1: F401 [*] `os` imported but unused
src/utils.py:25:80: E501 Line too long (95 > 88 characters)
Found 2 errors.
[*] 1 fixable with the --fix flag

$ ruff check --fix .
Fixed 1 error:
src/main.py:10:1: F401 Removed unused import `os`

Workflow

工作流

Run linter to check:

ruff check .

npx @biomejs/biome check src/

Review the complete output to understand violations
Auto-fix what's safe:
```
ruff check --fix .
```
Review the diff to verify auto-fixes are correct
Format code:
```
ruff format .
```
Review remaining issues and fix manually
Commit and push
Check CI/GitHub Actions

运行代码检查工具：

ruff check .

npx @biomejs/biome check src/

查看完整输出以了解违规情况
自动修复安全的问题：
```
ruff check --fix .
```
查看差异以验证自动修复是否正确
格式化代码：
```
ruff format .
```
查看剩余问题并手动修复
提交并推送
检查CI/GitHub Actions

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks

本技能使用以下共享模式：

反合理化 - 防止寻找捷径的合理化行为
验证清单 - 完成前的检查