develop-typescript

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Develop TypeScript

开发TypeScript

Write, review, or refactor framework-agnostic TypeScript with strict type safety, correct tsconfig, and idiomatic patterns.

编写、审查或重构与框架无关的TypeScript代码，确保严格的类型安全、正确的tsconfig配置以及符合规范的代码模式。

Trigger boundary

触发边界

Use this skill when:

writing new TypeScript code that must be strictly typed
reviewing existing TypeScript for type safety, anti-patterns, or missing narrowing
configuring or auditing tsconfig.json and linting rules
migrating JavaScript to TypeScript (or upgrading TS versions)
diagnosing and resolving type errors, inference failures, or performance issues

Do not use this skill when:

the task is primarily React/Vue/Angular component work (use framework-specific skills)
the task is exclusively about Node.js runtime APIs (use a Node.js skill)
the task is about build tooling only (use tooling-specific skills)

Repositories that happen to contain

.tsx

files are still in scope when the requested work is about TypeScript itself: tsconfig, safer typing, exported contracts, result/error patterns, or strictness audits.

在以下场景使用本Skill：

编写必须严格类型化的新TypeScript代码
审查现有TypeScript代码的类型安全性、反模式或缺失的类型收窄处理
配置或审核tsconfig.json与代码检查规则
将JavaScript迁移至TypeScript（或升级TS版本）
诊断并解决类型错误、类型推断失败或性能问题

请勿在以下场景使用本Skill：

任务主要涉及React/Vue/Angular组件开发（使用框架专属Skill）
任务仅围绕Node.js运行时API展开（使用Node.js专属Skill）
任务仅涉及构建工具（使用工具专属Skill）

若仓库中包含.tsx文件，但请求的工作内容聚焦于TypeScript本身（如tsconfig配置、更安全的类型定义、导出契约、结果/错误模式或严格性审核），仍属于本Skill的处理范围。

Definitions

定义

Load — read the file into working context so you can reference its content
Checked
as
— a cast following a runtime guard that proves the type (safe)
Unchecked
as
— a cast with no runtime proof; hides bugs (almost always wrong)
Block — in review mode, flag the issue and stop approving; do not auto-fix

加载 — 将文件读取至工作上下文，以便引用其内容
已检查的
as
— 跟随运行时守卫的类型转换，可证明类型合法性（安全）
未检查的
as
— 无运行时证明的类型转换；会隐藏bug（几乎总是错误的）
阻止 — 在审查模式下，标记问题并停止审批；不自动修复

Mode detection

模式检测

Before starting, determine your mode:

Signal	Mode	Behavior
"Write", "implement", "create", "add", "refactor", "tighten typing", "improve typing", "make TS stricter", "harden types"	Authoring	Write code, apply fixes, output files
"Review", "audit", "check", "look at"	Review	Report findings, never auto-fix, block on P0
Ambiguous	Ask	Clarify with the user before proceeding

开始前，先确定工作模式：

信号词	模式	行为
"Write", "implement", "create", "add", "refactor", "tighten typing", "improve typing", "make TS stricter", "harden types"	创作模式	编写代码、应用修复、输出文件
"Review", "audit", "check", "look at"	审查模式	报告发现的问题，绝不自动修复，对P0级问题实施阻止
模糊不清	询问模式	先与用户澄清需求再继续

Required workflow

必备工作流程

Step 1 — Classify the task

步骤1 — 任务分类

Identify the primary category and optionally one adjacent category:

Category	Reference to load
Type system (generics, narrowing, inference)	type-system.md
Patterns (result types, branded types, builders)	patterns.md
Anti-patterns (any, ts-ignore, unsafe casts)	anti-patterns.md
Error handling (Result, retry, aggregation)	error-handling.md
Strict config (tsconfig, strict flags)	strict-config.md
Tooling (ESLint, Biome, Prettier, CI)	tooling.md
Migration (JS-to-TS, version upgrades)	migration.md
Performance (compilation speed, traces)	performance.md
Testing (type tests, expect-type, tsd)	testing.md
Modern features (decorators, using, satisfies)	modern-features.md

Steering note: Most tasks span two categories. Load the primary reference plus one adjacent. If uncertain which category fits, scan the table above for keywords that match the user request.

确定主要类别，可选择一个相邻类别：

类别	需加载的参考文档
类型系统（泛型、类型收窄、类型推断）	type-system.md
代码模式（结果类型、品牌类型、构建器）	patterns.md
反模式（any、ts-ignore、不安全类型转换）	anti-patterns.md
错误处理（Result、重试、聚合）	error-handling.md
严格配置（tsconfig、严格模式标志）	strict-config.md
工具链（ESLint、Biome、Prettier、CI）	tooling.md
迁移（JS转TS、版本升级）	migration.md
性能（编译速度、追踪）	performance.md
测试（类型测试、expect-type、tsd）	testing.md
现代特性（装饰器、using、satisfies）	modern-features.md

指导说明： 大多数任务会涉及两个类别。加载主要参考文档及一个相邻文档。若不确定适用类别，扫描上表寻找与用户请求匹配的关键词。

Step 2 — Load references

步骤2 — 加载参考文档

Load the reference file(s) identified in Step 1. Read the full file — do not skim.

If the task involves existing code, also load:

The project's tsconfig.json (compare against strict-config.md baseline)
The project's ESLint/Biome config (check for rule conflicts)

Steering note: When reviewing tsconfig.json, only flag
moduleResolution: "node"
as legacy.
"node16"
,
"nodenext"
, and
"bundler"
are all modern and correct for their contexts. Choose the baseline that matches the repo's runtime first; strictness flags are orthogonal to module mode. Do not "upgrade"
node16
/
nodenext
projects to
bundler
unless the user explicitly wants that runtime change. If the repo has multiple tsconfig files, start with the config that governs the files you are touching, then follow its
extends
chain to shared base configs. If there is no ESLint/Biome config, record that absence and skip Step 5 conflict handling rather than inventing lint policy.

加载步骤1中确定的参考文档。需完整阅读，不可略读。

若任务涉及现有代码，还需加载：

项目的tsconfig.json（与strict-config.md中的基准配置对比）
项目的ESLint/Biome配置（检查规则冲突）

指导说明： 审查tsconfig.json时，仅将
moduleResolution: "node"
标记为旧版配置。
"node16"
,
"nodenext"
, and
"bundler"
均为现代配置，适用于各自的场景。首先选择与仓库运行时匹配的基准配置；严格性标志与模块模式相互独立。除非用户明确要求更改运行时，否则不要将
node16
/
nodenext
项目"升级"为
bundler
模式。若仓库包含多个tsconfig文件，先从你要修改的文件对应的配置开始，再跟随其
extends
链查看共享基础配置。若没有ESLint/Biome配置，记录该情况并跳过步骤5的冲突处理，不要自行制定代码检查规则。

Step 3 — Execute the task

步骤3 — 执行任务

Apply the patterns and rules from the loaded references.

In authoring mode:

Write code that follows the patterns in the reference files
Use
```
satisfies
```
for config objects, explicit return types for public functions
Never use bare
```
any
```
,
```
@ts-ignore
```
, or unchecked
```
as
```
Prefer
```
unknown
```
+ narrowing over
```
any
```
for dynamic data

In review mode:

Scan for every item in the anti-patterns.md review-mode checklist (Section: Review-Mode Scanning Checklist)
For each finding, classify as P0 (blocks approval) or P1 (should fix) or P2 (nit)
Block on: bare
```
any
```
in new code,
```
@ts-ignore
```
(should be
```
@ts-expect-error
```
), unchecked
```
as
```
, missing error narrowing
Flag but don't block on: style preferences, minor naming issues

Steering note: Distinguish lint warnings from type errors. Lint warnings are project-specific (respect the project's config). Type errors from
tsc
are universal and always blocking.

应用加载的参考文档中的模式与规则。

创作模式下：

编写符合参考文档中模式的代码
对配置对象使用
```
satisfies
```
，对公共函数添加显式返回类型
绝不使用裸
```
any
```
、
```
@ts-ignore
```
或未检查的
```
as
```
对于动态数据，优先使用
```
unknown
```
+类型收窄而非
```
any
```

审查模式下：

扫描anti-patterns.md中审查模式检查清单的所有项（章节：审查模式扫描清单）
对每个发现的问题分类为P0（阻止审批）、P1（应修复）或P2（小问题）
阻止审批的情况： 新代码中使用裸
```
any
```
、
```
@ts-ignore
```
（应使用
```
@ts-expect-error
```
）、未检查的
```
as
```
、缺失错误类型收窄
标记但不阻止审批的情况：风格偏好、轻微命名问题

指导说明： 区分代码检查警告与类型错误。代码检查警告是项目特定的（需遵循项目配置）。
tsc
抛出的类型错误是通用的，始终会阻止审批。

Step 4 — Audit and verify

步骤4 — 审核与验证

Run these checks:

bash

undefined

运行以下检查：

bash

undefined

Find unannotated exported functions (authoring mode)

查找未添加注解的导出函数（创作模式）

grep -rnE --include=".ts" --include=".tsx" "^export (default )?function" . | grep -v node_modules | grep -v ": " | head -20

Find bare 'any' usage

查找裸'any'的使用

grep -rnE --include=".ts" --include=".tsx" ": any\b" . | grep -v node_modules | head -20

Find @ts-ignore (should be @ts-expect-error)

查找@ts-ignore（应使用@ts-expect-error）

grep -rn --include=".ts" --include=".tsx" "@ts-ignore" . | grep -v node_modules

Find unchecked type assertions

查找未检查的类型断言

grep -rn --include=".ts" --include=".tsx" " as [A-Z]" . | grep -v node_modules | grep -v "// checked" | head -20

Search for satisfies opportunities (config objects typed with annotation)

寻找使用satisfies的机会（使用注解类型的配置对象）

grep -rnE --include=".ts" --include=".tsx" "^const .* : Record<" . | grep -v node_modules | head -10 grep -rnE --include=".ts" --include=".tsx" "^const .* : {" . | grep -v node_modules | head -10


> **Steering note:** The `satisfies` audit catches config objects that use type annotations
> where `satisfies` would preserve literal types. This is a common missed opportunity.
> Run these audits from the repository root, or replace `.` with the target package path in a monorepo.
> If the repo contains TSX and `jsx` is `react-jsx`, verify the React runtime/types are actually installed before treating the typecheck result as meaningful.

grep -rnE --include=".ts" --include=".tsx" "^const .* : Record<" . | grep -v node_modules | head -10 grep -rnE --include=".ts" --include=".tsx" "^const .* : {" . | grep -v node_modules | head -10


> **指导说明：** `satisfies`审核会捕获那些使用类型注解的配置对象，而使用`satisfies`可以保留字面量类型。这是一个常见的遗漏点。
> 从仓库根目录运行这些审核，或者在单体仓库中将`.`替换为目标包路径。
> 若仓库包含TSX文件且`jsx`设置为`react-jsx`，在将类型检查结果视为有效之前，需先验证React运行时/类型是否已实际安装。

Step 5 — Handle conflicts

步骤5 — 处理冲突

If the project's lint config contradicts skill recommendations:

For new code you're writing: follow the skill's stricter rules
For existing code under review: respect the project's config, flag conflicts as informational
Document the conflict: "Project disables X — consider re-enabling for new code"

Steering note: Do not unilaterally re-enable lint rules. The project may have valid reasons for disabling them (e.g., gradual migration from JavaScript, third-party type issues).

若项目的代码检查配置与Skill建议冲突：

对于你正在编写的新代码：遵循Skill更严格的规则
对于正在审查的现有代码：尊重项目配置，将冲突标记为信息说明
记录冲突："Project disables X — consider re-enabling for new code"

指导说明： Do not unilaterally re-enable lint rules. The project may have valid reasons for disabling them (e.g., gradual migration from JavaScript, third-party type issues).

Step 6 — Deliver

步骤6 — 交付成果

In authoring mode: Output the complete, compilable code. Ensure every exported function has an explicit return type annotation. For exported TSX components, follow the repo's existing convention; if none exists, prefer

ReactElement

via

import type { ReactElement } from 'react'

over relying on the global

JSX.Element

namespace.

In review mode: Output findings as a structured list with severity levels. Include specific line references and fix suggestions for each P0 and P1 finding.

Steering note: Always produce a deliverable — code or findings list. Never end with only commentary or advice. The user expects actionable output.

创作模式下： 输出完整的可编译代码。确保每个导出函数都有显式返回类型注解。对于导出的TSX组件，遵循仓库现有的约定；若没有约定，优先通过

import type { ReactElement } from 'react'

使用

ReactElement

，而非依赖全局

JSX.Element

命名空间。

审查模式下： 将发现的问题按严重程度整理为结构化列表。为每个P0和P1级问题包含具体的行号参考和修复建议。

指导说明： Always produce a deliverable — code or findings list. Never end with only commentary or advice. The user expects actionable output.

Common mistakes to avoid

需避免的常见错误

Mistake	Why it's wrong	What to do instead
Flagging `node16` moduleResolution as legacy	Only bare `"node"` is legacy	Check strict-config.md flag table
Using `any` for "I'll fix it later"	`any` disables all checking downstream	Use `unknown` and narrow
Ignoring cross-realm instanceof issues	Objects from iframes/workers fail instanceof	Use brand checks or Symbol.hasInstance
Auto-fixing code in review mode	Review should report, not modify	Block and describe; let the author fix
Skipping the deliverable step	User gets advice but no output	Always output code or structured findings
Treating `@ts-ignore` and `@ts-expect-error` as equivalent	`@ts-ignore` suppresses silently forever	Always prefer `@ts-expect-error` — it alerts when the error is fixed

错误	错误原因	正确做法
将 `node16` 模块解析标记为旧版	只有裸 `"node"` 是旧版配置	查看strict-config.md中的标志表
使用 `any` 作为"以后再修复"的临时方案	`any` 会禁用下游所有类型检查	使用 `unknown` 并进行类型收窄
忽略跨领域instanceof问题	来自iframe/worker的对象会导致instanceof检查失败	使用品牌检查或Symbol.hasInstance
在审查模式下自动修复代码	审查应仅报告问题，不修改代码	阻止审批并描述问题；让作者自行修复
跳过交付成果步骤	用户仅得到建议而无实际输出	始终输出代码或结构化问题清单
将 `@ts-ignore` 与 `@ts-expect-error` 视为等价	`@ts-ignore` 会永久静默抑制错误	始终优先使用 `@ts-expect-error` — 当错误被修复时它会发出提醒

Reference routing

参考文档路由

File	Load when
type-system.md	Working with generics, conditional types, type guards, narrowing, variance
patterns.md	Implementing Result types, branded types, builders, middleware, retry logic
anti-patterns.md	Reviewing code for unsafe patterns or scanning for anti-pattern violations
error-handling.md	Implementing error handling, retry logic, error aggregation, or Result types
strict-config.md	Configuring or auditing tsconfig.json and strict mode flags
tooling.md	Setting up or choosing between ESLint, Biome, Prettier, CI pipelines
migration.md	Migrating JS to TS, upgrading TS versions, handling circular dependencies
performance.md	Diagnosing slow compilation, reading traces, optimizing type-check speed
testing.md	Writing type-level tests, choosing test strategies, testing generics
modern-features.md	Using decorators, `using` / `Symbol.dispose` , `satisfies` , inferred predicates

文件	加载场景
type-system.md	处理泛型、条件类型、类型守卫、类型收窄、方差相关内容
patterns.md	实现结果类型、品牌类型、构建器、中间件、重试逻辑
anti-patterns.md	审查代码中的不安全模式或扫描反模式违规情况
error-handling.md	实现错误处理、重试逻辑、错误聚合或结果类型
strict-config.md	配置或审核tsconfig.json与严格模式标志
tooling.md	设置或选择ESLint、Biome、Prettier、CI流水线
migration.md	JS转TS迁移、TS版本升级、处理循环依赖
performance.md	诊断缓慢编译问题、读取追踪信息、优化类型检查速度
testing.md	编写类型级测试、选择测试策略、测试泛型
modern-features.md	使用装饰器、 `using` / `Symbol.dispose` 、 `satisfies` 、推断谓词

Guardrails

约束规则

Never introduce
```
any
```
— use
```
unknown
```
and narrow
Never use
```
@ts-ignore
```
— use
```
@ts-expect-error
```
with explanation
Never use unchecked
```
as
```
— always guard first, then cast
Always add explicit return types to exported functions
Always verify tsconfig against strict-config.md baseline before suggesting config changes
In review mode: report findings, never silently modify code

绝不引入
```
any
```
— 使用
```
unknown
```
并进行类型收窄
绝不使用
```
@ts-ignore
```
— 使用带说明的
```
@ts-expect-error
```
绝不使用未检查的
```
as
```
— 始终先添加守卫，再进行类型转换
始终为导出函数添加显式返回类型
在建议修改配置前，始终将tsconfig与strict-config.md基准配置进行验证
审查模式下：仅报告发现的问题，绝不静默修改代码