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。它包含以下几个关键部分技能名称与描述清晰定义这个技能是干什么的。例如create-react-component创建React组件、generate-zod-schema根据TypeScript接口生成Zod校验模式。上下文信息这是Skill的灵魂。它会注入当前项目的关键信息例如tsconfig.json的编译选项。package.json中的主要依赖及其版本。项目根目录下的README.md或CONTRIBUTING.md中关于代码风格的约定。相关工具ESLint, Prettier的配置文件摘要。项目特定的工具函数库的导入路径和常用模式。范例代码提供1-3个高质量的、本项目内的代码示例。例如对于create-react-component技能会提供一个现有的、风格标准的组件完整代码让AI“依葫芦画瓢”。约束与规则以条目的形式明确规定AI必须遵守和必须避免的事项。例如“必须使用const声明函数组件。”“必须使用我们自定义的useApi钩子进行数据请求而不是直接使用fetch。”“禁止使用any类型。”“样式必须使用CSS Modules类名格式为styles.container。”输出格式明确要求AI输出的格式。例如“只输出代码不要输出解释。”或者“将代码包裹在typescript ...代码块中。”3.2 工作流闭环如何运行一个Skill这套工作流通常与Claude Desktop应用深度集成这也是Matt主要演示的环境。其操作闭环如下触发在IDE或系统全局通过快捷键唤出Claude输入框。选择技能输入特定前缀如/skill或从列表中选择一个预定义的Skill如/create-react-component。提供输入紧接着给出本次任务的具体描述。例如“创建一个名为UserProfile的组件接收userId: string作为prop展示用户头像、名称和邮箱。”AI生成Claude会将Skill文件内容 你的具体描述作为组合提示词生成代码。由于Skill提供了丰富的上下文和约束生成的代码在风格、依赖和模式上与项目高度一致。审查与微调将生成的代码插入项目。由于质量很高审查通常很快。如需小修改可以继续在对话中引用之前的消息进行迭代因为上下文被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原版工作流的选择因为它支持从本地文件系统读取内容作为上下文。安装Claude Desktop从官方网站下载安装。配置自定义指令在Claude Desktop的设置中找到“Custom Instructions”或“上下文文件”配置项。关键点在于你需要配置一个“全局上下文”或“项目上下文”文件路径。更灵活的做法是使用一个“索引文件”来动态加载不同的Skill。组织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.getUser[](/api/users); return data; }, ...options, }); }Zustand Store示例:// 位于 src/stores/use-auth-store.ts import { create } from zustand; interface AuthState { user: User | null; login: (email: string, password: string) Promisevoid; logout: () void; } export const useAuthStore createAuthState((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.FCProps (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 classNamerelative 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 classNameabsolute 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 效能提升的具体体现代码评审时间减少70%以上因为生成的代码在风格、依赖和模式上高度一致评审者不再需要纠结于缩进、引号这类低级问题可以专注于业务逻辑本身。新手快速融入新成员入职第一天配置好Claude和项目Skill库他就能生成符合规范的代码极大降低了项目熟悉成本和初期犯错概率。复杂代码生成可靠性提升对于“生成一个Zod Schema来匹配这个TypeScript接口”这类有明确输入输出映射的任务Skill的准确率接近100%。我们将OpenAPI文档转TypeScript定义再转Zod校验的流程完全自动化了。知识沉淀标准化最好的实践不再只存在于资深成员的脑子里或零散的文档中而是被固化到了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. 超越TypeScriptSkill工作流的泛化思考虽然Matt Pocock的演示和我们的实践都集中在TypeScript/React领域但Skill工作流的思想是普适的。它可以迁移到任何你希望AI进行标准化、高质量输出的领域。后端开发创建create-express-routeSkill定义项目中间件使用规范、错误处理模式、日志格式和数据库查询封装。数据科学与分析创建>