1. 这个项目到底在解决什么问题1.1 从一个真实困境说起如果你最近一年在写 TypeScript尤其是用 AI 辅助写代码大概率遇到过这种场景你让 AI 帮你生成一个 React 组件它给你写出来的代码能跑但类型定义一塌糊涂——any满天飞、泛型参数乱用、类型断言随手就来。你让它改它改完还是那个味儿。问题出在哪不是模型不够强而是你给它的工程规范太模糊了。这就是 mattpocock skills 这个项目想解决的核心问题。它本质上是一份写给 AI 看的工程技能目录——把一位资深 TypeScript 教育者多年积累的编码习惯、类型设计原则、测试策略、重构手法拆解成一条条结构化的技能条目让 AI 智能体在生成代码时能按图索骥而不是自由发挥。我在实际项目里试过类似思路效果差异非常明显。同样一句帮我写个带缓存的请求 Hook没有技能目录约束时AI 给出的代码类型松散、边界处理随意挂上一份明确的技能规范后输出的代码几乎可以直接进 Code Review。这个项目的价值就在这儿它把资深工程师的隐性知识变成了AI 可读取的显性规则。1.2 为什么是技能目录而不是提示词模板很多人第一反应是这不就是高级一点的 Prompt 吗我一开始也这么想但仔细拆解后发现两者有本质区别。提示词模板通常是一次性、场景绑定的比如你是一个 React 专家请帮我写……。而技能目录是可组合、可复用、可测试的。它把能力拆成独立单元每个单元有自己的触发条件、输入输出约定、质量校验标准。这就像从给厨师一张菜谱升级到给厨师一套标准化的厨房操作手册——前者只能做一道菜后者能支撑整个餐厅的出品一致性。从工程角度看这个转变很关键。因为 AI 智能体在真实项目里要面对的不是单一任务而是连续多轮的决策这个类型该用联合还是泛型这个函数该拆还是该合这个测试该覆盖到什么粒度技能目录提供的正是这些决策点的判断依据。1.3 适合谁来参考这份内容不是给纯新手看的。如果你连 TypeScript 的泛型约束都还没搞明白直接上技能目录会消化不良。它更适合三类人有一定 TS 基础、正在用 AI 辅助开发的中级工程师你能看懂技能条目背后的意图能判断哪些适合你的项目。团队技术负责人你想给团队的 AI 编码流程建立统一规范这份目录是很好的起点。对 AI 工程实践感兴趣的工具开发者你想理解如何把人类工程经验结构化喂给模型这件事的落地方式。我个人的建议是先通读一遍理解整体思路然后挑 3 到 5 条跟你当前项目最相关的技能手动跑一遍感受一下差异再决定要不要全量引入。2. 核心设计思路拆解2.1 技能条目的三段式结构拆开看每一条技能基本都遵循一个稳定的结构触发场景 操作规范 验收标准。这个结构不是随便定的它对应了 AI 执行任务时的三个关键环节。触发场景解决的是什么时候该用这条技能。比如当需要为一个外部 API 响应建模时这就给了 AI 一个明确的激活条件。没有这个条件AI 要么该用不用要么乱用。操作规范是核心它描述具体怎么做。这里的关键是可执行性——不能写注意类型安全这种废话而要写优先使用 discriminated union 而非可选字段来建模状态。前者 AI 无法执行后者可以直接落地。验收标准最容易被忽略但恰恰最重要。它告诉 AI做到什么程度算合格。比如所有分支必须有类型收窄不允许出现隐式 any。有了这条AI 生成完代码后能自我检查而不是等你发现错误再返工。提示如果你要自己写技能条目务必把验收标准写具体。我踩过的坑就是只写了操作规范结果 AI 生成的代码看起来对但边界情况全是漏洞。2.2 为什么选择 TypeScript 作为切入点这个项目聚焦 TypeScript不是偶然。TS 的类型系统足够表达力强能把很多工程约束编码进去同时它又足够普及前端、Node 后端、工具链都在用。更重要的是TS 的类型错误是可静态验证的——这意味着 AI 生成的代码有一个客观的对错标准而不是靠人主观判断写得好不好。这一点在 AI 工程实践里极其关键。你让 AI 写 CSS好不好看很难自动判断但你让 AI 写 TS类型检查器会直接告诉你哪里错了。这种可验证性是构建可靠 AI 系统的基石。我在做类似尝试时发现凡是能被自动化工具验证的规范AI 的遵守率能到 90% 以上凡是靠感觉的规范遵守率直接腰斩。2.3 从教人到教 AI的思维转换mattpocock 本身是 TypeScript 教育者他的内容原本是给人看的。但把教学材料改造成 AI 技能目录需要一次思维转换。给人看的材料可以留白因为人有常识能补全。比如你说用类型守卫收窄类型人知道该写is关键字、知道要在运行时做检查。但 AI 不会自动补全这些你必须把每一步都写死。给人看的材料可以讲原理因为人能举一反三。但 AI 在单次任务里不需要原理它需要的是可直接套用的模式。所以技能目录里原理被压缩成一句话注释重点全放在怎么做上。这个转换过程其实挺痛苦的我试过把一篇技术文章改造成技能条目删掉了 70% 的为什么只保留是什么和怎么做结果 AI 的执行准确率反而上去了。这说明一个反直觉的结论喂给 AI 的内容信息密度比信息完整度更重要。3. 核心技能条目深度解析3.1 类型建模类技能这类技能解决的是如何把业务概念翻译成类型的问题。我挑几条最有代表性的说。状态建模优先用联合类型。这条技能的核心是当一个值有多种互斥状态时用 discriminated union 而不是一堆可选字段。比如一个请求状态不要写成{ loading?: boolean; data?: T; error?: Error }而要写成{ status: loading } | { status: success; data: T } | { status: error; error: Error }。为什么这么设计因为前者允许出现loading 和 error 同时为 true这种非法状态而后者从类型层面就杜绝了。AI 在生成代码时如果遵循这条技能就不会产出那种看起来能用但状态可能矛盾的代码。我在实际项目里把这条落地后跟状态相关的 bug 少了将近一半。边界数据必须显式建模。外部 API 返回的数据、用户输入、localStorage 读出来的值这些都不能直接信任。技能要求 AI 在接触这些数据的第一时间就做校验和类型收窄而不是一路as到底。具体操作上推荐用 schema 校验库比如 Zod 这类在边界处做一次解析解析通过后再进入类型安全的内部世界。这样内部代码就不需要反复做防御性检查整体复杂度大幅下降。3.2 函数设计类技能函数是代码的基本单元这类技能直接影响代码的可读性和可测试性。单一职责的硬性判断标准。技能里给了一个很实用的判断法如果你需要用和来描述一个函数做了什么那它就该拆。比如这个函数校验输入和发送请求那就是两个职责。这个标准比函数不超过 20 行之类的量化指标更好用因为它抓住了本质。参数超过三个就考虑对象化。这条看似简单但 AI 特别容易违反。它经常生成createUser(name, email, age, role, isActive)这种签名。技能要求超过三个参数时改用对象好处是调用方不用记参数顺序加参数时也不用改所有调用点。副作用显式化。纯函数和带副作用的函数要能一眼区分。技能建议把副作用网络请求、文件读写、日志集中在少数几个明确的函数里业务逻辑尽量保持纯净。这样测试时只需要 mock 那几个副作用点而不是到处打桩。3.3 测试策略类技能AI 写测试有个通病要么不写要么写一堆断言toBeTruthy()的废测试。这类技能就是来治这个的。测试行为而非实现。技能明确要求测试应该描述用户能观察到什么而不是内部调用了什么方法。比如测试一个购物车应该断言加入商品后总价正确而不是addItem 方法被调用了一次。前者在重构后依然有效后者一重构就红。每个测试只验证一个概念。注意是一个概念不是一个断言。一个测试里可以有多个断言但它们应该服务于同一个验证目标。这条技能帮 AI 避免了那种一个测试测了十个不相关的东西失败后不知道哪坏了的情况。边界值必须覆盖。空数组、零、负数、超长字符串、null、undefined——这些边界 AI 默认是不测的技能强制它列出来并逐个覆盖。我实测下来加上这条约束后AI 生成的测试能多抓出 30% 左右的潜在问题。3.4 重构类技能重构是 AI 最容易搞砸的环节因为它需要理解改动的影响范围。小步前进每步可验证。技能禁止 AI 一次性大改要求它把重构拆成一系列小步骤每步之后代码都能编译、测试都能通过。这个约束看起来降低了效率实际上大幅降低了改崩了回不去的风险。先加测试再重构。如果目标代码没有测试覆盖技能要求先补测试确认测试能通过再开始重构。这样重构过程中一旦破坏行为测试会立刻报警。保持公共接口稳定。重构内部实现时对外暴露的函数签名、类型定义尽量不动。如果必须动要同步更新所有调用点并明确标注这是破坏性变更。4. 实操落地把技能目录接入你的开发流程4.1 最小可行接入方案别一上来就想着全量接入那样大概率会失败。我建议从最小可行方案开始。第一步挑三条跟你当前痛点最相关的技能。比如你最近老是被类型问题坑就挑类型建模那三条。把它们整理成一个独立的规则文件放在项目根目录。第二步在你跟 AI 协作时把这个文件的内容作为上下文传进去。具体怎么传取决于你用的工具有的是在对话开头粘贴有的是配置成系统提示。核心是让 AI 在生成代码前能看到这些规则。第三步观察一周。记录 AI 哪些地方遵守了、哪些地方没遵守。没遵守的地方往往是你的规则写得不够具体或者跟 AI 的默认行为冲突太强。第四步根据观察结果迭代规则。把模糊的表述改具体把冲突的地方想清楚是坚持还是妥协。4.2 规则文件的组织方式我试过几种组织方式最后觉得按领域 优先级两层结构最实用。skills/ types/ modeling.md narrowing.md functions/ design.md purity.md testing/ behavior.md boundaries.md每个文件内部用统一的格式写条目## 技能名称 触发场景... 操作规范... 验收标准... 反例...反例这一项是我自己加的实测很有用。AI 看到正例知道该怎么做看到反例知道不该怎么做双向约束比单向指导效果好得多。4.3 参数与阈值的确定过程技能里有些条目涉及具体数值比如函数参数超过三个就对象化。这个三是怎么来的我的经验是这个数字不是拍脑袋定的而是基于人类工作记忆的容量。心理学上有个经典结论人一次能记住的信息块大约是 4 个左右。函数参数超过这个数调用方就容易记混顺序。所以三是个偏保守但安全的阈值。类似的还有嵌套层级不超过三层。超过三层后代码的缩进就开始影响阅读而且往往意味着逻辑可以抽取。这个阈值同样来自实践经验不是硬性规定你可以根据团队习惯微调。注意阈值类规则一定要允许例外。比如某些数学计算函数参数多但语义清晰强行对象化反而降低可读性。技能目录里应该明确默认遵守有充分理由可例外。4.4 与现有工具链的配合技能目录不是孤立的它要跟你的 lint、format、type check 配合。我的做法是能用工具自动检查的规则就不写进技能目录。比如缩进、分号、引号这些交给 Prettier能用 ESLint 规则表达的比如禁止 any配成 lint 规则。技能目录只负责那些工具难以自动检查、需要语义理解的规则。这样分工的好处是工具负责机械性检查AI 负责语义性遵守人负责最终判断。三层各司其职不重叠也不遗漏。5. 常见问题与排查技巧实录5.1 AI 不遵守技能规则怎么办这是最高频的问题。我总结了几个原因和对应解法。原因一规则太抽象。比如你写注意类型安全AI 根本不知道具体指什么。解法是把规则改写成可执行的动作比如所有外部数据入口必须经过 schema 校验。原因二规则太多超出上下文窗口。AI 一次能有效处理的规则数量是有限的塞太多它会选择性遗忘。解法是分批引入或者按任务类型动态加载相关规则。原因三规则之间冲突。比如一条说优先用 interface另一条说优先用 typeAI 就懵了。解法是定期审查规则集消除矛盾。原因四跟 AI 的默认倾向冲突太强。有些规则违背了模型训练时的常见模式遵守起来费劲。这种规则要么加强强调要么接受它偶尔违反。5.2 技能目录导致 AI 变死板有段时间我发现加了规则后 AI 生成的代码虽然规范但缺乏灵活性遇到规则没覆盖的情况就卡壳。解法是给技能目录加一个兜底条款当规则未覆盖当前场景时优先保证代码可读性和正确性并在注释里说明决策理由。这一条给了 AI 在规则之外做判断的空间避免了机械执行。另外规则里要区分必须和建议。必须项是红线建议项可以权衡。全写成必须AI 就没有腾挪余地了。5.3 团队协作中的规则同步多人团队用同一套技能目录最大的问题是版本不一致。A 同学本地改了规则B 同学还在用旧的生成的代码风格就对不上。我的做法是把技能目录纳入版本控制跟代码一起走 Code Review。规则变更需要说明理由重大变更要通知全员。同时给规则文件加版本号AI 生成的代码注释里可以带上遵循 skills v1.2方便追溯。5.4 常见问题速查表问题现象可能原因排查方向解决建议AI 完全无视规则规则未进入上下文检查规则是否真的传给了模型确认传递方式必要时放对话开头部分规则遵守部分不遵守规则优先级不清检查是否有冲突条目明确必须项与建议项生成的代码过度设计规则鼓励了复杂模式检查是否有为用而用的条目增加简单优先的兜底原则规则遵守但代码难读规则过于机械检查是否缺少例外条款补充有理由可例外的说明不同轮次输出不一致上下文被截断检查规则文件长度拆分文件按需加载5.5 我踩过的几个坑第一个坑是规则写太细。我一开始把每条规则都写到具体代码示例级别结果规则文件膨胀到几千行AI 反而抓不住重点。后来精简到每条规则不超过五行效果明显好转。第二个坑是忽略负面示例。只告诉 AI该怎么做它经常用错地方。加上不该怎么做的反例后误用率大幅下降。第三个坑是没有定期清理。项目演进后有些规则已经过时但还留在目录里导致 AI 遵守了错误的规范。现在我每个月会过一遍规则集删掉不再适用的。第四个坑是期望值过高。技能目录能提升 AI 输出的下限但不能保证上限。它让 AI 少犯低级错误但复杂的架构决策还是得人来定。想清楚这一点心态就平和了。6. 从技能目录延伸出的 AI 工程思考6.1 隐性知识的显性化是核心价值这个项目最打动我的地方不是它具体写了哪些规则而是它示范了一种方法论把资深工程师脑子里的隐性知识拆解成 AI 能消费的显性条目。这件事的意义远超 TypeScript。任何领域——后端架构、数据建模、UI 设计、甚至写作——都存在大量老师傅知道但说不清的经验。谁能把这些经验结构化谁就能让 AI 在该领域表现得更好。我在自己的项目里尝试过把代码审查经验结构化效果出乎意料。原本 AI 审查代码只会说这里可能有 bug结构化之后它能说出这里违反了 X 规则建议改成 Y。从模糊到具体这就是结构化的力量。6.2 可验证性是可靠 AI 系统的基石回到前面提过的观点TypeScript 之所以适合做这件事是因为它的错误可静态验证。这个特性让AI 生成 → 工具验证 → 反馈修正这个闭环能自动运转。推而广之任何想让 AI 稳定输出的场景都要想办法建立验证机制。写代码有类型检查和测试写文档有格式检查做数据处理有断言。没有验证的 AI 应用本质上是在赌运气。6.3 技能目录的边界在哪里说了这么多好处也得说清楚它做不到什么。它不能替代架构设计。技能目录管的是怎么写不管写什么。系统该怎么分层、模块该怎么划分这些还是人的活。它不能保证 100% 遵守。AI 是概率系统再明确的规则也有被忽略的时候。所以关键路径上的代码人工审查不能省。它不能自动适应新场景。规则是人写的遇到全新问题还是得人来更新规则。技能目录是工具不是魔法。想清楚这些边界你就能合理设定预期把它用在刀刃上而不是指望它包治百病。6.4 后续可以怎么扩展如果你已经跑通了基础版本可以考虑几个扩展方向。一是按项目类型定制规则集。React 项目、Node 服务、CLI 工具它们的工程约束不一样规则集也该有差异。二是引入规则优先级和依赖关系。有些规则是基础有些是进阶理清它们的关系能让加载更智能。三是建立规则的效果度量。记录引入某条规则前后AI 输出的质量变化用数据指导规则的增删。四是跨语言迁移。这套方法论不限于 TypeScriptPython、Go、Rust 都能用只是具体规则要重写。我个人在实际操作中的体会是技能目录这东西投入产出比最高的阶段是从 0 到 1——也就是从完全没有规范到建立起第一批核心规则。这个阶段能解决 80% 的常见问题。再往后就是精细打磨边际收益递减要根据实际需求决定投入多少。别为了追求完美规则集而陷入无休止的调整先用起来在实战中迭代才是正道。