claude code 生成 TypeScript 类型定义文件的方法

半年前，我接手了一个有着6年历史的电商中台项目。仓库里躺着200多个.js文件，没有一个类型定义。每次新同事入职，我都要重复同一句话：“看代码注释，虽然注释也没有。”给接口联调的时候，前端和Java后端的同学天天吵架，传参类型对不上，返回值结构猜不透，联调时间动辄三四个小时。

最让我记忆犹新的是去年双十一前的一次事故。物流模块一个函数把跟踪号从string悄悄改成了string[]，十几个下游服务直接挂掉，日志里全是trackingNumber.split is not a function。排查了两个小时，改回来花了30秒。那时候我在工位上想：要是有个完整的.d.ts文件，编译阶段就能拦住这个错误。

当时我试过微软的dts-gen、试过手动迁移、甚至考虑过直接把项目重写成TypeScript。全都不现实。直到我开始用Claude Code来系统性生成类型定义文件，效率才真正拉开了差距。

这篇文章，我把自己踩过的坑、打磨出的Prompt模型、以及六个月内实战积累的校验流程完整梳理出来。不讲泛泛的理论，只讲我怎么做的，以及你为什么应该这么做。

一、核心结论：Claude Code生成类型定义的真正价值不是“快”，而是“可持续”

先把我实践下来的核心结论摆出来，省得你翻到最后。

很多人第一次听说“用AI生成类型定义”，第一反应是：“快嘛，省时间。”但我想说的是，快只是个表面收益，真正改变工作方式的东西是这三个：

第一，类型定义从“一次性工程”变成了“随时可重建的产物”。过去手动写.d.ts，一旦源文件改了就面临同步更新的噩梦。用Claude Code，代码改了重新跑一遍Prompt，几分钟就能拿到对齐最新实现的新版本。维护成本归零。

第二，AI生成的内容不是成品，是高质量毛坯。这个认知特别关键。我见过有人直接用Claude Code生成的.d.ts提交PR，结果被同事指出十几个类型错误，从此对AI失去信心。问题不在AI，在于你把毛坯当精装交付了。正确的姿势是：AI生成占80分，人工校验补到95分，这才是效率最大化的节点。

第三，Prompt设计本身是技术资产。你用什么样的Prompt模型生成类型定义，直接决定了输出质量和后期修改成本。我在团队里沉淀了一套Prompt模板之后，新人第一天就能生成出和我打磨三个月同样质量的东西。这种可复制的确定性，才是Claude Code在工程团队里的真正护城河。

下面这张图能直观看到，在我自己的项目里，引入Claude Code后类型定义工作三个关键指标的变化：

你可能会问：89%的覆盖率够不够用？坦白讲，不够，但已经是巨大的进步。剩下的11%，是复杂泛型、运行时动态注入的类型、以及一些历史遗留的“魔法字符串”。这些后面我会专门讲怎么处理。

二、先理解场景：谁需要生成.d.ts，为什么现在这件事变得紧迫

你所在的组织正在发生的事

如果你在以下任何一种情况里，这篇文章对你就是刚需：

场景A：存量JS项目向TypeScript渐进迁移。 你的团队决定新代码用TS写，但老代码有几十个甚至上百个JS模块每天都在用。迁移计划排了半年，进度10%。原因很简单，类型定义是迁移的第一步，也是卡点。没有.d.ts，TS文件引不了JS模块；手动补全，工作量大到领导不敢批。

场景B：第三方内部库缺少类型支持。 你们公司有自己封装的工具库、组件库、中间件库，JavaScript写的，用了三四年。现在全公司推TypeScript，库的维护者说“等明年的迭代计划排上”。你等不了，每个引用都要自己declare module手写。

场景C：接手遗留系统，文档缺失。 这是最痛苦的。代码没有注释，原作者可能已经离职，.git/log里最近两年的commit message全是“fix”和“update”。你想搞清楚每个模块导出了什么、参数类型是什么，只能靠读源码和console.log。

这三个场景的共同点：类型定义的需求真实且紧迫，但传统方案（手动编写、工具生成、重写）的成本都太高。

为什么传统方案不好使了

我试过三条路，每条都走了一段，给你们省省时间：

dts-gen / ts-auto-gen这类自动化工具： 微软出的dts-gen我用了两周。它能基于运行时信息生成类型骨架，听起来很美好。实际问题在于，它只能“看到”模块导出的表层结构，对函数内部的类型流转、参数约束、回调签名几乎无能为力。举个例子，一个函数接受options对象，内部用Object.assign填充默认值，dts-gen推断出来的类型是any。你还是要手动去补。它解决的是“有没有”的问题，没解决“准不准”的问题。

大规模手动迁移： 我们团队曾经尝试过一个“人海战术”方案，抽三个前端，每人每天写5个模块的.d.ts，一个月搞定。两周后就放弃了。不是因为慢，是因为人写的东西天然不一致。小张喜欢用type，小李喜欢用interface，小王的泛型命名是T，小赵的是T1。合并到项目里的时候，类型定义之间的冲突比JS本身还多。更不要说人一多，对同一段代码的理解就会产生分歧，一个函数到底返回Promise<Order>还是Order？读取了四次源码才统一了意见。

直接重写成TypeScript： 对于还在频繁迭代的业务模块，这将是灾难。你在重写类型的同时，业务需求也在改。两边并行，合并成本成倍增加。而且不是所有模块都值得重写，有些逻辑虽然用JavaScript写，但运行稳定，两年没动过。这种情况下，“为类型而重写”的ROI太低了。

Claude Code的定位：不是替代方案，是排列组合里的最优解

我在做了所有这些尝试之后，把Claude Code定位成什么？它不是银弹，但它是在“成本-质量-速度”不可能三角里，目前能找到的最优平衡点。

解释一下这句话。dts-gen成本低、速度极快，但质量不可控。手动编写质量可控，但成本高、速度慢。Claude Code的特点是：速度接近自动化工具，质量接近中级开发者水平，成本集中在Prompt设计和结果校验这两个环节。 而这两个环节，恰恰是可以标准化和复用的。

这也是为什么我花大力气梳理了一套Prompt模型。模型好了，速度和质量同时上去，成本下来了。这算是我这半年最重要的发现。

三、常见误区：80%的人第一次用Claude Code生成类型定义会踩的五个坑

在讲正确方法之前，先讲错误。因为我在社区、技术群、以及自己带的新人身上观察到，大部分人第一印象就把这件事做歪了。如果你已经踩过这些坑，这一节能帮你定位问题；如果还没开始用，看完能省你两周弯路。

误区一：把Claude Code当成“一键生成”工具

最常见的做法：打开终端，输入生成这个文件的类型定义，然后把JS文件内容一股脑扔进去，等十几秒，输出一个.d.ts，复制粘贴到项目里，提交。

结果通常是这样的：

• 输出的类型定义里，所有参数都是any
• 复杂对象的嵌套结构被简化成了Record<string, any>
• 函数重载全部丢失

根因不在AI，在于你没有给它足够的上下文和约束。

Claude Code本质上是一个语言模型，它需要你明确告诉它：你要什么层级的类型精确度、你是否接受any的使用、你期望的类型命名风格是什么。你把所有决策权交给它，它就给你最低成本的答案，因为这是模型在信息不足时的安全策略。

误区二：单文件思维，忽略模块引用关系

一个JS模块，内部引用了另一个兄弟模块的函数。你只把当前模块的代码给Claude Code，它不知道引用模块的类型，于是所有跨模块的类型都被推断为any。

我最初的解决方案是：把所有相关文件的内容都塞进Prompt。效果确实好了一点，但Token消耗暴涨，而且Claude Code经常“记不住”太长的上下文。

后来我打磨出的做法是：先建立类型上下文，再请求类型生成。 具体来说，先用一次对话请求Claude Code：“请分析以下三个模块（贴上关键API的代码），总结它们的导出类型签名。”然后再用第二次对话：“基于你总结的类型签名，为模块A生成完整的.d.ts。”这个方法把跨模块引用准确率从40%左右提升到了75%以上。虽然还不是100%，但已经省下大量手动修正的时间。

误区三：忽视“any”的传染性

TypeScript里有一个恐怖的东西叫类型推断退化。一旦类型链路上出现一个any，下游所有类型推断都会退化为any。你花了大力气为一个函数声明了精确的类型，但因为它依赖的一个中间库的类型定义里有any，结果你的类型体操全白做。

Claude Code在风格上更倾向于保守，它在不确定的时候会主动使用any来避免类型错误。这很安全，但也很没用。

我的做法是：在Prompt里明确加一句约束，

> “禁止使用any类型。对于不确定的类型，使用unknown代替，并添加注释说明为什么此处使用了unknown。”

这个小小的约束，把生成结果的any数量从平均每个文件12个降到了2个以内。剩下的unknown你一眼就能定位，手动改成精确类型比在海量any里搜寻不知强多少。

误区四：不验证就交付

我团队里一个实习生，用Claude Code生成了一批类型定义，兴冲冲地提交了PR。代码review的时候，我发现他把一个联合类型string | number错误地推断成了string。问题出在哪儿？原始代码里，number值是通过parseInt转换的，Claude Code看到参数是string类型，就没往number方向想。

这不是AI的错，是类型推断本质上需要理解业务语义，而静态代码分析做不到这一点。

我的铁律是：AI生成的.d.ts文件，必须在tsc --noEmit下跑一遍，并且在实际调用的TS代码中引用测试。编译通过不意味着类型正确，但编译不通过意味着一定有问题。这是一个必要的门禁。

误区五：在单一文件上过度优化Prompt

有些人（包括曾经的我）有一种执念：一定要让Claude Code一次性输出完美的类型定义。于是不断调Prompt，加约束，测了20版还在纠结一个联合类型的命名问题。

这么做的问题在于：你的时间投入和AI产出的边际提升不成正比。 我用数据说话：

看到这个表你就该明白了：把Prompt优化到85%-90%的准确率，然后剩下的交给人工校验，是效率最高的策略。 追求从90%到95%的那5%，AI不适合干这个，花的时间够你手动修完所有问题了。

四、专业判断逻辑：我的“信息密度”决策框架

前面讲了误区，现在讲判断逻辑。这一节是整个文章的方法论核心，它不是操作手册，而是你在遇到不同项目、不同代码风格时，如何决定自己的策略。

什么是“代码信息密度”

这个概念是我自己总结的，用来评估一段JS代码适不适合让Claude Code生成类型定义，以及生成之后需要多少人工修正。

信息密度 = 类型结构复杂度 / 代码行数

简单说：

• 高信息密度代码：一个20行的函数，参数是嵌套了三层的对象，返回值根据条件分支变化，内部用了reduce做数据聚合。这种代码，类型推断难度高，Claude Code容易出错。
• 低信息密度代码：一个200行的模块，大部分是简单的CRUD操作，导出几个平铺的对象和函数。这种代码，类型结构简单，Claude Code的表现通常很好。

我拿自己项目里的模块做过分析：

这个表不是我编的，是我用6个月时间里生成过的47个模块记录下来的真实数据。它告诉我一件事：不要对所有模块用同一种策略。

基于信息密度的决策树

根据上面的数据，我提炼了一套决策逻辑：

低信息密度模块 → 标准Prompt + 自动化流程。 一次生成，tsc校验，少量手工修正，直接交付。这类模块占大多数，也是Claude Code最能发挥效率的场景。

中信息密度模块 → 增强Prompt + 上下文补充。 需要额外提供相关模块的类型签名作为上下文。生成后需要逐段review。准确率通常在80%-90%。

高信息密度模块 → AI生成骨架 + 人工精修。 别指望Claude Code能一次性搞定复杂的泛型推导和条件类型。让AI生成一个结构框架（声明了所有导出、参数和返回值，但类型可以用unknown占位），然后你手动替换精确类型。这样比全部手写快，也比只靠AI靠谱。

动态类型模块（运行时注入、原型链修改） → 不适合AI生成。 如果代码里大量使用Object.defineProperty、Proxy、原型链动态修改，Claude Code的静态分析完全失效。这种情况下，手动写类型定义比修正AI的错误输出更快。认栽。

为什么不用“复杂度”而用“信息密度”

你可能注意到我刻意避免用“模块复杂度”这个词。因为复杂度有很多维度，圈复杂度、依赖数、代码行数。这些和类型推断的难度不完全相关。

举个例子：一个递归算法模块，圈复杂度很高，但接收的参数很简单（一个数组和一个回调），返回一个布尔值。Claude Code处理起来几乎没问题。而一个配置管理模块，平铺直叙几百行，但内部有大量对象展开、条件合并、动态键名，AI几乎全猜错。

信息密度更精准地描述了“类型相关的工作量在代码中的集中程度”。 用它来判断AI的适用性，比我之前用的任何维度都准。

五、具体实操：我的Prompt模型与完整工作流

终于进入动手环节。这一节全是操作细节，一步一截图，一步一解释。

准备工作

在开始之前，确认你的环境：

{
Claude Code已安装并登录。我使用的是Anthropic的官方Claude Code CLI工具，模型选用Claude Sonnet 4。为什么不用Opus？我实测过，Opus在类型生成上只比Sonnet好大约5个百分点，但速度慢一倍，Token消耗高30%。对于批量生成场景，Sonnet是最佳性价比选择。
项目根目录下有.claude/settings.json。我在里面配置了：
"permissions": {

"allow": ["Read", "Write"]

}

}

这样Claude Code可以直接读取项目文件，不需要我每次手动粘贴代码。效率高很多。

对目标文件有基本了解。在开始生成之前，花两分钟扫一眼JS代码，判断它的信息密度等级。这一步决定你接下来用什么策略。

我的Prompt模型（五层结构）

经过上百次的Prompt调试，我最终稳定下来一个五层结构：

[角色设定] + [任务定义] + [源文件引用] + [输出约束] + [格式规范]
每一层拆开来讲：

第一层：角色设定

不是随便写一句“你是一个TypeScript专家”就完事。我现在的版本是：

> “你是一位专精于TypeScript类型系统的高级前端工程师。你擅长阅读JavaScript代码并推断精确的类型签名。你对any类型持零容忍态度，倾向于使用unknown、泛型约束、条件类型来保持类型安全。”

为什么要强调“零容忍态度”？因为Claude Code默认的行为模式是遇到不确定就放宽类型约束，我需要用强语气扭转这个默认倾向。

第二层：任务定义

这一层要极度具体。不是“生成类型定义”，而是：

> “为指定的JavaScript模块生成对应的TypeScript声明文件(.d.ts)。你需要导出模块中所有公共API的完整类型签名，包括但不限于：函数参数类型、返回值类型、对象属性类型、回调签名、Promise包裹类型。对于使用了泛型的函数，请保留泛型参数并添加适当的约束。”

第三层：源文件引用

如果Claude Code已经配置了文件读写权限，直接使用：

> “请读取src/services/logistics/目录下的以下文件：tracking.js, freight.js, warehouse.js。注意freight.js中引用了tracking.js的formatTrackingNo函数，请在推断类型时考虑这个跨模块依赖。”

如果你没有配置文件权限，就把关键代码片段粘贴进去。但注意，不要一次性贴超过1000行的代码，Claude Code的注意力机制在超长输入下会衰减。分批处理，每批3-5个中小文件。

第四层：输出约束

这是我迭代最多的部分。当前版本包含这些约束：

“禁止使用any类型。 对于不确定的类型，使用unknown并添加// TODO: verify this type注释。”

“保留原始JSDoc注释作为类型定义中的注释。”

“优先使用interface而非type 来定义对象结构，除非是联合类型或映射类型。”

“导出的所有类型声明必须使用export关键字。”

“不要修改或重新格式化原始代码中的字符串字面量类型。”

“对于Node.js回调风格（如(err, result) => void），请正确推断err的类型为Error | null。”

这套约束是我在实践中一个一个加出来的。最开始只有两条，后来每次遇到新类型的错误，我就加一条对应的约束。现在它稳定在了12条。

第五层：格式规范

> “输出格式：只输出.d.ts文件的完整内容，不要包含任何Markdown代码块标记，不要包含任何解释性文字。文件开头使用declare module包装，模块名从文件路径推断。”

这一层看着简单，但解决了最大的工程问题，可复制性。AI生成的内容如果没有统一的格式约束，有些会包在\\\typescript`里，有些会在开头加一段说明，有些会在末尾问“需要我调整吗”。格式不一致，批量处理的时候就会变成灾难。

实例一：标准模块生成全过程

拿我实际处理过的一个模块举例。这是我们项目中一个订单金额计算工具函数，JavaScript写的，代码大概200行，属于低信息密度模块。

源文件calculateAmount.js的核心结构：

导出函数calcItemTotal(price, quantity, discount)：接收三个number参数，返回number

导出函数applyPromo(amount, promoCode, config)：第二个参数是string，第三个参数是一个比较复杂的对象

导出常量TAX_RATE = 0.06

导出变量DEFAULT_CONFIG：一个嵌套对象

完整的Prompt输入：

> “你是一位专精于TypeScript类型系统的高级前端工程师。请为src/utils/calculateAmount.js生成完整的.d.ts类型声明文件。

>

> 该文件导出了：calcItemTotal, applyPromo, TAX_RATE, DEFAULT_CONFIG。

>

> 请读取该文件并生成类型定义。

>

> 约束：

> - 禁止使用any，不确定时使用unknown

> - 保留原始JSDoc注释

> - 使用export导出所有声明

> - 输出仅为.d.ts内容，不含Markdown标记

> - 模块名使用calculate-amount”

Claude Code的输出：

declare module 'calculate-amount' {
/

计算单个商品项的金额

@param price - 商品单价

@param quantity - 购买数量

@param discount - 折扣率，0-1之间

*/

export function calcItemTotal(

price: number,

quantity: number,

discount: number

): number;

/

应用促销规则计算最终金额

@param amount - 初始金额

@param promoCode - 促销码

@param config - 促销配置对象

*/

export function applyPromo(

amount: number,

promoCode: string,

config: PromoConfig

): number;

export interface PromoConfig {

/ 最低消费门槛 */

threshold: number;

/ 折扣类型 */

type: 'percentage' | 'fixed';

/ 折扣值 */

value: number;

/ 是否可与其他优惠叠加 */

stackable: boolean;

/ 排除的商品分类ID列表 */

excludeCategories?: string[];

}

/ 默认税率 */

export const TAX_RATE: number;

/ 默认促销配置 */

export const DEFAULT_CONFIG: PromoConfig;

}

declare module 'route-planner' {
export interface GraphNode {

id: string;

label: string;

// TODO: 类型随业务场景变化，需要精确定义

metadata: unknown;

}

export interface Graph {

nodes: GraphNode[];

adjacency: number[][];

}

// TODO: 这是可辨识联合类型，成功和失败时的结构不同

export type RouteResult =

| { path: unknown[]; cost: number; success: true }

| { error: string; success: false };

export function findRoute(

graph: Graph,

start: string,

end: string,

options?: {

/ 最大搜索深度 */

maxDepth?: number;

/ 避开的节点ID列表 */

avoidNodes?: string[];

}

): RouteResult;

}

拿到这个骨架后，我再花20分钟，把unknown换成精确类型，把GraphNode.metadata拆成联合类型，把RouteResult.path的类型从unknown[]改成TNode[]并加上泛型参数。

总耗时30分钟。如果我不用AI直接从零手写，同样的模块需要1小时以上。省了50%的时间，而且省在“搭建类型框架”这个最磨人的环节。

批量处理工作流

当你有几十个文件要处理时，单个文件的做法效率还不够。我设计了一套批处理流程：

第一步：分类。 把所有JS文件按信息密度分成三组。这一步不需要精确分析，扫一眼就能判断。

第二步：优先级排序。 先处理“被最多其他模块引用的核心模块”。这些模块的类型定义一旦完成，后面处理依赖模块时，Claude Code就可以把这些已有类型作为上下文，大幅提升准确率。

第三步：建立类型上下文库。 每完成一批核心模块，我就在一个types-context.md文件里记录它们的核心类型签名。后续处理外层模块时，在Prompt里引用这个文件。

第四步：自动化脚本串联。 我写了一个简单的Node.js脚本：

• 读取待处理的文件列表
• 拼接Prompt（调用上面说的五层模型模板）
• 逐文件调用Claude Code CLI
• 将输出写入对应的.d.ts文件
• 对每个生成结果执行tsc --noEmit，标记编译失败的模块

这套流程让我在两小时内处理完了32个工具类模块，其中28个编译通过，4个需要手动修复。而纯手写同样数量，预估工时是3个工作日。

六、验收标准：生成之后你必须做的四件事

AI生成的内容，不经校验就直接用，迟早出事。我给自己和团队定了四条验收标准，缺一不可。

一、编译器校验（门禁级别）

这是最低标准。对每个生成的.d.ts文件，执行：

npx tsc --noEmit --strict
会报两种错误。一种是“真的错了”，类型签名和实际代码对不上，必须修。另一种是“过于严格”，比如strictNullChecks下，一个可能为null的值你用string声明了，编译器报错。这种错误要判断：到底是类型声明写错了，还是代码本身有潜在的null安全问题。

我的经验是：不要因为编译器报错就放宽类型。 如果代码真的可能为null，在类型定义里就应该反映这一点（用string | null）。这恰恰是TypeScript引入类型系统的初衷，暴露潜在的运行时风险。

二、交叉引用的完整性检查

编译器不会告诉你的事，你的类型定义是不是孤立于项目之外。

具体做法：在项目中找一个实际引用了该模块的TS文件（没有就新建一个临时的），写几行简单的调用代码：

import { calcItemTotal, applyPromo, PromoConfig } from 'calculate-amount';
// 故意传错参数类型，看编译器能不能捕获

calcItemTotal(100, 2, 0.1);  // 正确

calcItemTotal('100', 2, 0.1);  // 应该报错

// 检查复杂类型能否正常使用

const config: PromoConfig = {

threshold: 100,

type: 'percentage',

value: 20,

stackable: true

};

applyPromo(200, 'PROMO2024', config);

如果这些代码编译通过，且IDE能正确提供自动补全，你的类型定义就算立住了。

三、any渗透审计

我前面说过，Claude Code有时会在不应该的地方偷偷用any。验收的时候必须专门查一遍。

我用的命令：

grep -n 'any' generated-types/*.d.ts
对每个出现的any，问自己三个问题：

这个any是AI偷懒用的，还是确实无法确定类型？
如果是无法确定，能否用unknown+类型守卫替代？
如果确实需要any（比如函数重载的场景），是否添加了注释说明原因？
我的标准是：一个类型定义文件里，any的出现次数不应超过3次，且每次都必须有注释。

四、与源码同步更新的机制

这一条解决的是“生成完就过时”的问题。

我的做法：在JS源码文件头部加入一个特殊注释：

/

@dts generated-by-claude-code

@dts-last-sync 2025-06-15

@dts-md5 a1b2c3d4

*/

同时维护一个Git hook（pre-commit），检测JS文件的MD5是否和.d.ts记录中的一致。如果不一致，在commit时给出警告：“类型定义可能已过时，请在合并前重新生成。”

这套机制不能完全自动化，但至少能在你忘记更新类型定义的时候提醒你。对于团队协作，这种提醒已经足够有价值。

七、不同场景下的策略取舍

不是所有情况都适合用Claude Code。这一节讲几个做决策的关键分界线。

新建项目 vs 遗留项目

新建项目，直接上TypeScript，不需要Claude Code生成类型定义。 这是在浪费时间。类型定义应该和代码一起写，原生TS的类型系统比任何AI推测都精确。

遗留JS项目，且TypeScript迁移在计划中或已经在进行中，Claude Code是目前最佳的类型定义初始化方案。 它能在一周内完成手动需要数月的工作量。

遗留JS项目，但短期内没有TypeScript迁移计划。 我的判断是：如果项目还在活跃迭代，值得用Claude Code生成一套.d.ts，给自己（和同事）提供编辑器智能提示和类型检查。如果项目已进入维护模式，改动频率很低，手动维护一套最小化的类型定义就够了，不值得为生成和校验投入时间。

内部库 vs 对外暴露的API

内部使用的工具库、组件库，用Claude Code生成类型定义，验证通过后交付，ROI极高。因为使用者是内部同事，即便类型有少量偏差，发现问题、沟通、修正的链路很短。

对外发布的开源库或SDK，类型定义是产品的一部分。用户会根据.d.ts文件判断你的库是否“好用”。这种情况下，Claude Code只能作为初稿工具。最终发布前必须经过人工逐行review，确保类型命名符合社区惯例、泛型设计合理、没有任何any或unknown暴露给用户。我个人的标准是：对外发布的类型定义，每行至少经过两次人工检查。

数据密集型 vs 逻辑密集型代码

数据密集型代码（大量的对象定义、API响应结构、配置类型），Claude Code极其好用。这类代码的模式重复但结构嵌套，AI生成既快又不容易出错。我在处理一个API网关项目的80个接口响应类型时，Claude Code一次性生成，正确率超过90%。

逻辑密集型代码（复杂算法、状态机、设计模式实现），AI的表现明显下降。不是因为它不能理解逻辑，而是理解逻辑所需的“思考”在类型定义这个环节体现不出来。它只能看到参数和返回值，看不到函数内部的类型流转。这类代码，手动编写类型定义仍然是更可靠的选择。

时间资源的分配决策

我用一个简单的公式来指导自己的决策：

如果(模块数量 > 20 且 预计手动工时 > 40小时 且 信息密度平均 → 投资建立批量生成流程 + Prompt模板

否则

→ 逐模块手动编写或使用简化类型声明

这个公式帮我避免了一种常见情况：花了三天时间搭自动化流程，结果只需要处理6个模块。自动化有固定成本，规模不够的时候，手动做反而更经济。

八、进阶话题：当Claude Code生成的类型定义需要扩展时

生成的类型定义不是终点。你会遇到需要扩展的情况，源文件加了新函数、改了参数结构、或者你发现类型不够精确想要增强。

如何用Claude Code做增量更新

场景：一个模块原本有5个导出函数，你生成了.d.ts。现在源码里加了第6个函数。

不要全量重新生成。 全量生成会覆盖你之前手动修正过的部分（那些精细的泛型约束、你手动把unknown改成精确类型的地方）。重新修正的成本可能比新增的工作量还大。

我的做法：

1. 把新增的代码和现有的.d.ts一起喂给Claude Code：
   > “以下是模块A的当前类型定义文件（粘贴.d.ts内容）。源码中新增了以下函数（粘贴新函数代码）。请更新类型定义文件，只新增必要的类型声明，不要修改已有的类型定义。”
2. 手动对比Claude Code输出的diff，确认它只改了新增的部分。
3. 如果Claude Code“手痒”改了已有定义（它有时会“优化”已有类型），直接拒绝，只接受新增部分的改动。

这个方法把增量更新的时间控制在5分钟以内，而全量重新生成加重新校验通常需要20分钟以上。

从.d.ts反向生成接口文档

一个意外收获：类型定义本身就是最精确的接口文档。

我发现，一套完整的.d.ts文件，配合TypeScript的类型提取，可以自动生成API文档。我的做法是使用typedoc工具，配置它只扫描.d.ts文件：

npx typedoc --entryPoints generated-types/ --out docs/api

生成的文档包含所有函数签名、参数说明（JSDoc注释自动转换）、类型约束。而且文档和代码的类型定义严格同步，因为文档就是从类型定义生成的。

这个效果让我在团队内部推广类型定义生成的时候，多了一个强大的说服点：这不只是开发体验的提升，连带文档都一起搞定了。

团队协作中的版本控制策略

.d.ts文件要不要提交到Git仓库？这是一个在社区里争论不休的问题。

我的实践结论是：分情况处理。

由Claude Code生成、经过人工校验的类型定义：提交。 它们是源码的编译产物，但经过了人工验证，可以视为“团队工程师认可的接口契约”。提交到仓库，其他人在不同分支上都能受益。

未经校验的AI原始输出：绝不提交。 建立一个generated-types/.draft/目录，加入.gitignore。原始生成结果放这里，校验通过后再移到正式目录。

对于需要频繁重新生成的模块（源码改动频繁），可以只提交校验脚本，在CI中自动生成类型定义并检查。代码仓库保持轻量，生成逻辑保持可复现。

九、我犯过的最大错误与最终认识

写到这里，我想坦诚地分享一个反思。

刚开始使用Claude Code生成类型定义的时候，我脑子里有一个隐含的目标：让AI全自动、零人工介入地输出完美的类型定义。 我花了大量的时间调Prompt、处理边界case、甚至研究Claude Code的内部行为模式，幻想有一天达到这个目标。

直到某一天，我在处理一个特别复杂的模块时，意识到一个问题：为了节省20分钟的手动修正时间，我已经花了4个小时调试Prompt。这个账根本算不过来。

从那以后，我调整了自己的预期模型：Claude Code不是全自动工厂，是高效率的半自动机床。它做粗加工，我做精加工。 45分钟的活它干15分钟，剩下5-10分钟我收尾。总时间从45分钟降到20-25分钟，一天能处理的模块量从6个涨到15个以上。

更重要的是，我不再因为AI偶尔犯的错误而焦虑。因为在我的工作流里，错误是预期之内的事，校验环节就是为了捕获和修正这些错误而存在的。

追求的是“系统的可靠输出”，而不是“单次输入的完美结果”。 这是我花了半年时间才真正理解的东西。

十、总结：下一步你该做什么

读完这篇文章，你已经有了完整的方法论。但我知道，理论和实践之间有巨大的鸿沟。以下是我建议的启动步骤，按优先级排列：

1. 今天就挑一个低信息密度的模块试手。 不要一口气处理整个项目，找一个简单的工具函数文件，用我在第五节给的Prompt模型跑一遍。感受整个流程：Prompt输入 → 生成 → tsc校验 → 人工修正。这个过程大概15-30分钟，让你对AI的实际表现有一个真实的判断基准。

2. 建立你自己的约束清单。 我在第四节给出的12条约束是针对我的项目优化出来的。你的项目有自己特有的代码风格、命名惯例、类型使用偏好。每遇到一个新类型的问题，就把对应的约束加到你的Prompt模板里。一个月后，你会有一个完全适配自己项目的高精度Prompt。

3. 先把核心依赖模块的类型定义搞定。 不要按文件顺序处理，按依赖顺序。找出被引用最多的那10个模块，优先生成它们的类型定义。这些核心类型一旦到位，后续所有依赖模块的生成准确率会明显提升。

4. 设置质量门禁。 在项目的husky或CI中加入类型定义的校验步骤。不求全自动，但求在每次有人试图提交过时的类型定义时给予警告。团队越大，这个机制的价值越高。

5. 接受“85%就是好结果”。 不要被完美主义拖垮。AI给你85%的准确率，剩下15%手动修正。总效率仍然远高于纯手动。追求从85%到95%，你投入的时间可能比从0%到85%还多。不值得。

半年前那个让我凌晨三点还在排查物流错误的日子里，我从未想过类型定义这件事可以被这样重新定义。Claude Code没有替我做所有的工作，但它替我做掉了最无聊、最重复、最消磨人的那部分。我负责判断，它负责执行。

这才是AI辅助编程该有的样子。不是为了偷懒，是为了把有限的精力，花在真正需要人类判断力的事情上。

如果你也在类型定义的泥潭里挣扎，希望这篇文章能帮你走出来。开始动手，从一个文件开始。