clean-typescript
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseClean TypeScript: Index And Review Guide
规范TypeScript：索引与审查指南
Use this as the TypeScript entry point. It routes broad review work to focused skills and summarizes the rules most likely to affect design. Prefer clear runtime behavior and precise public types over cleverness or type-system escape hatches.
将此作为TypeScript的入门参考。它会将宽泛的审查工作引导至针对性技能，并总结最可能影响设计的规则。优先选择清晰的运行时行为和精确的公共类型，而非巧妙的技巧或类型系统的规避手段。
Comments (C1-C5)
注释规范（C1-C5）
- C1: No metadata in comments (use Git)
- C2: Delete obsolete comments immediately
- C3: No redundant comments
- C4: Write comments well if you must
- C5: Never commit commented-out code
- C1：注释中不要包含元数据（使用Git管理）
- C2：立即删除过时注释
- C3：避免冗余注释
- C4：若必须添加注释，请确保注释质量
- C5：绝不提交被注释掉的代码
Error Handling (EH1-EH4)
错误处理规范（EH1-EH4）
- EH1: Throw objects with useful context
Error - EH2: Catch and narrow before reading properties
unknown - EH3: Do not swallow failures
- EH4: Use typed recoverable results only when the project style or domain warrants it
- EH1：抛出带有有用上下文信息的对象
Error - EH2：捕获类型并在读取属性前进行类型收窄
unknown - EH3：不要掩盖失败
- EH4：仅当项目风格或领域需求时，才使用可恢复的类型化结果
Functions (F1-F9)
函数规范（F1-F9）
- F1: Maximum 3 arguments (use parameter objects/interfaces for more)
- F2: No output arguments (return values)
- F3: No flag arguments (split functions)
- F4: Delete dead functions
- F5: Reduce nesting with early returns, helper functions, extraction, or refactoring
- F6: Keep one level of abstraction per function
- F7: Name and simplify complex conditions
- F8: Separate commands from queries
- F9: Keep side effects explicit and isolated
- F1：最多3个参数（参数更多时使用参数对象/接口）
- F2：不使用输出参数（改用返回值）
- F3：不使用标志参数（拆分函数）
- F4：删除无用函数
- F5：通过提前返回、辅助函数、代码提取或重构减少嵌套
- F6：每个函数保持单一抽象层级
- F7：为复杂条件命名并简化
- F8：将命令与查询分离
- F9：保持副作用明确且独立
General (G1-G5)
通用规范（G1-G5）
- G1: No duplicated knowledge
- G2: No obscured intent
- G3: Named constants, not magic values
- G4: Functions do one thing
- G5: Delete dead code
- G1：避免重复逻辑
- G2：不要隐藏代码意图
- G3：使用命名常量，而非魔法值
- G4：函数单一职责
- G5：删除无用代码
Modules (M1-M8)
模块规范（M1-M8）
- M1: Keep declarations close to use
- M2: Order code for top-down reading
- M3: Keep modules cohesive
- M4: Keep dependency direction obvious
- M5: Avoid empty abstractions
- M6: Separate construction from use
- M7: Avoid temporal coupling
- M8: Keep public exports small and intentional
- M1：声明与使用位置尽量接近
- M2：代码按自上而下的阅读顺序排列
- M3：保持模块内聚性
- M4：明确依赖方向
- M5：避免空抽象
- M6：将构造与使用分离
- M7：避免时序耦合
- M8：保持公共导出精简且有明确意图
Async (A1-A5)
异步规范（A1-A5）
- A1: Isolate async workflows
- A2: Make ordering explicit
- A3: Avoid shared mutable state across awaits
- A4: Make cancellation, timeouts, retries, and fallbacks visible
- A5: Test race-prone behavior
- A1：隔离异步工作流
- A2：明确执行顺序
- A3：避免在await之间共享可变状态
- A4：让取消、超时、重试和回退逻辑可见
- A5：测试易出现竞态条件的行为
TypeScript-Specific (TS1-TS3)
TypeScript专属规范（TS1-TS3）
- TS1: Keep imports explicit and stable; avoid namespace-style overuse and implicit dependencies
- TS2: Prefer literal unions, discriminated unions, or const objects for closed sets; use enums only when they match project convention
- TS3: Type public interfaces explicitly; use plus narrowing instead of
unknownat boundariesany
- TS1：保持导入明确且稳定；避免过度使用命名空间风格和隐式依赖
- TS2：对于封闭集合，优先使用字面量联合类型、可辨识联合类型或const对象；仅当符合项目约定时才使用枚举
- TS3：为公共接口显式定义类型；在边界处使用加类型收窄，而非
unknownany
Boundaries (B1-B4)
边界规范（B1-B4）
- B1: Treat external data as until validated
unknown - B2: Convert API, JSON, env, storage, database, and SDK shapes into internal types at the edge
- B3: Keep vendor types out of domain code unless they are the domain
- B4: Test tricky boundary mappings and invalid external shapes
- B1：外部数据在验证前视为类型
unknown - B2：在系统边缘将API、JSON、环境变量、存储、数据库和SDK的数据结构转换为内部类型
- B3：除非供应商类型属于领域范畴，否则不要将其引入领域代码
- B4：测试复杂的边界映射和无效的外部数据结构
Objects and Data (OD1-OD7)
对象与数据规范（OD1-OD7）
- OD1: Use plain data for transfer, rendering, serialization, and pattern matching
- OD2: Use objects/classes when behavior and invariants belong together
- OD3: Model impossible states out with discriminated unions
- OD4: Keep DTOs separate from domain models when external shape differs
- OD5: Avoid excessive object-chain knowledge
- OD6: Represent absence explicitly instead of vague failures
null - OD7: Replace repeated conditionals with a domain model, lookup, strategy, or exhaustive union dispatch
- OD1：在传输、渲染、序列化和模式匹配中使用纯数据
- OD2：当行为与不变量需要结合时，使用对象/类
- OD3：通过可辨识联合类型排除不可能的状态
- OD4：当外部结构与内部不同时，保持DTOs与领域模型分离
- OD5：避免过度依赖对象链
- OD6：显式表示缺失，而非模糊的错误
null - OD7：用领域模型、查找表、策略模式或穷尽联合类型分发替代重复条件判断
Skill Routing
技能路由
| Work | Use |
|---|---|
| Broad duplication, intent, magic values, dead code | |
| Comments and TSDoc | |
| Functions, arguments, mutation, flags | |
| Modules, classes, file order, cohesion, coupling, dependency construction, over-abstraction | |
| Promises, retries, timeouts, cancellation, race conditions | |
| Error handling and fallbacks | |
| APIs, JSON, config, storage, SDKs | |
| DTOs, domain models, classes, unions | |
| Names | |
| Tests | |
| 工作内容 | 使用技能 |
|---|---|
| 广泛重复、意图模糊、魔法值、死代码 | |
| 注释与TSDoc | |
| 函数、参数、变更、标志 | |
| 模块、类、文件顺序、内聚性、耦合性、依赖构造、过度抽象 | |
| Promise、重试、超时、取消、竞态条件 | |
| 错误处理与回退 | |
| API、JSON、配置、存储、SDK | |
| DTOs、领域模型、类、联合类型 | |
| 命名 | |
| 测试 | |
TypeScript Precision
TypeScript精度优化
- Prefer when validating object literals without widening useful literal types.
satisfies - Avoid assertions unless crossing a boundary that cannot express the type; narrow first when possible.
as - Keep unsafe parsing at the edge of the system and pass typed values inward.
- 验证对象字面量时，若不想拓宽有用的字面量类型，优先使用。
satisfies - 除非跨越无法表达类型的边界，否则避免使用断言；尽可能先进行类型收窄。
as - 将不安全的解析放在系统边缘，向内传递类型化的值。
Names (N1-N7)
命名规范（N1-N7）
- N1: Choose descriptive names
- N2: Right abstraction level
- N3: Use standard nomenclature
- N4: Unambiguous names
- N5: Name length matches scope
- N6: No encodings
- N7: Names describe side effects
- N1：选择描述性名称
- N2：匹配正确的抽象层级
- N3：使用标准命名法
- N4：名称无歧义
- N5：名称长度与作用域匹配
- N6：不使用编码式命名
- N7：名称需描述副作用
Tests (T1-T11)
测试规范（T1-T11）
- T1: Test everything that could break
- T2: Use coverage tools
- T3: Don't skip trivial tests
- T4: Ignored test = ambiguity question
- T5: Test boundary conditions
- T6: Exhaustively test near bugs
- T7: Look for patterns in failures
- T8: Check coverage when debugging
- T9: Unit tests should be fast; isolate slower integration tests
- T10: Prefer test data builders over brittle inline fixtures
- T11: Test behavior contracts, not incidental implementation details
- T1：测试所有可能出错的内容
- T2：使用覆盖率工具
- T3：不要跳过简单测试
- T4：忽略的测试=待明确的问题
- T5：测试边界条件
- T6：针对疑似错误进行穷尽测试
- T7：从失败中寻找规律
- T8：调试时检查覆盖率
- T9：单元测试应快速；将较慢的集成测试隔离
- T10：优先使用测试数据构建器，而非脆弱的内联测试数据
- T11：测试行为契约，而非偶然的实现细节
AI Behavior
AI行为规范
When reviewing code, use this skill for the first-pass sweep: identify violations by rule number (e.g., "G1 violation: duplicated logic").
When writing detailed fixes or explanations for a specific category, read the corresponding sub-skill file before proceeding — for example, read when addressing F-rule violations. If the Skill tool is available, invoke the skill by name instead. The sub-skills contain code examples and nuance that this index omits.
../clean-typescript-functions/SKILL.mdWhen fixing or editing code, report what was fixed (e.g., "Fixed: extracted magic value to (G3)").
SECONDS_PER_DAY审查代码时，使用本技能进行首轮扫描：通过规则编号识别违规情况（例如："违反G1规则：逻辑重复"）。
编写针对特定类别的详细修复方案或解释时，请先阅读对应的子技能文件再开展工作——例如，处理F类规则违规时，阅读。若Skill工具可用，直接按名称调用对应技能即可。子技能包含本索引未提及的代码示例和细节。
../clean-typescript-functions/SKILL.md修复或编辑代码时，需报告修复内容（例如："已修复：将魔法值提取为（G3规则）"）。
SECONDS_PER_DAY