code-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Quality Setup

代码质量工具链设置

When starting or scaffolding any project, set up formatting, linting, import sorting, type checking, and pre-commit hooks before writing application code. This prevents the painful scenario of adding these tools later and facing thousands of lines of formatting changes in a single commit.

在启动或搭建任何项目时，在编写业务代码之前先设置代码格式化、代码检查（Linting）、导入排序、类型检查以及预提交钩子。这可以避免后续再添加这些工具时，单次提交就需要修改数千行格式代码的痛苦场景。

Detect the ecosystem

检测项目生态系统

Determine the project type from existing files or the scaffolding context:

Signal	Ecosystem
`pyproject.toml` , `setup.py` , `requirements.txt` , `.py` files	Python
`package.json` , `tsconfig.json` , `.ts` / `.js` / `.tsx` files	JavaScript/TypeScript
Both present	Monorepo — configure each ecosystem separately

Also check for existing quality tooling configs (

.eslintrc

.prettierrc

biome.json

[tool.black]

[tool.ruff]

pyproject.toml

.pre-commit-config.yaml

lefthook.yml

). If present, preserve them — only migrate to different tools if the user explicitly requests it (see Guardrails).

从现有文件或搭建上下文判断项目类型：

识别信号	所属生态
`pyproject.toml` , `setup.py` , `requirements.txt` , `.py` 文件	Python
`package.json` , `tsconfig.json` , `.ts` / `.js` / `.tsx` 文件	JavaScript/TypeScript
同时存在上述两类文件	单体仓库（Monorepo）—— 分别为每个生态系统配置工具

同时检查是否已有成熟的代码质量工具配置文件（如

.eslintrc

、

.prettierrc

、

biome.json

、

pyproject.toml

中的

[tool.black]

或

[tool.ruff]

、

.pre-commit-config.yaml

、

lefthook.yml

）。如果已存在，请保留这些配置——仅当用户明确要求时，才迁移到其他工具（参见约束规则）。

Set up tooling

配置工具链

After detecting the ecosystem, follow the appropriate guide:

Python projects — see python.md for Ruff + pre-commit setup
JS/TS projects — see javascript.md for Biome + Knip + lefthook + tsc setup

检测完项目生态系统后，按照对应指南操作：

Python 项目——参考 python.md 完成 Ruff + pre-commit 配置
JS/TS 项目——参考 javascript.md 完成 Biome + Knip + lefthook + tsc 配置

Standard command contract

标准命令约定

Every project must expose these five commands (via

package.json

scripts or

Makefile

Command	What it does
`format`	Auto-format and sort imports
`lint`	Lint without writing (report only)
`typecheck`	Run type checker ( `tsc --noEmit` , `mypy` , or `pyright` )
`check`	All non-writing checks: lint + typecheck + unused-code detection
`check:fix`	Run autofixers (format + lint fix), then run `check`

Pre-commit hooks should run

check:fix

so that commits are always clean.

每个项目必须提供以下五个标准命令（通过

package.json

脚本或

Makefile

实现）：

命令	功能说明
`format`	自动格式化代码并排序导入语句
`lint`	执行代码检查（仅报告问题，不修改代码）
`typecheck`	运行类型检查工具（如 `tsc --noEmit` 、 `mypy` 或 `pyright` ）
`check`	执行所有非修改类检查：代码检查 + 类型检查 + 未使用代码检测
`check:fix`	先运行自动修复工具（格式化 + 代码检查修复），再执行 `check` 命令

预提交钩子应配置为运行

check:fix

，确保所有提交的代码都是规范的。

Workflow

实施流程

Install and configure the tools (formatter, linter, type checker)
Add pre-commit hook infrastructure (lefthook or pre-commit)
Run the full suite once to establish a clean baseline
Fix any initial issues so the first "real" commit starts clean
Commit the configuration files as the first or second commit in the project

安装并配置工具（格式化工具、代码检查工具、类型检查工具）
添加预提交钩子基础设施（lefthook 或 pre-commit）
首次运行完整工具链，建立干净的基准线
修复所有初始问题，确保第一个「正式」提交是干净的
将配置文件作为项目的第一个或第二个提交提交到仓库

When working on existing projects

现有项目的处理方式

If a project already has code but no quality tooling:

Add and configure the tools
Run the formatter first — commit the formatting changes in a single dedicated commit with a message like
```
chore: apply initial formatting
```
Run the linter — fix issues and commit separately:
```
chore: fix initial lint issues
```
Wire up pre-commit hooks last so all future commits are clean

如果项目已有代码但未配置代码质量工具：

添加并配置工具链
先运行格式化工具——将格式修改单独提交到一个专属的提交中，提交信息示例：
```
chore: apply initial formatting
```
运行代码检查工具——修复问题并单独提交：
```
chore: fix initial lint issues
```
最后配置预提交钩子，确保后续所有提交的代码都是规范的

Guardrails

约束规则

Don't replace existing mature tooling. If a project already uses ESLint/Prettier, Black, or other established tools, keep them. Only migrate to Biome/Ruff if the user explicitly asks.
Don't broadly disable rules to force a green baseline. Use narrow, targeted exceptions (
```
// biome-ignore
```
,
```
# noqa: XX
```
) with comments explaining why — never bulk-suppress to make errors disappear.
If tooling binaries aren't available, scaffold configs anyway. Write the configuration files and report the install commands the user needs to run.

不要替换已有的成熟工具。如果项目已使用 ESLint/Prettier、Black 或其他成熟工具，请保留它们。仅当用户明确要求时，才迁移到 Biome/Ruff。
不要为了快速通过检查而大范围禁用规则。使用精准、针对性的例外声明（如
```
// biome-ignore
```
、
```
# noqa: XX
```
）并附上注释说明原因——绝不批量禁用规则来掩盖错误。
如果工具二进制文件不可用，仍需生成配置文件。编写好配置文件，并告知用户需要执行的安装命令。

Completion checklist

完成校验清单

Before considering the setup done, verify:

Formatter, linter, and type checker installed and configured for the project's ecosystem
Import sorting enabled (Ruff's
```
I
```
rules or Biome's
```
organizeImports
```
)
All five standard commands work:
```
format
```
,
```
lint
```
,
```
typecheck
```
,
```
check
```
,
```
check:fix
```

Pre-commit hooks configured and executable (

pre-commit run --all-files

npx lefthook run pre-commit

)

Baseline autofix applied and a clean check passes with no errors

在确认设置完成前，请验证以下内容：

已为项目生态系统安装并配置好格式化工具、代码检查工具和类型检查工具
已启用导入排序功能（Ruff 的
```
I
```
规则或 Biome 的
```
organizeImports
```
）
五个标准命令均可正常运行：
```
format
```
、
```
lint
```
、
```
typecheck
```
、
```
check
```
、
```
check:fix
```

预提交钩子已配置且可执行（如

pre-commit run --all-files

或

npx lefthook run pre-commit

）

已应用基准自动修复，且干净的检查无任何错误通过