code-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apply a small set of type-driven quality techniques when writing or refactoring code. Each technique has its own reference — the principle, a real before/after from this repo, and the smells to grep for. Read the reference(s) that match the code in front of you; don't apply all five blindly.

在编写或重构代码时，应用一套小型的类型驱动质量提升技术。每种技术都有对应的参考文档——包含核心原则、本仓库中的真实前后对比示例，以及需要排查的代码异味。请阅读与当前代码匹配的参考文档，不要盲目套用全部五种技术。

When this fires

触发场景

A request to refactor / clean up / improve / harden / tighten code or an API — or when you're about to write a new module/type/public export and want it right the first time. Not a bug hunt (use

/code-review

当需要对代码或API进行_重构/清理/优化/强化/精简_时，或者在编写新模块/类型/公共导出并希望一步到位保证质量时。不适用于漏洞排查（请使用/code-review）。

The techniques — read the matching reference

技术方案——阅读匹配的参考文档

Smell in front of you	Technique	Reference
a magic `0` / `""` / `-1` ; the same primitive re-validated at many sites; `"x" in obj` repeated	Parse, don't validate	`references/parse-dont-validate.md`
a field that's always `""` ; boolean-flag soup; a sentinel standing in for "absent"; an impossible combo that still compiles	Make illegal states irrepresentable	`references/make-illegal-states-irrepresentable.md`
a `switch` / `if` -chain on a union with no exhaustiveness guard	Exhaustive matching	`references/exhaustive-matching.md`
logic tangled with IO ( `spawn` / `fetch` / `fs` ); a function that's hard to test	Pure functions + injected seams	`references/pure-functions.md`
a public export with a fuzzy shape; a `string` that means an enum; a leaked internal helper	Public-API quality	`references/public-api-quality.md`

你遇到的代码异味	对应技术	参考文档
魔法值 `0` / `""` / `-1` ；同一原始类型在多处重复验证；重复使用 `"x" in obj` 判断	Parse, don't validate（解析而非验证）	`references/parse-dont-validate.md`
始终为空字符串的字段；布尔标志堆砌；用标记值表示“不存在”；仍能编译的非法组合	Make illegal states irrepresentable（使非法状态无法表示）	`references/make-illegal-states-irrepresentable.md`
针对联合类型的 `switch` / `if` 判断链未添加穷尽性检查	Exhaustive matching（穷尽匹配）	`references/exhaustive-matching.md`
逻辑与IO操作（ `spawn` / `fetch` / `fs` ）耦合；难以测试的函数	纯函数+注入式隔离	`references/pure-functions.md`
形状模糊的公共导出；用作枚举的 `string` 类型；泄露的内部辅助函数	Public-API quality（公共API质量）	`references/public-api-quality.md`

How to apply

应用步骤

Name the decision out loud before you change the shape — what illegal state it forbids, where the parse boundary sits (the
```
surface-architecture-decisions
```
reflex). A quality change the reviewer can't see is churn.
One technique at a time, tests stay green. Change the type, let
```
tsc
```
show you every call site, fix them, run the tests. Never batch five refactors into one unreviewable diff.
Don't over-abstract (rule-of-three / YAGNI). A tagged union for 3 real variants is good; an abstraction for a difference that doesn't exist yet is the bug this skill is supposed to prevent.
Prefer the strongest option the DECIDABILITY allows — a type that can't express the bad state beats a runtime check that hopes to catch it; but a runtime guard at a boundary beats nothing when the input is genuinely dynamic.

明确说明决策内容：在修改代码结构前，清晰阐述该决策的目的——比如禁止了哪种非法状态，解析边界位于何处（遵循
```
surface-architecture-decisions
```
准则）。如果评审者无法理解质量提升的意图，修改就变成了无意义的变动。
一次应用一种技术，保持测试通过：修改类型定义，让
```
tsc
```
指出所有调用位置，逐一修复后运行测试。切勿将五种重构操作批量处理成一个难以评审的差异提交。
避免过度抽象（遵循三次原则/YAGNI准则）：为3个真实存在的变体使用标签联合类型是合理的；但为尚未出现的差异提前构建抽象，恰恰是本技能旨在预防的问题。
在可判定范围内优先选择最严格的方案：无法表达错误状态的类型优于依赖运行时检查来捕获问题的方案；但当输入确实是动态的时，在边界处添加运行时防护总比没有好。

Guardrails

约束规则

Quality only, not correctness. This skill improves shape/design; it does not hunt for bugs — that's
```
/code-review
```
.
Every change removes a real failure mode. If you can't name the bug the new shape prevents, don't make the change.
Keep the public surface small. A new
```
export
```
is a contract (see the public-API reference); don't widen it to make a refactor convenient.

仅关注质量，不涉及正确性：本技能仅优化代码结构与设计，不负责漏洞排查——该场景请使用/code-review。
每一处修改都要消除真实的失效模式：如果你无法说明新结构能预防的具体问题，就不要进行修改。
保持公共接口简洁：新的
```
export
```
意味着一份契约（请参考公共API质量的相关文档）；不要为了方便重构而随意扩大公共接口范围。",