TypeScript AI编程：从“瞎写”到“可控”的工程实践指南

1. 从“AI瞎写”到“代码可控”一个TypeScript开发者的真实困境如果你和我一样是个重度依赖AI辅助编程的TypeScript开发者那你一定经历过这种场景面对一个复杂的业务逻辑你满怀期待地向ChatGPT或Claude抛出一个问题它“唰”地一下生成了一大段看起来功能完备的代码。你兴冲冲地复制粘贴到项目里VSCode的TypeScript服务器立刻开始疯狂报错类型不匹配、属性未定义、泛型推断失败……红色的波浪线瞬间爬满了屏幕。你不得不像个考古学家一样逐行去“修复”AI生成的代码这个过程往往比你自己从头写还要耗时。更糟糕的是为了快速让错误消失你可能会引入一些as any的暴力类型断言或者把本应严谨的接口定义得松散无比。几次迭代下来一个本应清晰的项目逐渐变成了连自己都看不懂的“类型屎山”——这就是典型的“AI瞎写”导致的恶果。我最近在GitHub上关注到TypeScript专家Matt Pocock提出的一个概念他称之为“Skill”。这并非一个具体的库或框架而是一套方法论和最佳实践的集合核心目标直指我们上述的痛点如何有效地约束和引导AI让它生成出高质量、类型安全、易于维护的TypeScript代码从而避免“瞎写”和“造山”。在AI编程助手日益普及的今天这已经从一个“锦上添花”的技巧变成了关乎项目长期健康度的“生存技能”。本文将结合我自己的实践深入拆解Matt Pocock“Skill”包的核心思想并分享一套可落地的实操方案。2. 理解“Skill”的本质不只是提示词工程很多人一听到“引导AI”第一反应就是去优化提示词Prompt。这没错但Matt Pocock的“Skill”概念走得更远。它更像是一套用于与AI协作的“开发约束体系”。这个体系包含多个层次2.1 环境层配置即合约你的tsconfig.json、eslint.config.js、prettier.config.js这些配置文件不仅仅是工具设置更是你与AI之间的“质量合约”。一个松散的配置会默许AI生成各种投机取巧的代码。实战配置升级以tsconfig.json为例大多数人使用的是tsc --init生成的默认配置这给了AI太大的“自由发挥”空间。我们需要收紧策略{ compilerOptions: { strict: true, // 启用所有严格类型检查选项的快捷方式 noImplicitAny: true, // 禁止隐含的any类型 strictNullChecks: true, // 严格的null和undefined检查 strictFunctionTypes: true, // 对函数类型进行更严格的检查 strictBindCallApply: true, // 对bind、call、apply进行严格检查 noImplicitThis: true, // 禁止this表达式的隐含any类型 alwaysStrict: true, // 以严格模式解析并为每个源文件生成use strict exactOptionalPropertyTypes: true, // 可选属性必须明确设置为undefined noUncheckedIndexedAccess: true, // 访问索引签名时类型包含undefined // 重要明确弃用警告避免未来兼容性问题 ignoreDeprecations: 5.0, // 如果你在使用TypeScript 5.0可以忽略特定版本的弃用警告。注意选项“baseUrl”在TS 5.0的某些版本中已被标记为弃用建议使用paths配合baseUrl的替代方案或查阅最新文档。 } }注意关于baseUrl弃用的问题这是一个常见的坑。在较新版本的TypeScript中baseUrl选项可能被标记为弃用。更推荐的做法是使用paths配置来定义模块路径映射或者使用如tsconfig-paths这样的工具。在AI生成涉及路径配置的代码时一个严格的tsconfig会立刻暴露这种过时的用法迫使你或引导AI使用更现代、更推荐的方式。为什么这么做当你的编译器选项如此严格时AI生成的任何偷懒的any类型、可能为null的未处理情况、不严谨的函数签名都会立刻被编译器揪出来。这迫使AI实际上是通过你去要求AI必须在第一次尝试时就给出类型严谨的代码。2.2 模式层建立代码“成语”库“Skill”的第二个层面是定义一套项目内公认的代码模式或“成语”。AI不擅长发明但擅长模仿和组合。如果你告诉它“在我们项目中处理异步数据流统一使用try/catch配合Result类型模式”或者“状态管理一律使用useReducer配合特定的action结构”那么AI后续生成的代码就会高度一致可读性和可维护性大大提升。例如你可以为AI提供这样的上下文可以放在一个专门的patterns.md文件里或在复杂的提示词中引用## 本项目数据获取模式 - 函数命名fetchXxx 表示可能抛出错误的原始获取getXxx 表示处理了错误、返回安全结果的函数。 - 错误处理使用 try/catch将错误转换为统一的 AppError 类型。 - 返回类型使用 PromiseResultT, AppError 模式其中 Result 为 { success: boolean; data?: T; error?: AppError }。当你的需求是“写一个获取用户信息的函数”时AI基于这个上下文生成的代码就会自然符合项目规范而不是随意发明一种新的错误处理方式。2.3 工具层善用VSCode插件与AI专属技能这就是“Skill”更字面意思的一层。除了通用的AI助手现在有很多工具能直接将最佳实践“注入”到AI的交互中。Claude Code / Cursor的“技能”功能像Cursor编辑器内置的AI或Claude for Code允许你定义自定义的“技能”Skills。你可以创建一个名为“TypeScript Strict Mode Helper”的技能其系统提示词就包含了你项目的tsconfig严格规则摘要和代码模式。每次与AI对话时激活这个技能它就相当于带上了你项目的“开发规范手册”。专门的AI编码助手插件有些VSCode插件专门为优化AI代码生成而设计。它们可以在后台分析你的项目结构、依赖和代码风格并自动调整发送给AI模型的提示词使其生成更贴合本项目的代码。利用GitHub Copilot的上下文Copilot会读取你当前打开的文件和相邻文件来提供建议。因此有意识地在项目根目录或常用工具目录放置高质量的“样板代码”文件如/patterns/async-wrapper.ts能显著提升Copilot建议的质量。Copilot看到这些样板会倾向于推荐类似的模式。3. 构建你的防“屎山”工作流从提问到合并有了“Skill”的理念和分层我们需要将其融入日常开发工作流。下面是一个我经过多次踩坑后总结出的、可操作的四步工作流。3.1 第一步精准提问——提供“超配”上下文向AI提问时最常见的错误是上下文不足。不要只说“帮我写一个用户登录的API函数”。你要提供一份“需求规格说明书”技术上下文 “这是一个Next.js 14项目使用App Router已经配置了next-auth。数据库是Prisma ORM连接PostgreSQL。”代码上下文 直接粘贴相关模型定义、工具函数或环境变量结构。// 粘贴你的Prisma User模型定义 model User { id Int id default(autoincrement()) email String unique name String? password String } // 粘贴你的环境变量类型定义 declare namespace NodeJS { interface ProcessEnv { DATABASE_URL: string; NEXTAUTH_SECRET: string; } }约束条件 “函数必须完全类型安全使用try/catch处理Prisma错误返回类型为PromiseResult{id: number, email: string}, AuthError并且要包含输入验证使用Zodschema是z.object({email: z.string().email(), password: z.string().min(6)})。”这样提问AI生成垃圾代码的概率会急剧下降。它是在你画的“框框”里创作。3.2 第二步即时验证——编译器作为第一道关卡AI给出代码后绝对不要直接复制到大段业务逻辑中。应该创建一个临时测试文件如/tmp/ai-test.ts。将AI生成的代码粘贴进去。立即运行TypeScript编译器检查npx tsc --noEmit /tmp/ai-test.ts。如果出现类型错误不要手动修。把错误信息直接反馈给AI“你生成的代码在严格模式下有这些类型错误[粘贴错误信息]请修正。” 让AI自己学习并纠正。这个过程本身就是在训练AI适应你的“Skill”环境。3.3 第三步风格规整——让AI学习你的代码“相貌”通过编译器检查后代码在逻辑和类型上可能没问题了但风格可能与你项目不符比如缩进、引号、命名习惯。这时不要自己动手格式化。如果你配置了Prettier和ESLint直接对临时文件运行npx prettier --write /tmp/ai-test.ts npx eslint --fix /tmp/ai-test.ts。观察自动修复了哪些地方。如果有些ESLint规则如命名约定无法自动修复将这些规则警告再次反馈给AI“代码需要遵守我们的ESLint规则特别是变量命名应采用camelCase函数名应为PascalCase等。”经过几次迭代AI会逐渐“记住”你项目的代码风格偏好。3.4 第四步人工复审——最后的逻辑与设计把关自动化工具能解决语法和风格问题但无法理解业务逻辑的深意。这是你必须介入的一步。审查重点边界情况 AI是否处理了空数组、null/undefined输入、网络超时、并发冲突性能影响 循环内是否有不必要的计算数据库查询是否可能产生N1问题安全性 用户输入是否经过充分的验证和转义是否有敏感信息泄露的风险依赖引入 AI是否不必要地引入了新的第三方库或者使用了项目中已废弃的旧API将你发现的问题再次作为“需求变更”或“Bug报告”提交给AI让它修正。这个过程循环往复直到代码达到可合并的标准。4. 高级技巧利用TypeScript类型体操主动约束AI对于中高级TypeScript开发者可以更进一步利用TypeScript强大的类型系统本身作为“AI约束框架”。这相当于为AI编程划定了一个绝对无法越界的“类型安全围栏”。4.1 定义“品牌类型”防止概念混淆AI经常混淆概念相似的参数。比如userId和orderId可能都是number类型但逻辑上绝不能混用。我们可以定义“品牌类型”// 定义品牌类型基础工具 type BrandT, B extends string T { __brand: B }; // 创建具体的品牌类型 type UserId Brandnumber, UserId; type OrderId Brandnumber, OrderId; type EmailAddress Brandstring, EmailAddress; // 构造函数通常来自验证逻辑 function toUserId(id: number): UserId { // 这里可能有验证逻辑比如检查ID是否为正整数 if (id 0) throw new Error(Invalid User ID); return id as UserId; } function toEmailAddress(email: string): EmailAddress { const emailRegex /^[^\s][^\s]\.[^\s]$/; if (!emailRegex.test(email)) throw new Error(Invalid email address); return email as EmailAddress; } // 使用场景AI生成的函数签名会被严格约束 declare function getUserOrders(userId: UserId, orderId: OrderId): PromiseOrder[]; declare function sendNotification(to: EmailAddress, message: string): Promisevoid; // 测试 const uid toUserId(123); const oid 456 as OrderId; // 注意直接断言是危险的应使用构造函数 const email toEmailAddress(testexample.com); getUserOrders(uid, oid); // OK getUserOrders(oid, uid); // 类型错误TS会报错Argument of type OrderId is not assignable to parameter of type UserId.当你要求AI“编写一个根据用户ID和订单ID查询详情的函数”时如果你在上下文中提供了UserId和OrderId这两个品牌类型AI生成的函数签名就会正确使用它们。如果它试图用number严格的tsconfig会报错如果它把参数顺序写反类型系统会立即捕获。这从根本上杜绝了一类隐蔽的Bug。4.2 使用模板字面量类型约束字符串格式对于有固定格式的字符串如API路径、特定的编码字符串可以使用模板字面量类型。type ApiRoute /api/v1/${users | products | orders}; type ResourceId ${string}-${string}-${string}-${string}-${string}; // 简化版UUID格式 declare function fetchApi(route: ApiRoute, id: ResourceId): Promiseany; // AI生成的调用如果不符合格式将无法通过编译 fetchApi(/api/v1/users, 550e8400-e29b-41d4-a716-446655440000); // OK fetchApi(/api/v1/items, some-id); // 类型错误items不在联合类型中且id格式不对。通过预先定义这些精细的类型你相当于为AI设定了一条“类型轨道”它生成的代码只要在类型上正确在逻辑上犯大错的几率就小了很多。5. 应对常见陷阱与疑难杂症即便有了完善的“Skill”体系在实际操作中还是会遇到一些棘手问题。以下是我遇到的一些典型场景及应对策略。5.1 AI执着于使用过时或弃用的API这是非常常见的问题。比如AI可能基于旧的训练数据推荐使用request已弃用而不是fetch或者使用旧的baseUrl配置方式。解决方案在提示词中明确声明版本 “本项目使用TypeScript 5.4Next.js 14.2请使用这些版本稳定且推荐的API。”利用编译器错误作为教学工具 当AI生成弃用API的代码并导致编译警告/错误时将完整的错误信息包括建议的替代方案反馈给AI。例如“你使用的baseUrl选项在TS 5.0中已弃用编译器建议使用paths进行模块路径映射。请修正。”为AI提供最新的官方文档片段 如果某个API变化很大可以直接在提问时粘贴一小段新API的官方文档或示例代码让AI基于此进行生成。5.2 AI生成的代码类型正确但逻辑诡异有时AI会写出一些通过类型检查但逻辑上完全说不通或效率极低的代码。比如它可能用一个O(n^2)的循环去查找一个可以用Map在O(1)内完成的任务。解决方案要求AI解释关键步骤 在提示词末尾加上“请为这段代码的关键部分添加简要的注释说明其算法意图和复杂度”。这能迫使AI“思考”其逻辑有时它能自己发现逻辑问题。进行代码审查时重点关注算法和数据结构 这是目前AI的薄弱环节。对于复杂的逻辑处理人工复审必须深入算法层面质疑每一个循环和条件判断。提供算法范例 如果你希望用特定的算法如二分查找、动态规划直接在上下文中提供该算法的TypeScript实现范例让AI基于此进行适配而不是自己发明。5.3 在大型Monorepo或复杂项目结构中AI迷失方向当项目结构非常复杂包含多个包、私有依赖、特殊的路径别名时AI很容易生成错误的导入路径或无法理解模块之间的关系。解决方案简化提问上下文 不要一开始就让AI处理整个复杂项目。先让它针对一个独立的、边界清晰的模块比如一个工具函数、一个React组件生成代码。确保提供给它的import语句是准确的。使用“技能”或自定义指令定义路径映射 在AI助手的自定义指令或“技能”设置中明确写出你项目的路径别名规则。例如“本项目使用/*指向/src/*components/*指向/src/components/*。请在所有生成的导入语句中使用这些别名。”分而治之 将大任务拆解成多个有明确输入输出的小函数让AI逐个生成然后由你来组装。这比让AI一次性生成一个庞大复杂的文件要可靠得多。6. 将“Skill”体系固化为团队资产个人实践固然重要但“Skill”的最大价值在于成为团队共识。只有这样才能防止不同成员引入风格迥异、质量参差不齐的AI代码真正避免“屎山”的滋生。创建团队“Skill”文档 在项目Wiki或根目录的CONTRIBUTING.md中开辟一个“AI辅助编码规范”章节。内容应包括项目严格的tsconfig.json和代码检查规则摘要。推荐的AI提问模板。项目特定的代码模式库如错误处理、数据获取、状态管理范式。常见的“AI陷阱”及应对方法。共享配置与脚本 将最优的tsconfig.json、.eslintrc.js、.prettierrc等配置文件纳入版本控制。甚至可以编写一个验证脚本如scripts/validate-ai-code.ts供团队成员在集成AI生成的代码前自动运行进行编译和基础逻辑检查。在Code Review中加入“AI代码审查”项 在Pull Request模板中增加一个复选框“✅ 本次提交中的AI生成代码已通过本地严格类型检查与逻辑复审”。让审查者也重点关注AI生成代码的边界情况、性能和设计问题。定期复盘与更新 技术栈和AI模型都在快速演进。团队应定期如每季度回顾“Skill”文档更新过时的约束添加新的最佳实践分享成功的AI协作案例和踩坑教训。经过一段时间的实践我和我的团队已经将这套方法深度集成到工作流中。最大的感受是心态从“怀疑AI代码”转变为“引导AI产出可靠代码”。我们不再被动地接受或拒绝AI的产出而是主动地设计一个高质量的生产环境让AI在这个环境中只能生成符合我们高标准的结果。这就像给一匹野马套上了缰绳和跑道它依然能奔跑如飞但方向始终可控最终抵达我们想要的目的地。AI编程不是替代而是一场需要精心设计规则的人机协作。Matt Pocock的“Skill”包概念正是这场协作游戏的优秀规则书。