AI编码工程化实战：用TypeScript类型、测试与代码审查构建稳定工作流

先从一个反直觉的现象说起。很多人给编辑器装上一套 AI 编码插件之后工作流不但没有变快反而变得更乱了。AI 生成一段代码粘贴进来类型报错修一下运行测试挂了几个用例再修好不容易跑通回头一看代码结构已经没法看了。我见过不少团队实习生用 AI 生成代码的速度是快了但 review 和返工的时间反而翻倍。问题从来不是 AI 不够聪明而是我们的开发流程根本没有准备好“接住” AI 的输出。Matt Pocock Skills 这套工作流核心就是用类型系统、自动测试和代码审查三道闸门把 AI 从“一个话很多的实习生”训练成“一个稳定交付的工程化协作者”。这篇博文我完整拆解一下我是怎么从零搭起来的包括提示词模板、工程配置、CI 接入和踩坑记录。1. 从“让AI写代码”到“让AI按工程规范交付”1.1 先搞清Matt Pocock Skills到底是一套什么Matt Pocock 在 TypeScript 社区里是个绕不开的名字他做 Total TypeScript 教程、维护 Type Challenges日常大量输出关于类型编程的内容。这几年他把重心明显转向了 AI 辅助编程而且观点一直很鲜明AI 生成代码的最大问题不是“代码错”而是“没有约束地生产代码”。他把自己的工程实践打包成一套可复用的方法就是这里说的 Matt Pocock Skills。它不是一个具体插件也不是某一家 AI 工具的专属配置而是一整套工作流。这套工作流的核心可以概括成一句话让 AI 在“类型安全 自动测试 人工审查”的闭环里工作。你先帮 AI 把边界条件定死再让它产出实现代码接着让测试去验证行为最后由人去做架构层面的判断。每一步都有机器检查兜底AI 的输出就从“看起来能用”变成“可验证、可合并、可维护”。对正在带团队做 AI 工程化落地的人来说这套思路的价值比单纯收藏一堆提示词要高得多。1.2 为什么工程化不是“装个插件”那么简单很多人理解的 AI 工程化就是买一个 IDE 插件比如 Cursor、Copilot 或通义灵码然后让 AI 跟着写代码。用了一个月之后发现代码量确实上去了但 TypeScript 报错也上去了测试用例没人补code review 的时候根本不知道 AI 写的这段代码为什么要这样写。说到底AI 本质上是概率生成器它不知道你项目的技术债不知道你们的代码规范也不清楚业务上哪些边界条件不能碰。它只是在“生成看起来合理的代码”而不是在“按照工程规范交付代码”。工程化的本质是给不确定性加约束。输入侧我们用结构化的提示词约束任务边界过程侧我们用目录结构和纯函数拆分约束代码形态输出侧我们用 TypeScript 严格模式、Zod schema、Vitest 测试和 ESLint 规则去自动验证产物。这一整套东西就像工厂流水线上的质检工位AI 是那台高速运转的机器但每一件产品都要过质检台不合格就退回重做。没有这些约束AI 的效率越高埋下的坑就越多。1.3 “生成—验证—修复”闭环是整套工作流的主干我这套工作流的主干是一个循环每天在项目里会跑几十遍。拿到一个开发任务之后先拆解成足够小的子任务然后让 AI 按照固定顺序输出先定义类型和运行时校验 schema再写实现代码代码通过tsc --noEmit的类型检查之后接着让 AI 根据类型签名批量生成测试用例测试在 CI 里跑起来挂了就自动把失败信息回传给 AI 修复最后由 AI 产出一份初步 code review 报告人只在关键时刻做最终决策。每一个环节失败就返回上一步重新生成或者打回修改。这个循环很像 TDD 里的红绿重构只不过“红灯”多数情况来自 AI 的错误而不是测试先行。实测下来这个闭环把 AI 生成代码的可合并率从我早期的不到三成提升到了八成以上。原因很简单类型约束帮 AI 排除了一大堆低级错误测试则把业务行为锁死剩下的问题基本都能在人工 review 阶段快速处理。2. 工作流的核心设计把AI当成团队里最勤奋的实习生2.1 第一阶段类型先行给AI装上安全网我在项目里定了一条硬规矩AI 动业务代码之前必须先把 TypeScript 类型定义和 Zod schema 交出来。这么做不是走过场是因为类型定义本质上就是一份“机器可读的需求文档”它把函数入参、出参、可选字段、边界值全部约束死了。AI 拿到一份精确的类型契约之后再去生成实现代码自由度虽然变小了但出错率也大幅下降。TypeScript 严格模式再加几个狠选项相当于给 AI 装了一张安全网。我当前的 tsconfig 里有几个常开的关键项strict: true是底线noUncheckedIndexedAccess逼着 AI 处理数组下标可能为 undefined 的情况exactOptionalPropertyTypes禁止把undefined塞进可选属性。项目里所有 API 入参都会配一个 Zod schema再用z.infer反推出类型。比如用户登录模块我会先让 AI 写出这样的 schemaimport { z } from zod; export const loginSchema z.object({ email: z.string().email(), password: z.string().min(8).max(64), }); export type LoginInput z.infertypeof loginSchema;这一小段代码不是业务逻辑但它把整个模块的输入边界焊死了。AI 后面生成的业务函数必须在LoginInput类型下面工作想传个空字符串进来类型检查直接拦下。对 AI 来说一个精确的类型定义比五百字自然语言描述更有效因为它不是“参考”是“必须遵守的契约”。2.2 第二阶段测试兜底让AI自己给自己写考题类型只解决了数据形状问题解决不了业务行为问题。AI 完全可能写一个类型正确但行为错误的函数比如把用户状态判断写反、在边界条件里直接抛异常、漏了空数组场景。所以第二步必须让 AI 给刚写完的实现代码生成测试。很多团队让 AI 写测试只是让它“看着实现代码随便补几个用例”这很容易变成自说自话。正确做法是先给 AI 函数签名和 schema让它在不看实现细节的情况下从外部行为出发设计测试用例。举一个登录模块的测试生成提示词我实际用的是这个模板请基于以下函数签名和 Zod schema生成 Vitest 测试用例。 函数签名: validateLoginInput(input: LoginInput): { ok: true; data: LoginInput } | { ok: false; error: ZodError } Schema: loginSchema 要求: 1. 覆盖正常输入、非法 email、短密码、超长密码、空对象五个场景 2. 不 mock 内部实现只从外部调用 3. 使用 describe/it 结构 4. 断言使用 vitest 的 expectAI 产出的一段典型测试长这样import { describe, it, expect } from vitest; import { validateLoginInput } from ./login; import { loginSchema } from ../schemas/login; describe(validateLoginInput, () { it(应该接受合法输入, () { const result validateLoginInput({ email: ab.com, password: 12345678 }); expect(result).toMatchObject({ ok: true }); }); it(应该拒绝非法邮箱, () { const result validateLoginInput({ email: not-an-email, password: 12345678 }); expect(result.ok).toBe(false); }); });这些测试用例是 AI 给自己出的考题。一旦它后面修改了实现测试就会像哨兵一样报告行为是否被破坏。这也是整个工作流里我最看重的部分AI 生成代码不可怕可怕的是没有约束地生成代码而测试就是最硬的约束。2.3 第三阶段Review把关人类只做关键决策类型检查和单测属于机器可自动校验的层面但代码最终要进主干还需要一层人工 review。全量 review AI 的输出太累了我的做法是让 AI 先做一轮“初筛 review”生成结构化报告我再基于报告做最终拍板。重点看四类问题类型边界有没有失控、边界条件有没有遗漏、错误处理是否缺失、命名和模块边界是否与项目一致。代码风格问题缩进、引号、顺序完全交给 ESLint 和 Prettier不浪费模型和人的时间。我用的 review 提示词模板是这样的请以资深代码审查者的身份审查下面的代码 diff。 只关注四类问题 1. 类型安全问题尤其是 any、类型断言、未处理 null/undefined 2. 逻辑边界条件遗漏如空数组、负数、超长字符串、并发冲突 3. 错误处理缺失如文件读取失败、API 超时、数据库异常 4. 模块命名与项目现有风格不一致 不要评论代码风格不要输出客套话。 每个问题按严重程度从高到低排序指出所在文件和修复建议。AI 产出的 review 报告未必全对但它能快速找出人类容易忽略的边界情况。尤其当代码量比较大的时候让 AI 挡在人类前面做第一道过滤review 效率会高很多。人类 review 只聚焦架构和业务语义层面不再纠结“这个变量是不是写错了”。3. 实操在真实项目里从零搭建这套工作流3.1 先准备一个能“接住AI”的工程骨架搭建这套工作流第一步不是配 AI 工具而是把工程骨架准备好。一个空项目直接喂给 AI它很容易放飞自我所以我建议目录结构强制按职责分好让 AI 每次生成代码都有明确的落点。我常用的最小工程结构长这样src/ schemas/ # Zod schema 集中管理 services/ # 业务逻辑纯函数 utils/ # 通用工具函数 agents/ # AI agent 相关脚本 tests/ unit/ # 单元测试 integration/ # 集成测试 .github/ workflows/ # CI 流水线依赖方面TypeScript 和 Vitest 是硬要求Zod 负责运行时校验ESLint 加 prettier 统一风格changesets 管理版本变更。最小 package.json 脚本长这样{ scripts: { typecheck: tsc --noEmit, test: vitest run, test:watch: vitest, lint: eslint . --max-warnings0, format: prettier --write ., ci: npm run typecheck npm run lint npm run test } }把这些脚本定义好的价值在于AI 生成的代码都会统一地跑在npm run ci这个总检入口下面。不管是人写的还是 AI 写的只要过不了这三个检查就不允许进主干。代码风格在这里被标记了--max-warnings0意味着 lint 警告也会失败避免 AI 生成“能用但是到处警告”的代码。3.2 配置AI编码助手和提示词模板工程骨架准备完毕后接下来是配置 AI 编码助手。我用过好几家工具最终沉淀下来的经验是工具可以换但提示词模板必须有一套属于自己的。因为模板里承载的是项目的规则和上下文这是工具不会替你做的事。我通常把所有模板放在仓库根目录的prompts/文件夹里版本化管理谁要改流程都要走 PR。四个最核心的模板分别是系统提示词、代码生成模板、测试生成模板、code review 模板。系统提示词是全局约束我写的版本大概是这样你是一个参与本项目开发的全栈工程师。 项目使用 TypeScript strict 模式、Zod 做运行时校验、Vitest 做单测。 项目约束 1. 任何业务逻辑必须先给出类型定义和 Zod schema 2. 纯函数优先副作用单独封装 3. 必须通过 tsc --noEmit 和 eslint 才能提交 4. 不要尝试编写超出需求的抽象层 5. 输出格式先类型、再实现、最后补充说明这套系统提示词的作用是给 AI 建立“肌肉记忆”。每次新开对话不用重新解释项目背景直接贴模板就能进入状态。代码生成模板和测试模板则按任务类型灵活调整比如 handle 一个“给购物车模块加接口校验”的需求我会把需求和现有类型定义贴进模板AI 输出的质量会比直接说“帮我写段代码”高出一个量级。3.3 以“用户登录模块”为例完整跑一遍生成流程光说理论容易飘我拿一个真实跑过的例子演示一下完整流程。任务是给用户登录模块增加输入校验和错误码。第一步我把任务拆成四个子任务定义 schema、实现校验函数、生成测试、生成修改建议。然后给 AI 发送第一个 prompt要求它先输出 schema任务为登录模块定义 Zod schema 和类型。 约束email 必须是合法邮箱password 长度为 8-64 位不要求 trim 输出。 输出仅输出 schema 文件和对应 type。AI 会给出类似上面 loginSchema 的代码。我把它放进src/schemas/login.ts。第二步让 AI 生成实现函数要求类型必须匹配LoginInput任务基于 src/schemas/login.ts 中的 loginSchema实现 validateLoginInput 函数。 函数签名: (input: LoginInput) { ok: true; data: LoginInput } | { ok: false; error: ZodError } 要求使用 safeParse不要吞掉具体校验错误。产出的函数大概是import { loginSchema, type LoginInput } from ../schemas/login; import { ZodError } from zod; export function validateLoginInput(input: LoginInput): | { ok: true; data: LoginInput } | { ok: false; error: ZodError } { const result loginSchema.safeParse(input); if (result.success) { return { ok: true, data: result.data }; } return { ok: false, error: result.error }; }第三步我把函数签名和 schema 贴给 AI让它生成测试用例。测试跑完之后如果出现失败比如 AI 写的函数没有 noUncheckedIndexedAccess 概念相关我会直接把它改成“基于失败信息修复函数”而不是跳过问题。整条链路走完这段代码才算进入可提交流程。你会发现这个过程中的每个步骤AI 都不需要猜需求因为它所有的输入和输出边界都是确定的。3.4 把AI Agent接入CI流水线让检查自动化本地跑完还不够要让这套检查成为团队级约束。我在 GitHub Actions 里配了一条最基础的流水线每次 PR 和 push 到主分支都会自动执行类型检查、lint 和测试name: ai-workflow-check on: pull_request: push: branches: [main] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: npm - run: npm ci - run: npm run typecheck - run: npm run lint - run: npm run test在此基础上我又加了 AI Agent 自动初筛评论。Agent 会读取 PR diff先用 review 模板生成一份结构化意见以评论形式发回。如果 CI 报错了Agent 还会读取失败日志在评论里给出“最可能的 3 个修复方向”并生成可选的 patch 文件。人类开发者看完评论一键应用或者拒绝。这条链路跑通之后AI 不仅参与“写代码”还参与“查问题和提修复方案”整个团队的工作重心就变成了“决策”而不是“做苦力”。3.5 没有官方API时本地模型怎么顶上有不少团队因为数据合规要求不能用云端 AI 服务只能在内网搭模型。我实际试过用 Ollama 部署开源模型作为备用比如 Qwen2.5-Coder 和 DeepSeek-Coder 系列。准备工作不复杂内网机器装 Ollama拉取模型然后配置一个 OpenAI 兼容的本地代理AI 插件只需要改一下 base URL 就能接上。本地部署最大的好处是数据不出内网同时可以针对项目微调参数不过推理能力通常比云端旗舰模型弱一些尤其是在复杂类型推演上更容易翻车。本地模型环境下我的建议是降低对 AI“一次生成完美代码”的预期把更多工作量放到“修复循环”上。举个例子本地点一个 14B 模型写出的 Zod schema 偶尔会有低级错误但类型检查和测试会把这些问题暴露出来AI 看了一遍报错信息后往往就能改对。整个工作流对模型能力的依赖并没有想象中那么高因为一道道验证关卡帮你兜住了下限。配置上我建议把 temperature 调到 0.2 以下上下文窗口按内存量力设置不然容易在长文件生成时出现上下文截断。4. 实战中的坑与排查技巧4.1 AI生成代码“看起来对但类型报错”这是最常见的一类问题AI 生成的函数看着很合理但tsc --noEmit一跑就是一排错误。出现这种情况九成是因为 schema 和类型没有同步更新或者泛型推断失败。比如改了 schema 里 email 字段为可选项但实现函数还在用LoginInput[email]当必填。我的排查经验是不要直接让 AI 改代码先把tsc输出完整贴给 AI让它先解释“这些错误说明了什么类型契约被违反了”再让它给出修复方案。还有一个小技巧把 tsconfig 里的noUncheckedIndexedAccess和exactOptionalPropertyTypes打开能逼出 AI 非常多潜在的 undefined 处理问题。早期我用默认严格模式很多数组取值的 undefined 问题在代码评审时才暴露打开这两个选项之后AI 在生成代码时就会主动加判空逻辑。实测下来虽然一开始 AI 报错频率高了但修完之后代码的健壮性明显上一个台阶。4.2 自动测试大面积失败别急着让AI改实现AI 生成的测试第一次跑就全过这种场景反而少见。更常见的是生成 20 个测试有 5 个挂掉。我刚开始遇到这种情况第一反应是让 AI “修复测试”结果它改着改着就把断言强度改弱了变成“能跑过就行”。后来我定了一条规矩AI 收到测试失败信息后必须先分类是测试问题还是实现问题。测试问题包括 mock 数据没有对齐、时间函数不稳定、随机数导致断言失败实现问题则要看行为是否和 schema 或需求文档冲突。如果失败原因是 mock 和实现耦合太深比如测试里 mock 了内部 service结果 service 内部重构了测试就跟着挂。这种我会直接要求 AI 重写测试改为“只从外部调用不 mock 业务内部实现”。行为测试虽然写起来约束更多但它对重构的容忍度高得多。经历过一次大重构之后你就会明白稳定的测试套件比测试数量重要一百倍因为没人愿意每天花两小时修和自己业务无关的破测试。4.3 AI Review误报太多怎么调AI 做的初筛 review 一开始经常误报什么“这个函数缺少注释”也要提一句或者把代码风格问题当成严重 bug 列出来。后来我发现根因是系统提示词里的“问题定义”写得太模糊。AI 不清楚你说的“代码风格”边界在哪也不知道你对“边界条件”的重视程度当然只能想到什么说什么。解决方法是把 review 标准做成显式 CHECKLIST喂给 AI 之前自己先校准一遍。我的 review 提示词经过几轮迭代后现在都带“反面示例”也就是告诉 AI 哪些情况不属于严重问题避免它混淆优先级。AI review 报告的定位要明确它只是“候选人”不是“裁判”。所有它提出的问题我必须快速扫一遍才能决定采纳还是忽略。跑了一个季度之后报告质量会明显变好因为它能从你的采纳行为里学到偏好。如果你觉得一个工具每次 review 都要大量人工纠正那就说明你的 review 标准还没沉淀成提示词这本身就是问题。4.4 模型输出不稳定和幻觉问题AI 生成同一个任务两次结果可能完全不同这是概率模型的固有属性。消除不稳定性的办法不是找到一个“永远稳定”的工具而是工程化地管理输出变量。我的做法是保持上下文稳定把类型定义、schema、相关文件路径都贴进提示词、降低 temperature 参数、把大任务拆成小任务、并要求 AI 在每个输出前先写出“我根据哪些约束做了哪些决策”。这个“决策说明”步骤非常有用因为它能逼着模型在生成代码前先理清思路很多幻觉就是跳过了这一步导致的。关于幻觉还有一个重要认知不要把 AI 当成知识库它更像“按你给定上下文执行的代码生成器”。它说的“根据 Node.js v20 文档”不一定真的查了文档可能只是编了一段看起来权威的说法。所以涉及第三方 API、依赖版本、框架更新这类需要实时信息的内容一定要把真实文档内容粘贴进提示词并明确要求它只基于粘贴的上下文回答。我已经养成了习惯提问时先贴链接和关键文档片段AI 的答案质量会立刻上一个台阶。5. 关于这套工作流我最后想说几句这套东西我跑了几个月最大的感受是AI 工程化的难点不在于“选哪个模型”也不在于“写多漂亮的提示词”而在于你愿不愿意把工程纪律落实成机器可执行的检查项。类型报错就回头修类型测试挂了就查测试review 意见不准就调整提示词每一处都在把“AI 的自由发挥”往“工程约束”上拉。一旦这个闭环建立起来你会发现 AI 生成代码的质量会稳定地提升因为每失败一次你的项目就多了一条约束AI 下一次犯同样错误的概率就少一分。最后再分享一个我踩过坑之后养成的习惯所有 AI 提示词模板都要像代码一样放进仓库里版本管理。每次发现某个提示词导致输出质量下降就提个 PR 修改附上实测对比。这件事听起来很麻烦但它会把“调教 AI 的经验”从个人私货变成团队的资产。等到团队里任何一个人接手项目都能直接用同一套工作流稳定产出代码这才是 AI 工程化真正该有的模样。