accelint-ts-best-practices

JavaScript 和 TypeScript 最佳实践

为使用现代 JavaScript/TypeScript 代码库的 AI Agent 和大模型制定的全面编码标准。

**注意：**此技能侧重于通用最佳实践、TypeScript 模式和安全性。如需优化性能，请改用 accelint-ts-performance 技能。

何时使用此技能

此技能提供 JavaScript 和 TypeScript 代码的专家级模式。加载 AGENTS.md，浏览规则摘要并为你的任务找出相关优化项。

使用方法

此技能采用渐进式披露结构，以尽量减少上下文用量：

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

阅读 AGENTS.md，简要了解按类别整理的所有规则及其单行摘要。

2. 按需加载具体规则

找到相关模式或问题后，加载对应的参考文件，获取详细的实现指导：

快速入门：

• 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
• bundler-paths.md - 使用可静态分析的导入路径和文件系统路径，以实现最佳打包效果

安全性：

• input-validation.md - 使用 schema 验证外部数据
• assertions.md - 拆分断言并包含具体值
• error-handling.md - 明确处理所有错误
• error-messages.md - 面向用户的消息与面向开发者的消息

性能：

• 对于性能优化任务，请使用 accelint-ts-performance 技能获取全面的性能分析工作流和优化模式

文档：

• 对于文档编写任务，请使用 accelint-ts-documentation 技能获取全面的 JSDoc 和注释指导

3. 应用模式

每个参考文件都包含：

• ❌ 展示反模式的错误示例
• ✅ 展示最佳实现的正确示例
• 关于该模式为何重要的说明

4. 使用报告模板

调用此技能时，请使用标准报告格式：

模板： assets/output-report-template.md

报告格式包括：

• 含影响评估的执行摘要
• 用于确定优先级的严重级别（Critical、High、Medium、Low）
• 影响分析（潜在错误、类型安全、可维护性、运行时故障）
• 分类（类型安全、安全性、状态管理、返回值、代码质量）
• 指向 references/ 中详细指南的模式参考
• 用于跟踪所有问题的第二阶段汇总表

使用审查模板的情况：

• 通过 /accelint-ts-best-practices <path> 直接调用技能
• 用户要求跨一个或多个文件“审查代码质量”或“审计代码”，从而隐式调用技能

不使用报告模板的情况：

• 用户要求“修复此类型错误”（直接实现）
• 用户询问“这段代码有什么问题？”（回答问题）
• 用户要求具体修复（直接应用修复，不提供正式报告）