AI编码协作实战：基于Skill工作流解决TypeScript项目四大痛点

1. 项目概述：当AI编码成为日常，我们到底在烦恼什么？

如果你和我一样，已经深度依赖AI助手（比如Claude、ChatGPT）来写TypeScript代码，那你一定经历过下面这些让人血压飙升的时刻：你满怀期待地丢过去一个复杂需求，它给你生成了一段看起来“完美”的代码，你兴冲冲地复制粘贴到项目里，结果编辑器瞬间被一片红色波浪线淹没——类型错误、未定义的变量、不兼容的接口……你不得不像个侦探一样，在AI生成的代码和自己项目的上下文之间来回切换，手动修复这些“惊喜”。或者，你让它帮你重构一个函数，它确实照做了，但生成的代码风格和你项目里已有的代码格格不入，你又得花时间去统一缩进、命名规范。更别提那些需要结合多个文件上下文才能正确实现的逻辑，AI往往因为“失忆”而给出片面的、甚至错误的方案。

这就是当前AI编码的四大核心痛点：上下文丢失、代码风格混乱、类型安全失控，以及反馈循环低效。我们不是在否定AI的能力，恰恰相反，是因为它太有用了，我们才迫切希望它能更好地融入我们的工作流，而不是成为一个需要额外“伺候”的麻烦。

最近，TypeScript领域的知名开发者Matt Pocock分享了他的一套名为“Skill”的工作流，在社区里引起了不小的反响。这套方法不是某个新工具，而是一套结合了现有工具（主要是Claude Code）的最佳实践和思维模式。它精准地瞄准了上述痛点，提供了一套可落地的解决方案。我花了一些时间深入研究并实践了这套工作流，它彻底改变了我与AI协作编码的方式。这篇文章，我就来为你深度拆解Matt Pocock的Skill工作流，看看它是如何系统性地解决这四大痛点的，并分享我在适配和实践过程中的一些关键细节和踩坑经验。

2. Skill工作流核心设计思路：从“问答”到“协作”

在拆解具体方案之前，我们必须先理解Skill工作流背后的核心哲学。传统的AI编码模式，更像是一种“问答式”或“命令式”的交互：我提问，你回答；我下指令，你执行。这种模式将AI置于一个“黑盒”执行者的角色，而开发者则扮演着“需求提出者”和“质量检验员”的双重角色，负担很重。

Skill工作流的核心转变在于，它将AI从一个“代码生成器”提升为一个“具有上下文感知能力的编码协作者”。它的设计思路围绕着以下几个关键原则展开：

2.1 原则一：赋予AI完整的项目上下文

这是解决“上下文丢失”痛点的根本。AI生成的代码之所以经常出类型错误或逻辑偏差，根本原因在于它对当前项目的模块结构、类型定义、依赖关系、配置文件（如tsconfig.json）一无所知，它只是在基于一个非常狭窄的对话窗口进行“盲猜”。

Skill工作流强调，在开始任何有意义的编码任务前，必须首先将AI“引入门”。这意味着需要将项目的关键上下文信息主动地、结构化地提供给AI。这不仅仅是上传一两个文件，而是包括：

• 项目根配置：package.json（了解依赖和脚本）、tsconfig.json（理解TypeScript编译规则和路径映射）。
• 类型定义核心：项目中关键的types.ts、interfaces.ts文件，或者那些导出公共类型的入口文件。
• 相关模块：与当前任务直接相关的其他源代码文件。

这样做的目的是为了让AI在生成代码时，其“心智模型”能与你的项目现状对齐，从源头上减少因信息不对称导致的错误。

2.2 原则二：建立清晰、一致的代码风格契约

“代码风格混乱”往往导致生成的代码难以直接集成。Skill工作流认为，代码风格不应该在每次对话中靠人工描述来约定，而应该作为一种“自动化契约”存在。

这主要通过利用你项目中已有的静态代码检查工具来实现，最重要的是ESLint和Prettier。工作流的核心步骤之一，是让AI在生成代码后，主动运行这些工具来格式化代码。但Matt Pocock的洞见在于更进一步：他建议将项目的ESLint配置文件（如.eslintrc.js）和Prettier配置文件（如.prettierrc）也作为上下文提供给AI。AI在理解了你的具体规则（比如是使用单引号还是双引号，尾随逗号的规则，@typescript-eslint的具体规则集）之后，能在生成代码的第一时间就做出更符合约定的风格选择，从而大幅减少后续格式化的调整工作量。

2.3 原则三：将类型安全作为即时反馈环

对于TypeScript项目而言，类型错误是最高频的“惊喜”。Skill工作流将类型检查从“事后诸葛亮”变成了“实时教练”。其操作模式不是等代码都写完了，复制到编辑器里再看一片红，而是在AI生成代码的同一个环境中，立即运行TypeScript编译器（tsc）或类型检查命令（tsc --noEmit）进行验证。

如果发现类型错误，这个反馈会立即返回给AI，让它自行分析错误信息并修正代码。这个过程可以循环多次，直到生成的代码能通过类型检查。这相当于为AI配备了一个“TypeScript结对编程伙伴”，极大地提升了生成代码的可靠性和可用性。

2.4 原则四：构建可复用、可组合的“技能”（Skill）

“Skill”这个名字本身就点明了精髓。与其每次都对AI进行冗长的、重复性的上下文灌输和规则说明，不如将这些固定的操作流程封装成一个个可复用的“技能”。例如，“创建一个新的React组件”可以是一个Skill，“添加一个新的API端点类型”可以是另一个Skill。

每个Skill本质上是一个包含了预设上下文、固定操作步骤和验收条件的模板或指令集。一旦定义好，开发者只需要触发这个Skill并输入具体参数（比如组件名、Props类型），AI就能基于预设好的高质量工作流自动执行，省去了大量重复沟通成本。这是将AI协作从“手工作坊”升级到“流水线”的关键。

3. 核心工具链与配置详解

Matt Pocock的Skill工作流主要围绕Claude（特别是Claude Code）设计，但其理念可以迁移到其他具备类似能力的AI编码助手。下面我结合自己的实践，详细拆解所需的工具和关键配置。

3.1 核心AI平台：Claude Code的优势与设置

Claude Code（或Claude桌面应用/API）是这套工作流的首选，原因有几个：

1. 超长上下文窗口：这是实现“完整项目上下文”原则的物理基础。Claude支持高达200K的上下文，足以容纳中型项目的大量关键文件。
2. 强大的代码理解与生成能力：在TypeScript和现代前端栈方面表现尤为出色。
3. 文件上传与处理能力：可以方便地上传整个文件夹或多个文件，为AI提供素材。

实操设置要点：

• 使用桌面应用或Web版聊天界面：对于探索和一次性任务，直接使用聊天界面，通过文件上传功能提供上下文。
• 为复杂项目创建专属对话：我习惯为每个正在活跃开发的项目创建一个独立的Claude对话。在这个对话里，我会一次性上传项目骨架文件（package.json,tsconfig.json,.eslintrc.js等），并在对话开头用System Prompt或第一条消息明确：“接下来所有讨论都基于已上传的[项目名]项目上下文。”这能有效建立对话的“长期记忆”。
• 注意Token消耗：虽然上下文长，但上传大量文件会消耗Token。要有策略地上传，优先上传配置文件、类型定义和当前任务密切相关的模块，而不是整个src目录。

3.2 辅助工具：让AI能执行命令

这是工作流能自动化的关键。我们需要让AI不仅能“看”到我们的代码，还能在我们的开发环境中“动手操作”。

1. 终端（Terminal）访问：这是运行tsc、npm run lint、npm run test等命令的前提。在Claude Code中，这意味着需要开启其代码解释器（Code Interpreter）功能或类似的代码执行环境。
2. Node.js与项目依赖：确保AI执行的代码环境里，已经安装了项目所需的Node.js版本和所有依赖（通过npm install或yarn install）。通常，你需要先在AI的沙盒环境中初始化项目。

注意：在Claude Code的沙盒环境中执行npm install可能会比较慢，且每次新会话环境可能重置。对于大型项目，一种折中方案是提前准备好一个package-lock.json或yarn.lock，并上传node_modules中核心依赖的d.ts文件？不，这太复杂了。更实际的建议是：对于重度依赖本地类型检查的任务，最佳实践仍然是在本地开发环境中运行工作流，利用AI生成代码，然后手动或通过脚本在本地终端执行检查命令，再将结果反馈回AI。Matt Pocock演示的“全自动”流程在沙盒环境中对小型项目可行，但对复杂项目，“人机协同”的半自动流程更稳健。

3.3 配置文件：风格与规则的基石

如前所述，将配置文件作为上下文至关重要。你需要准备并上传：

• tsconfig.json：让AI了解你的目标ES版本、模块系统、路径别名（paths）、严格模式标志等。AI会根据这个配置来理解如何正确地导入模块和通过类型检查。
• .eslintrc.js/.eslintrc.json：定义代码质量规则。上传这个能让AI在生成代码时避免明显的风格错误，例如使用==还是===，变量命名规范等。
• .prettierrc：定义代码格式化规则。虽然Prettier通常事后运行，但AI提前知道规则后，生成的代码在格式上会更“顺眼”。

一个关键技巧：如果你的项目使用了像@antfu/eslint-config这类流行的、规则集繁多的ESLint配置，直接上传整个配置文件可能内容太多。一个有效的替代方案是，在给AI的指令中直接引用它：“本项目使用@antfu/eslint-config规则集，请遵循其TypeScript和React相关规则。” 然后，在要求AI执行npm run lint时，它自然会应用这些规则。

4. 实战演练：一个完整的Skill工作流案例

让我们通过一个具体的场景，来串联上述所有原则和工具。假设我们要在一个现有的Next.js + TypeScript项目中，添加一个新的API路由端点GET /api/users/[id]/posts，用于获取某个用户的帖子列表。

4.1 第一步：初始化上下文与定义Skill

首先，在Claude中为这个项目创建一个新的对话或使用已有的项目对话。

初始消息（提供上下文）：

我将基于已上传的[你的项目名]项目进行开发。以下是项目关键信息摘要： - 框架：Next.js 14 (App Router) - 语言：TypeScript - 数据库ORM：Prisma - 代码风格：已配置ESLint（含`@typescript-eslint`）和Prettier。 - 相关文件已上传：`package.json`, `tsconfig.json`, `.eslintrc.js`, `prisma/schema.prisma` (数据模型), `app/api/users/[id]/route.ts` (现有的用户详情端点)。 现在，请执行一个名为“创建Next.js App Router API端点”的Skill。本次任务的具体参数如下： - 方法：GET - 路径：`/api/users/[id]/posts` - 功能描述：根据URL中的用户ID，从数据库查询该用户发布的所有帖子，并按创建时间倒序返回。需要处理用户不存在的情况。 - 依赖：需使用项目已有的Prisma客户端实例（可从`@/lib/prisma`导入）。

这条消息完成了多件事：

1. 设定了对话背景（项目类型）。
2. 明确了已提供的上下文文件。
3. 触发了一个预定义的“Skill”——创建API端点，并给出了具体参数。

4.2 第二步：AI生成代码与初步检查

一个足够“聪明”的AI（在拥有上下文的情况下）应该会进行如下操作：

1. 分析需求与上下文：读取prisma/schema.prisma，了解User和Post模型的结构及其关系。查看tsconfig.json中的paths，确认@/别名指向何处。参考已有的app/api/users/[id]/route.ts，学习项目API路由的编写模式（比如如何处理动态参数[id]，如何组织响应）。
2. 生成核心代码：创建文件app/api/users/[id]/posts/route.ts，并生成类似以下的代码：

import { NextRequest, NextResponse } from 'next/server'; import prisma from '@/lib/prisma'; export async function GET( request: NextRequest, { params }: { params: { id: string } } ) { try { const userId = params.id; // 首先检查用户是否存在 const user = await prisma.user.findUnique({ where: { id: userId }, }); if (!user) { return NextResponse.json({ error: 'User not found' }, { status: 404 }); } // 查询该用户的所有帖子 const posts = await prisma.post.findMany({ where: { authorId: userId }, orderBy: { createdAt: 'desc' }, // 可以选择性地包含作者信息 include: { author: { select: { id: name: true, email: true } } }, }); return NextResponse.json(posts); } catch (error) { console.error('Failed to fetch user posts:', error); return NextResponse.json( { error: 'Internal server error' }, { status: 500 } ); } }

3. 执行风格与类型检查（自动化环节）：理想的工作流中，AI接下来应该自动执行：

   # 1. 用Prettier格式化刚生成的代码 npx prettier --write app/api/users/[id]/posts/route.ts # 2. 运行ESLint检查 npx eslint app/api/users/[id]/posts/route.ts --fix # 3. 运行TypeScript类型检查（针对这个文件或整个项目） npx tsc --noEmit --project .

   然后，AI会读取这些命令的输出。如果没有错误，则继续；如果有错误（例如，@/lib/prisma路径在tsconfig.json中未正确配置，或者prisma.post.findMany的include参数类型错误），AI会分析错误信息，修正代码，并重新运行检查，直到通过。

4.3 第三步：处理反馈与迭代优化

在实际操作中，AI可能无法一次性通过所有检查，或者你可能对生成的代码有额外的要求。这时就进入了交互优化阶段。

可能的反馈循环：

• 场景A：类型错误。AI报告tsc发现错误：Property 'name' does not exist on type '...'。AI会分析错误，发现include语句中的select结构写错了，修正为author: { select: { id: true, name: true, email: true } }，然后重新运行检查。
• 场景B：功能增强。你觉得返回的数据字段太多，想过滤一下。你可以直接提出：“请修改查询，只返回id、title、createdAt和excerpt字段。” AI会修改Prisma查询的select部分，并可能再次运行检查以确保类型匹配。
• 场景C：风格微调。你希望错误日志更结构化。你可以说：“请将console.error替换为项目里常用的logger.error，并从@/lib/logger导入。” AI会照做，并更新导入语句。

这个“生成 -> 检查 -> 反馈 -> 修正”的循环，就是Skill工作流提升代码质量的核心机制。它将原本需要开发者手动完成的琐碎检查工作，部分自动化了。

4.4 第四步：验收与集成

当代码通过所有自动化检查（类型、风格），并且功能符合你的要求后，这个Skill任务就完成了。你可以让AI总结一下所做的更改，然后将其提供的最终代码复制到你的本地项目中。

此时，由于AI生成的代码已经在“模拟环境”中通过了基于你项目配置的严格检查，它集成到你本地代码库后引发冲突或错误的概率就大大降低了。你只需要运行一下项目的测试（如果有的话），就可以相对放心地提交代码。

5. 构建你自己的可复用Skill库

掌握了单次任务的流程后，我们可以将其固化、模板化，形成个人或团队的Skill库，这才是效率产生质变的关键。

5.1 如何定义一个Skill

一个Skill通常包含以下几个部分，你可以将其保存为一个Markdown文档或笔记：

1. Skill名称：清晰的任务描述，如“创建React组件（TypeScript + Tailwind CSS）”。
2. 前置条件/上下文：执行此Skill前需要提供给AI的文件和信息列表。
   • 必需文件：tsconfig.json,.eslintrc.js,tailwind.config.js, 相关的全局类型定义。
   • 可选文件：一个类似的组件作为示例。
3. 核心指令模板：一个可复用的提示词模板，其中包含变量占位符。

   请执行“创建React组件”Skill。 参数： - 组件名称：{componentName} - 组件类型：FC (函数组件) - 样式方案：Tailwind CSS - Props类型：{propsInterface} - 位置：`src/components/{componentName}.tsx` 要求： 1. 使用`interface`定义Props。 2. 导出命名的函数组件。 3. 遵循项目中的ESLint和Prettier配置。 4. 生成后，请运行`npx tsc --noEmit`和`npx eslint`进行检查和修复。

4. 验收标准：Skill完成后的输出应满足的条件，例如“无TypeScript错误”、“ESLint检查通过”、“组件可通过import正常使用”。

5.2 我的常用Skill示例

以下是我为自己项目积累的几个Skill示例：

Skill 1: 创建工具函数（Utility Function）

• 上下文：tsconfig.json,lib/index.ts（工具函数入口）。
• 指令模板：“在src/lib/utils目录下创建一个名为{functionName}的工具函数。功能描述：{description}。需包含JSDoc注释、完整的TypeScript类型定义，并处理边界情况。创建后运行类型检查。”

Skill 2: 添加Prisma模型查询扩展

• 上下文：prisma/schema.prisma,lib/prisma.ts。
• 指令模板：“在src/lib/prisma-extensions下为{ModelName}模型添加一个名为{extensionName}的Prisma客户端扩展。功能：{具体功能，如‘通过邮箱查找用户，若不存在则创建’}。请使用prisma.$extends方法，确保类型安全。完成后检查类型。”

Skill 3: 编写单元测试（Vitest + Testing Library）

• 上下文：vitest.config.ts,tsconfig.json, 待测试的源文件。
• 指令模板：“为文件{filePath}中的{functionOrComponentName}编写单元测试。测试文件位置：{testFilePath}。使用Vitest和Testing Library。覆盖主要用例和边界情况。生成测试后，请尝试运行npm run test:unit -- {testFilePath}看是否通过。”

5.3 Skill的管理与分享

你可以使用任何你喜欢的笔记工具（如Notion、Obsidian）来管理这些Skill模板。在团队中，可以建立一个共享的文档或Wiki，将这些标准化的工作流沉淀下来，新成员也能快速上手，保证团队代码风格和质量的统一。

6. 常见问题、局限性与应对策略

尽管Skill工作流强大，但在实践中仍会遇到一些挑战。以下是我遇到的一些典型问题及解决方法。

6.1 上下文依然不够“聪明”

问题：即使上传了tsconfig.json，AI有时还是会生成错误的路径导入，比如忽略了配置中的baseUrl或paths。对策：在初始指令中明确强调。“请注意，本项目tsconfig.json中配置了baseUrl: ‘./src’和路径别名@/*，所有导入请使用以@/开头的绝对路径。”

6.2 自动化命令执行失败

问题：在Claude Code的沙盒环境中，运行npm run lint可能因为缺少某些依赖或全局包而失败。对策：

1. 简化命令：将复杂的npm run lint（可能背后是eslint . --ext .ts,.tsx --fix）拆解成更直接的命令，如npx eslint specific-file.ts --fix。
2. 分步指导：如果环境确实受限，就放弃全自动。采用“半自动”模式：让AI生成代码 -> 你手动在本地终端运行检查命令 -> 将错误信息粘贴回对话 -> AI进行修正。
3. 提供错误日志：当命令失败时，要求AI查看错误输出并提供解决方案。有时AI能根据错误提示，建议你先行安装某个缺失的包（npm install -D @types/node）。

6.3 生成的代码逻辑有缺陷

问题：AI通过了类型检查，但业务逻辑可能存在边缘情况漏洞，或者算法效率不高。对策：这是AI的固有局限，无法完全避免。Skill工作流解决的是“机械性错误”（类型、风格），而非“逻辑性错误”。因此，开发者的代码审查（Code Review）环节仍然不可或缺。将AI视为一个强大的初级协作者，它负责完成结构正确、类型安全的“草稿”，而资深开发者负责审查其业务逻辑的合理性和最优性。

6.4 对大型、复杂任务的支持有限

问题：对于需要同时修改多个相互关联文件的重构任务，AI可能难以保持全局一致性。对策：将大任务拆解成多个顺序执行的小Skill。例如，“重构用户认证模块”可以拆解为：1) 创建新的认证类型定义；2) 创建认证上下文Provider组件；3) 修改登录页面使用新上下文；4) 修改受保护路由组件。按顺序执行并确保每个子任务通过检查后，再进行下一个。

6.5 成本与效率的权衡

问题：为每个小任务都执行完整的“上传上下文 -> 生成 -> 检查”循环，前期可能感觉比直接手写代码更慢。对策：这确实存在学习曲线和初期效率成本。但它的回报在于：

1. 代码质量：显著减少了低级错误和风格不一致。
2. 知识沉淀：Skill模板是可复用的团队资产。
3. 专注度提升：开发者可以将认知资源更多地集中在架构设计和复杂逻辑上，而不是纠结于语法和格式。 对于非常简单的、闭着眼睛都能写对的代码（比如一个简单的console.log），当然不需要动用这套流程。它最适合用于那些有一定复杂度、容易出错、或需要遵循严格规范的编码任务。

7. 进阶技巧：将工作流集成到开发环境中

为了更进一步，我们可以探索将Skill工作流的理念与本地开发工具结合，创造更流畅的体验。

7.1 结合IDE插件

一些IDE插件（如Cursor、Windsurf、Claude for VS Code）已经深度集成了AI能力。你可以利用这些插件的“项目感知”特性，它们能自动将当前打开的文件或项目结构作为上下文提供给AI，省去手动上传文件的步骤。你可以在插件中自定义一些“快捷指令”，这些指令本质上就是封装好的Skill。

7.2 使用脚本自动化上下文收集

对于经常需要提供的标准上下文（配置文件），可以写一个简单的Shell脚本或Node脚本，将它们打包成一个临时文件或直接生成一段包含其内容的提示词。

#!/bin/bash # 脚本：generate_context.sh echo “### 项目上下文 ###” echo “\`\`\`json” cat package.json echo “\`\`\`” echo “\`\`\`json” cat tsconfig.json echo “\`\`\`” # ... 可以继续cat其他配置文件

运行这个脚本，将输出直接复制到AI对话中，可以快速建立基础上下文。

7.3 与Git结合，进行增量开发

在进行功能开发时，可以让AI基于某个Git分支或提交进行工作。指令可以是：“基于当前feat/user-profile分支的代码，实现以下功能……”。这样AI生成的代码会更有针对性，减少与现有代码的冲突。完成AI辅助编码后，你仍然需要用git diff仔细审查变更，然后再提交。

8. 总结与个人实践心得

Matt Pocock的Skill工作流不是一个神奇的银弹，而是一套极具实践智慧的“方法论”。它没有引入任何新工具，而是重新组织了开发者与现有强大工具（AI、TypeScript、Linter）之间的关系。其核心价值在于，它通过流程和规范，将AI的“创造力”与机器的“严谨性”结合起来，让前者在后者划定的安全边界内高效发挥。

从我个人的实践来看，这套工作流带来的最大改变是心理负担的减轻。我不再需要时刻担心AI生成的代码会破坏项目的类型安全或代码风格，因为检查环节被前置并部分自动化了。我可以更放心地将一些模式固定、但容易出错的“模板代码”交给AI去生成，而自己则专注于更核心的设计和逻辑问题。

开始实践时，建议从一个小的、定义明确的任务开始，比如“为这个接口添加一个TypeScript类型定义”。严格按照“提供上下文 -> 明确指令 -> 要求检查”的步骤走一遍，感受整个流程。然后，将这个过程记录下来，形成一个你自己的第一个Skill模板。随着积累的Skill越来越多，你会发现自己与AI的协作会变得越来越顺畅，越来越像与一位训练有素、熟知你项目所有规矩的搭档一起编程。

最后要记住，工具和流程始终是为人服务的。Skill工作流是提升效率和质量的利器，但最终代码的所有权和责任仍然在开发者自己手中。保持批判性思维，坚持代码审查，将AI作为你能力的放大器，而不是替代者，这才是人机协同编码的长期之道。