typescript-clean-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clean Code

Principles, practices, and workflows for TypeScript developers.

面向TypeScript开发者的原则、实践与工作流。

Critical: Reference-First Approach

关键：参考优先原则

Always load and consult the reference files before applying any principle or making any recommendation. The references in this skill contain curated, authoritative knowledge from Robert C. Martin's books, adapted for TypeScript. When this skill is active:

Read references before responding - For any code quality or professional practice topic, load the relevant
```
rules.md
```
and
```
examples.md
```
files from
```
references/
```
before giving advice or writing code. Do not rely on general knowledge alone.
Reference content overrides internal knowledge - If your general knowledge conflicts with what the reference files state, follow the reference files. They contain the specific rules, thresholds, and patterns this skill enforces.
Cite specific rules - When making recommendations, reference the specific rule (e.g., "per
```
references/functions/rules.md
```
Rule 1: Keep Functions Small, 2-5 lines ideal") so the user can trace the guidance back to its source.
Use examples from reference files - Prefer the bad/good code examples in
```
references/[topic]/examples.md
```
over generating your own. These examples are curated for TypeScript and demonstrate the exact patterns intended.
Follow workflows step-by-step - When executing a task (review, refactoring, TDD, etc.), load the corresponding workflow file and follow each step, loading the reference files each step points to.

Do not skip loading references. Even if you "know" Clean Code principles, the reference files contain specific TypeScript adaptations, thresholds, checklists, and smell catalogs that your general knowledge may not match exactly.

在应用任何原则或给出任何建议前，请务必加载并参考参考文件。 此技能中的参考内容源自Robert C. Martin的书籍，专为TypeScript适配。当启用此技能时：

先阅读参考再回复 - 针对任何代码质量或专业实践相关主题，在提供建议或编写代码前，从
```
references/
```
目录加载对应的
```
rules.md
```
和
```
examples.md
```
文件。不要仅依赖通用知识。
参考内容优先于内部知识 - 如果你的通用知识与参考文件内容冲突，请遵循参考文件。它们包含此技能所强制执行的具体规则、阈值和模式。
引用具体规则 - 给出建议时，请引用具体规则（例如：“根据
```
references/functions/rules.md
```
规则1：保持函数精简，理想长度为2-5行”），以便用户可以追溯指导内容的来源。
使用参考文件中的示例 - 优先使用
```
references/[topic]/examples.md
```
中的错误/正确代码示例，而非自行生成。这些示例是专为TypeScript整理的，展示了预期的精确模式。
逐步遵循工作流 - 执行任务（评审、重构、TDD等）时，加载对应的工作流文件并遵循每个步骤，加载各步骤指向的参考文件。

请勿跳过加载参考文件的步骤。 即使你“了解”Clean Code原则，参考文件中包含了针对TypeScript的特定适配、阈值、检查清单和代码坏味道目录，这些内容可能与你的通用知识不完全匹配。

Quick Start

快速开始

For a task: Check
```
guidelines.md
```
→ find the right workflow → load it → follow each step (loading referenced files)
For reference: Load the specific
```
rules.md
```
and
```
examples.md
```
files relevant to your work → apply them
Follow the workflow: Step-by-step process for consistent results — always load the files each step references

针对任务：查看
```
guidelines.md
```
→ 找到合适的工作流 → 加载它 → 逐步遵循（加载参考文件）
针对参考：加载与当前工作相关的特定
```
rules.md
```
和
```
examples.md
```
文件 → 应用它们
遵循工作流：分步流程确保结果一致 — 务必加载每个步骤指向的文件

Workflows

工作流

Step-by-step processes for common tasks:

Workflow	When to Use
`workflows/code-review/workflow.md`	Reviewing code for quality
`workflows/pr-review/workflow.md`	Reviewing pull requests
`workflows/tdd.md`	Test-driven development cycle
`workflows/refactoring/workflow.md`	Safe refactoring with tests
`workflows/new-feature.md`	Building new functionality
`workflows/bug-fix.md`	Fixing bugs properly
`workflows/test-strategy.md`	Planning test coverage
`workflows/estimation.md`	Estimating tasks (PERT)
`workflows/deadline-negotiation.md`	Handling unrealistic deadlines

针对常见任务的分步流程：

工作流	适用场景
`workflows/code-review/workflow.md`	评审代码质量
`workflows/pr-review/workflow.md`	评审拉取请求
`workflows/tdd.md`	测试驱动开发周期
`workflows/refactoring/workflow.md`	带测试的安全重构
`workflows/new-feature.md`	构建新功能
`workflows/bug-fix.md`	正确修复Bug
`workflows/test-strategy.md`	规划测试覆盖率
`workflows/estimation.md`	估算任务（PERT法）
`workflows/deadline-negotiation.md`	处理不切实际的截止日期

Step-File Architecture (Code Review, PR Review, Refactoring)

步骤文件架构（代码评审、PR评审、重构）

The code review, PR review, and refactoring workflows use a step-file architecture for context-safe execution:

Each workflow has a
```
workflow.md
```
entry point that describes steps and loads
```
steps/step-01-init.md
```
Each step is a separate file in
```
steps/
```
, loaded sequentially
Progress is tracked via
```
stepsCompleted
```
array in the output document's YAML frontmatter
If context is compacted mid-workflow,
```
step-01-init.md
```
detects the existing output and
```
step-01b-continue.md
```
resumes from the last completed step
Each step loads specific reference files before analysis and cites rules in findings
The refactoring workflow includes a loop (steps 4-7) for iterative change-test-commit cycles

代码评审、PR评审和重构工作流采用步骤文件架构以确保上下文安全执行：

每个工作流都有一个
```
workflow.md
```
入口文件，描述步骤并加载
```
steps/step-01-init.md
```
每个步骤是
```
steps/
```
目录中的独立文件，按顺序加载
进度通过输出文档YAML前置元数据中的
```
stepsCompleted
```
数组跟踪
如果工作流中途压缩上下文，
```
step-01-init.md
```
会检测现有输出，
```
step-01b-continue.md
```
会从最后完成的步骤恢复
每个步骤在分析前加载特定参考文件，并在结论中引用规则
重构工作流包含循环（步骤4-7），用于迭代的变更-测试-提交周期

Reference Categories

参考分类

Part 1: Code Quality (Clean Code book)

第一部分：代码质量（《Clean Code》书籍）

Category	Files	Purpose
naming	3	Variable, function, class naming
functions	4	Function design and review
classes	3	Class/module design
comments	3	Comment best practices
error-handling	3	Exception handling
unit-tests	3	Clean test principles
formatting	3	Code layout
smells	3	Code smell catalog (50+)

分类	文件数	用途
naming	3	变量、函数、类命名
functions	4	函数设计与评审
classes	3	类/模块设计
comments	3	注释最佳实践
error-handling	3	异常处理
unit-tests	3	整洁测试原则
formatting	3	代码布局
smells	3	代码坏味道目录（50+种）

Part 2: Professional Practices (Clean Coder book)

第二部分：专业实践（《The Clean Coder》书籍）

Category	Files	Purpose
professionalism	3	Professional ethics
saying-no	3	Declining requests
commitment	3	Making promises
coding-practices	3	Daily habits, flow, debugging
tdd	3	TDD workflow and benefits
practicing	3	Deliberate practice
acceptance-testing	3	Requirements as tests
testing-strategies	3	Test pyramid
time-management	3	Meetings, focus
estimation	3	PERT estimation
pressure	3	Working under pressure
collaboration	3	Working with teams

分类	文件数	用途
professionalism	3	职业伦理
saying-no	3	拒绝请求
commitment	3	做出承诺
coding-practices	3	日常习惯、工作流、调试
tdd	3	TDD工作流与优势
practicing	3	刻意练习
acceptance-testing	3	以测试表达需求
testing-strategies	3	测试金字塔
time-management	3	会议、专注度
estimation	3	PERT估算
pressure	3	高压下工作
collaboration	3	团队协作

Key Principles (Summary Only — Always Load Full References)

核心原则（仅摘要 — 请务必加载完整参考文件）

These are abbreviated reminders. Always load the corresponding reference files for the full rules, thresholds, and examples before applying.

以下是简化的提示。在应用前，请务必加载对应的参考文件以获取完整规则、阈值和示例。

Code Quality

代码质量

Readability →

references/formatting/rules.md

references/naming/rules.md

Single Responsibility →

references/classes/rules.md

references/functions/rules.md

Small Units →
```
references/functions/rules.md
```
(Rule 1: 2-5 lines ideal)
Meaningful Names →
```
references/naming/rules.md
```
DRY →
```
references/smells/rules.md
```
(G5)
Clean Tests →
```
references/unit-tests/rules.md
```

可读性 →

references/formatting/rules.md

、

references/naming/rules.md

单一职责 →

references/classes/rules.md

、

references/functions/rules.md

小单元 →
```
references/functions/rules.md
```
（规则1：理想长度2-5行）
有意义的命名 →
```
references/naming/rules.md
```
DRY（不重复） →
```
references/smells/rules.md
```
（G5）
整洁测试 →
```
references/unit-tests/rules.md
```

Professional Practices

专业实践

Take Responsibility →
```
references/professionalism/rules.md
```
Say No →
```
references/saying-no/rules.md
```
Commit Clearly →
```
references/commitment/rules.md
```
Estimates != Commitments →
```
references/estimation/rules.md
```
Stay Clean Under Pressure →
```
references/pressure/rules.md
```

承担责任 →
```
references/professionalism/rules.md
```
学会拒绝 →
```
references/saying-no/rules.md
```
清晰承诺 →
```
references/commitment/rules.md
```
估算≠承诺 →
```
references/estimation/rules.md
```
高压下保持整洁 →
```
references/pressure/rules.md
```

Guidelines

指南

See

guidelines.md

for:

Task → workflow mapping
Situation → reference file mapping
Decision tree for common scenarios

查看

guidelines.md

获取：

任务→工作流映射
场景→参考文件映射
常见场景决策树

Reference Loading Checklist

参考文件加载检查清单

Before giving any code advice or writing code, verify:

Identified which reference categories apply to the current task
Loaded the
```
rules.md
```
for each applicable category
Loaded
```
examples.md
```
if demonstrating patterns or reviewing code
Loaded the relevant
```
workflow/*.md
```
if executing a multi-step task
Will cite specific rules/files in recommendations

在提供任何代码建议或编写代码前，请确认：

确定了当前任务适用的参考分类
加载了每个适用分类的
```
rules.md
```
若要演示模式或评审代码，加载了
```
examples.md
```
若要执行多步骤任务，加载了相关的
```
workflow/*.md
```
会在建议中引用具体规则/文件