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

如果你最近也在用Claude、ChatGPT或者Cursor来写TypeScript，大概率会和我有一样的感受：这东西太强了，但用起来又总感觉哪里不对劲。一开始是惊喜，代码生成速度飞快，解释也头头是道。但用着用着，问题就来了：生成的代码风格五花八门，项目里一会儿是双引号一会儿是单引号；让它改个函数，它可能把不相干的逻辑也动了，还得花时间Review；最头疼的是，一些复杂的业务逻辑，你描述半天，AI生成的代码要么跑不通，要么完全理解错了你的意图，最后调试的时间比自己写还长。

这就是典型的“AI编码蜜月期”后的阵痛。我们团队从去年开始全面尝试AI辅助编码，Matt Pocock的“Skill工作流”正是我们在这个摸索过程中，找到的一剂解药。Matt Pocock是谁？如果你深耕TypeScript社区，对这个名字一定不陌生，他是TypeScript领域的顶级布道师和工具开发者，他的type-fest、ts-reset等库在社区里被广泛使用。他提出的这套工作流，并不是某个具体的软件，而是一套结合了Claude、自定义指令（Skill）和工程化思维的方法论，专门用来解决上述四大痛点：代码风格不一致、上下文理解偏差、复杂逻辑生成不可靠、以及迭代修改效率低下。

简单来说，Skill工作流的核心思想是“教会AI像你的资深同事一样编程”。它不是让AI天马行空地自由发挥，而是通过精心设计的“技能”（Skill）—— 一组包含上下文、范例和约束的指令集 —— 来引导AI，使其输出高度符合项目规范、可预测且高质量的结果。接下来，我会结合我们团队近半年的实战经验，深度拆解这套工作流是如何落地，并彻底改变我们与AI协作方式的。

2. 核心痛点拆解：为什么“直接问AI”往往行不通？

在深入Skill工作流之前，我们必须先认清单纯与AI对话式编程的局限性。很多人（包括最初的我）把Claude或ChatGPT当作一个无所不知的编程伙伴，直接抛出问题：“帮我写一个React表单校验钩子”。结果往往差强人意，问题就出在以下几个关键环节。

2.1 痛点一：缺乏项目上下文与规范约束

AI模型是通用的，它学习了海量的公共代码，但对你当前项目的独特环境一无所知。这导致了几个具体问题：

• 代码风格混乱：你的项目用ESLint + Prettier，约定使用单引号、2空格缩进、尾随逗号。但AI可能生成双引号、4空格缩进。每次生成后都需要手动格式化，或者更糟，把这些不一致的代码提交了上去。
• 依赖和版本不匹配：你项目里用的是TanStack Query v5，但AI可能基于更常见的v4语法生成代码，导致API根本对不上。
• 项目特定模式缺失：每个成熟项目都有自己沉淀下来的工具函数、自定义Hooks、状态管理封装和错误处理范式。AI无法自动复用这些“内部最佳实践”，导致生成的代码与现有架构格格不入。

注意：这不仅仅是“风格”问题。不一致的代码会显著增加团队的认知负担和代码评审成本，长远来看会损害代码库的健康度。

2.2 痛点二：需求描述模糊与“幻觉”代码

编程本质上是将模糊的需求转化为精确指令的过程。当我们用自然语言向AI描述时，这种模糊性会被放大。

• 歧义性：“处理用户上传的图片”这个需求，包含压缩、格式转换、存储、生成缩略图、记录元数据等无数子任务。AI可能会选择一个它认为最“常见”的实现，但这很可能不是你的本意。
• 逻辑“幻觉”：对于复杂算法或业务逻辑，AI可能会生成一段看起来非常合理、注释详尽的代码，但其中隐藏着细微的逻辑错误或边界条件处理不当。它自信地“推理”出一个解决方案，但这个推理过程对于黑盒模型来说是不可审计的。
• 缺少边界案例：我们自己在编码时会下意识考虑异常流、空值、网络失败等情况。AI在单次生成中，往往专注于“快乐路径”，需要你反复提示“请添加错误处理”才会补充，且补充的质量参差不齐。

2.3 痛点三：迭代与修改中的上下文丢失

这是对话式AI最令人沮丧的一点。你让AI生成一个函数，然后说：“把参数user改成userInfo，并增加一个options配置项。”AI很可能会重写整个函数，而不是进行最小范围的修改。更糟糕的是，在重写过程中，它可能丢失了你之前已经认可或调整过的某些精妙逻辑。每一次迭代都不是在原有代码基础上的“差分更新”，而是一次推倒重来，你需要反复核对，效率极低。

2.4 痛点四：知识更新滞后与特定技术栈盲区

大型语言模型的知识有截止日期。对于发展日新月异的前端生态（如React Server Components, Next.js 15+的新API，某个库的最新版本），AI可能给出过时甚至错误的建议。此外，对于你们公司内部封装的SDK、私有的API网关规范，AI更是一无所知。

Matt Pocock的Skill工作流，正是针对这四个痛点，提出的一套系统性解决方案。它不是替代AI，而是为AI装上“导航仪”和“操作手册”，让它能在你项目的“地图”内高效、可靠地工作。

3. Skill工作流核心架构：从“聊天”到“工程化协作”

Skill工作流的核心，是将一次性的、模糊的AI对话，转变为可复用、可组合、具备强约束的“技能”调用。你可以把它想象成为你项目定制的AI“函数”，每个“函数”（Skill）都有明确的输入、输出、副作用说明和丰富的内部上下文。

3.1 什么是“Skill”？

一个Skill，在Matt的体系中，是一个结构化的文本文件（通常是.md或.txt）。它包含以下几个关键部分：

1. 技能名称与描述：清晰定义这个技能是干什么的。例如：create-react-component（创建React组件）、generate-zod-schema（根据TypeScript接口生成Zod校验模式）。
2. 上下文信息：这是Skill的灵魂。它会注入当前项目的关键信息，例如：
   • tsconfig.json的编译选项。
   • package.json中的主要依赖及其版本。
   • 项目根目录下的README.md或CONTRIBUTING.md中关于代码风格的约定。
   • 相关工具（ESLint, Prettier）的配置文件摘要。
   • 项目特定的工具函数库的导入路径和常用模式。
3. 范例代码：提供1-3个高质量的、本项目内的代码示例。例如，对于create-react-component技能，会提供一个现有的、风格标准的组件完整代码，让AI“依葫芦画瓢”。
4. 约束与规则：以条目的形式明确规定AI必须遵守和必须避免的事项。例如：
   • “必须使用const声明函数组件。”
   • “必须使用我们自定义的useApi钩子进行数据请求，而不是直接使用fetch。”
   • “禁止使用any类型。”
   • “样式必须使用CSS Modules，类名格式为styles.container。”
5. 输出格式：明确要求AI输出的格式。例如：“只输出代码，不要输出解释。”或者“将代码包裹在typescript ...代码块中。”

3.2 工作流闭环：如何运行一个Skill？

这套工作流通常与Claude Desktop应用深度集成（这也是Matt主要演示的环境）。其操作闭环如下：

1. 触发：在IDE或系统全局，通过快捷键唤出Claude输入框。
2. 选择技能：输入特定前缀（如/skill）或从列表中选择一个预定义的Skill（如/create-react-component）。
3. 提供输入：紧接着，给出本次任务的具体描述。例如：“创建一个名为UserProfile的组件，接收userId: string作为prop，展示用户头像、名称和邮箱。”
4. AI生成：Claude会将Skill文件内容 + 你的具体描述作为组合提示词，生成代码。由于Skill提供了丰富的上下文和约束，生成的代码在风格、依赖和模式上与项目高度一致。
5. 审查与微调：将生成的代码插入项目。由于质量很高，审查通常很快。如需小修改，可以继续在对话中引用之前的消息进行迭代，因为上下文被Skill固定了，AI的修改会更精准。

3.3 与普通Prompt工程的关键区别

你可能会说，这不就是写个详细的Prompt吗？确实有相似之处，但Skill工作流将其工程化了，关键区别在于：

• 复用性：一个写好的Skill，可以被团队所有成员、在所有相关任务中无限复用。
• 可维护性：当项目规范更新（比如从axios切换到fetch），你只需要更新对应的Skill文件，所有人的AI助手行为都会同步更新。
• 组合性：简单的Skill可以组合成复杂的工作流。例如，可以先运行generate-types-from-api（从API文档生成类型），再运行generate-zod-schema（根据类型生成校验），最后运行create-react-hook（生成包含校验逻辑的Hook）。
• 版本控制：Skill文件可以放入Git仓库，像管理代码一样管理AI的“行为规范”，实现Code Review和变更追溯。

这套架构，将AI从一个需要反复调教的“实习生”，变成了一个熟读项目手册、遵守开发规范的“高级工程师”。

4. 实战：构建你的第一个TypeScript项目Skill库

理论说得再多，不如动手实践。下面我将以一个典型的TypeScript + React项目为例，带你一步步创建几个核心的Skill，并分享我们在实战中积累的配置心得。

4.1 环境准备与Claude Desktop配置

首先，你需要一个能方便集成自定义指令的AI助手客户端。Claude Desktop是Matt原版工作流的选择，因为它支持从本地文件系统读取内容作为上下文。

1. 安装Claude Desktop：从官方网站下载安装。
2. 配置自定义指令：在Claude Desktop的设置中，找到“Custom Instructions”或“上下文文件”配置项。关键点在于，你需要配置一个“全局上下文”或“项目上下文”文件路径。更灵活的做法是，使用一个“索引文件”来动态加载不同的Skill。
3. 组织Skill目录：在你的项目根目录下，创建一个.claude或.skills的文件夹（隐藏目录是个好选择）。在里面，为不同类型的Skill建立子目录，例如：

   .skills/ ├── typescript/ │ ├── create-function.md │ └── generate-zod-schema.md ├── react/ │ ├── create-component.md │ ├── create-hook.md │ └── update-component.md └── project-context.md (全局项目上下文)

4.2 编写核心Skill文件详解

让我们深入两个最常用Skill的内部，看看具体怎么写。

4.2.1project-context.md- 定义项目全局上下文

这个文件是所有其他Skill的基础，它定义了AI关于这个项目的“常识”。

# 项目上下文：Acme Dashboard (v2.0) ## 技术栈与版本 - **语言**: TypeScript 5.4+，严格模式 (`strict: true`) - **前端框架**: React 18+，使用函数组件和Hooks - **构建工具**: Vite 5.0+ - **样式方案**: Tailwind CSS 3.4 + CSS Modules (用于复杂组件) - **状态管理**: Zustand 4.4+ - **数据获取**: TanStack Query (React Query) v5 - **HTTP客户端**: 自定义封装基于 `fetch` 的 `apiClient`，详见 `src/lib/api.ts` - **表单管理**: React Hook Form 7.50+ 配合 Zod 3.22+ 进行校验 - **UI库**: 无，使用自定义设计系统组件，从 `@acme/ui` 导入 - **工具类**: 日期处理使用 `date-fns`，工具函数使用 `lodash-es` ## 代码规范 - **代码风格**: 使用项目根目录下的 `.prettierrc` 和 `.eslintrc.cjs` 配置。 - **命名约定**: - 组件: `PascalCase`，如 `UserProfileCard` - 函数/变量: `camelCase` - 常量: `UPPER_SNAKE_CASE` - 类型/接口: `PascalCase` - **导入顺序**: 第三方库 -> 项目内部模块 -> 相对路径导入 -> 样式/类型。使用 `eslint-plugin-import` 自动排序。 - **禁止事项**: - 禁止使用 `any` 类型。必要时使用 `unknown` 或精确类型。 - 禁止使用 `console.log` 提交。使用自定义的 `logger` 工具。 - 禁止直接使用 `fetch` 或 `axios`，必须使用封装的 `apiClient`。 ## 项目结构摘要

src/ ├── components/ # 通用组件 ├── features/ # 功能模块 ├── hooks/ # 自定义 React Hooks ├── lib/ # 工具函数、API客户端等 ├── stores/ # Zustand 状态存储 ├── types/ # 全局类型定义 └── utils/ # 纯工具函数

## 常用代码模式示例 1. **数据查询Hook示例**: ```typescript // 位于 src/features/users/api/use-users.ts import { useQuery } from '@tanstack/react-query'; import { apiClient } from '@/lib/api'; import { User } from '../types'; export function useUsers(options?: { enabled?: boolean }) { return useQuery({ queryKey: ['users'], queryFn: async () => { const data = await apiClient.get<User[]>('/api/users'); return data; }, ...options, }); }

2. Zustand Store示例:

// 位于 src/stores/use-auth-store.ts import { create } from 'zustand'; interface AuthState { user: User | null; login: (email: string, password: string) => Promise<void>; logout: () => void; } export const useAuthStore = create<AuthState>((set) => ({ user: null, login: async (email, password) => { const user = await apiClient.post('/api/login', { email, password }); set({ user }); }, logout: () => set({ user: null }), }));

这个文件内容较多，但至关重要。它一次性告诉了AI关于这个项目的几乎所有“规矩”。 #### 4.2.2 `react/create-component.md` - 创建React组件技能 这个Skill会继承全局上下文，并专注于组件创建的细节。 ```markdown # Skill: create-react-component **描述**: 创建一个新的React函数组件，符合Acme Dashboard项目的所有规范。 ## 上下文继承 请完整阅读并遵循 `.skills/project-context.md` 中的所有规范。 ## 组件特定约束 1. **组件声明**: 必须使用 `const ComponentName: React.FC<Props> = (props) => { ... }` 或更推荐的 `function ComponentName(props: Props) { ... }` 形式。优先使用后者。 2. **Props类型**: 必须定义独立的 `interface` 或 `type` 用于Props。禁止内联定义。 3. **默认导出**: 组件**必须**默认导出 (`export default ComponentName`)。 4. **导入路径**: 使用 `@/` 作为src目录的别名。绝对禁止使用相对路径 `../../` 跳出 `src` 目录。 5. **样式**: - 简单组件: 优先使用Tailwind CSS类名。 - 复杂组件: 必须使用CSS Modules，文件命名为 `ComponentName.module.css`，并在组件顶部导入为 `import styles from './ComponentName.module.css'`。 6. **逻辑分离**: 如果组件逻辑超过50行，考虑将业务逻辑抽离到自定义Hook中。Hook应放在 `src/hooks/` 或对应feature的目录下。 7. **错误边界**: 如果组件涉及数据获取，必须在组件内部或父级进行错误处理，不能仅依赖TanStack Query的error状态。 ## 输出格式 请只输出TypeScript代码。将完整的组件代码包裹在 ```typescript ... ``` 代码块中。不要输出任何解释性文字，除非我明确要求。 ## 范例 **需求**: “创建一个用户头像组件，显示圆形头像，有在线状态指示器。” **输出**: ```typescript import React from 'react'; import cn from 'classnames'; // 假设项目安装了 `classnames` import styles from './UserAvatar.module.css'; export interface UserAvatarProps { /** 用户头像图片URL */ src: string; /** 用户显示名称，用于alt文本 */ alt: string; /** 用户在线状态 */ isOnline: boolean; /** 头像尺寸，默认为 'md' */ size?: 'sm' | 'md' | 'lg'; } const sizeClasses = { sm: 'w-8 h-8', md: 'w-12 h-12', lg: 'w-16 h-16', }; export default function UserAvatar({ src, alt, isOnline, size = 'md', }: UserAvatarProps) { return ( <div className="relative inline-block"> <img src={src} alt={alt} className={cn( 'rounded-full object-cover border-2 border-white', sizeClasses[size], styles.avatar // 假设有一些自定义CSS Modules样式 )} /> {isOnline && ( <span className="absolute bottom-0 right-0 w-3 h-3 bg-green-500 border-2 border-white rounded-full" aria-label="在线" /> )} </div> ); }

当你在Claude中输入“/skill create-react-component 创建一个产品卡片组件，显示图片、标题、描述和价格，支持点击跳转”，AI就会基于这个Skill的严格约束和范例，生成一个风格、导入、模式都完全符合你项目要求的组件代码，几乎无需修改即可使用。 ### 4.3 高级Skill设计：处理复杂逻辑与迭代 对于更复杂的任务，比如“重构一个冗长的组件”，单一的生成技能可能不够。这时需要“迭代修改”技能。 #### 4.3.1 `react/update-component.md` - 迭代修改组件技能 这个Skill的关键在于引导AI进行“最小化修改”，并理解代码差异。 ```markdown # Skill: update-react-component **描述**: 根据要求，对提供的现有React组件代码进行精准修改。目标是进行最小化变更，保持原有代码结构和风格。 ## 核心原则 1. **只改必要部分**: 除非要求，否则不要重写整个组件。只修改与需求直接相关的代码行。 2. **保持风格**: 修改后的代码必须与原有代码的缩进、命名、引号风格完全一致。 3. **理解上下文**: 我会提供完整的现有组件代码。你的修改必须基于对这段代码逻辑的完整理解。 ## 操作流程 1. 我会首先粘贴现有的组件代码。 2. 然后提出具体的修改要求（例如：“将状态管理从useState迁移到Zustand store `useProductStore`”、“为`handleSubmit`函数添加防抖”）。 3. 你输出**完整的、修改后的组件代码**。在修改的代码行附近，可以添加简短的注释 `// [修改]` 来说明变动，但这不是必须的。 ## 范例 （此处可以提供一个简单的“before & after”例子，展示如何添加一个Prop）

使用这个Skill时，你先粘贴旧代码，再给出指令。AI会像一位经验丰富的同事进行Code Review一样，给出精准的差分修改建议，极大提升了重构和迭代的效率。

5. 效能提升与避坑指南：半年实战经验汇总

部署Skill工作流的前几周是调整期，一旦磨合完成，效率提升是指数级的。以下是我们团队总结的核心经验和常见陷阱。

5.1 效能提升的具体体现

1. 代码评审时间减少70%以上：因为生成的代码在风格、依赖和模式上高度一致，评审者不再需要纠结于缩进、引号这类低级问题，可以专注于业务逻辑本身。
2. 新手快速融入：新成员入职第一天，配置好Claude和项目Skill库，他就能生成符合规范的代码，极大降低了项目熟悉成本和初期犯错概率。
3. 复杂代码生成可靠性提升：对于“生成一个Zod Schema来匹配这个TypeScript接口”这类有明确输入输出映射的任务，Skill的准确率接近100%。我们将OpenAPI文档转TypeScript定义再转Zod校验的流程完全自动化了。
4. 知识沉淀标准化：最好的实践不再只存在于资深成员的脑子里或零散的文档中，而是被固化到了Skill里。任何团队成员都能通过调用Skill，产出同样高质量的代码。

5.2 常见陷阱与解决方案

尽管Skill工作流很强大，但设置和使用不当也会踩坑。

陷阱一：Skill文件过于冗长或模糊

• 问题：把整个项目的代码都塞进上下文，导致每次提示词令牌数超标，响应变慢，且AI可能无法抓住重点。或者约束写得模糊，比如“写好一点”。
• 解决方案：遵循“最小必要信息”原则。上下文只放最关键的技术栈版本、目录结构和1-2个最经典的范例。约束要用肯定、明确的语句，如“必须使用const声明”、“禁止使用alert”。

陷阱二：Skill维护滞后于项目发展

• 问题：项目从React Router v6升级到v7，但Skill里还是v6的范例，导致AI生成过时代码。
• 解决方案：将.skills目录纳入Git管理。任何技术栈或架构的重大升级，对应的Skill更新必须作为任务项列入升级清单。可以建立简单的CI检查，在相关配置文件变更时，提醒更新Skill。

陷阱三：过度依赖AI，创造力下降

• 问题：开发者对所有代码都使用Skill生成，不再思考更优的架构或算法。
• 解决方案：明确Skill的定位是“高级助手”和“规范执行者”，而非“架构师”。它最适合生成重复的样板代码（CRUD组件、API Hook）、执行明确的模式转换（类型生成校验）、或基于清晰范例的扩展。对于全新的、复杂的业务逻辑核心，仍应以人的设计为主，AI辅助实现细节。

陷阱四：不同Skill之间冲突

• 问题：create-componentSkill要求默认导出，但另一个create-hookSkill要求命名导出，造成困惑。
• 解决方案：建立统一的Skill元规则文档，并在所有Skill开头引用。或者，在project-context.md中定义全局的导出规范。定期进行Skill库的“代码审查”，确保一致性。

5.3 我们的Skill目录演进

经过半年演进，我们的.skills目录结构变得更加精细：

.skills/ ├── README.md # Skill使用指南 ├── project-context.md # 全局上下文 ├── api/ │ ├── generate-query-hook.md # 生成TanStack Query Hook │ └── generate-mutation-hook.md ├── react/ │ ├── component/ │ │ ├── create-presentational.md # 无状态展示组件 │ │ └── create-container.md # 数据获取容器组件 │ └── hook/ │ ├── create-context-hook.md │ └── create-effect-hook.md ├── typescript/ │ ├── utility-types.md # 生成Partial, Pick等工具类型 │ └── zod-from-interface.md # 核心技能，从接口生成Zod └── testing/ # 测试相关技能 ├── create-vitest-test.md └── create-storybook-story.md

这种模块化组织，让团队成员能像调用函数库一样，精准地调用所需的AI能力。

6. 超越TypeScript：Skill工作流的泛化思考

虽然Matt Pocock的演示和我们的实践都集中在TypeScript/React领域，但Skill工作流的思想是普适的。它可以迁移到任何你希望AI进行标准化、高质量输出的领域。

• 后端开发：创建create-express-routeSkill，定义项目中间件使用规范、错误处理模式、日志格式和数据库查询封装。
• 数据科学与分析：创建>