我最早用 Claude Code 的时候其实有点失望。默认状态下它就是一个能看懂代码的聊天终端你问一句它答一句今天嘱咐的约定明天就忘换一台机器更是从零开始。直到我把 CLAUDE.md、Skills、插件和 MCP 这四层扩展真正串起来这个工具才从“能用”变成“好用”。这篇文章就是想把 Claude Code 的扩展栈完整梳理一遍四个部分各解决什么问题、怎么配、配的时候为什么这样做、有哪些文档里不会写的坑。不管你是单人项目的个人开发者还是正准备把 AI 编程助手引到团队里的技术负责人这套思路都可以直接照着落地。它不是教你背 API而是给你一张地图让你知道手里这些积木每一块该往哪儿放。1. 为什么这四样东西必须放在一起讲很多人接触 Claude Code 之后第一步都是先写一个 CLAUDE.md然后以为“配置”就到此为止了。等用了一段时间会发现光有记忆文件还远远不够——AI 知道你们项目的规矩但它不知道遇到事情该走什么流程也够不到项目之外的数据和系统。这时候才想起来 Skills、插件、MCP然后又容易装一堆东西把环境搞乱。问题的根源在于大家把这四样东西当成孤立的“功能”在学而不是当成一个分层协作的体系在理解。1.1 默认状态的 Claude Code 缺三样东西我先说默认状态最让人抓狂的三个问题你就明白扩展栈为什么是刚需。第一个是失忆。默认情况下每个会话开始AI 对项目的了解基本等于零。它知道常见框架的套路但不知道你这个仓库的特殊约定比如“错误处理必须走统一封装”“数据库访问只能经过 repository 层”“提交之前必须跑 lint”。你不说它就不知道而且下次会话还得再说一遍。第二个是没流程。你让 AI“帮我加一个新页面”它也许能生硬地写出来但它不知道你们团队的完整流程是先看路由、再建空组件、补测试、跑 lint、最后按固定格式提交。它会“做”但不会“按规矩做”。这是最别扭的地方——结果像模像样过程乱七八糟。第三个是够不到外部系统。AI 在终端里跑但它默认只能读写当前工作区的东西。你要它去查生产数据库、去调用内部接口、去翻某个远端知识库它是没这个通道的。不是它不会是压根没有手伸出去。扩展栈这四个东西恰好就对应解决上面三个问题CLAUDE.md 管记忆Skills 管流程MCP 管对外连接插件则负责把前面几样打包成一个可以分发、可以安装的整体。1.2 四层各管一件事谁也替代不了谁我用一个比较直白的类比来解释这四层的关系你以后写配置的时候心里就有谱了。CLAUDE.md 是入职手册。它告诉 AI 你们这家“公司”也就是项目的规矩、禁忌、默认偏好。它必须在场而且是常驻的。Skills 是标准作业程序SOP。手册告诉你“公司要求代码评审”SOP 告诉你“评审时先看 diff、再逐项检查错误处理和边界条件、最后按严重程度输出问题清单”。它是按需调用的操作流程。插件是部署包。你把手册片段、SOP、常用命令、自动化钩子打成一个安装包一条命令装到任何项目、任何人的机器上。MCP 是外部接口管道。它给 AI 提供真正能伸手去操作外部世界的工具比如读写指定目录、查数据库、抓网页、操作浏览器。四者不是层层包含的关系而是各管一摊组合起来才是一个完整的扩展体系。下面的表格可能更直观扩展层解决什么问题作用时机典型存放位置谁来维护CLAUDE.md项目记忆与约束每次会话启动时自动加载项目根目录、用户主目录项目负责人Skills可复用的执行流程任务命中描述时按需唤起.claude/skills/目录需要该流程的人插件配置的打包与分发安装后生效随更新迭代插件仓库 / 本地插件目录插件作者MCP外部工具与数据接入会话中按需调用工具.mcp.json/ settings 配置接入方我见过最多的翻车方式就是有人拿 CLAUDE.md 当垃圾桶把所有流程、所有外部工具说明全塞进去结果文件几千行AI 读完了也不知道该先干哪件事。也有人反过来以为接了 MCP 就万事大吉数据库连着但根本没人告诉 AI 怎么按公司规范写查询。这四样东西各归各位才会真正好用。2. CLAUDE.md先让 AI 记住“你项目的规矩”CLAUDE.md 是整个扩展栈的底座也是大多数人第一个会接触的东西。它的定位非常纯粹长期记忆。每次 Claude Code 在项目里启动会话时会自动读取当前项目根目录下的 CLAUDE.md大小写两种写法都能识别把这个文件里的内容当作默认的项目背景知识。这份文件不只会被读一次。它在会话开始时加载上下文压缩之后也会重新加载所以它必须承担起“每次都把该说的规矩说清楚”的责任。你不需要在对话里反复重复项目约定只要把这些约定沉淀进文件里。2.1 文件放在哪里、按什么优先级合并CLAUDE.md 不是只能放在项目根目录。它实际上分成几个层级越靠后的层级代表越通用的记忆项目级放在项目根目录通常叫CLAUDE.md或claude.md随仓库走所有协作者共享。这是最常用的一层。用户级放在用户主目录下的~/.claude/CLAUDE.md存储你用所有项目时都希望 AI 知道的个人偏好比如你惯用的提交格式、你希望代码里注释用什么语言。局部目录在较新的版本里某些子目录也可以放自己的 CLAUDE.md适用于仓库里存在多个独立子项目、规范不一致的情况。不过实际使用中我建议先不要用等单仓多项目的复杂度真正出现再上否则容易踩到“到底哪份文件生效”的坑。这三个层级不是互斥的而是会合并加载。项目级文件带来项目约束用户级文件带上个人偏好两者冲突时项目约束通常优先。这个设计很有用团队规范和个人习惯可以分离不会各说各话。2.2 真正值得写进去的内容写 CLAUDE.md 最大的误区是把它当成一本说明书把什么技术栈介绍、API 文档、安装步骤全往里面塞。这些东西值的不是“让 AI 记住”而是“让 AI 查到”。正确的做法是只写那些不看代码就绝对猜不到的隐性知识。我习惯把内容分成四类项目级别的验证命令。构建、测试、lint、类型检查分别是什么命令一次写清楚省得 AI 瞎猜。架构层面的硬约束。哪些层不能互相依赖、数据库访问必须走哪、新功能要放在哪个目录这类约束代码里看不出来但 AI 一旦违反代码风格立刻崩盘。常见陷阱的记录。比如“这个模块的 hook 不能提前 return否则清理逻辑不执行”“测试环境 mock 必须显式断言调用次数”这些都是你踩过坑换来的经验写进去最值钱。当前项目的“方言”。你们团队对命名、提交信息、注释格式的特殊习惯。举个例子一份精简的 CLAUDE.md 可能长这样# 项目基线 ## 如何验证改动 - 安装依赖pnpm install - 启动开发服务pnpm dev - 全量测试pnpm test -- --run - 提交前必须通过pnpm lint pnpm typecheck ## 代码组织 - 业务逻辑不允许直接依赖 UI 组件层 - 数据库访问统一走 server/db/repo.ts - 新页面先注册到 src/router.ts再创建组件目录 ## 已知陷阱 - 生命周期里的 cleanup 逻辑不能提前 return - 测试环境 mock 请求时必须断言调用次数忽略断言会被当作通过注意这里每个条目前面都是-而不是长段落。官方建议和我的实际体验是一致的CLAUDE.md 尽量用简洁的要点式写法行数控制在 500 行以内。模型在上下文里读长段落散文抓重点的效率远远低于读结构化的条目文件一旦超过某个阈值前面的规则在后面的会话里可能会被稀释甚至丢失。2.3 用 import 做文档索引而不是复制粘贴CLAUDE.md 的另一个关键特性是import指令。你可以在文件里通过路径引入其他文件的内容比如docs/architecture.md被引入的文件会作为 CLAUDE.md 的一部分被加载。这个机制的用途很重要它让你不用把所有内容都塞进一个文件。项目架构文档太长可以放在独立文档里发布流程说明很长可以单独存一个文件CLAUDE.md 里只需要写一行docs/release.md。这样既保持了主文件的精简又能让 AI 在需要时获得完整文档。不过我建议引入的文件同样要克制。每次会话启动时被import的文件也会被加载如果你的主文件引入一堆巨型文档那 CLAUDE.md 是不是精简就不重要了上下文一样会被撑爆。我一般只引入两类东西一是架构总纲二是真正高频使用的流程文档。2.4 我反复踩的 CLAUDE.md 坑先说说我自己最常遇到的问题。第一是文件写得太细连“如果看到 X 就执行 Y”这种琐碎规则都要写结果一天之后AI 的行为被一堆相互掣肘的小规则绑住动一步就撞一条。后来我把那些“行为指令”全部从 CLAUDE.md 里清出去只留“项目事实”行为交给 Skills 去管效果立刻变了。第二是不维护。CLAUDE.md 是活文档仓库目录重构了、命令从 pnpm 换成 bun 了文件还在用旧的信息。AI 的记忆一旦过时比没有记忆更坑因为它会一本正经地用旧命令做新项目。直到我给自己定了一条规矩每次项目有结构性变化顺手更新 CLAUDE.md这个坑才算填上。第三是放着自动生成工具不用。新版 Claude Code 有/init命令可以自动扫描项目生成一份初始 CLAUDE.md也有/memory命令直接在会话里编辑它。很多人不知道有这两个命令还手动敲文件其实用/init生成底稿、再自己补充隐性知识效率高得多。3. Skills把高频流程变成 AI 的肌肉记忆CLAUDE.md 解决了“AI 知道规矩”的问题但规矩是静态的。真实项目里更常见的需求是有一个固定的流程AI 每次遇到同类任务时都应该照着走。比如代码评审、新增模块脚手架、发布前检查、数据迁移脚本的编写规范。这些流程如果都写进 CLAUDE.md文件会膨胀得没法看如果每次在对话里手把手教 Claude效率又太低。Skills 就是专门解决这个问题的。3.1 SKILL.md 的骨架与触发机制一个 Skill 本质上是一个目录目录里必须有一个SKILL.md文件还可以放配套的脚本、模板、参考文档。目录放在固定的 Skills 目录下比如个人级别放~/.claude/skills/项目级别放.claude/skills/插件也可以自带 Skills。SKILL.md的头部有一段 YAML front matter其中最核心的是description字段。Claude 决定“这个任务要不要用这个 Skill”靠的就是这个描述是否命中当前任务。session 启动时它会扫描所有可用技能的 description一旦判定当前用户请求与某个技能匹配才会把技能文件的实际内容加载进上下文。所以写 description 的黄金法则就是不要抽象要具体把触发词写进去。下面这个例子就是正确方向--- name: code-review description: 用于审查代码改动质量。当用户要求 review、检查 MR、提交前自查、或提出“这段代码有什么问题”时使用。 ---注意这里把“review”“检查 MR”“提交前自查”这些实际会出现的说法都列了出来这样描述跟用户真实请求的命中率会明显提高。如果 description 只写“帮助审查代码”很多时候它根本不会被唤起。3.2 一个可复用的 Skill 长什么样SKILL.md 的正文部分是流程指示我强烈建议写成“步骤清单 校验点”的形式而不是一篇自由发挥的散文。还是拿代码评审技能举例# 代码审查流程 1. 先获取 diff只看增量代码不要通读整个文件。 2. 逐项检查 - 错误处理是否完备空值、异常路径 - 边界条件是否有明显遗漏 - 是否有性能隐患重复查询、O(n^2) 循环 - 改动是否偏离项目现有模式以 CLAUDE.md 为准 3. 输出问题清单按“必须改 / 建议改 / 可选优化”分组。 4. 每条问题给出具体修改示例不要只给结论。如果你在 Skill 旁边放一个scripts/目录还可以配合脚本做更复杂的操作比如读取最近的 git diff 生成上下文、调用接口获取 MR 信息。我通常在技能里这么写“先运行scripts/analyze_diff.sh把输出作为审查的输入”。这样技能就不仅是提示词而是一个真正的自动化流程。3.3 Skills 与 CLAUDE.md 的边界很多人分不清 Skills 和 CLAUDE.md 的区别我总结一句非常实用的话约束写进 CLAUDE.md流程写进 Skills。CLAUDE.md 适合放“不许做什么、必须用什么、命令是什么”这类常驻约束。比如“不允许在 reducer 里写异步逻辑”。Skills 适合放“遇到某类任务时按这个步骤做”的流程。比如“写一个新的异步请求模块时先建 action、再建 saga、最后补测试”。同样是“代码规范”相关的内容怎么拆分呢如果内容是判断依据什么算违反规范放 CLAUDE.md如果是执行步骤拿到一段代码后怎么检查放 Skills。判断依据需要每次都在场流程只需要在任务命中时出现。搞清这条边界之后你的配置会干净很多。还有一个容易踩的坑一个 Skill 里写了太多不属于流程的决策性内容。比如技能里塞了一大段“为什么我们规定要用这种写法”这些解释性内容在真正执行时用处不大反而拖长上下文。解释放文档或 CLAUDE.md技能里只留“怎么做”和“做完怎么验证”。4. 插件把散装配置打包成能分发的东西CLAUE.md、Skills 这些配置在你自己机器上整理好了但问题来了怎么给别人用怎么在另一个项目里复用一整套规范总不能靠复制粘贴目录吧。插件Plugin要解决的就是这个问题——它是整个扩展栈的“分发层”。4.1 插件到底是什么插件的本质是一个打包单元。它可以把以下这些组件装进一个“盒子”里Skills、自定义斜杠命令、子代理subagent、钩子hook、MCP 服务器配置甚至 CLAUDE.md 片段。用户通过一条安装命令就能把这个盒子装进自己的 Claude Code 环境里所有组件一起生效。安装流程通常是两条命令。先添加插件市场marketplace然后再安装具体的插件/plugin marketplace add owner/repo /plugin install plugin-name在克隆了插件市场仓库之后插件目录本身放在.claude-plugin/下。一个插件需要两个关键文件marketplace.json描述市场上有哪些插件plugin.json描述这个插件自身。4.2 一个最小插件的解剖plugin.json的结构大意是描述插件里装了哪些组件用一个简化例子说明{ name: team-standards, description: 团队日常开发规范与工程流程, version: 0.2.0, components: { commands: [commands/release], skills: [skills/code-review, skills/scaffold-module], hooks: [hooks/post-tool-use] } }这里的commands是指插件注册的斜杠命令。比如/release一执行就会跑一套发布流程skills就是前面说的技能安装插件等于把技能一起装进来hooks是最有分量的部分它能在特定事件发生时自动触发脚本比如每次工具调用结束后强制格式化代码或者每次会话开始前自动检查分支干净程度。我建议第一次接触插件的人先把“钩子”单独拎出来理解。它是插件里唯一一个不是“让 AI 多做事”而是“在 AI 做事前后自动做点事”的机制。钩子能实现很多硬性约束比如不让 AI 直接修改线上配置、不允许提交前漏掉格式检查。它的用途和 Skills 完全不同常用来做执行边界控制。4.3 什么时候值得做插件插件不是越早做越好。我的建议是先在自己环境里裸配跑通所有组件都稳定了再考虑打包成插件。过早做插件化你会陷入“改代码要重新安装”“版本兼容要对齐”的泥潭真正的业务价值还没体现就被工程复杂度拖死了。出现以下信号就可以考虑打包这套配置要在两个以上项目里复用并且已经稳定运行了两周以上。团队里有多个人需要同一套规范你不想挨个指导。你需要通过钩子对 AI 行为做硬性控制项目级配置不够用了。安全性同样要放在前面。安装任何第三方插件之前先看一下它的仓库内容特别是 hooks 和 commands 部分。插件拥有的权限不小一个恶意的 hook 可以做到的事情远比一个普通配置文件多。我的原则是private 仓库里的自用插件随便装公网第三方插件必须通读代码。5. MCP把外部世界接进来的那根管子再好的记忆和流程都改变不了一个事实Claude Code 默认只能访问当前工作区里的文件。项目用到的数据库数据、内部接口、远端文档它一概够不着。MCPModel Context Protocol就是为了打破这个边界而存在的统一协议层。5.1 MCP 到底解决什么问题MCP 是一个开放的协议用一句话解释它定义了 AI 应用如何与外部工具、数据源、服务进行标准化的通信。你可以把每个 MCP 服务器想象成一根管道管道一端是 Claude Code另一端是你的文件系统、数据库、HTTP 服务、浏览器或者其他任何你想让 AI 操作的东西。这种设计最值钱的地方在于标准化。只要一个服务遵循 MCP 协议Claude Code 就能直接调用它提供的工具不需要为每个外部系统单独写集成代码。打个比方传统集成方式是每个家电厂商给你一根专用遥控器MCP 是统一成一种通用插座所有符合规格的电器插上去就能用。Claude Code 里接入 MCP 后外部服务提供的能力会以“工具”的形式出现在会话中模型在合适的时候自动调用。你可以在/mcp命令里查看当前已经连接的所有 MCP 服务器以及它们提供了哪些工具。5.2 配置 MCP 的几种姿势MCP 配置有几种存放位置用途不一样。最常用的是项目共享配置.mcp.json放在项目根目录随仓库一起提交。里面用mcpServers声明各个服务器每个服务器通过command、args、env定义启动方式。举一个用官方标准服务器连接 git 的示例{ mcpServers: { git: { command: npx, args: [-y, modelcontextprotocol/server-git] } } }如果某个 MCP 只希望你自己用、不想随仓库共享可以放到.claude/settings.json里的mcpServers字段或者通过/mcp命令交互式配置。个人全局配置也有对应的位置通常记录在用户级配置文件里。三种位置的关系是项目级共享配置给团队用局部配置给自己用全局配置给所有项目用。MCP 服务器有两种连接方式。一种是刚才示例里的本地进程方式通过 stdio 通信适合跑在你自己机器上的工具比如本地文件系统、本地数据库。另一种是远程 HTTP 方式连接远端部署好的 MCP 服务适合访问公司内部的统一数据层或者公共 API 网关。远程方式通常需要处理鉴权配置会复杂一些但好处是数据不落地工具统一由服务端维护版本。5.3 安全边界与权限这一节我愿意花多一点篇幅因为 MCP 是扩展栈里权限最大、也最容易被低估的部分。一个 MCP 服务器启动之后它在你的机器上拥有和你当前账号几乎一样的权限。它可以读写文件、发网络请求、执行命令。这跟浏览器里装一个扩展有点像扩展声明了权限它就能做那些事。所以接 MCP 的第一原则就是只接入你信任的服务器。实际操作中我给自己定了三条安全底线第三方公开服务器必须读源代码之后才允许启动一旦发现行为异常立即用/mcp断开。涉及数据库、内部系统的连接串和密钥只通过环境变量注入绝不写进.mcp.json随仓库提交共享配置文件里不要出现任何真实凭据。文件系统类服务器一定要设置允许访问的目录白名单不要让 AI 能碰到整个磁盘。比如默认只允许访问当前项目和指定的数据目录其他路径一律拒绝。还要清楚一件事MCP 服务器带来的上下文负担是真实的。每多一个服务器模型在不调用工具时也要知道这个工具的存在工具越多可用上下文就越被稀释。所以我强烈建议从零到一控制数量先接一个真正高频使用的服务器跑通跑稳再考虑加第二个。不要一上来连五个数据库、三个浏览器AI 没被外部能力撑强反而被工具清单拖笨。5.4 MCP 与 Skills 的分工MCP 和 Skills 都属于“能力扩展”经常被混为一谈但二者分工完全不同。Skills 是流程与行为告诉 AI “遇到这类任务应该怎么做”。MCP 是接口与通道告诉 AI “你有这个工具可以调用”。一个管怎么想一个管怎么够得着。实际上它们经常配合使用Skill 里写清楚流程和判断标准流程中的某一步需要访问外部系统时MCP 工具负责真正执行。举一个实际组合场景数据库迁移质量检查这个任务Skill 定义“先读取迁移文件、检查索引变更、对比生产库结构、输出风险报告”这些步骤其中“读取生产库结构”这一步AI 通过一个数据库 MCP 工具来执行。没有 SkillAI 拿到数据库也不知道该查什么没有 MCPAI 知道流程也够不到数据库。两者缺一不可。这也是为什么我一直强调四层要一起理解和配置而不是单点拼凑。6. 一套可落地的组合建议与我的使用体会前面把四层都拆开讲了最后把它们拼回去给一套我实际使用下来比较舒服的配置基线。你可以参照这个基线从零搭起也可以拿它来审视自己现有的配置哪里失衡了。6.1 我的推荐基线配置扩展层数量建议主要内容CLAUDE.md200~300 行构建命令、架构约束、已知陷阱、import 架构文档Skills3~5 个代码评审、新增模块脚手架、发布前检查、数据迁移检查插件0~2 个团队规范化配置、需要钩子强约束的场景MCP0~2 个文件系统限定目录、数据库或内部接口二选一先接不要追求配置越多越好。我见过一些人的环境CLAUDE.md 写了上千行Skills 十几个MCP 连了七八个服务结果 AI 每次启动都在加载海量信息真正的任务反而不聚焦。扩展栈的价值不是“装得多”而是“分层清楚各司其职”。6.2 最容易翻车的三个组合场景第一把 MCP 当 Skills 用。有人接了数据库 MCP 后以为 AI 就会天然按公司规范写 SQL 了。实际上 MCP 只给了它“连接数据库”的能力规范还得靠 CLAUDE.md 写流程还得靠 Skill 固化。接上 MCP 之后如果发现 AI 写出来的查询风格不对先检查是不是没配流程而不是再换一个 MCP 服务器。第二多层配置互相打架。CLAUDE.md 里说“提交信息用 emoji 前缀”插件里的 hook 又在提交前强制检查 commit template两边不一致时你怎么修都修不干净。我后来养成一个习惯凡是约束类内容只维护一份权威来源其他层引用而不复制。第三插件升级带来的隐性变化。插件是分发单元不是只读配置。别人更新了插件你的环境行为也跟着变有时候 hook 行为变化了你还不知道。凡是对稳定性敏感的项目我会把插件锁在一个固定版本升级前先在分支环境里验证一轮。6.3 最后分享一个小技巧每次会话初期都值得用/context看一眼当前实际加载了什么。很多人以为配置了 CLAUDE.md、装了插件、接了 MCPAI 就全都知道了其实上下文压缩、配置失效、文件路径错误都可能让某部分没有真正生效。这东西就跟看日志一样多看一眼能省掉后面大量的“为什么 AI 不听我的指令”的困惑。我自己的维护节奏是每周顺手翻一遍 CLAUDE.md 有没有过时信息新技能先在真实任务里手工试三次再固化MCP 服务器每加一个就问一句“这个真的高频吗”。按这个节奏用了很长一段时间之后最明显的变化不是 AI 会的东西多了而是它犯的低级错误少了目录不乱建了命令不乱猜了提交前的检查一项都不会漏。扩展栈真正的收益就是这种“不用反复解释它就知道该怎么配合你”的默契。
我最早用 Claude Code 的时候其实有点失望。默认状态下它就是一个能看懂代码的聊天终端你问一句它答一句今天嘱咐的约定明天就忘换一台机器更是从零开始。直到我把 CLAUDE.md、Skills、插件和 MCP 这四层扩展真正串起来这个工具才从“能用”变成“好用”。这篇文章就是想把 Claude Code 的扩展栈完整梳理一遍四个部分各解决什么问题、怎么配、配的时候为什么这样做、有哪些文档里不会写的坑。不管你是单人项目的个人开发者还是正准备把 AI 编程助手引到团队里的技术负责人这套思路都可以直接照着落地。它不是教你背 API而是给你一张地图让你知道手里这些积木每一块该往哪儿放。1. 为什么这四样东西必须放在一起讲很多人接触 Claude Code 之后第一步都是先写一个 CLAUDE.md然后以为“配置”就到此为止了。等用了一段时间会发现光有记忆文件还远远不够——AI 知道你们项目的规矩但它不知道遇到事情该走什么流程也够不到项目之外的数据和系统。这时候才想起来 Skills、插件、MCP然后又容易装一堆东西把环境搞乱。问题的根源在于大家把这四样东西当成孤立的“功能”在学而不是当成一个分层协作的体系在理解。1.1 默认状态的 Claude Code 缺三样东西我先说默认状态最让人抓狂的三个问题你就明白扩展栈为什么是刚需。第一个是失忆。默认情况下每个会话开始AI 对项目的了解基本等于零。它知道常见框架的套路但不知道你这个仓库的特殊约定比如“错误处理必须走统一封装”“数据库访问只能经过 repository 层”“提交之前必须跑 lint”。你不说它就不知道而且下次会话还得再说一遍。第二个是没流程。你让 AI“帮我加一个新页面”它也许能生硬地写出来但它不知道你们团队的完整流程是先看路由、再建空组件、补测试、跑 lint、最后按固定格式提交。它会“做”但不会“按规矩做”。这是最别扭的地方——结果像模像样过程乱七八糟。第三个是够不到外部系统。AI 在终端里跑但它默认只能读写当前工作区的东西。你要它去查生产数据库、去调用内部接口、去翻某个远端知识库它是没这个通道的。不是它不会是压根没有手伸出去。扩展栈这四个东西恰好就对应解决上面三个问题CLAUDE.md 管记忆Skills 管流程MCP 管对外连接插件则负责把前面几样打包成一个可以分发、可以安装的整体。1.2 四层各管一件事谁也替代不了谁我用一个比较直白的类比来解释这四层的关系你以后写配置的时候心里就有谱了。CLAUDE.md 是入职手册。它告诉 AI 你们这家“公司”也就是项目的规矩、禁忌、默认偏好。它必须在场而且是常驻的。Skills 是标准作业程序SOP。手册告诉你“公司要求代码评审”SOP 告诉你“评审时先看 diff、再逐项检查错误处理和边界条件、最后按严重程度输出问题清单”。它是按需调用的操作流程。插件是部署包。你把手册片段、SOP、常用命令、自动化钩子打成一个安装包一条命令装到任何项目、任何人的机器上。MCP 是外部接口管道。它给 AI 提供真正能伸手去操作外部世界的工具比如读写指定目录、查数据库、抓网页、操作浏览器。四者不是层层包含的关系而是各管一摊组合起来才是一个完整的扩展体系。下面的表格可能更直观扩展层解决什么问题作用时机典型存放位置谁来维护CLAUDE.md项目记忆与约束每次会话启动时自动加载项目根目录、用户主目录项目负责人Skills可复用的执行流程任务命中描述时按需唤起.claude/skills/目录需要该流程的人插件配置的打包与分发安装后生效随更新迭代插件仓库 / 本地插件目录插件作者MCP外部工具与数据接入会话中按需调用工具.mcp.json/ settings 配置接入方我见过最多的翻车方式就是有人拿 CLAUDE.md 当垃圾桶把所有流程、所有外部工具说明全塞进去结果文件几千行AI 读完了也不知道该先干哪件事。也有人反过来以为接了 MCP 就万事大吉数据库连着但根本没人告诉 AI 怎么按公司规范写查询。这四样东西各归各位才会真正好用。2. CLAUDE.md先让 AI 记住“你项目的规矩”CLAUDE.md 是整个扩展栈的底座也是大多数人第一个会接触的东西。它的定位非常纯粹长期记忆。每次 Claude Code 在项目里启动会话时会自动读取当前项目根目录下的 CLAUDE.md大小写两种写法都能识别把这个文件里的内容当作默认的项目背景知识。这份文件不只会被读一次。它在会话开始时加载上下文压缩之后也会重新加载所以它必须承担起“每次都把该说的规矩说清楚”的责任。你不需要在对话里反复重复项目约定只要把这些约定沉淀进文件里。2.1 文件放在哪里、按什么优先级合并CLAUDE.md 不是只能放在项目根目录。它实际上分成几个层级越靠后的层级代表越通用的记忆项目级放在项目根目录通常叫CLAUDE.md或claude.md随仓库走所有协作者共享。这是最常用的一层。用户级放在用户主目录下的~/.claude/CLAUDE.md存储你用所有项目时都希望 AI 知道的个人偏好比如你惯用的提交格式、你希望代码里注释用什么语言。局部目录在较新的版本里某些子目录也可以放自己的 CLAUDE.md适用于仓库里存在多个独立子项目、规范不一致的情况。不过实际使用中我建议先不要用等单仓多项目的复杂度真正出现再上否则容易踩到“到底哪份文件生效”的坑。这三个层级不是互斥的而是会合并加载。项目级文件带来项目约束用户级文件带上个人偏好两者冲突时项目约束通常优先。这个设计很有用团队规范和个人习惯可以分离不会各说各话。2.2 真正值得写进去的内容写 CLAUDE.md 最大的误区是把它当成一本说明书把什么技术栈介绍、API 文档、安装步骤全往里面塞。这些东西值的不是“让 AI 记住”而是“让 AI 查到”。正确的做法是只写那些不看代码就绝对猜不到的隐性知识。我习惯把内容分成四类项目级别的验证命令。构建、测试、lint、类型检查分别是什么命令一次写清楚省得 AI 瞎猜。架构层面的硬约束。哪些层不能互相依赖、数据库访问必须走哪、新功能要放在哪个目录这类约束代码里看不出来但 AI 一旦违反代码风格立刻崩盘。常见陷阱的记录。比如“这个模块的 hook 不能提前 return否则清理逻辑不执行”“测试环境 mock 必须显式断言调用次数”这些都是你踩过坑换来的经验写进去最值钱。当前项目的“方言”。你们团队对命名、提交信息、注释格式的特殊习惯。举个例子一份精简的 CLAUDE.md 可能长这样# 项目基线 ## 如何验证改动 - 安装依赖pnpm install - 启动开发服务pnpm dev - 全量测试pnpm test -- --run - 提交前必须通过pnpm lint pnpm typecheck ## 代码组织 - 业务逻辑不允许直接依赖 UI 组件层 - 数据库访问统一走 server/db/repo.ts - 新页面先注册到 src/router.ts再创建组件目录 ## 已知陷阱 - 生命周期里的 cleanup 逻辑不能提前 return - 测试环境 mock 请求时必须断言调用次数忽略断言会被当作通过注意这里每个条目前面都是-而不是长段落。官方建议和我的实际体验是一致的CLAUDE.md 尽量用简洁的要点式写法行数控制在 500 行以内。模型在上下文里读长段落散文抓重点的效率远远低于读结构化的条目文件一旦超过某个阈值前面的规则在后面的会话里可能会被稀释甚至丢失。2.3 用 import 做文档索引而不是复制粘贴CLAUDE.md 的另一个关键特性是import指令。你可以在文件里通过路径引入其他文件的内容比如docs/architecture.md被引入的文件会作为 CLAUDE.md 的一部分被加载。这个机制的用途很重要它让你不用把所有内容都塞进一个文件。项目架构文档太长可以放在独立文档里发布流程说明很长可以单独存一个文件CLAUDE.md 里只需要写一行docs/release.md。这样既保持了主文件的精简又能让 AI 在需要时获得完整文档。不过我建议引入的文件同样要克制。每次会话启动时被import的文件也会被加载如果你的主文件引入一堆巨型文档那 CLAUDE.md 是不是精简就不重要了上下文一样会被撑爆。我一般只引入两类东西一是架构总纲二是真正高频使用的流程文档。2.4 我反复踩的 CLAUDE.md 坑先说说我自己最常遇到的问题。第一是文件写得太细连“如果看到 X 就执行 Y”这种琐碎规则都要写结果一天之后AI 的行为被一堆相互掣肘的小规则绑住动一步就撞一条。后来我把那些“行为指令”全部从 CLAUDE.md 里清出去只留“项目事实”行为交给 Skills 去管效果立刻变了。第二是不维护。CLAUDE.md 是活文档仓库目录重构了、命令从 pnpm 换成 bun 了文件还在用旧的信息。AI 的记忆一旦过时比没有记忆更坑因为它会一本正经地用旧命令做新项目。直到我给自己定了一条规矩每次项目有结构性变化顺手更新 CLAUDE.md这个坑才算填上。第三是放着自动生成工具不用。新版 Claude Code 有/init命令可以自动扫描项目生成一份初始 CLAUDE.md也有/memory命令直接在会话里编辑它。很多人不知道有这两个命令还手动敲文件其实用/init生成底稿、再自己补充隐性知识效率高得多。3. Skills把高频流程变成 AI 的肌肉记忆CLAUDE.md 解决了“AI 知道规矩”的问题但规矩是静态的。真实项目里更常见的需求是有一个固定的流程AI 每次遇到同类任务时都应该照着走。比如代码评审、新增模块脚手架、发布前检查、数据迁移脚本的编写规范。这些流程如果都写进 CLAUDE.md文件会膨胀得没法看如果每次在对话里手把手教 Claude效率又太低。Skills 就是专门解决这个问题的。3.1 SKILL.md 的骨架与触发机制一个 Skill 本质上是一个目录目录里必须有一个SKILL.md文件还可以放配套的脚本、模板、参考文档。目录放在固定的 Skills 目录下比如个人级别放~/.claude/skills/项目级别放.claude/skills/插件也可以自带 Skills。SKILL.md的头部有一段 YAML front matter其中最核心的是description字段。Claude 决定“这个任务要不要用这个 Skill”靠的就是这个描述是否命中当前任务。session 启动时它会扫描所有可用技能的 description一旦判定当前用户请求与某个技能匹配才会把技能文件的实际内容加载进上下文。所以写 description 的黄金法则就是不要抽象要具体把触发词写进去。下面这个例子就是正确方向--- name: code-review description: 用于审查代码改动质量。当用户要求 review、检查 MR、提交前自查、或提出“这段代码有什么问题”时使用。 ---注意这里把“review”“检查 MR”“提交前自查”这些实际会出现的说法都列了出来这样描述跟用户真实请求的命中率会明显提高。如果 description 只写“帮助审查代码”很多时候它根本不会被唤起。3.2 一个可复用的 Skill 长什么样SKILL.md 的正文部分是流程指示我强烈建议写成“步骤清单 校验点”的形式而不是一篇自由发挥的散文。还是拿代码评审技能举例# 代码审查流程 1. 先获取 diff只看增量代码不要通读整个文件。 2. 逐项检查 - 错误处理是否完备空值、异常路径 - 边界条件是否有明显遗漏 - 是否有性能隐患重复查询、O(n^2) 循环 - 改动是否偏离项目现有模式以 CLAUDE.md 为准 3. 输出问题清单按“必须改 / 建议改 / 可选优化”分组。 4. 每条问题给出具体修改示例不要只给结论。如果你在 Skill 旁边放一个scripts/目录还可以配合脚本做更复杂的操作比如读取最近的 git diff 生成上下文、调用接口获取 MR 信息。我通常在技能里这么写“先运行scripts/analyze_diff.sh把输出作为审查的输入”。这样技能就不仅是提示词而是一个真正的自动化流程。3.3 Skills 与 CLAUDE.md 的边界很多人分不清 Skills 和 CLAUDE.md 的区别我总结一句非常实用的话约束写进 CLAUDE.md流程写进 Skills。CLAUDE.md 适合放“不许做什么、必须用什么、命令是什么”这类常驻约束。比如“不允许在 reducer 里写异步逻辑”。Skills 适合放“遇到某类任务时按这个步骤做”的流程。比如“写一个新的异步请求模块时先建 action、再建 saga、最后补测试”。同样是“代码规范”相关的内容怎么拆分呢如果内容是判断依据什么算违反规范放 CLAUDE.md如果是执行步骤拿到一段代码后怎么检查放 Skills。判断依据需要每次都在场流程只需要在任务命中时出现。搞清这条边界之后你的配置会干净很多。还有一个容易踩的坑一个 Skill 里写了太多不属于流程的决策性内容。比如技能里塞了一大段“为什么我们规定要用这种写法”这些解释性内容在真正执行时用处不大反而拖长上下文。解释放文档或 CLAUDE.md技能里只留“怎么做”和“做完怎么验证”。4. 插件把散装配置打包成能分发的东西CLAUE.md、Skills 这些配置在你自己机器上整理好了但问题来了怎么给别人用怎么在另一个项目里复用一整套规范总不能靠复制粘贴目录吧。插件Plugin要解决的就是这个问题——它是整个扩展栈的“分发层”。4.1 插件到底是什么插件的本质是一个打包单元。它可以把以下这些组件装进一个“盒子”里Skills、自定义斜杠命令、子代理subagent、钩子hook、MCP 服务器配置甚至 CLAUDE.md 片段。用户通过一条安装命令就能把这个盒子装进自己的 Claude Code 环境里所有组件一起生效。安装流程通常是两条命令。先添加插件市场marketplace然后再安装具体的插件/plugin marketplace add owner/repo /plugin install plugin-name在克隆了插件市场仓库之后插件目录本身放在.claude-plugin/下。一个插件需要两个关键文件marketplace.json描述市场上有哪些插件plugin.json描述这个插件自身。4.2 一个最小插件的解剖plugin.json的结构大意是描述插件里装了哪些组件用一个简化例子说明{ name: team-standards, description: 团队日常开发规范与工程流程, version: 0.2.0, components: { commands: [commands/release], skills: [skills/code-review, skills/scaffold-module], hooks: [hooks/post-tool-use] } }这里的commands是指插件注册的斜杠命令。比如/release一执行就会跑一套发布流程skills就是前面说的技能安装插件等于把技能一起装进来hooks是最有分量的部分它能在特定事件发生时自动触发脚本比如每次工具调用结束后强制格式化代码或者每次会话开始前自动检查分支干净程度。我建议第一次接触插件的人先把“钩子”单独拎出来理解。它是插件里唯一一个不是“让 AI 多做事”而是“在 AI 做事前后自动做点事”的机制。钩子能实现很多硬性约束比如不让 AI 直接修改线上配置、不允许提交前漏掉格式检查。它的用途和 Skills 完全不同常用来做执行边界控制。4.3 什么时候值得做插件插件不是越早做越好。我的建议是先在自己环境里裸配跑通所有组件都稳定了再考虑打包成插件。过早做插件化你会陷入“改代码要重新安装”“版本兼容要对齐”的泥潭真正的业务价值还没体现就被工程复杂度拖死了。出现以下信号就可以考虑打包这套配置要在两个以上项目里复用并且已经稳定运行了两周以上。团队里有多个人需要同一套规范你不想挨个指导。你需要通过钩子对 AI 行为做硬性控制项目级配置不够用了。安全性同样要放在前面。安装任何第三方插件之前先看一下它的仓库内容特别是 hooks 和 commands 部分。插件拥有的权限不小一个恶意的 hook 可以做到的事情远比一个普通配置文件多。我的原则是private 仓库里的自用插件随便装公网第三方插件必须通读代码。5. MCP把外部世界接进来的那根管子再好的记忆和流程都改变不了一个事实Claude Code 默认只能访问当前工作区里的文件。项目用到的数据库数据、内部接口、远端文档它一概够不着。MCPModel Context Protocol就是为了打破这个边界而存在的统一协议层。5.1 MCP 到底解决什么问题MCP 是一个开放的协议用一句话解释它定义了 AI 应用如何与外部工具、数据源、服务进行标准化的通信。你可以把每个 MCP 服务器想象成一根管道管道一端是 Claude Code另一端是你的文件系统、数据库、HTTP 服务、浏览器或者其他任何你想让 AI 操作的东西。这种设计最值钱的地方在于标准化。只要一个服务遵循 MCP 协议Claude Code 就能直接调用它提供的工具不需要为每个外部系统单独写集成代码。打个比方传统集成方式是每个家电厂商给你一根专用遥控器MCP 是统一成一种通用插座所有符合规格的电器插上去就能用。Claude Code 里接入 MCP 后外部服务提供的能力会以“工具”的形式出现在会话中模型在合适的时候自动调用。你可以在/mcp命令里查看当前已经连接的所有 MCP 服务器以及它们提供了哪些工具。5.2 配置 MCP 的几种姿势MCP 配置有几种存放位置用途不一样。最常用的是项目共享配置.mcp.json放在项目根目录随仓库一起提交。里面用mcpServers声明各个服务器每个服务器通过command、args、env定义启动方式。举一个用官方标准服务器连接 git 的示例{ mcpServers: { git: { command: npx, args: [-y, modelcontextprotocol/server-git] } } }如果某个 MCP 只希望你自己用、不想随仓库共享可以放到.claude/settings.json里的mcpServers字段或者通过/mcp命令交互式配置。个人全局配置也有对应的位置通常记录在用户级配置文件里。三种位置的关系是项目级共享配置给团队用局部配置给自己用全局配置给所有项目用。MCP 服务器有两种连接方式。一种是刚才示例里的本地进程方式通过 stdio 通信适合跑在你自己机器上的工具比如本地文件系统、本地数据库。另一种是远程 HTTP 方式连接远端部署好的 MCP 服务适合访问公司内部的统一数据层或者公共 API 网关。远程方式通常需要处理鉴权配置会复杂一些但好处是数据不落地工具统一由服务端维护版本。5.3 安全边界与权限这一节我愿意花多一点篇幅因为 MCP 是扩展栈里权限最大、也最容易被低估的部分。一个 MCP 服务器启动之后它在你的机器上拥有和你当前账号几乎一样的权限。它可以读写文件、发网络请求、执行命令。这跟浏览器里装一个扩展有点像扩展声明了权限它就能做那些事。所以接 MCP 的第一原则就是只接入你信任的服务器。实际操作中我给自己定了三条安全底线第三方公开服务器必须读源代码之后才允许启动一旦发现行为异常立即用/mcp断开。涉及数据库、内部系统的连接串和密钥只通过环境变量注入绝不写进.mcp.json随仓库提交共享配置文件里不要出现任何真实凭据。文件系统类服务器一定要设置允许访问的目录白名单不要让 AI 能碰到整个磁盘。比如默认只允许访问当前项目和指定的数据目录其他路径一律拒绝。还要清楚一件事MCP 服务器带来的上下文负担是真实的。每多一个服务器模型在不调用工具时也要知道这个工具的存在工具越多可用上下文就越被稀释。所以我强烈建议从零到一控制数量先接一个真正高频使用的服务器跑通跑稳再考虑加第二个。不要一上来连五个数据库、三个浏览器AI 没被外部能力撑强反而被工具清单拖笨。5.4 MCP 与 Skills 的分工MCP 和 Skills 都属于“能力扩展”经常被混为一谈但二者分工完全不同。Skills 是流程与行为告诉 AI “遇到这类任务应该怎么做”。MCP 是接口与通道告诉 AI “你有这个工具可以调用”。一个管怎么想一个管怎么够得着。实际上它们经常配合使用Skill 里写清楚流程和判断标准流程中的某一步需要访问外部系统时MCP 工具负责真正执行。举一个实际组合场景数据库迁移质量检查这个任务Skill 定义“先读取迁移文件、检查索引变更、对比生产库结构、输出风险报告”这些步骤其中“读取生产库结构”这一步AI 通过一个数据库 MCP 工具来执行。没有 SkillAI 拿到数据库也不知道该查什么没有 MCPAI 知道流程也够不到数据库。两者缺一不可。这也是为什么我一直强调四层要一起理解和配置而不是单点拼凑。6. 一套可落地的组合建议与我的使用体会前面把四层都拆开讲了最后把它们拼回去给一套我实际使用下来比较舒服的配置基线。你可以参照这个基线从零搭起也可以拿它来审视自己现有的配置哪里失衡了。6.1 我的推荐基线配置扩展层数量建议主要内容CLAUDE.md200~300 行构建命令、架构约束、已知陷阱、import 架构文档Skills3~5 个代码评审、新增模块脚手架、发布前检查、数据迁移检查插件0~2 个团队规范化配置、需要钩子强约束的场景MCP0~2 个文件系统限定目录、数据库或内部接口二选一先接不要追求配置越多越好。我见过一些人的环境CLAUDE.md 写了上千行Skills 十几个MCP 连了七八个服务结果 AI 每次启动都在加载海量信息真正的任务反而不聚焦。扩展栈的价值不是“装得多”而是“分层清楚各司其职”。6.2 最容易翻车的三个组合场景第一把 MCP 当 Skills 用。有人接了数据库 MCP 后以为 AI 就会天然按公司规范写 SQL 了。实际上 MCP 只给了它“连接数据库”的能力规范还得靠 CLAUDE.md 写流程还得靠 Skill 固化。接上 MCP 之后如果发现 AI 写出来的查询风格不对先检查是不是没配流程而不是再换一个 MCP 服务器。第二多层配置互相打架。CLAUDE.md 里说“提交信息用 emoji 前缀”插件里的 hook 又在提交前强制检查 commit template两边不一致时你怎么修都修不干净。我后来养成一个习惯凡是约束类内容只维护一份权威来源其他层引用而不复制。第三插件升级带来的隐性变化。插件是分发单元不是只读配置。别人更新了插件你的环境行为也跟着变有时候 hook 行为变化了你还不知道。凡是对稳定性敏感的项目我会把插件锁在一个固定版本升级前先在分支环境里验证一轮。6.3 最后分享一个小技巧每次会话初期都值得用/context看一眼当前实际加载了什么。很多人以为配置了 CLAUDE.md、装了插件、接了 MCPAI 就全都知道了其实上下文压缩、配置失效、文件路径错误都可能让某部分没有真正生效。这东西就跟看日志一样多看一眼能省掉后面大量的“为什么 AI 不听我的指令”的困惑。我自己的维护节奏是每周顺手翻一遍 CLAUDE.md 有没有过时信息新技能先在真实任务里手工试三次再固化MCP 服务器每加一个就问一句“这个真的高频吗”。按这个节奏用了很长一段时间之后最明显的变化不是 AI 会的东西多了而是它犯的低级错误少了目录不乱建了命令不乱猜了提交前的检查一项都不会漏。扩展栈真正的收益就是这种“不用反复解释它就知道该怎么配合你”的默契。
知识建站
内容驱动
阅读友好版式
SEO 精细化
线索转化