前阵子我把 Claude Code 的用法彻底重构了一遍。起因很简单项目越做越复杂每次让 Claude 干活前都要重复交代一堆上下文遇到跨仓库、查数据库、翻文档的场景还得手动贴数据。后来我系统性地把 Skills 和 MCP 引入工作流从裸用状态升级到了工程化状态效率提升是肉眼可见的。这篇文章就把我这一路的拆解思路、踩坑记录和最终落地方案完整写出来希望对那些还在把 Claude Code 当高级聊天框用的朋友有实际帮助。1. 从裸用到工程化为什么要重构 AI 开发工作流1.1 裸用的典型状态与痛点先说说什么叫裸用。我刚接触 Claude Code 的时候用法非常简单在项目目录里打开终端敲claude然后把需求输入进去让它改代码。听起来很顺但用久了就会发现几个很难受的问题。第一是上下文断裂。Claude 每次会话只保留当前窗口里的对话历史它不会自动记住你上周定的架构规范、你习惯的目录组织方式、你常用的测试套路。哪怕你昨天刚跟它讨论过一个核心模块的设计今天开个新会话它完全失忆。我一开始的做法是把这些内容塞进 CLAUDE.md但这本质上是靠人肉维护一份越来越长的文档写的时候费劲更新的时候更费劲。第二是工具能力单薄。裸用状态下的 Claude Code主要能力就是读文件、写文件、跑命令、看报错。可实际开发里我需要它查数据库表结构、调用内部 API、读取某个第三方服务的接口文档、搜索企业知识库里的历史决策。这些能力裸用状态下一个都没有每次都得停下来等我手动把数据粘给它。第三是行为不可控。同一个指令今天它给你一套实现明天可能给你另一套完全不同的实现。没有约束的情况下代码风格飘忽、命名习惯不稳定、测试覆盖时多时少。短平快的项目无所谓但一旦进入多人协作、长期维护的阶段这种不确定性就是隐患。1.2 工程化的核心让 AI 掌握方法论而不是碰运气我这里说的工程化不是去改 Claude Code 源码也不是搞什么复杂的自动化部署而是做三件事把团队的规范、项目的上下文、外部工具的能力系统性地暴露给 AI 代理。具体拆开就是三层。第一层是行为规范层告诉 Claude Code 应该遵循什么规则、什么代码风格、什么流程步骤。第二层是能力扩展层让它能够调用外部工具和数据源而不仅仅是在文件系统里打转。第三层是场景封装层把高频的、重复的任务模式固化成可复用的技能让它在遇到同类型任务时自动按最优路径执行。这三层对应到我实际使用中就是 CLAUDE.md MCP Server Skills 的组合拳。CLAUDE.md 管规矩MCP 管触手Skills 管套路。三者配合起来Claude Code 从一个会聊天的代码助手变成了一个懂项目、有工具、有章法的开发参与者。我的核心体会是裸用等于每次都在赌 AI 的临场发挥工程化则是把发挥下限系统性抬高。前者靠运气后者靠设计。2. Skills把高频动作沉淀为可复用能力2.1 Skills 的本质与工作方式Skills 这个概念简单理解就是给 Claude Code 预置的任务执行脚本。它可以是一套包含指令、示例、约束条件、工作流程的描述性文件也可以附带一些可执行的辅助脚本。Claude 在对话过程中会根据当前任务自动检索并加载合适的 Skills然后按照其中定义的方法论来执行。我倾向于把 Skills 理解成一个岗位说明书加操作手册的结合体。它告诉 Claude Code你在什么场景下该做什么事、按什么顺序做、用什么样的标准去检查结果。和你在对话里临时交代一句话不同Skills 是结构化的、可长期积累的、能团队共享的资产。用个生活化的类比裸用 Claude Code 就像你雇了个聪明但没受过公司培训的新员工他什么都会一点但不知道你们公司的流程和标准。Skills 就是入职培训手册把我们这里干活的方式固化下来新人照着手册做产出自然稳定。2.2 从 0 到 1 编写一个自己的 Skill我建议所有人从自己的实际痛点出发写第一个 Skill不要一上来就搞复杂的。以我为例我的第一个 Skill 是代码审查因为团队里每周都有代码评审来回沟通成本很高。编写流程是这样的。首先在 Claude Code 的项目目录下创建一个.claude/skills/目录每个 Skill 一个子目录。目录里放一个SKILL.md文件这个文件是 Skill 的核心描述文件用 Markdown 编写里面包含 Skill 的名称、描述、使用场景和执行步骤。其次在frontmatter区域里写清楚这个 Skill 的元信息。name是技能名description是关键字段因为 Claude 会依据 description 来判断什么时候该加载这个 Skill。description 写得越具体、越带有触发条件命中率越高。比如当用户请求代码审查时使用此技能适用于提交 PR 前的自查场景就比代码审查技能有效得多。然后就是正文部分。我把正文拆成几个固定模块背景与目的、输入要求、执行步骤、质量标准、常见错误避免。执行步骤部分一定要写详细不要用模糊动词。比如检查命名是否符合项目的 camelCase 规范要比检查代码质量可操作性强太多。最后我还给每个 Skill 配了一个examples/目录里面放一两个典型的输入输出示例。Claude 在加载 Skill 时会参考这些示例来理解预期效果这对复杂任务的执行一致性帮助极大。2.3 几个值得抄作业的 Skill 设计我目前线上在用的 Skills 有六个每个解决一类特定问题。除了代码审查还有几个我觉得通用性很强、可以直接借鉴设计的。第一个是技术方案设计。这个 Skill 被触发的场景是当我提出一个功能需求时它不会直接动手写代码而是先输出一份技术方案包含模块拆分、数据流设计、接口定义、风险点评估。最关键的是它要求我确认方案后才进入编码阶段。这个 Skill 帮我避免了最贵的错误——让 AI 照着错误的理解写了大量代码。第二个是Git 提交规范化的 Skill。它会在每次提交前检查暂存区的变更按照团队的 Conventional Commits 规范生成 commit message同时自动关联项目的任务编号。以前我手动写 commit message写多了就敷衍现在这个流程完全自动化了。第三个是重构风险评估 Skill。当我要对某个模块做重构时它会先梳理这个模块的所有调用方、读取测试覆盖情况、列出高风险改动点然后给出一个分步完成的重构计划。它不会一刀切地把代码全部重写而是要求保持行为不变的前提下小步推进。这个 Skill 的设计思想非常适合那些有历史包袱的老项目。写 Skill 的时候有个心得不要试图让一个 Skill 覆盖太多场景。每个 Skill 负责单一职责描述里写清楚触发条件覆盖面窄一点没关系命中率才是关键。3. MCP连接外部工具与数据的标准协议3.1 MCP 到底解决了什么问题MCP 全称是 Model Context Protocol你可以把它理解为 AI 应用接入外部工具和数据的USB 接口标准。在没有 MCP 之前每个 AI 工具要连接外部系统都得为它定制适配器。你给 Claude Code 写一套连接数据库的代码换到其他 AI 工具上又得重写一套。MCP 的架构非常清晰一端是 MCP Server负责封装具体的能力并暴露成标准的工具接口另一端是 MCP Client也就是 Claude Code 这类 AI 应用负责发现可用的工具并通过对话上下文决定是否调用。中间的通信协议是标准化的所以理论上同一个 MCP Server 可以服务任何支持 MCP 的 AI 客户端。对我实际开发工作流来说MCP 最大的价值是把 Claude Code 从只读文件系统变成了能真正和外部世界交互的代理。它可以实时查数据库、请求内部接口、搜索文档、操作测试环境。裸用状态下那种数据靠贴、接口靠查的憋屈感彻底消失了。我最早部署 MCP 的原因很朴素Claude Code 调整一个数据模型之后需要手动跑了 SQL 去验证表结构是否匹配。有了连接数据库的 MCP Server 之后它自己就能查表的字段定义和索引情况反馈到代码修改里。从人工喂数据到自主取数据这个变化是整个工作流效率提升的根基。3.2 搭建和使用 MCP Server搭建一个 MCP Server 并没有想象中那么复杂。MCP 的 SDK 提供了 Python 和 TypeScript 两种主要语言版本你只需要实现一个继承自Server的类然后在内部注册工具函数即可。以我写的一个内部文档检索 MCP Server 为例核心流程分三步。第一步用 SDK 创建服务器实例并声明能力第二步注册一个search_docs工具接收查询关键词返回从内部文档仓库搜索到的条目第三步在配置文件中把服务器地址声明给 Claude Code。配置过程非常简单只需要在你的用户配置目录下找到.claude.json文件在mcpServers字段里声明服务器和启动命令。我的配置结构大致是每个 MCP Server 有一个名字、一条启动命令和必要的环境变量。Claude Code 启动时会自动拉起这些服务器并获取它们暴露的工具列表。一个值得强调的设计细节是MCP 工具函数一定要设计成窄而明确的接口。比如让数据库 MCP 提供query_database这个只读查询工具就不要顺手加一个execute_write的写权限工具。工具的可调用范围确定了 AI 的权限边界接口设计得越窄误操作的风险越低。3.3 选型与组合经验MCP Server 生态增长得非常快市面上已经有大量现成实现数据库连接、GitHub 操作、浏览器控制、文档搜索、设计工具对接、甚至各种专业软件都有社区维护的 MCP 适配。我的选型原则是能复用就不自研自研就瞄准内部资产。像数据库和 GitHub 这类通用能力直接用现成的 MCP Server 就行。但内部文档、私有 API、专属测试环境这些外界无法访问的资源我会自己写 MCP Server 包装起来。组合使用的时候要注意一个实际问题MCP Server 并不是越多越好。每个 Server 都会向 Claude 暴露一组工具工具列表越长模型做工具选择时的负担就越大出现误调用、调错工具的概率也会上升。我目前的策略是按项目维度配置 MCP Server不同的项目只挂载该项目真正需要的服务器。还有一点很重要在引入生产环境之前先在小范围试验。MCP Server 本质上是给 AI 开了一个信息访问通道通道里面跑的数据越敏感出问题的代价就越大。我通常先在本地配置里默认全禁用按需逐个开启并优先给工具函数加只读权限。4. 落地实操一套完整的工程化工作流4.1 项目级配置从零搭起下面我完整跑一遍从零搭建这套工作流的过程你可以直接照着操作。第一步初始化项目目录结构和基础配置。在项目根目录创建.claude/目录里面建skills/和commands/两个子目录。skills/放团队成员共享的各类技能commands/放自定义的斜杠命令比如/review、/test、/deploy这些快捷键。第二步编写根目录的CLAUDE.md。这是 Claude Code 的宪法级文件每次会话都会自动加载。我把它分成几个固定区块项目架构概览、编码规范与命名约定、常用命令与构建流程、部署架构与环境差异说明、与外部服务交互时的注意事项。写这个文件时我踩过一个坑一开始写得太长太细Claude 反而抓不住重点。后来我压缩到 150 行以内只保留必须遵守的硬规则和高频使用的信息效果立刻好了很多。第三步按项目需要挂载 MCP Server。我打开 Claude Code 的配置界面运行/mcp命令进入管理页面然后把当前项目所需的服务器添加进来。添加完成后用/status检查所有 MCP Server 的连接状态确保没有红标报错。第四步把核心 Skill 放进.claude/skills/。项目里所有开发者共用同一个仓库Skills 一进来就能被团队所有人使用。这一步需要配合代码评审流程新增 Skill 必须先经过审核再合入主干避免有人塞入行为不明确的 Skill。4.2 典型场景走一遍从需求到上线的完整链路为了让你更直观地理解这套工作流的效果我拿一个真实的日常工作场景来走一遍完整流程给项目的用户服务模块增加一个密码过期提醒功能。我在终端里打开 Claude Code输入请求同时指定使用技术方案设计 Skill。它先没有写代码而是加载了项目的架构文档和领域模型描述输出了一份包含数据表变更、服务层接口、前端页面改动点的方案。我确认方案没跑偏后回复按方案实施。随后 Claude Code 通过数据库 MCP Server 检查了用户表现有的字段结构确认是否已经有最后修改密码时间字段通过 Git MCP 查看了相关历史提交以了解决策背景然后按项目的编码规范完成了后端改动和测试用例。整个过程中它自己调用工具取数据、自己查文档确认接口语义我在旁边只需要看日志判断方向是否正确。代码写完后触发/review命令。它调用了代码审查 Skill按照预设的检查清单逐项检查了改动命名是否符合规范、是否缺少必要注释、测试覆盖是否充分、是否有明显的异常抛出遗漏。检查结果列在屏幕上我看到一个接口的返回格式与已有约定不完全一致提了一句话让它修正。改完之后触动/test命令它通过测试 MCP 的接口在本地环境跑了一遍新增用例全部通过后它自动生成了一个规范的提交信息把功能、任务编号、改动范围都写清楚了。整套流程走下来我的实际操作量只有描述需求、确认方案、指出一个问题、确认提交。其他所有环节都是 Claude Code 在有规范、有工具、有流程的状态下自主完成的。这不叫取代程序员这叫把程序员的精力从琐碎执行中释放出来。4.3 从单人使用到团队协作个人使用和团队使用之间的差距我觉得主要在于标准和沉淀两个字。个人用的时候Skill 写得粗糙点没关系自己知道自己要什么。但团队用的时候每个 Skill 和每条配置都要经受集体审视。我在团队里推动这套工作流时做了三件事。第一把 Skills 仓库化、版本化管理。所有 Skill 都放在一个独立的 Git 仓库里走 PR 流程合入合入后其他成员拉取更新即可使用。第二约定 CLAUDE.md 的编写职责。项目负责人维护架构信息技术骨干维护规范和最佳实践一线开发者共同维护调试方法和常见问题。第三定期复盘 Skills 的使用效果。每个月看一次哪些 Skill 的触发频率低、哪些场景还覆盖不到然后迭代版本。团队协作中最容易出现的坑是配置漂移。不同成员的本地环境中MCP Server 的版本和配置可能不一致导致同一个 Skill 在不同人机器上的行为效果不一样。我目前的解决办法是在项目仓库里锁定一份配置模板成员通过一条同步命令拉取最新的配置。这个环节我们还在持续优化但整体稳定度已经比早期提升了很多。实操层面的体会工程化不是一次性改造而是一个持续迭代的过程。每当我发现某个环节重复劳动明显就会把它抽象成一个 Skill 或一个 MCP 工具。这样积累下来的资产会越来越大工作流会越用越顺。5. 常见问题与排查技巧实录5.1 高频踩坑与解决方案先说几个我实际使用中反复遇到的问题以及对应的解决办法。第一个是 Skill 没有被触发。明明写了 Skill也放在正确目录了但任务并不匹配。排查思路是检查 Skill 的description字段是否包含足够的触发关键词如果任务描述和 description 之间缺乏语义交集Claude 就不知道什么时候该用这个 Skill。把 description 改成当用户提出任何代码修改请求时先进行方案设计这种带明确触发边界的描述匹配率会大幅上升。第二个是 MCP Server 启动失败。常见原因是依赖未安装完整、端口被占用、环境变量缺失。我的排查套路是先去看 Claude Code 的状态输出定位到具体的 Server 名称然后手动执行一遍启动命令看真实的报错信息。绝大多数情况下问题都出在环境上下文不一致终端里能跑但是被 Claude Code 拉起时缺少了某些环境变量。解决办法是在配置里显式写好环境变量不做隐式依赖。第三个是上下文窗口被撑爆。当 Claude Code 同时挂着 Skill 大文件、加载 CLAUDE.md、还调用了好多个 MCP 工具时上下文容量很快就满了后面的对话质量明显下降。遇到这种情况最好的办法不是在那硬着头皮继续聊而是拆分任务开一个新会话把当前进度和剩余任务通过一个简短的状态文件传递过去。这个做法虽然土但在大任务执行时非常管用。5.2 排查思路与一个小技巧排查这类问题我建议养成从哪个环节断了查哪个环节的习惯。Claude Code 不走通检查配置文件和模型调用日志Skill 不生效检查目录结构和触发描述MCP 连接失败检查服务端进程和网络连通性。链条上每一环单独验证很快就知道瓶颈出在哪。再分享一个我后来才学会的小技巧在项目里维护一个会话状态文件。每当我准备结束一个大任务的会话时让 Claude Code 把当前进度、未完成事项、下一步建议写成一个名为SESSION.md的文件。下个会话开始的时候让它先读这个文件无缝衔接。这个技巧对长周期项目尤其好用直接把上下文断裂这个裸用状态最大的痛点给补上了。5.3 关于这套工作流的几个深刻教训最后想分享几条绝对不会写在官方文档里的教训。第一不要太迷信完全自动化。我给 Claude Code 挂过非常多的 MCP 工具试图让它全自动完成所有事情。结果发现工具越多决策质量反而下降。现在我刻意为它留白每个重要节点都需要我明确确认后才继续。真正的高效不是让 AI 一口气跑到底而是在关键节点上人机协作各自发挥优势。第二Skills 的设计要追求最小有效。每次写一个 Skill 之前先问自己这个场景每个月会遇到几次如果答案是不超过三次那不值得做 Skill。做个通用一点的模板命令就够了。Skill 贵在精不在多经验沉淀要跟着真实需求走不是为了好看去凑数量。第三整个工作流的维护本身需要投入时间。Skills 会过时、MCP 工具会被版本迭代淘汰、CLAUDE.md 里的信息会与实际架构脱节。我在每个迭代周期都会专门留出一个时间段用于更新这套 AI 工作流配置。把它当成项目基础设施来维护而不是写完就再也不管。回头看看这一路的调整我最庆幸的不是学会了某个具体技能而是建立了一套沉淀方法论的习惯。每次发现一个重复性的劳动环节我都条件反射地思考能不能固化成 Skill能不能通过 MCP 打通数据源能不能写进规则文件让它默认遵守正是这种习惯让 Claude Code 从一个偶尔好用的玩具变成了真正能扛起日常开发任务的工程化组件。