说实话刚开始把 Claude Code 引入到日常开发时我用的方式非常“裸”打开终端敲 claude然后把问题一句一句丢给它像在用聊天软件。代码报错了把报错贴进去要写个脚本描述一下需求让它直接生成偶尔让它重构某个函数再手动复制回编辑器。第一批任务确实惊艳但越到后面越不对劲。同一个项目我每个新会话都要花大量时间重新描述背景它经常不理解我们仓库的命名规范和目录约定改完 A 文件漏掉 B 文件甚至会在不稳定的状态下凭空“建议”一些根本不存在的 API。我当时以为是大模型还不够强后来才发现问题出在工作流本身——没有把 Claude Code 当成工程体系的一部分来用。真正扭转局面的是两件事Skills 和 MCP。前者把提示词沉淀成可复用的技能包后者用统一协议让 AI 连接真实项目中的工具和数据。这篇内容就围绕这两个关键词聊聊我是怎么从裸用过渡到工程化以及途中踩过的坑。1. 从“裸用”起步那些看似好用但撑不住的时刻1.1 裸用阶段我到底做了什么刚开始用 Claude Code 时我的操作路径非常原始在项目根目录打开终端启动会话然后像跟同事聊天一样提需求。比如贴一段报错信息问“这个为什么报错”或者把某个文件整段塞进对话说“帮我优化一下”再比如让它“写个脚本批量重命名文件”。确实很多一次性任务它完成得相当漂亮尤其是写正则、改 JSON、解释陌生代码这类“短平快”的事情。但问题也随之而来。因为我从来没有给它提供项目级上下文每次新会话它都像第一天入职的实习生对仓库一无所知。我要不厌其烦地解释目录结构、技术栈、命名规范。有一次我让它修改一个登录接口的异常处理它按照通用 RESTful 风格改了但根本没注意到我们这个老项目里统一返回结构是{ code, msg, data }结果前端拿到数据后直接报错。这还不算最难受的。更难受的是它的“记忆力”只存在于当前会话。一旦我关掉终端重开之前的约定、结论、踩过的坑全部归零。明明昨天刚讨论过某个模块不能动今天新会话里它又“自信”地动了。这种体感就像你有一个随叫随到的助手但这个助手每次见面都把你们之间发生过的一切忘得干干净净。1.2 问题集中在哪三个地方裸用阶段的问题我在复盘后大致归纳成三类。第一是上下文断层。AI 没有长期记忆项目背景、技术规范、历史决策全部靠手动重复。随着项目变大重复成本越来越高。第二是动作不可复现。同样的需求今天用一套 prompt明天换一套说法生成的结果千差万别。偶尔调出了一个很满意的处理方式但下次想再用时已经忘了当初是怎么说清楚的。那些“灵光一现”的 prompt 全部散落在聊天记录里没法沉淀。第三是边界缺失。Claude Code 在裸用模式下没有明确的“能做什么、不能做什么”的约束。它可能擅自修改不应该动的文件可能在改完代码后不跑测试也可能因为上下文太长而忽略掉前面的指令。没有验收标准没有工具护栏整个产出就像开盲盒。我当时觉得“AI 编程还不太可靠”但后来才意识到不是它的能力不行而是我压根没有用工程化的方式管理它。裸用本质上是把一个需要流程管理的 Agent 当成了即时问答工具。1.3 促使我改变的那次重构真正让我下定决心整改的是一次老后台重构。项目里有一块基于 jQuery 加服务端模板渲染的报表功能需要抽成一个 Vue3 组件。任务链条很长先梳理原有渲染逻辑再搞清数据接口然后封装组件还要适配现有的样式体系。我用 Claude Code 断断续续改了三天。每天新开会话的第一件事都是重新向它解释项目背景。头两天它还能配合我完成一些片段但到第三天它在改了其中一个子组件后告诉我“整个功能已经完成”。我 review 时发现关联的接口层压根没动样式变量也是新造的和项目现有的设计系统完全不一致。那一刻我彻底明白问题不在模型而在我的工作流。我需要把“项目背景”“操作步骤”“工具连接”全部变成可持续的资产而不是每次靠嘴说。2. Skills把对话经验固化成可复用的工程资产2.1 Skills 不是“高级提示词”而是岗位说明书我第一次认真研究 Skills 时以为它就是把一长段精心写好的 prompt 保存下来这样下次能直接引用。深入用下来才发现完全不是一回事。Skills 是一套结构化的技能包。它通常放在项目根目录的.claude/skills/下每个 skill 是一个独立文件夹里面有一份SKILL.md文件。这份文件不仅仅是“指令文本”它还包含 YAML frontmatter 区域用来声明这个 skill 的name、description、when_to_use等元信息。Claude Code 启动后会扫描这些 skill根据当前用户请求的语义自动判断是否该加载某个 skill。也就是说普通 prompt 是“人主动把它塞给 AI”而 Skill 是“AI 根据任务内容自主选择调用”。前者靠手后者靠机制。用一个生活化的类比普通 prompt 相当于你每次临时吩咐实习生“去帮我倒杯水”而 Skill 是把“倒水流程、水温要求、放在哪个位置”写成一张标准作业指导书实习生看到“想喝水”这个场景就会自己抽出这张卡执行。差距是质的。真正厉害的地方在于Skill 可以按需加载。它不会把所有步骤全部写进系统提示词里而是在任务匹配时才进入上下文既不浪费 token也不会干扰其他任务的判断。这一点在长流程工作中尤其重要。2.2 官方市场、find skills 与社区生态Skills 的生态发展速度比我预期的快。现在官方市场已经提供了不少常用技能包可以直接通过类似skills search的交互式命令查找和安装。社区里也能找到大量别人分享的 skill 库有些直接挂在 GitHub 上支持一键导入。我看到有人在讨论一个叫find skills的辅助工具作用是扫描本地或远程仓库里的 Skills 并给出安装建议。实际用下来它最大的价值不是“帮你装”而是“帮你发现”。如果你不确定某个工作流能不能写成 skill先用这类工具搜一下别人有没有做过类似的事能省不少时间。社区里还有一个热度很高的项目叫Superpower Skills它把大量常用技能打包成一套完整库。这个库的设计思路很有启发但我个人的建议是不要整个仓库全量安装。因为技能数量一多AI 在匹配时可能会被无关描述干扰反而降低准确率。我当时的做法是把这个仓库 clone 下来翻了一遍目录只挑选其中两三个真正贴合我日常需求的 skill 文件手动挪进自己的项目里。这样既能享受社区成果又不会让技能系统变得臃肿。2.3 手写一个前端开发的 Skill附模板与其依赖别人的 skill我更推荐从自己的重复劳动中提炼。拿我最常做的“前端组件开发”举例我写了一个名为fe-vue-component的 skill专门规范 Vue3 组件的创建流程。目录结构很简单.claude/skills/fe-vue-component/ └── SKILL.mdSKILL.md的内容大致长这样--- name: fe-vue-component description: 用于创建或重构 Vue3 组件当用户提出“写组件”“封装弹窗”“做按钮”等需求时使用 when_to_use: 需要新增或修改 Vue3 组件时 --- ## 目标 按照当前项目的组件规范生成代码避免引入项目外的命名和样式习惯。 ## 步骤 1. 查看项目现有组件目录src/components确认命名和文件组织方式。 2. 阅读项目相关样式变量文件src/styles/variables.scss只使用已有变量。 3. 生成组件模板使用 script setup langts。 4. 组件的 props 必须定义类型和默认值。 5. 抛出的事件统一使用 emit 声明。 6. 生成配套的单元测试文件覆盖默认渲染、props 传参和事件触发。 ## 验收标准 - 组件文件可以通过 ESLint 检查。 - 没有引用不存在的样式变量或工具函数。 - 单测全部通过。这个 skill 写好后我在一个新会话里只需要说“帮我写一个确认弹窗组件”Claude Code 就会通过 description 自动匹配到这个技能包然后按照上面的步骤执行。它不会再问我“你们项目用什么框架”这样基础的问题也不会凭空造出来一个不存在的样式变量。如果你要自己写关键有两点一是description要写得具体包含你可能用的动词和对象名否则 AI 容易匹配不上二是正文步骤要写得机械、可执行别写形容词别写模糊的目标要用 AI 能一步步执行的指令。2.4 我筛选 Skills 的四个标准沉淀 skill 这个习惯挺好但如果不加控制skill 库很容易变成垃圾场。我一开始什么都想往里塞写了十几个技能包结果真正高频使用的没几个反而因为技能太多AI 匹配的时候经常选错。后来我删到只剩五个核心技能正常工作反而顺畅了。我现在筛选一个需求是否要沉淀为 Skill只问四个问题筛选标准我的解释是否重复出现三次以上偶尔一次的操作不值得做成技能反复做的动作才值得固化是否只解决一件事一个 Skill 只负责一个场景不能做成“万能工具箱”是否有明确验收标准没有验收标准AI 做完之后你不知道对不对是否能让团队复用技能包要能和同事共享里面的路径、命令不能是个人专用路径3. MCP给 Agent 装上标准化的“外部器官”3.1 MCP 出现之前工具接入有多乱Skills 解决的是“AI 怎么做”的问题但 AI 要真正完成工程任务还得能访问外部系统和工具。比如查 GitHub issue、读数据库、操作浏览器、调用内部 API。在我用 MCP 之前这些接入是极其零散的。我记得最早想让 Claude Code 直接查项目里的 Jira 任务靠的是在 prompt 里贴一段认证命令的输出然后人工把结果复制给它。想让 AI 跑测试就让它输出命令我再到另一个终端手动执行再把结果贴回来。整个过程割裂又低效AI 看起来是主角实际上只是个“只会说话的代码生成器”真正的脏活累活还要人肉中转。后来社区里出现了一批为不同平台写的专用插件或 adapter但每家接口都不一样。今天接 GitHub 一套认证明天接数据库一套协议换个 Agent 又得重写。这种“各搞各的”状态本质上和 AI 生态需要稳定基础设施的目标背道而驰。3.2 MCP 协议的核心机制工具发现与调用MCPModel Context Protocol要解决的就是这个“标准接口”问题。它最早由 Anthropic 提出如今已经变成 AI Agent 与外部工具之间事实上的开放协议之一。你可以把它理解成一个“USB-C 接口”过去每个设备都有自己的充电口现在统一之后同一个接口可以插不同的设备。从协议层面看MCP 的运作机制主要有三个角色MCP Server 负责把工具能力暴露出来MCP Client 负责在 AI 和 Server 之间建立连接AI 模型则作为调用方按需使用工具。Claude Code 原生就是一个 MCP Client它启动时会根据配置连接若干 MCP Server获取这些 Server 暴露出的工具列表然后在对话过程中自主决定何时调用某个工具。整个过程可以简化为工具发现、工具选择、工具调用、结果返回。AI 不需要提前内置某个系统怎么访问只需要按 MCP 规范向 Server 发起请求Server 收到后执行动作再把结构化结果返回给 AI。这样新增一个工具、替换一个工具都不需要改 AI 本身的逻辑只改配置就行。3.3 常用 MCP 服务与选型建议在实际项目中我接入的 MCP 服务基本都是围绕“读取项目信息、调用外部系统、执行并验证动作”这三类需求来选的。下面是几个我常用的类型和选择建议MCP 服务类型典型实现我用来做什么注意事项文件系统 MCPmodelcontextprotocol/server-filesystem让 AI 读取指定目录、写文件但不会越权访问全盘权限范围越窄越好别直接给根目录GitHub MCPGitHub 官方 MCP Server查询 issue、PR、创建代码审查评论需要 Personal Access Tokentoken 要用最小权限数据库 MCPPostgres / SQLite MCP Server查表结构、跑只读查询、生成迁移脚本生产库强烈建议配置只读账号浏览器自动化 MCPPlaywright MCP Server做端到端页面验证、截图、检查渲染结果注意并发调用时会占用浏览器实例自定义业务 MCP自己用 Python/Node 封装内部接口把公司内部 API 暴露给 AI统一鉴权优先走内部网关避免公网暴露MCP 的潜力还不止编程领域。我在社区看到有人把 Altium Designer 的 PCB 设计工具封装成 MCP Server也有人给 Unreal Engine 5.8 做了 MCP 集成让 AI 能在游戏引擎里调场景对象。这说明它正在变成一个通用“外设协议”AI 能触及的边界会越来越大。3.4 Claude Code 接入 MCP 的实操流程接入 MCP 并不复杂关键是要清楚配置位置和测试方法。以我常用的项目级配置为例我会在项目根目录创建一个.mcp.json文件。这个文件会随仓库提交让团队里所有人拿到同一个配置。一个最小可用的配置大概长这样{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: 你的token } } } }配置完成后我一般会在 Claude Code 会话里输入/mcp查看当前已连接的服务器列表再用/mcp test测试某个 server 是否正常。如果配置正确对话里提到“查一下这个 issue 的详情”AI 就会自动选择 GitHub MCP 工具去拉取数据。这里有几个我从实际踩坑中总结的点不要把 token 直接写在.mcp.json并提交到仓库。更好的做法是从环境变量读取或者使用配置文件引用的方式。首次运行通过npx拉取 server 包时会比较慢有时候会误认为失败。可以先手动在终端跑一次把包缓存好再交给 Claude Code。不要一次性接入太多 MCP 服务。服务多了AI 在每次任务时都要“考虑”要不要用哪个工具反而拖慢判断也让上下文更容易膨胀。3.5 多 AI 协作中的 MCP 定位最近“多 AI 协作”的话题越来越热很多人期待不同 AI Agent 之间能互相交流。在我看来真正落地价值更大的多 AI 协作不是让它们之间去自由聊天而是让它们共享同一套 MCP 工具层互相之间通过文件、消息队列或任务结果来协同。举个例子我在一个项目里同时用了 Claude Code 和 Codex。Claude Code 负责把旧模块重构成新组件并写好单测另一个 Agent 则通过 GitHub MCP 创建 PR、补充描述再驱动一个小型测试脚本跑回归。两个 Agent 不直接对话但都在同一个仓库、同一套 MCP 服务下工作各自的结果会落到同一个目录谁需要谁就去拿。MCP 在这里扮演的是“公共工具层”价值在于避免每个 Agent 都去单独对接一套 API。如果你想尝试多 AI 协作我建议先别太花哨。从“一个 Agent 写代码另一个 Agent 做检查”开始把两边的工具分开再通过文件或 Git 分支做交接。等稳定之后再叠加更多角色。一开始就让多个 AI 自由发言大概率会把事情搞乱。4. 工程化工作流落地从“一次性命令”到“可持续体系”4.1 用 CLAUDE.md 补齐 AI 的“入职培训”在我把 Skills 和 MCP 引入工作流后还差最后一块拼图项目级长期记忆。前面说过裸用最大的痛点是每次会话都要重复介绍项目背景。后来我发现 Claude Code 会在项目启动时自动读取根目录下的CLAUDE.md这个文件就是给 AI 看的“入职手册”。我用得很简单把它当成一个持续更新的项目档案。里面会写清楚这几类信息项目目录结构哪些目录是核心源码哪些是生成产物不要动。常用命令测试、构建、lint 的准确命令。代码规范命名方式、组件结构、接口约定。明确禁区哪些目录、哪些操作不允许 AI 自动执行。最近的重要决策比如“当前正在从 jQuery 迁移到 Vue3新代码只允许写在 src 下”。有人会问这和 README 有什么区别区别在于README 是给人看的里面很多背景故事和设计讨论AI 读了反而抓不住重点。CLAUDE.md是给 Agent 看的必须写成指令式、结构化、尽量少歧义。每当我调整工作流比如增加了一个新的 Skill 或 MCP 服务我都会顺手把相关使用方式也记录在这个文件里。这样每次新会话AI 都能快速获得它需要知道的信息。4.2 VS Code 集成让 Agent 在编辑器里工作虽然 Claude Code 本质是命令行工具但长时间开着终端切来切去并不舒服。我目前的主力搭配是 VS Code在集成终端里启动 Claude Code并通过 VS Code 的扩展能力把 AI 的产出直接展示在编辑器里。这样有一个很大的好处Claude Code 生成或修改代码后我可以直接在 diff 视图里逐行确认而不是先手动复制到编辑器、再切换到终端看错误提示。我通常会让它先完成一轮修改然后我切到“源代码管理”面板查看所有变更再决定接受还是回退。另外在 VS Code 里选中一段代码可以直接通过扩展发给 Claude Code 做解释或重构省去了复制粘贴的麻烦。如果你每天要处理大量跨文件改动这类集成体验能让整个流程顺滑很多。但要注意编辑器集成只是“操作层面”的优化真正决定工作流质量的依然是前面说的 Skills、MCP 和CLAUDE.md这些底层资产。4.3 一个需求从提出到交付的完整走读工程化之后我的一个典型任务流程已经和裸用阶段完全不一样。拿前面提到的“报表模块迁移到 Vue3”来说现在的执行顺序是这样的第一步在项目根目录启动 Claude Code。它会自动读取CLAUDE.md了解仓库基本情况和规则然后我先说一句“开始处理报表模块迁移”。此时它不需要我再重复项目背景。第二步它会根据任务描述匹配fe-vue-component这个 Skill然后按照技能包里的步骤先扫描现有组件目录查询样式变量文件确认接口数据格式。这一步主要靠 Skills 保证“按规范做”。第三步我通过 MCP 连接了数据库只读服务让 AI 直接查询报表页面对应的几张表结构拿到真实的字段名和关联关系。这个过程在裸用阶段是做不到的以前都靠我手动导出数据给它。第四步它生成组件代码、修改关联接口调用并且生成单元测试。我会让它先写完测试再跑一遍确认全部通过。如果涉及页面渲染我还会通过 Playwright MCP 打开本地页面看实际效果。第五步我在 VS Code 里 review 所有改动有选择地接受或要求它修改。这一轮下来一个原本要反复对话三天的小型重构现在基本能在半天内完成而且输出稳定很多。4.4 质量保障让 Agent 先写测试再写实现我最后想重点强调一个让我收益巨大的习惯对生成型任务强制让 Agent 先写测试再写实现。这不是什么新概念本质上是把 TDD 引入到 Agent 工作流里但它对 AI 的约束效果出乎意料的好。当你只说“帮我写一个格式化金额的函数”时AI 经常会给出一个看似完整、但边界情况一塌糊涂的实现。但如果要求它先写测试用例它必须先把参数、输出、异常情况、边界值想清楚再动手写代码。这个过程其实是在强迫 AI 做需求拆解。我在一个纯函数提炼的 skill 里就加了这条规则第一步列出函数签名和所有可能的输入第二步写测试用例第三步运行测试确认用例失败第四步实现代码直至测试通过第五步补注释。实测下来这种方式生成代码的“肉眼可见的正确率”提高了很多因为测试用例就是验收标准AI 不再能“自己说完成了就完成了”。5. 常见问题与排查经验实录5.1 Skills 不生效或匹配不准在做完一堆技能包后我第一个遇到的坑就是“Skills 不生效”。具体表现是我在对话里明明说“帮我写个弹窗组件”但 Claude Code 完全没有按我规定的步骤来而是像平时一样自由发挥。排查下来最常见的原因有四种。一是目录结构不对技能包必须放在项目根目录.claude/skills/下放错位置扫不到。二是SKILL.md的 frontmatter 缺少必要字段尤其是description写的太泛导致 AI 无法判断该不该用。三是项目根目录不是当前工作目录Claude Code 启动时就扫错了路径。四是当前对话的上下文已经接近上限模型选择了简单路径而不是去加载一个长 skill。遇到这种情况我建议先检查一下自己的 Claude Code 版本然后通过交互式命令查看当前可见的 skills。你也可以直接在会话里问“你现在能看到哪些 skills”确认它是否感知到了技能包。如果能看到但没触发问题大概率出在description上把它改得更具体一点比如把“处理组件相关需求”改成“当用户提出创建、修改 Vue3 组件时使用”命中率会高很多。5.2 MCP 连不上、工具调用超时MCP 的问题会比 Skills 更“基础设施化”。我整理了一份简单的排查表基本能覆盖绝大多数情况现象可能原因我的处理方式/mcp显示 server not foundnpx 首次拉包失败或网络不稳先手动运行一遍对应命令等缓存成功后再接入调用时返回 401/403token 失效或权限不足重新生成 token尽量使用最小权限 scope工具调用超时server 启动慢或请求数据量过大适当增加超时时间或者把数据查询拆小分批获取node 版本冲突不同 MCP server 依赖的 node 版本不一致用 nvm 或 asdf 固定项目 node 版本多个 server 互相影响全局配置和项目配置叠加检查全局配置避免重复挂载同一个 server另外我还遇到过一种情况本地 Python 写的自定义 MCP server 因为依赖库没有安装完整而启动失败。调试时一定要看当时的启动日志而不是只盯着 AI 的回话。Claude Code 本身提供了状态查看和测试的命令记得多利用。5.3 上下文不够用与结果漂移即使有了 Skills 和 MCP上下文窗口依然是限制。我在做大型重铸时经常碰到的问题是任务进行到一半AI 开始遗忘最初的规则甚至出现“前后不一致”的漂移。这不是因为它变笨了而是上下文里的信息太多太杂早期指令被挤掉了。我的经验是把“上下文工程”当成和 prompt 工程同等重要的事。具体做法有很多用CLAUDE.md承担项目级记忆用 Skill 承载操作步骤用 MCP 查询实时数据这样一来AI 就不需要把大量背景信息塞进对话里上下文压力自然减小。还有一个很实用的小技巧在项目里维护一个worklog.md让 AI 每完成一个重要步骤就往里面追加一条记录。新会话开始时先让它读这个日志再继续任务。这样即使上下文被截断它也总能从外部日志里把关键状态找回来。比“祈祷 AI 别忘事”可靠得多。5.4 团队协作的安全边界最后说一下团队协作里的安全边界。工程化意味着这些 AI 配置不再是一个人电脑里的私人玩具而是会进入代码仓库、被多人使用的正式工具。这个阶段安全和权限必须前置。我的具体实践是.mcp.json文件会提交到 git但所有密钥通过本地环境变量加载并且把记录密钥的文件加入.gitignore。MCP 服务给 AI 的权限能收窄就收窄比如文件系统服务只允许操作项目目录数据库服务给只读账号GitHub token 只开需要的仓库范围。同时我也会在CLAUDE.md里写清“禁区”明确哪些命令 AI 不能自主执行比如生产环境发布、删除迁移文件、清理数据库等。当然指望 AI 完全自律并不现实所以最终拦截还是要靠工具层的权限控制规则文本只是第一道提示。团队新人入职后克隆仓库就能获得一致的 AI 配置这比让他们翻文档、装插件、配 token 高效得多。从裸用到工程化我最大的感受是不是 AI 突然变强了而是我的工作流终于把经验变成了资产。以前每次对话都是一次“一次性博弈”现在每次对话都在调用一套可持续升级的基础设施。如果你也卡在“AI 偶尔神勇经常不稳定”的状态不妨从先写一个SKILL.md、配一个 MCP 服务开始。花不了多少时间但整个开发体感会完全不一样。