1. 为什么我要把 Claude Code 从“裸用”升级成工程化工作流最早用 Claude Code 的时候我跟大多数人一样就是打开终端敲一句需求等它吐代码复制粘贴跑一下报错了再贴回去。这种“裸用”模式在写个脚本、改个函数的时候确实爽但一旦项目稍微复杂一点问题就全冒出来了上下文丢失、重复解释项目结构、每次都要重新告诉它“我们团队用 pnpm 不用 npm”、生成的代码风格跟项目里其他文件完全不一致。最要命的是你没法把一次成功的协作经验沉淀下来下次换个会话一切归零。后来我开始认真研究Claude Code Skills和MCP这两套机制才意识到它们解决的根本不是“让 AI 多写几行代码”的问题而是把 AI 协作从“一次性对话”变成“可复用、可组合、可版本管理的工程资产”。Skills 负责把领域知识、操作规范、检查清单固化下来MCP 负责把外部工具、数据源、服务能力接进来。两者一结合Claude Code 就不再是一个孤立的聊天窗口而是真正嵌入了你的开发流水线。这篇文章适合两类人看一类是已经在用 Claude Code 但还停留在“裸用”阶段、想进一步提升效率的开发者另一类是刚开始接触 AI 辅助开发、想直接按工程化思路搭建工作流的同学。我会把 Skills 的设计逻辑、MCP 的接入方式、两者如何配合、以及我在实际项目中踩过的坑全部拆开讲清楚。核心关键词Claude Code、Skills、MCP、AI 开发工作流会贯穿全文但我不堆概念只讲能直接抄作业的东西。先说结论Skills 解决的是“AI 该怎么做事”的问题MCP 解决的是“AI 能碰到什么”的问题。前者是方法论后者是工具箱。没有 SkillsMCP 接进来也是一堆散装能力没有 MCPSkills 再规范也只能在本地文件里打转。两者合起来才构成一个完整的 AI 开发工作流。2. Skills 到底是什么把“老员工经验”写成 AI 能执行的规范2.1 Skills 的本质不是提示词模板而是可组合的能力单元很多人第一次看到 Skills会下意识觉得“这不就是系统提示词吗”。我一开始也这么想但用久了发现完全不是一回事。系统提示词是一大段静态文本塞进上下文就完事Skills 是一个有结构、有触发条件、有依赖关系的能力单元。它可以包含指令、示例、脚本、资源文件甚至引用其他 Skills。你可以把它理解成给 AI 写的“岗位操作手册”而不是“一段叮嘱”。举个实际例子。我团队里有一个api-designSkill里面规定了所有新增接口必须用 RESTful 风格、错误码统一走项目里的ErrorCode枚举、分页参数必须叫pageNum和pageSize、返回值必须包一层ResultT。这些规则如果写在系统提示词里每次会话都要占大量 token而且容易被后续对话冲淡。写成 Skill 之后只有当任务涉及接口设计时才会被加载精准且省上下文。Skills 的另一个关键特性是可组合。一个frontend-componentSkill 可以依赖style-guideSkill 和test-writerSkill。当你要写一个新组件时Claude Code 会自动把这几层规范都拉进来生成出来的代码天然符合项目标准。这种组合能力是单纯堆提示词做不到的。2.2 一个 Skill 的标准结构长什么样不同版本的 Claude Code 对 Skills 的目录结构支持略有差异但核心组成是一致的。我以自己项目里最常用的一个 Skill 为例展示它的完整结构skills/ api-design/ SKILL.md # 核心指令文件定义触发条件和行为规范 examples/ good-example.ts # 正面示例 bad-example.ts # 反面示例 scripts/ validate.sh # 可选的校验脚本 resources/ error-codes.md # 参考资源SKILL.md是整个 Skill 的入口通常包含三部分元信息名称、描述、触发关键词、指令正文具体规则和步骤、引用关系依赖哪些其他 Skill 或资源。元信息里的描述非常关键它决定了 Claude Code 在什么场景下会主动加载这个 Skill。描述写得太窄该触发时不触发写得太宽不该触发时乱触发反而干扰正常任务。我踩过的一个坑是早期我把api-design的描述写成“用于接口开发”结果写前端组件时它也偶尔被拉进来因为“组件要调接口”也算沾边。后来改成“当任务涉及新增、修改后端 HTTP 接口定义时使用”触发就精准多了。这个细节看起来小但直接影响工作流的稳定性。2.3 为什么 Skills 能解决“每次都要重新解释”的痛点“裸用”模式下最大的浪费是重复沟通。你每开一个新会话都要告诉 AI项目用什么框架、目录怎么组织、命名规范是什么、测试怎么写、提交信息格式是什么。这些信息每次都要重新输入既费 token 又费精力而且 AI 还不一定每次都记得住。Skills 把这些“项目常识”从对话里抽出来变成持久化的资产。你只需要在项目根目录维护一套 Skills所有会话共享。新来的同事只要拉下代码Claude Code 就自动具备同样的项目认知。这一点对团队协作的价值极大——它把“某个人很会用 AI”变成了“整个团队都用同一套 AI 规范”。更妙的是Skills 可以版本管理。你可以用 Git 追踪每次规范变更谁改的、为什么改、什么时候生效全都清清楚楚。这比散落在各处的提示词片段靠谱太多。我现在的习惯是每当团队在代码评审里发现一个反复出现的问题就把它固化成一个 Skill 规则。久而久之Skills 库就成了团队工程规范的活文档。3. MCP 接入实战让 Claude Code 真正“长出手脚”3.1 MCP 是软件协议别跟硬件协议搞混先澄清一个高频困惑MCP 全称是 Model Context Protocol它是一个软件层面的通信协议不是硬件协议。你可以把它类比成“AI 工具界的 USB-C 接口标准”——以前每个工具都要为每个 AI 客户端单独写适配现在只要工具实现了 MCP任何支持 MCP 的客户端都能直接调用。它定义的是“AI 如何发现工具、如何调用工具、如何拿回结果”这套交互规则。这个类比很重要因为很多人第一次听到“协议”两个字会联想到底层硬件通信。实际上 MCP 工作在应用层传输方式通常是标准输入输出或者本地网络端口跟串口、I2C 那些完全不是一个层面。理解这一点你才能明白为什么 MCP 能让 Claude Code 瞬间接入几十种外部能力。MCP 的核心概念有三个Server提供能力的服务端、Client调用能力的客户端比如 Claude Code、ToolServer 暴露出来的具体操作。一个 MCP Server 可以暴露多个 ToolClaude Code 根据任务需要自动选择合适的 Tool 调用。整个过程对用户是透明的你只需要在配置里声明要连哪些 Server。3.2 在 Claude Code 里配置 MCP Server 的完整步骤配置 MCP 的方式取决于你用的是命令行版还是编辑器插件版但核心逻辑一致告诉 Claude Code“去哪里找这个 Server、怎么启动它”。我以最常见的本地 Server 为例走一遍完整流程。第一步确认你的 Claude Code 版本支持 MCP。在终端里执行claude --version如果版本较老先升级。MCP 支持是较新版本才引入的能力老版本里找不到相关配置项。第二步找到配置文件。命令行版通常在用户目录下的配置文件夹里编辑器插件版则在对应插件的设置里。配置文件一般是 JSON 格式结构如下{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/your/project] }, database: { command: npx, args: [-y, modelcontextprotocol/server-sqlite, /path/to/db.sqlite] } } }这里mcpServers是固定字段下面每个键是一个 Server 的名字command和args描述如何启动它。filesystem这个 Server 让 Claude Code 能读写指定目录database让它能查询 SQLite 数据库。配置完成后重启 Claude Code它会在启动时自动拉起这些 Server。第三步验证连接。在 Claude Code 里问一句“你现在能访问哪些工具”它会列出当前可用的 MCP Tool。如果列表里没有你配置的 Server说明启动失败需要去看日志排查。注意MCP Server 的启动命令必须能在你的环境里直接执行。如果你用npx启动但本地没装 Node.js或者路径写错Server 会静默失败。我第一次配置时就是因为路径里有个空格没转义折腾了半小时才发现。3.3 几个真正提升效率的 MCP 组合MCP 的价值在于组合。单独接一个文件系统 Server作用有限但把文件系统、数据库、浏览器自动化、项目管理工具全接进来Claude Code 就能完成端到端的任务。我目前工作流里最常用的几个组合文件系统 Git让 Claude Code 能直接读项目文件、看提交历史、理解代码演进脉络。这样它生成的代码不会跟现有风格脱节因为它真的“看过”项目。数据库 接口文档让 Claude Code 能查真实表结构生成的数据访问层代码字段名、类型全都对得上不用我手动改。浏览器自动化 前端项目这个组合特别适合前端开发。Claude Code 可以启动本地开发服务器、打开页面、截图、检查控制台报错然后根据实际渲染结果调整代码。这比“盲写 CSS”效率高一个数量级。项目管理工具把任务系统接进来后Claude Code 能直接读取任务描述、更新任务状态、关联提交记录。整个“接任务—写代码—提 PR—更新状态”的链路可以半自动化。需要提醒的是MCP Server 不是接得越多越好。每接一个 Server启动时就多一份开销上下文里也多一份工具描述。我建议按需接入用完就关。我自己的配置里长期只保留文件系统和 Git 两个其他按项目临时加。4. Skills 与 MCP 协同从“能做事”到“按规矩做事”4.1 两者分工Skills 管规范MCP 管能力单独用 SkillsClaude Code 知道该怎么做但拿不到外部数据单独用 MCPClaude Code 能拿到数据但不知道怎么处理才符合项目规范。两者结合才是完整的工作流。我举个真实场景。团队要新增一个“用户积分查询”接口。没有工程化工作流时我得手动告诉 AI查一下数据库表结构、按我们的接口规范写、错误码用哪个、分页参数叫什么、写完补个测试。有了 Skills MCP 之后我只需要说一句“新增用户积分查询接口”剩下的自动完成Claude Code 先加载api-designSkill知道接口规范然后通过数据库 MCP 查到user_points表的真实结构接着按 Skill 里的模板生成 Controller、Service、Mapper 三层代码再通过文件系统 MCP 把代码写到正确目录最后加载test-writerSkill 补上单元测试。整个过程我只说了一句话。这就是工程化的威力把“人脑里的隐性知识”和“外部系统的显性数据”同时喂给 AI让它在一个受约束的框架里自主完成复杂任务。4.2 设计协同工作流时的三个关键决策第一个决策Skill 的粒度怎么定。太粗一个 Skill 管所有事触发不准太细几十个 Skill 互相依赖维护成本高。我的经验是按“职责边界”划分一个 Skill 对应一类明确的开发活动比如“接口设计”“组件开发”“数据库迁移”“测试编写”。每个 Skill 控制在 200 行以内超过就拆。第二个决策MCP 的权限怎么控。文件系统 MCP 如果给了整个磁盘的读写权限风险很大。我的做法是每个项目单独配置只开放项目目录数据库 MCP 只给只读账号。写操作尽量通过 Skill 里定义的脚本走而不是让 AI 直接调 MCP 写。这样既保留了灵活性又控制了风险。第三个决策失败时怎么兜底。MCP Server 可能挂Skill 可能触发错。我在工作流里加了一层“自检”机制关键操作完成后Claude Code 会跑一遍 Skill 里定义的校验脚本比如 lint 检查、类型检查、测试。校验不过就回滚重来而不是把错误代码直接提交。4.3 一个完整的端到端工作流示例我把上面这些串起来展示一个从需求到提交的完整流程。假设任务是“给现有订单列表加一个按状态筛选的功能”。第一步Claude Code 读取任务描述识别出这涉及后端接口修改和前端组件修改自动加载api-design和frontend-component两个 Skill。第二步通过数据库 MCP 查询订单表结构确认状态字段的名称和枚举值。第三步按api-designSkill 规范修改后端接口新增status查询参数更新对应的 Service 和 Mapper。第四步按frontend-componentSkill 规范修改前端列表组件新增状态下拉筛选框绑定查询参数。第五步加载test-writerSkill为后端接口补上参数校验测试为前端组件补上交互测试。第六步运行 Skill 里定义的校验脚本确认 lint、类型检查、测试全部通过。第七步通过 Git MCP 创建分支、提交代码、生成符合规范的提交信息。整个过程我参与的部分只有第一步和最后一步的确认。中间六步全是自动完成。这就是我所说的“从裸用到工程化”的实际差距。5. 实操中踩过的坑与排查速查表5.1 Skills 不触发或乱触发怎么办这是最常见的问题。表现是明明写了 SkillClaude Code 却不用或者在不该用的场景下硬套。根本原因通常是 Skill 的元信息描述不够精准。排查思路分三步。第一检查SKILL.md里的描述字段看它是否用了足够具体的触发条件。避免“用于开发”这种模糊表述改成“当任务涉及新增或修改后端 HTTP 接口时使用”。第二检查是否有多个 Skill 的描述重叠导致竞争。如果有合并或明确边界。第三在 Claude Code 里手动问它“你为什么没加载某个 Skill”它的回答往往能直接指出问题。我自己的经验是Skill 描述里最好包含正向触发词和反向排除词。比如“用于接口设计不用于前端组件开发”。这样能大幅降低误触发率。5.2 MCP Server 启动失败怎么排查MCP 相关问题的排查核心是看日志。Claude Code 通常会输出 Server 的启动日志和错误信息。常见原因有这么几类问题现象可能原因解决方法Server 列表为空配置文件路径错误确认配置文件在 Claude Code 读取的目录下启动即退出命令不存在或参数错误手动在终端执行一遍启动命令看报错连接超时端口被占用或权限不足换端口或用管理员权限运行工具调用报错Server 版本与客户端不兼容升级 Server 到最新版本中文路径乱码路径编码问题项目路径避免中文和空格提示手动在终端执行 MCP Server 的启动命令是排查问题最快的方法。如果手动都起不来Claude Code 里肯定也起不来。5.3 上下文被撑爆的预防措施Skills 和 MCP 都会占用上下文。Skills 加载指令MCP 加载工具描述。接得太多上下文很快就不够用表现为 Claude Code 开始“忘事”、回复变短、忽略之前的约定。预防措施有三条。第一Skills 按需加载不要把所有 Skill 都设成常驻。第二MCP Server 用完就关尤其是那些工具数量多的 Server。第三定期清理不再使用的 Skill 和 Server 配置。我每个月会 review 一次配置把三个月没用过的全删掉。另外一个小技巧把长文档类的资源放在 Skill 的resources目录里让 Claude Code 按需读取而不是一股脑塞进上下文。这样既保留了信息又不占常驻空间。5.4 团队协作时的配置同步问题Skills 和 MCP 配置如果只存在个人机器上团队协作就会出问题你这边跑得好好的工作流同事那边完全复现不了。解决办法是把 Skills 目录和 MCP 配置模板一起纳入版本管理。我的做法是项目根目录下建.claude/文件夹里面放skills/和mcp.example.json。新同事拉下代码后把mcp.example.json复制成mcp.json填上自己本地的路径和密钥就能获得一致的工作流。Skills 目录直接共享不需要每个人单独维护。这个做法还有一个好处Skills 的变更可以走代码评审。谁改了规范、为什么改都有记录。这比口头传达靠谱得多。6. 我个人的一些实战心得用这套工作流大半年下来最大的感受是AI 辅助开发的瓶颈从来不是模型能力而是工程化程度。同样的模型裸用和工程化用产出质量能差出好几倍。Skills 和 MCP 提供的正是这种工程化能力——前者把经验固化后者把能力打通。我现在维护着大概十几个 Skills覆盖接口设计、组件开发、数据库迁移、测试编写、代码评审、提交规范等场景。MCP 方面长期开着文件系统和 Git按项目临时加数据库和浏览器自动化。这套配置让我在大多数日常开发任务里只需要说一句话就能拿到符合项目规范的完整代码。如果你刚开始搭这套东西我的建议是从一个 Skill 和一个 MCP Server 开始别贪多。先把“接口设计”这一个场景跑通体会到工程化的收益之后再逐步扩展。踩坑是必然的但只要方向对每踩一个坑都是在给未来的自己省时间。最后分享一个我最近才想明白的点Skills 和 MCP 的配置本身也是代码也需要重构。当你发现某个 Skill 越来越臃肿、某个 MCP 组合越来越别扭时那就是该重构的信号。别让工作流本身变成技术债。