typescript-clean-code
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseClean Code
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 and
rules.mdfiles fromexamples.mdbefore giving advice or writing code. Do not rely on general knowledge alone.references/ - 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 Rule 1: Keep Functions Small, 2-5 lines ideal") so the user can trace the guidance back to its source.
references/functions/rules.md - Use examples from reference files - Prefer the bad/good code examples in over generating your own. These examples are curated for TypeScript and demonstrate the exact patterns intended.
references/[topic]/examples.md - 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 - 参考内容优先于内部知识 - 如果你的通用知识与参考文件内容冲突，请遵循参考文件。它们包含此技能所强制执行的具体规则、阈值和模式。
- 引用具体规则 - 给出建议时，请引用具体规则（例如：“根据规则1：保持函数精简，理想长度为2-5行”），以便用户可以追溯指导内容的来源。
references/functions/rules.md - 使用参考文件中的示例 - 优先使用中的错误/正确代码示例，而非自行生成。这些示例是专为TypeScript整理的，展示了预期的精确模式。
references/[topic]/examples.md - 逐步遵循工作流 - 执行任务（评审、重构、TDD等）时，加载对应的工作流文件并遵循每个步骤，加载各步骤指向的参考文件。
请勿跳过加载参考文件的步骤。 即使你“了解”Clean Code原则，参考文件中包含了针对TypeScript的特定适配、阈值、检查清单和代码坏味道目录，这些内容可能与你的通用知识不完全匹配。
Quick Start
快速开始
- For a task: Check → find the right workflow → load it → follow each step (loading referenced files)
guidelines.md - For reference: Load the specific and
rules.mdfiles relevant to your work → apply themexamples.md - 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 |
|---|---|
| Reviewing code for quality |
| Reviewing pull requests |
| Test-driven development cycle |
| Safe refactoring with tests |
| Building new functionality |
| Fixing bugs properly |
| Planning test coverage |
| Estimating tasks (PERT) |
| Handling unrealistic deadlines |
针对常见任务的分步流程：
| 工作流 | 适用场景 |
|---|---|
| 评审代码质量 |
| 评审拉取请求 |
| 测试驱动开发周期 |
| 带测试的安全重构 |
| 构建新功能 |
| 正确修复Bug |
| 规划测试覆盖率 |
| 估算任务（PERT法） |
| 处理不切实际的截止日期 |
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 entry point that describes steps and loads
workflow.mdsteps/step-01-init.md - Each step is a separate file in , loaded sequentially
steps/ - Progress is tracked via array in the output document's YAML frontmatter
stepsCompleted - If context is compacted mid-workflow, detects the existing output and
step-01-init.mdresumes from the last completed stepstep-01b-continue.md - 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.mdsteps/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.mdreferences/naming/rules.md - Single Responsibility → ,
references/classes/rules.mdreferences/functions/rules.md - Small Units → (Rule 1: 2-5 lines ideal)
references/functions/rules.md - Meaningful Names →
references/naming/rules.md - DRY → (G5)
references/smells/rules.md - Clean Tests →
references/unit-tests/rules.md
- 可读性 → 、
references/formatting/rules.mdreferences/naming/rules.md - 单一职责 → 、
references/classes/rules.mdreferences/functions/rules.md - 小单元 → （规则1：理想长度2-5行）
references/functions/rules.md - 有意义的命名 →
references/naming/rules.md - DRY（不重复） → （G5）
references/smells/rules.md - 整洁测试 →
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 for:
guidelines.md- 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 for each applicable category
rules.md - Loaded if demonstrating patterns or reviewing code
examples.md - Loaded the relevant if executing a multi-step task
workflow/*.md - Will cite specific rules/files in recommendations
在提供任何代码建议或编写代码前，请确认：
- 确定了当前任务适用的参考分类
- 加载了每个适用分类的
rules.md - 若要演示模式或评审代码，加载了
examples.md - 若要执行多步骤任务，加载了相关的
workflow/*.md - 会在建议中引用具体规则/文件