accelint-ts-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

JavaScript and TypeScript Best Practices

JavaScript与TypeScript最佳实践

Comprehensive coding standards for JavaScript and TypeScript applications, designed for AI agents and LLMs working with modern JavaScript/TypeScript codebases.

Note: This skill focuses on general best practices, TypeScript patterns, and safety. For performance optimization, use the

accelint-ts-performance

skill instead.

面向AI Agent和LLM的JavaScript与TypeScript应用全面编码规范，适用于现代JavaScript/TypeScript代码库。

注意： 本Skill专注于通用最佳实践、TypeScript模式与安全性。如需性能优化，请改用

accelint-ts-performance

Skill。

When to Use This Skill

何时使用本Skill

This skill provides expert-level patterns for JavaScript and TypeScript code. Load AGENTS.md to scan rule summaries and identify relevant optimizations for your task.

本Skill为JavaScript与TypeScript代码提供专家级实践模式。加载AGENTS.md可查看规则摘要，确定与你的任务相关的优化方向。

How to Use

使用方法

This skill uses a progressive disclosure structure to minimize context usage:

本Skill采用渐进式披露结构，以最小化上下文占用：

1. Start with the Overview (AGENTS.md)

1. 从概览开始（AGENTS.md）

Read AGENTS.md for a concise overview of all rules with one-line summaries organized by category.

阅读AGENTS.md获取所有规则的简洁概览，其中按类别列出了单行规则摘要。

2. Load Specific Rules as Needed

2. 根据需要加载特定规则

When you identify a relevant pattern or issue, load the corresponding reference file for detailed implementation guidance:

Quick Start:

quick-start.md - Complete workflow examples with before/after code

General Best Practices:

naming-conventions.md - Descriptive names, qualifier ordering, boolean prefixes
functions.md - Function size, parameters, explicit values
control-flow.md - Early returns, flat structure, block style
state-management.md - const vs let, immutability, pure functions
return-values.md - Return zero values instead of null/undefined
misc.md - Line endings, defensive programming, technical debt
code-duplication.md - Extract common patterns, DRY principle, when to consolidate

TypeScript:

any.md - Avoid any, use unknown or generics
enums.md - Use as const objects instead of enum
type-vs-interface.md - Prefer type over interface

Safety:

input-validation.md - Validate external data with schemas
assertions.md - Split assertions, include values
error-handling.md - Handle all errors explicitly
error-messages.md - User-friendly vs developer-specific messages

Performance:

For performance optimization tasks, use the
```
accelint-ts-performance
```
skill for comprehensive profiling workflows and optimization patterns

Documentation:

For documentation tasks, use the
```
accelint-ts-documentation
```
skill for comprehensive JSDoc and comment guidance

当你确定相关模式或问题时，加载对应的参考文件以获取详细的实现指导：

快速入门：

quick-start.md - 包含代码前后对比的完整工作流示例

通用最佳实践：

naming-conventions.md - 描述性命名、限定符顺序、布尔值前缀
functions.md - 函数大小、参数、显式值
control-flow.md - 提前返回、扁平化结构、代码块风格
state-management.md - const与let的使用、不可变性、纯函数
return-values.md - 返回零值而非null/undefined
misc.md - 行尾、防御式编程、技术债务
code-duplication.md - 提取通用模式、DRY原则、何时合并代码

TypeScript相关：

any.md - 避免使用any，改用unknown或泛型
enums.md - 使用as const对象替代enum
type-vs-interface.md - 优先使用type而非interface

安全性相关：

input-validation.md - 使用校验规则验证外部数据
assertions.md - 拆分断言、包含具体值
error-handling.md - 显式处理所有错误
error-messages.md - 用户友好型与开发者专用型错误消息

性能优化：

针对性能优化任务，请使用
```
accelint-ts-performance
```
Skill获取全面的性能分析工作流与优化模式

文档编写：

针对文档编写任务，请使用
```
accelint-ts-documentation
```
Skill获取全面的JSDoc与注释指导

3. Apply the Pattern

3. 应用实践模式

Each reference file contains:

❌ Incorrect examples showing the anti-pattern
✅ Correct examples showing the optimal implementation
Explanations of why the pattern matters

每个参考文件包含：

❌ 展示反模式的错误示例
✅ 展示最优实现的正确示例
该实践模式重要性的解释

4. Use the Report Template

4. 使用报告模板

When this skill is invoked, use the standardized report format:

Template:

assets/output-report-template.md

The report format provides:

Executive Summary with impact assessment
Severity levels (Critical, High, Medium, Low) for prioritization
Impact analysis (potential bugs, type safety, maintainability, runtime failures)
Categorization (Type Safety, Safety, State Management, Return Values, Code Quality)
Pattern references linking to detailed guidance in references/
Phase 2 summary table for tracking all issues

When to use the audit template:

Skill invoked directly via
```
/accelint-ts-best-practices <path>
```
User asks to "review code quality" or "audit code" across file(s), invoking skill implicitly

When NOT to use the report template:

User asks to "fix this type error" (direct implementation)
User asks "what's wrong with this code?" (answer the question)
User requests specific fixes (apply fixes directly without formal report)

当调用本Skill时，请使用标准化报告格式：

模板：

assets/output-report-template.md

该报告格式包含：

带有影响评估的执行摘要
用于优先级排序的严重级别（Critical、High、Medium、Low）
影响分析（潜在bug、类型安全、可维护性、运行时故障）
分类（类型安全、安全性、状态管理、返回值、代码质量）
指向references/中详细指导的实践模式链接
用于跟踪所有问题的Phase 2摘要表格

何时使用审计模板：

通过
```
/accelint-ts-best-practices <path>
```
直接调用Skill时
用户要求“评审代码质量”或“审计文件代码”，隐式调用Skill时

何时不使用报告模板：

用户要求“修复这个类型错误”（直接实现修复）
用户询问“这段代码有什么问题？”（直接回答问题）
用户请求特定修复（直接应用修复，无需正式报告）