上周我让 Claude Code 给项目加个订单改单幂等支持改造它啪一下甩出 200 行代码跑起来直接 500。我盯着报错看了三分钟才意识到问题不在模型是我没跟它讲清楚「权限」到底指什么。这个场景你熟不熟。AI 编程 agent 写不出好代码根因往往不是模型笨是我们没把需求讲清楚。TypeScript 大神 Matt PocockTotal TypeScript 作者6 万开发者订阅的 newsletter 主理人把他每天在用的 agent skills 开源了。今天我就用「加权限控制」这个真实需求带你把这套东西跑通顺便聊聊我最近转到的一个更狠的国产替代品。大家可以点 star 支持下mattpocock/skills 官方仓库https://github.com/mattpocock/skillsspec-superflow 官方仓库https://github.com/MageByte-Zero/spec-superflow先说清楚mattpocock/skills 到底是个啥Matt 对自己的 skills 定位就一句话small、easy to adapt、composable能跟任何模型配合。他明确反对vibe coding也看不上 GSD、BMAD、Spec-Kit 那种「把你的控制权拿走」的重型框架。怎么理解 small / composable。它不是一个大而全的 prompt 模板而是一堆可以单独拿出来改的小技能。你 clone 到项目里哪个不顺手就改哪个。这点对国内团队很关键因为英文社区那套默认假设你用 GitHub、用 Linear到了咱们这环境经常水土不服。换成大白话composable 的意思是你可以只挑/tdd用完全不碰/triage两个 skill 之间不耦合。Matt 把 AI 写代码跑偏归纳成 4 个失败模式每个都有对应解法。第一agent 没按你想的做。根因是你脑子里的决策分支没讲清解法是/grill-me、/grill-with-docs。第二太啰嗦。同一个概念每次换个说法模型越聊越乱解法是建一套共享语言写进CONTEXT.md。第三代码跑不通。缺反馈环解法是/tdd加/diagnosing-bugs。第四写成一团浆糊。架构没设计就开写解法是/codebase-design、/improve-codebase-architecture。两层分类是这套设计的核心。Matt 把 skill 分成 user-invoked 和 model-invoked。前者是你手动敲/xxx来编排流程的比如grill-me、grill-with-docs、triage、to-spec、to-tickets、implement、wayfinder、improve-codebase-architecture、setup-matt-pocock-skills、ask-matt。后者是 agent 自动调用或你主动调用的持有可复用纪律比如tdd、diagnosing-bugs、research、domain-modeling、code-review、resolving-merge-conflicts、prototype、grilling。mattpocock/skills 两层技能架构我得强调一个关系。user-invoked 负责「编排」它会去调用 model-invoked 的纪律。比如你跑/implement它内部会驱动/tdd提交前再拉/code-review。所以两层不是并列摆设是「调度员」加「执行工人」。社区里最火的两个是/grill-me和/grill-with-docs前者逼你想清后者还顺手把共识落成文档。一句话记住。user-invoked 负责「想清楚、排好队」model-invoked 负责「动手做、做漂亮」。三步装好5 分钟跑起来安装有两种姿势取决于你想不想改源码。第一种直接 copy 进项目可改。skills.sh这套会把 skills 原样拷进你的仓库你后续随便 hack。npx skillslatest add mattpocock/skills跑完你会看到项目里多了一个 skills 目录里面每个技能都是独立文件夹各自带一份SKILL.md改起来零成本。我试了从敲命令到看到目录生成不到 20 秒。这种方式的代价是你得自己追作者更新但换来的是完全的控制权。第二种Claude Code 插件市场只读随作者更新。你不想改源码、只想用最新版就走这个。/plugin marketplace add mattpocock/skills /plugin install mattpocock-skillsmattpocock区别在哪儿。第一种你拥有副本能改第二种作者一更新你就自动跟上但动不了源码。说实话个人项目用第一种公司项目用第二种省心毕竟没人想每次 upstream 改了都得手动 merge。装完还不是终点**真正让它生效的是/setup-matt-pocock-skills**。这条命令会连问你三个问题把工作流跟你团队的实际工具对齐。setup-matt-pocock-skills 配置流程它会问用哪个 issue tracker选项有 GitHub、Linear、local files。再问triage 阶段用什么 labels 来分类比如bug和feature。最后问/triage生成的 docs 存到项目哪个位置常见是docs/。这三个答案定下来整套 skill 才算真正接进你的研发流。我第一回跳过了这步结果/to-spec生成的 spec 不知道往哪放白跑一遍。所以这条命令别省。装完顺手ls skills看一眼确认每个 SKILL.md 都躺在那后面调用才不会报找不到。实战用 /grill-me 把「加权限」逼问清楚现在拿开头那个真实需求串一遍「帮我在项目里加一个权限控制」。你以为这句话够了其实不够。敲/grill-meagent 会像审犯人一样把「权限」背后的每个决策分支都问出来。是基于角色的 RBAC还是基于属性的 ABAC。管理员能删别人数据吗。没登录的人看到什么。我那次被问了 11 轮才发现自己根本没想清楚「游客能不能看预览」。**更狠的是/grill-with-docs**。它不只是问还会把你们达成共识的共享语言写进CONTEXT.md把关键架构决策写进ADRArchitecture Decision Record。这俩文件后续所有 skill 都会读等于给团队和 agent 建了本「通用词典」。grill-with-docs 闭环拿我那个权限需求举例CONTEXT.md里会记一句「权限在本项目指 RBAC角色含 guest/adminguest 仅可读预览」。以后不管哪个 skill 上手都不会再把 guest 当匿名处理。这种共享语言才是/grill-with-docs比/grill-me多出来的价值从「想清楚」升级到「记下来」。有了共享语言下一步/tdd。它强制红绿重构一个 feature、一个 bug 都按垂直切片来先写挂的测试再写能过的实现。我那个权限接口就是先写了「未授权访问返回 403」的测试才动手写中间件结果一次跑通没踩坑。需求聊透了怎么办。用/to-spec把当前对话直接合成一份 spec 发到你的 issue tracker不用再开会对齐。/implement则按 spec 或 tickets 去构建过程中驱动/tdd提交前还会跑/code-review做 Standards 和 Spec 两轴检查。这套流程跑下来开头那个 500 报错的问题从源头就消失了。不是模型变聪明了是你终于把话说清楚了。用了一周Matt 这套的留白我得讲清楚我客观说Matt 这套真不错但用了一周有两个留白必须讲不然就是盲目吹。第一个偏西方开发者默认。issue tracker 默认 GitHub、Linear文档全是英文。国内团队用起来要改不少地方triage labels 那套也得自己接飞书、接 TAPD。我司用飞书光是把/triage的落点从 GitHub issues 改到飞书多维表就调了大半天官方文档里压根没这种例子。第二个它不强行把执行钉死。Matt 的设计哲学是「给你工具不替你做主」。规划阶段你用/to-spec想得很清楚但到了/implement执行期agent 仍可能跑偏因为中间没有一道硬墙拦着它。这对个人小项目无所谓但棕地大项目、多人协作、要长期维护的场景跑偏一次的代价就很高。我一个同事就遇到过spec 写得好好的实现时 agent 自作主张改了数据模型code review 才抓出来返工大半天。你品这种「规划严、执行松」的断层恰恰是多人协作最怕的。这俩留白正好是国产的spec-superflow补上的地方。顺着这个话头重磅来了。更隐蔽的是Matt 的 skill 之间靠你手动串联。/to-spec出了 spec/implement要不要严格照做全看你 prompt 怎么写没有任何机制校验实现和 spec 对得上。这层信任成本项目一大就压不住也是「规划严、执行松」最让人头疼的地方。这两个坑单看都不致命叠在多人长期项目上就成了慢性失血每次返工都在吞进度你还没察觉。重磅spec-superflow 把纪律焊死了MageByte-Zero/spec-superflow当前版本 v0.10.0MIT 协议。它源码级融合了OpenSpec规划引擎和Superpowers执行纪律还自己写了个contract-builder桥接层独创 8 状态路由。最关键的一点它自包含你不用单独装 OpenSpec 或 Superpowers 运行时一个包全搞定。spec-superflow 8 状态工作流启动就一句话「用 workflow-start 开始」。它做的是内容级状态检测比对你当前 proposal 的范围和契约意图锁自动路由到正确的下一个 skill。你中间卡住了喊一句「帮我看看现在该干什么」它也能接上。完整路径长这样你说「帮我加一个权限控制」它走 workflow-start → exploringneed-explorer 问你是 RBAC 还是 ABAC→ specifyingspec-writer 出四份工件加 Schema 校验→ bridgingcontract-builder 压成 execution-contract.md→ 你批准 → executingbuild-executor 跑 TDD 到 SDD 到 Review Gate→ 收口 → 同步。9 个核心 skill 覆盖完整生命周期。spec-superflow 9 个核心 skillsworkflow-start是入口做内容级状态检测加 8 状态路由还会阻止非法跳转。need-explorer探索需求一次一问加方案对比。spec-writer出 proposal、specs、design、tasks 四份工件Schema 引擎实时校验。contract-builder把四份工件压缩成execution-contract.md。build-executor执行TDD 铁律加 SDD 子代理驱动加 Review Gate。bug-investigator调试4 阶段根因分析连错 3 次以上直接质疑架构。code-reviewer审查三级问题分级。release-archivist收口spec-merger同步。它背后的设计原则写得很直白Spec First、Guarded Handoff、Strong Guardrails、Schema Validated、Execute Disciplined、Self-Contained。前五个合起来就是一句话规划和实现之间有一道护栏不是建议是强制。硬约束才是它和 Matt 最大的区别。没有execution-contract.md或没被批准不允许实现。full 或 hotfix 没有 current execution plan或者任一 wave 缺 pass review receipt不允许推进。需求变了强制回退遇 bug 强制走 debugging不允许「随便试试」。这道墙Matt 那套是没有的。平台覆盖也猛。18 个平台都支持Claude Code、Cursor、OpenAI Codex、GitHub Copilot、Gemini CLI、Cline、Kiro、Windsurf、Qwen Code、Amazon Q、Roo Code、Continue、Pi、Qoder、OpenCode、WorkBuddy、Trae而且全程中文文档。装 spec-superflow一句话启动按你用的工具挑一条命令。WorkBuddy 用户一行搞定。npx spec-superflowlatest install-workbuddy这条命令会把 9 个 skill 直接放进 WorkBuddy 的 skills 目录装完重开对话就能用「用 workflow-start 开始」唤醒。Cursor 用户两种都行。npx spec-superflowlatest install-cursor # 或者 curl -fsSL https://raw.githubusercontent.com/MageByte-Zero/spec-superflow/main/scripts/install-cursor.mjs | node -Claude Code 用户走插件市场。/plugin marketplace add MageByte-Zero/spec-superflow /plugin install spec-superflowspec-superflow装完打开对话输入「用 workflow-start 开始」它会自动检测你当前在流程的哪一步。我第一次启动它直接识别出我已有的 proposal跳到 bridging 阶段省了我重新走一遍探索。**还有个全局 CLIssf**装完能直接npm install -g spec-superflow拿到。常用几条。ssf list # 列出所有 skill ssf validate dir # 校验 spec 是否符合 Schema ssf doctor # 诊断环境是否装全 ssf execution recommend dir # 给当前目录推荐执行策略我常用ssf doctor排查为什么某个 skill 没出现基本 10 秒定位到是插件没激活。顺手给你看两个真实输出体感。$ ssf list workflow-start need-explorer spec-writer contract-builder build-executor bug-investigator code-reviewer release-archivist spec-merger $ ssf validate ./specs ✓ proposal schema valid ✓ 4 artifacts consistent看到这两段你就知道环境是健康的。如果 validate 报红它还会告诉你是哪份工件缺字段不至于盲改。除了 list 和 validate我推荐新人先跑一次ssf doctor它会检查插件市场有没有装全、SKILL.md 是否就位漏了哪步直接报出来。还有个冷门但好用的ssf execution recommend dir给它一个目录它根据改动文件数推荐你走 full、hotfix 还是 tweak 快速路径省得自己判断。另外启动后除了「用 workflow-start 开始」你还能喊「继续上次的工作流」或「帮我看看现在该干什么」断点续跑不用重来。我一般新机器装完先ssf doctor跑一遍确认 9 个 skill 全亮再开 workflow-start避免用到一半发现某个 skill 没加载。mac 和 Linux 一条命令通吃Windows 用 PowerShell 跑同样的 npx 即可路径差异它自己处理不用你手动配环境变量。一张表看清Matt 和 spec-superflow 谁适合你公平说两套不是替代关系是不同取舍。Matt 给你的自由度高spec-superflow 给你的约束力强选哪个看你怕什么。mattpocock/skills vs spec-superflow 对比维度mattpocock/skillsspec-superflow设计理念small、可改、composableSpec First、强护栏、自包含执行纪律软引导不强行约束execution-contract 硬墙TDDSDDReview Gate平台支持不限模型靠 agent 承载18 个平台原生适配文档语言英文中文自包含两层都是独立小文件融合 OpenSpecSuperpowers单包适合场景个人项目、想自己改棕地大项目、多人协作、长期维护我解释下这张表背后的权衡。Matt 那列「软引导」不是缺点是设计选择他信不过「替你做主」的框架所以把控制权留给你。spec-superflow 那列「硬墙」也不是笨重它只对规划到实现的接缝处强制日常写代码照样灵活。所以别看成一个高级一个低级是「要自由」还是「要保险」的区别。我的判断。想要轻量、能随便改、泡在英文生态里Matt 这套很舒服。想要「想清楚再写、写完不跑偏」的硬纪律尤其中文团队、大项目spec-superflow 是更稳的选择。举个具体例子你一个人写 side project需求天天变Matt 的轻量 skill 让你随时改方向不费劲。但你是五人团队维护一个跑了三年的老系统每次合主干都怕 agent 偷偷改结构那道 execution-contract 硬墙就是你的保险丝。所以别被「高级」二字带偏选哪个只看你怕自由还是怕跑偏。说结论中文开发者直接上 spec-superflow省流。如果你是中文开发者做需要长期维护的功能要的就是「想清楚再写、写完不跑偏」别犹豫直接装 spec-superflow。我为什么这么笃定。国内团队三个现实痛点它正好全中中文文档不用翻18 个平台不用挑边站自包含不用先折腾上游运行时。对比 Matt 那套你还得自己把 GitHub 默认改成飞书、把英文文档读顺这些隐性成本对项目进度是实打实的损耗。它把 OpenSpec 的规划严谨和 Superpowers 的执行纪律焊成一道墙这些对国内团队是省心的。GitHub 在这https://github.com/MageByte-Zero/spec-superflow一条命令就能起步比如npx spec-superflowlatest install-workbuddy装完输入「用 workflow-start 开始」就能看见它帮你把需求拆开。小需求你仍可以用 Matt 的轻量 skill 快速过要进主干的大功能交给 spec-superflow 的 execution-contract这一步我替你踩过坑值得。真要二选一也不冲突我前面说的分工就是答案小活儿 Matt大活儿 spec-superflow两边命令都贴在上面了复制粘贴就能跑。别再让 agent 替你把需求「猜」出来那才是开头那个 500 报错的根源想清楚再写比写快更重要。把这篇文章收进你的 AI 编程文件夹下次开工前先问自己一句需求讲清楚了吗没讲清楚就先 grill再上 contract顺序别反。我不是站队国产才这么讲是同样的需求在 Matt 那套里我得自己盯实现在 spec-superflow 里合约替我盯省下的精力够我多 review 两个 PR。常见问题spec-superflow 和 OpenSpec、Superpowers 是什么关系我还要单独装吗。源码级融合不是并列拼装。它把 OpenSpec 的规划引擎和 Superpowers 的执行纪律直接编进自己包里你不需要单独装任何一个运行时这也是它「自包含」的含义。我已经在用 OpenSpec能共存吗。能。建议在不同会话里混用你现有的 OpenSpec 工件可以直接被 spec-superflow 的contract-builder接管不用重写。execution-contract 什么时候算过期。看内容不看时间戳。spec-superflow 做内容级状态检测比对 proposal 范围和契约意图锁内容没变就不过期变了就强制回退重走。SDD 具体怎么工作。build-executor里SDD 子代理先 recommend你 confirm 之后才 plan。每个 wave 先出 review report你给 pass 或 fail拿到 pass receipt 才允许推进下一 wave。一次性脚本或小需求适合用吗。不适合。spec-superflow 明确不服务一次性脚本或纯咨询场景这种用 Matt 的轻量 skill 反而更快。hotfix≤2 文件和 tweak≤4 文件它有快速路径走。