用命令行工具写代码这件事近两年变化真的很大。早期大家把AI当成一个会聊天的搜索引擎复制粘贴报错、让它写个函数来回切窗口。后来终端里出现了能直接读仓库、改文件的编程代理接上之后效率确实上了一个台阶但很快又撞上另一堵墙它记不住项目约定、不知道仓库里有哪些自动化脚本、不能自己调内部接口每次新开会话都得从头交代一遍。这个痛点正好引出我今天要聊的主题以Claude Code为代表的终端编程代理它的扩展能力其实是一套组合拳——CLAUDE.md、Skills、插件和MCP。这四个词经常被一起提到但很多人只用了其中一两个或者根本不清楚它们的边界和分工。这套扩展栈的意义在于它把AI从通用代码生成器变成了懂这个项目、守这套规矩、能用这些工具的工程助手。CLAUDE.md解决的是“它知不知道规矩”Skills解决的是“它会不会某种技能”插件解决的是“它能不能改变命令行交互本身”MCP解决的是“它能不能碰到外部系统和数据”。四者各管一摊又互相补充。这篇文章我会从底层原理讲到实际操作把每个组件的定位、写法、执行方式和常见坑都摊开说一遍适合刚接触终端AI编程的新手也适合已经配置过一部分、想系统理一遍的老手。1. 先理清四个组件的分工与边界聊扩展之前先把这四样东西在脑子里的坐标系摆正。很多人混淆CLAUDE.md和MCP因为都在“给AI喂信息”但它们的机制完全不同。CLAUDE.md是静态上下文。它是一份放在项目根目录的说明文件每次会话启动时被读入上下文相当于你给AI一份入职手册。它告诉AI这个项目用什么技术栈、代码风格是什么、测试命令是什么、有哪些禁忌。它的核心特征是“常驻、被动、文本化”。与之相对MCP是动态能力。MCP服务器通过标准协议暴露工具tools和资源resourcesAI在运行过程中按需调用。它就像给AI配了一副可以随时伸出去的手查数据库、发HTTP请求、搜文档、操作文件系统。MCP不提供“背景知识”提供“实时动作”。Skills则介于两者之间。它不是全局常驻的说明而是一套“按需加载的知识包”。你可以在项目里放多个skill目录每个skill包含技能说明、参考示例甚至可执行脚本。Claude Code在遇到匹配场景时会先读取技能说明再决定怎么行动。它解决的是“知道一个道理”和“真的会做这件事”之间的鸿沟。插件跟上面的逻辑又不同。插件的目标不是影响AI的“思考内容”而是影响Claude Code这个程序本身的运行行为——比如给CLI增加快捷命令、改状态栏显示、在特定事件会话开始、工具调用前后插入自定义逻辑。你可以把插件理解为“编辑器扩展”或“命令行增强脚本”它围绕软件的壳做文章而不是围绕模型的脑。这样一拆边界就很清楚了CLAUDE.md是“规矩”Skills是“本领”MCP是“手脚”插件是“皮肤和筋骨”。四者的加载时机、作用对象、依赖条件都不一样但组合起来才能构成一个完整的智能体工作环境。另外一个容易被忽略的点是权限差异。CLAUDE.md和插件属于默认信任范围文件放在项目里、配置写在设置里就能生效Skills和MCP则涉及命令执行和外部资源访问需要显式授权。理解这套信任模型能帮你避免很多安全上的意外。2. CLAUDE.md项目的“入职手册”到底怎么写2.1 文件位置与读取机制CLAUDE.md的核心规则很简单这是一个普通文本文件一般放在项目根目录或用户级配置目录。Claude Code在每次会话启动时都会自动读取它作为初始上下文的一部分。它的兄弟姐妹还包括CLAUDE.local.md用于本地专属规则不进版本库和CLAUDE.global.md用户级全局规则这个层级设计很实用全局管通用习惯项目管专属约定本地管个人工作流三者按优先级互相补充没有冲突。读取机制上有几个细节值得注意。首先CLAUDE.md是在会话开始时一次性读入的不是每次都重新扫描。这意味着你写的内容越前置、越重要AI对其遵循度就越高塞在最末尾的补充条款模型注意力可能就不够。其次如果项目里有多个嵌套目录Claude Code会向上查找最近的CLAUDE.md合理放在子项目目录里可以实现“分区上下文”。我在一个 monorepo 项目里就曾把前端和后端的规范分开前端目录的CLAUDE.md讲组件规范和UI库用法后端目录的则讲接口和数据模型约定AI在对应目录下干活时遵守度明显比单一总文件要高。提示CLAUDE.md的措辞会直接影响模型的解读。建议多用肯定祈使句“用X而不是Y”“必须做Z”少用模糊描述。给AI定规矩跟给人写代码规范一样要可验证、可执行不能只说“代码要优雅”。2.2 优先级与“系统性指令”CLAUDE.md在生效机制上有点像智能体提示词体系里的“系统提示词system prompt”。它的优先级高于用户消息但如果消息里出现同主题的明确指示则用户消息能够覆盖文件内容。这听上去很合理AI既要有默认价值观又要能听用户的临时命令。但是存在一个隐藏问题CLAUDE.md是“纯文本说明”它没有强约束的能力。比如你写“禁止修改src目录下的文件”AI在后续多轮对话中完全有可能忘了这条规则。为了解决这类问题实践中我会配合三种手段把关键禁令写进CLAUDE.md最前面因为开头信息衰减最少在涉及高风险操作的工具调用描述里把规则也复述一遍必要时把重要规则抽成可执行的脚本或hooks在动作发生前后做物理拦截。肉眼观察下来CLAUDE.md对AI的“风格塑造”作用最强对“行为强制”作用偏弱。你让它遵守命名规范、测试习惯它能做到你想靠它防止AI误删文件靠不住。2.3 编写CLAUDE.md的实操骨架下面是一个我在多个项目中验证过的模板按信息重要性从上到下排列# 项目脚手架 ## 技术栈 - 前端TypeScript ReactViteUI库使用 xxx - 后端Python FastAPIORM 使用 SQLAlchemy 2.x - 数据库PostgreSQL 16Redis 7 ## 常用命令 - 安装依赖npm install - 运行开发服务器npm run dev - 跑测试npm test -- --watch - 代码检查npm run lint ## 架构约定 - 前端组件放在 src/components页面放在 src/pages - 接口统一走 src/services 下的 request 封装 - 新接口必须写 Pydantic Schema不允许直接返回 dict ## 禁忌 - 不要修改 src/migrations 下的历史迁移文件 - 提交前必须跑一遍 lint 和 tests - 不要把密钥写进代码或配置文件这份文件的核心逻辑是“用AI最容易理解的方式降低它的决策噪声”。技术栈、命令、架构约定这三项能解决80%的胡写乱猜问题禁忌项则能防患于未然。写的时候要记住Claude Code不会替你查package.json它靠的就是你这份文件。你写“测试用Vitest”它就按Vitest来你不写它可能就按Jest来跑都跑不起来。2.4 常见的CLAUDE.md写作陷阱第一用“尽量”“可能”“应该”这类软性词。模型不是人它不会从“尽量”里读出强调意味反而容易把规则当成可选项。第二文件写成论文。超过300行的CLAUDE.md模型真正能稳定遵循的可能只有前面几十行。我自己的建议CLAUDE.md最多控制在80行以内长内容用SKILL.md或独立文档承载通过技能机制按需加载。第三把敏感信息写进CLAUDE.md。它底层的文件读取是文本级别的一旦文件进了版本库任何能读仓库的人都能看到。API密钥、内网地址、跳板机信息都不该放进这份文件。3. Skill按需加载的“职业技能包”3.1 Skill机制的底层逻辑如果说CLAUDE.md是给Claude Code一本放在桌上的手册那么Skills就是“当你遇到某类问题时它翻出对应章节来读”。Skill的本质是一个目录里面有一个SKILL.md说明文件通常带YAML frontmatter还可能附带示例代码、脚本、模板文件。当对话中触发匹配条件时Claude Code会把这个Skill的内容注入上下文指导后续行为。这个“按需加载”设计背后有一个非常现实的原因上下文窗口是有限的。CLAUDE.md一直在窗口里占位置但技能包可以超过100个、每个几千字如果全部注入会话还没开始就已经消耗完上下文预算了。Skill机制等于给上下文做了一层“缓存分页”需要时再换页效率和成本都兼顾。3.2 SKILL.md的内容结构以一个“代码审查”技能为例它的结构大致是--- name: code-review description: 在改动进入主干前对代码变更执行全面审查输出问题清单与修改建议。 --- # 代码审查 Skill 1. 读取 git diff确认变更范围 2. 逐文件检查错误处理、边界条件、日志、兼容性 3. 对照项目规范读取 CLAUDE.md检查一致性 4. 输出问题清单按严重程度排序每条附具体行号和修改建议description字段非常重要它决定了这个Skill会在什么情况下被Claude Code“想起”。description里应该包含触发场景、目标对象、输出预期。我见过很多写得极差的skilldescription是“一个有用的技能”结果模型永远无法匹配到它。写description的原则是让模型能在“用户提出某个需求”时把这个需求映射到这个技能上。3.3 一手搭建从想法到可用的Skill确认需求边界。建议从高频动作开始代码审查、依赖升级、写提交信息、补测试、生成变更日志。创建目录。/your-project/.claude/skills/code-review/里面放SKILL.md。这里可以补充配套文件比如review_prompt.md模板以及scripts/run_review.sh这样的辅助脚本。编写SKILL.md核心是给Claude Code一套可执行的操作步骤。测试触发起一个会话输入“帮我审查一下最近这版改动”观察是否匹配。迭代优化如果没有触发重点调整description的关键词和场景描述。3.4 Skill与CLAUDE.md的分工心得实际项目中CLAUDE.md和Skills的搭配才是重点。CLAUDE.md管“这个项目怎么做”Skills管“这类事情怎么做”。比如CLAUDE.md里写“测试框架是Vitest命令是npm test”Skill里写“当用户要求补测试时先检查现有测试风格再按项目惯例生成对应测试文件”。前者提供基础事实后者提供行为策略。还有一点要提醒同一个项目里Skills不宜过杂。几十个Skill全部堆在一个目录里匹配时模型反而容易混淆。我建议按使用频率把Skill分成两档——高频的放.claude/skills/低频的放在文档仓库或单独目录下需要时手动指定。高质量技能包的标准不是数量多而是每个包都能给出比模型“默认发挥”更好的结果。4. 插件改造Claude Code本身的黑科技4.1 插件能碰到的区域Skills和CLAUDE.md都在影响模型输入而插件的目标完全不同它直接修改Claude Code这个程序的行为。它的能力半径取决于插件API的暴露面常见场景包括注册新的斜杠命令如/review、/deploy让用户直接在输入框下达自定义指令监听会话生命周期事件开始、结束、工具调用前后在事件中执行自定义逻辑修改状态栏、主题、输出格式这是对交互层进行定制把外部脚本封装成工具让Claude Code在需要时自动调用对工具调用的结果做后置处理比如格式化输出、压缩日志、失败重试。打个比方Skills负责“教AI新技能”插件负责“给Claude Code这个壳加功能”。4.2 一个真实的插件实用案例我遇到的一个实际需求是团队使用自建的任务ID规范格式类似TASK-2024-xxxxClaude Code在写提交信息时经常漏掉ID。CLAUDE.md里写了规则但模型偶尔还是会忘。此时插件就可以来解决。实现思路是注册一个会话开始事件在Claude Code的上下文里注入一个自定义指令并用脚本读取当前分支名里的任务ID再把“这个分支对应的是任务ID xxx所有提交信息必须包含它”自动写入会话上下文。这样就不需要用户在每条消息里反复提醒AI也不会再忘。这个案例说明了插件和CLAUDE.md的互补文件提供规则插件则能做到动态注入与强制执行。4.3 插件开发的入门步骤插件的基本形态是一个目录内含插件配置信息和入口脚本。配置里声明插件的名称、版本、apiVersion以及它要监听哪些事件、注册哪些命令。下面是常见的三层结构第一层插件入口文件定义注册事件和命令的处理器第二层辅助脚本处理实际业务逻辑读分支名、查任务ID第三层配置声明把行为声明和脚本文件联系起来。开发时注意三点一是先确认API版本Claude Code的插件API升级较快不同版本的事件名和字段可能完全不同二是处理好异步与超时问题插件里任何阻塞式逻辑都会拖慢整个CLI的响应三是尽量让插件保持“薄”和“可失败”一段插件逻辑如果出错至少要能给用户一个明确的stderr输出不能静默堵死后续流程。4.4 插件与Skills的边界再梳理我见过有人把“技能”和“插件”混为一谈实际上可以这么区分Skill影响“模型的行为”输入的是文本说明输出的是更高质量的推理结果插件影响“程序的行为”输入的是事件和配置输出的是CLI的功能变化。一个简单的判定方法如果这个功能通过写一份说明文件就能实现那就是Skill如果必须依赖程序逻辑、监听事件、调用外部脚本那就是插件。用错概念会导致配置摆错位置排查问题时报错信息又对不上号白费很多时间。注意插件目前仍是一个变化较快的领域。建议没有一定JavaScript或CLI开发经验的朋友先从官方插件或社区成熟插件入手等摸清了事件机制再考虑自己写。插件目录结构写错、缺少依赖、入口路径不一致是常见的安装失败原因。5. MCP把外部系统和数据接进对话里5.1 MCP协议到底解决什么问题MCPModel Context Protocol是一个开放的通信协议它定义了一套Client/Server架构让AI应用能通过统一标准接入外部工具、数据源和自动化能力。在Claude Code中MCP被用作“外部工具总线”。模型不直接知道“怎么查某个数据库”而是通过MCP服务器暴露的“工具”来间接完成这件事。在MCP出现之前每个AI应用都要为每个外部系统写专门的集成代码接口各不相同、维护成本高、连通性差。MCP的价值就在于提供了统一标准一个MCP服务器可以被多个支持MCP的客户端复用一个客户端也能挂多个不同的MCP服务器。这是一种很典型的“面向协议编程”——先定义标准所有服务往标准上靠生态就能滚动起来。5.2 从架构上理解一次MCP调用的完整链路用户在对话中提出需求比如“查一下xx订单的状态”Claude Code识别出这需要外部工具把调用请求发给本地的MCP ClientMCP Client按协议将请求路由到对应的MCP ServerMCP Server执行真实的业务逻辑查数据库、发HTTP、执行命令执行结果通过MCP Client返回给Claude CodeClaude Code把结果放进对话上下文继续推理并组织回答。这个架构有一个明显的好处权限边界清晰。MCP Server只暴露经过编写的工具集而不是给AI一个SSH壳子。同时在多工具场景下模型可以通过“同一次调用发起多个工具请求”的方式并行处理多项操作再由Client按序分发整体效率会有显著提升。5.3 配置MCP服务器的两种方式与实战Claude Code中MCP服务器的配置通常有两种形态本地stdio型子进程交互和远程HTTP型网络请求。本地stdio型适合跑在开发机上的工具比如文件系统、数据库、命令行执行器远程HTTP型适合对接团队共享服务比如统一的代码搜索、集中式文档检索。下面给一份本地stdio型MCP服务器的配置示例以JSON格式配置{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/your/project] }, database: { command: node, args: [/path/to/your/mcp-db-server/index.js] } } }这份配置的含义是注册两个MCP服务器一个是官方文件系统服务把你的项目目录暴露给AI可以限定只读或可写另一个是你自己写的数据库查询服务在index.js里用MCP SDK封装了若干查询函数。配置完成后重启Claude Code输入“查一下这个项目的订单表有没有异常记录”它就会自动找到database服务器调用对应工具并返回结果。我自己的经验是刚上手MCP时先接一个本地文件系统filesystem练手就够了。跑通“AI调工具读文件→拿到内容→继续推理”这个闭环再逐步接数据库、浏览器自动化、代码搜索服务。一上来就接七八个服务器排查问题时反而分不清是哪个服务超时。5.4 MCP服务器开发速成如果现有生态里没有你需要的服务器自己写一个并不难。MCP SDK提供了一套成熟的能力层开发者只需要实现以下几个环节定义工具名称和输入Schema让模型能看懂参数实现工具处理函数执行真实动作启动服务器并监听端口/管道在配置里注册服务器设置合理的启动命令和参数。写MCP服务时输入Schema的描述质量直接影响模型调用的准确率。描述务必具体“函数接收订单ID格式ORD-2024-xxx”。还要考虑工具之间的依赖关系复杂的业务动作拆成多个简单工具比一个巨型工具更可控。提示MCP服务会执行真实操作权限设计一定要谨慎。只在配置里暴露必要的最小权限不要图方便给根目录的读写权限。真实环境中曾出现过配置了一个能写全盘的filesystem服务器结果AI一把梭把构建产物目录删了的情况。6. 组合应用与问题排查实录6.1 一套完整的扩展栈配置方案理解了四个组件的分工之后可以看看它们在真实项目里怎么组合成一个整体。以我维护的一个中大型Web应用为例整体配置长这样CLAUDE.md根目录定义技术栈、命令、目录结构、错误处理规范、代码风格CLAUDE.local.md个人机器不进仓库包含开发者自己的代理设置、个人工作目录偏好Skills目录code-review代码审查generate-changelog基于git log生成变更日志dependency-upgrade依赖升级与兼容性检查test-generation按项目惯例补测试插件自定义的提交信息命令强制从分支名提取任务ID并校验提交信息格式MCP服务器filesystem隔离到项目目录database只读查询线上库的表结构playwright浏览器自动化用于运行UI测试和视觉回归这套配置下来Claude Code的表现会有很明显的跃升。最直观的感受是它不再需要你在每个新会话里重复解释“这个项目的命令是什么、目录怎么组织、测试怎么跑”而是自动按照既有工作流走。它查数据库、跑UI测试、出变更日志全程不需要我手动切工具窗口。6.2 常见问题速查表现象根因解决方案CLAUDE.md规则没有生效文件位置放错或使用了被忽略的后缀确认放在正确的根目录且文件名完全匹配Skill一直无法触发description字段没有写触发场景重写description加入具体行为动词和场景名词插件安装后没反应apiVersion不匹配事件名写错检查插件配置与当前CLI版本看启动时控制台日志MCP服务器连接失败本地路径或环境变量不对直接手动运行启动命令查看报错输出MCP工具执行超时schema过于复杂服务端并发处理弱拆分工具粒度控制同步耗时操作模型频繁误用MCP工具工具描述写得不具体在工具的description里写明使用条件、参数格式会话开始时上下文太长CLAUDE.md或全局配置过于臃肿精简文件内容长说明迁入Skill按需加载多个规则冲突时行为不可控优先级机制不明确在CLAUDE.md顶部写明“如与全局配置冲突以本文件为准”排查问题有一个通用思路先把事件关掉再一个个加回来跑最短复现路径看哪一步断了。这条思路对CLAUDE.md、Skill、插件和MCP全都适用——四者叠加时出现的问题往往是最后一个加进来的组件引起的。6.3 组合使用的安全与维护心得扩展栈能提升多少效率就伴随多大风险。MCP服务器有真实执行权插件能监听事件CLAUDE.md能注入高优先级指令——这三者都在影响一个“不是人的执行体”。安全意识必须跟着升级。我自己定的几条安全底线文件系统MCP永远白名单目录不允许全局写权限任何MCP服务器不直接暴露生产环境写权限只读接口优先插件里不做高危操作高危动作只能在工具调用的授权流程里完成仓库里的CLAUDE.md和Skills全员可见写的每一句话都会被AI当成行为准则所以措辞要克制、准确定期审查扩展栈的更新版本插件和MCP服务器的依赖要锁版本避免上游更新破坏行为。最后再分享一个关于这套扩展栈的经验如果你打算正式把这套东西用起来我唯一的建议是不要一次性配齐。拿一个周末先只加CLAUDE.md跑一周。你会发现AI的“常识性错误”明显减少于是有动力加Skills再跑一周挑一个最痛的点比如提交信息总忘任务ID去试试插件最后才接MCP服务器。这个顺序能让每次变化都可感知、可回退、可复盘。还有一个我踩过好几回的坑改动CLAUDE.md或Skill之后没有清空会话。由于CLAUDE.md只在新会话开始时加载旧会话里你改了文件它也看不到。如果你改了配置却感觉AI没反应先起一个新会话再测而不要原地命令它“记住新规则”。这听起来像废话但我在这个问题上浪费过不少时间。这套东西上手之后还有一个意外收获对模型上下文和成本的感知会变得很敏锐。你开始知道哪些内容该常驻、哪些该按需加载甚至能根据单个Skill的description命中情况判断哪些场景被覆盖得好。这种“把模型当作一个真正的执行者来配置”的思路换个其他编程代理工具也一样适用。希望这篇长文能帮你把这套扩展栈在自己的项目里真正落地。 用命令行工具写代码这件事近两年变化真的很大。早期大家把AI当成一个会聊天的搜索引擎复制粘贴报错、让它写个函数来回切窗口。后来终端里出现了能直接读仓库、改文件的编程代理接上之后效率确实上了一个台阶但很快又撞上另一堵墙它记不住项目约定、不知道仓库里有哪些自动化脚本、不能自己调内部接口每次新开会话都得从头交代一遍。这个痛点正好引出我今天要聊的主题以Claude Code为代表的终端编程代理它的扩展能力其实是一套组合拳——CLAUDE.md、Skills、插件和MCP。这四个词经常被一起提到但很多人只用了其中一两个或者根本不清楚它们的边界和分工。这套扩展栈的意义在于它把AI从通用代码生成器变成了懂这个项目、守这套规矩、能用这些工具的工程助手。CLAUDE.md解决的是“它知不知道规矩”Skills解决的是“它会不会某种技能”插件解决的是“它能不能改变命令行交互本身”MCP解决的是“它能不能碰到外部系统和数据”。四者各管一摊又互相补充。这篇文章我会从底层原理讲到实际操作把每个组件的定位、写法、执行方式和常见坑都摊开说一遍适合刚接触终端AI编程的新手也适合已经配置过一部分、想系统理一遍的老手。1. 先理清四个组件的分工与边界聊扩展之前先把这四样东西在脑子里的坐标系摆正。很多人混淆CLAUDE.md和MCP因为都在“给AI喂信息”但它们的机制完全不同。CLAUDE.md是静态上下文。它是一份放在项目根目录的说明文件每次会话启动时被读入上下文相当于你给AI一份入职手册。它告诉AI这个项目用什么技术栈、代码风格是什么、测试命令是什么、有哪些禁忌。它的核心特征是“常驻、被动、文本化”。与之相对MCP是动态能力。MCP服务器通过标准协议暴露工具tools和资源resourcesAI在运行过程中按需调用。它就像给AI配了一副可以随时伸出去的手查数据库、发HTTP请求、搜文档、操作文件系统。MCP不提供“背景知识”提供“实时动作”。Skills则介于两者之间。它不是全局常驻的说明而是一套“按需加载的知识包”。你可以在项目里放多个skill目录每个skill包含技能说明、参考示例甚至可执行脚本。Claude Code在遇到匹配场景时会先读取技能说明再决定怎么行动。它解决的是“知道一个道理”和“真的会做这件事”之间的鸿沟。插件跟上面的逻辑又不同。插件的目标不是影响AI的“思考内容”而是影响Claude Code这个程序本身的运行行为——比如给CLI增加快捷命令、改状态栏显示、在特定事件会话开始、工具调用前后插入自定义逻辑。你可以把插件理解为“编辑器扩展”或“命令行增强脚本”它围绕软件的壳做文章而不是围绕模型的脑。这样一拆边界就很清楚了CLAUDE.md是“规矩”Skills是“本领”MCP是“手脚”插件是“皮肤和筋骨”。四者的加载时机、作用对象、依赖条件都不一样但组合起来才能构成一个完整的智能体工作环境。另外一个容易被忽略的点是权限差异。CLAUDE.md和插件属于默认信任范围文件放在项目里、配置写在设置里就能生效Skills和MCP则涉及命令执行和外部资源访问需要显式授权。理解这套信任模型能帮你避免很多安全上的意外。2. CLAUDE.md项目的“入职手册”到底怎么写2.1 文件位置与读取机制CLAUDE.md的核心规则很简单这是一个普通文本文件一般放在项目根目录或用户级配置目录。Claude Code在每次会话启动时都会自动读取它作为初始上下文的一部分。它的兄弟姐妹还包括CLAUDE.local.md用于本地专属规则不进版本库和CLAUDE.global.md用户级全局规则这个层级设计很实用全局管通用习惯项目管专属约定本地管个人工作流三者按优先级互相补充没有冲突。读取机制上有几个细节值得注意。首先CLAUDE.md是在会话开始时一次性读入的不是每次都重新扫描。这意味着你写的内容越前置、越重要AI对其遵循度就越高塞在最末尾的补充条款模型注意力可能就不够。其次如果项目里有多个嵌套目录Claude Code会向上查找最近的CLAUDE.md合理放在子项目目录里可以实现“分区上下文”。我在一个 monorepo 项目里就曾把前端和后端的规范分开前端目录的CLAUDE.md讲组件规范和UI库用法后端目录的则讲接口和数据模型约定AI在对应目录下干活时遵守度明显比单一总文件要高。提示CLAUDE.md的措辞会直接影响模型的解读。建议多用肯定祈使句“用X而不是Y”“必须做Z”少用模糊描述。给AI定规矩跟给人写代码规范一样要可验证、可执行不能只说“代码要优雅”。2.2 优先级与“系统性指令”CLAUDE.md在生效机制上有点像智能体提示词体系里的“系统提示词system prompt”。它的优先级高于用户消息但如果消息里出现同主题的明确指示则用户消息能够覆盖文件内容。这听上去很合理AI既要有默认价值观又要能听用户的临时命令。但是存在一个隐藏问题CLAUDE.md是“纯文本说明”它没有强约束的能力。比如你写“禁止修改src目录下的文件”AI在后续多轮对话中完全有可能忘了这条规则。为了解决这类问题实践中我会配合三种手段把关键禁令写进CLAUDE.md最前面因为开头信息衰减最少在涉及高风险操作的工具调用描述里把规则也复述一遍必要时把重要规则抽成可执行的脚本或hooks在动作发生前后做物理拦截。肉眼观察下来CLAUDE.md对AI的“风格塑造”作用最强对“行为强制”作用偏弱。你让它遵守命名规范、测试习惯它能做到你想靠它防止AI误删文件靠不住。2.3 编写CLAUDE.md的实操骨架下面是一个我在多个项目中验证过的模板按信息重要性从上到下排列# 项目脚手架 ## 技术栈 - 前端TypeScript ReactViteUI库使用 xxx - 后端Python FastAPIORM 使用 SQLAlchemy 2.x - 数据库PostgreSQL 16Redis 7 ## 常用命令 - 安装依赖npm install - 运行开发服务器npm run dev - 跑测试npm test -- --watch - 代码检查npm run lint ## 架构约定 - 前端组件放在 src/components页面放在 src/pages - 接口统一走 src/services 下的 request 封装 - 新接口必须写 Pydantic Schema不允许直接返回 dict ## 禁忌 - 不要修改 src/migrations 下的历史迁移文件 - 提交前必须跑一遍 lint 和 tests - 不要把密钥写进代码或配置文件这份文件的核心逻辑是“用AI最容易理解的方式降低它的决策噪声”。技术栈、命令、架构约定这三项能解决80%的胡写乱猜问题禁忌项则能防患于未然。写的时候要记住Claude Code不会替你查package.json它靠的就是你这份文件。你写“测试用Vitest”它就按Vitest来你不写它可能就按Jest来跑都跑不起来。2.4 常见的CLAUDE.md写作陷阱第一用“尽量”“可能”“应该”这类软性词。模型不是人它不会从“尽量”里读出强调意味反而容易把规则当成可选项。第二文件写成论文。超过300行的CLAUDE.md模型真正能稳定遵循的可能只有前面几十行。我自己的建议CLAUDE.md最多控制在80行以内长内容用SKILL.md或独立文档承载通过技能机制按需加载。第三把敏感信息写进CLAUDE.md。它底层的文件读取是文本级别的一旦文件进了版本库任何能读仓库的人都能看到。API密钥、内网地址、跳板机信息都不该放进这份文件。3. Skill按需加载的“职业技能包”3.1 Skill机制的底层逻辑如果说CLAUDE.md是给Claude Code一本放在桌上的手册那么Skills就是“当你遇到某类问题时它翻出对应章节来读”。Skill的本质是一个目录里面有一个SKILL.md说明文件通常带YAML frontmatter还可能附带示例代码、脚本、模板文件。当对话中触发匹配条件时Claude Code会把这个Skill的内容注入上下文指导后续行为。这个“按需加载”设计背后有一个非常现实的原因上下文窗口是有限的。CLAUDE.md一直在窗口里占位置但技能包可以超过100个、每个几千字如果全部注入会话还没开始就已经消耗完上下文预算了。Skill机制等于给上下文做了一层“缓存分页”需要时再换页效率和成本都兼顾。3.2 SKILL.md的内容结构以一个“代码审查”技能为例它的结构大致是--- name: code-review description: 在改动进入主干前对代码变更执行全面审查输出问题清单与修改建议。 --- # 代码审查 Skill 1. 读取 git diff确认变更范围 2. 逐文件检查错误处理、边界条件、日志、兼容性 3. 对照项目规范读取 CLAUDE.md检查一致性 4. 输出问题清单按严重程度排序每条附具体行号和修改建议description字段非常重要它决定了这个Skill会在什么情况下被Claude Code“想起”。description里应该包含触发场景、目标对象、输出预期。我见过很多写得极差的skilldescription是“一个有用的技能”结果模型永远无法匹配到它。写description的原则是让模型能在“用户提出某个需求”时把这个需求映射到这个技能上。3.3 一手搭建从想法到可用的Skill确认需求边界。建议从高频动作开始代码审查、依赖升级、写提交信息、补测试、生成变更日志。创建目录。/your-project/.claude/skills/code-review/里面放SKILL.md。这里可以补充配套文件比如review_prompt.md模板以及scripts/run_review.sh这样的辅助脚本。编写SKILL.md核心是给Claude Code一套可执行的操作步骤。测试触发起一个会话输入“帮我审查一下最近这版改动”观察是否匹配。迭代优化如果没有触发重点调整description的关键词和场景描述。3.4 Skill与CLAUDE.md的分工心得实际项目中CLAUDE.md和Skills的搭配才是重点。CLAUDE.md管“这个项目怎么做”Skills管“这类事情怎么做”。比如CLAUDE.md里写“测试框架是Vitest命令是npm test”Skill里写“当用户要求补测试时先检查现有测试风格再按项目惯例生成对应测试文件”。前者提供基础事实后者提供行为策略。还有一点要提醒同一个项目里Skills不宜过杂。几十个Skill全部堆在一个目录里匹配时模型反而容易混淆。我建议按使用频率把Skill分成两档——高频的放.claude/skills/低频的放在文档仓库或单独目录下需要时手动指定。高质量技能包的标准不是数量多而是每个包都能给出比模型“默认发挥”更好的结果。4. 插件改造Claude Code本身的黑科技4.1 插件能碰到的区域Skills和CLAUDE.md都在影响模型输入而插件的目标完全不同它直接修改Claude Code这个程序的行为。它的能力半径取决于插件API的暴露面常见场景包括注册新的斜杠命令如/review、/deploy让用户直接在输入框下达自定义指令监听会话生命周期事件开始、结束、工具调用前后在事件中执行自定义逻辑修改状态栏、主题、输出格式这是对交互层进行定制把外部脚本封装成工具让Claude Code在需要时自动调用对工具调用的结果做后置处理比如格式化输出、压缩日志、失败重试。打个比方Skills负责“教AI新技能”插件负责“给Claude Code这个壳加功能”。4.2 一个真实的插件实用案例我遇到的一个实际需求是团队使用自建的任务ID规范格式类似TASK-2024-xxxxClaude Code在写提交信息时经常漏掉ID。CLAUDE.md里写了规则但模型偶尔还是会忘。此时插件就可以来解决。实现思路是注册一个会话开始事件在Claude Code的上下文里注入一个自定义指令并用脚本读取当前分支名里的任务ID再把“这个分支对应的是任务ID xxx所有提交信息必须包含它”自动写入会话上下文。这样就不需要用户在每条消息里反复提醒AI也不会再忘。这个案例说明了插件和CLAUDE.md的互补文件提供规则插件则能做到动态注入与强制执行。4.3 插件开发的入门步骤插件的基本形态是一个目录内含插件配置信息和入口脚本。配置里声明插件的名称、版本、apiVersion以及它要监听哪些事件、注册哪些命令。下面是常见的三层结构第一层插件入口文件定义注册事件和命令的处理器第二层辅助脚本处理实际业务逻辑读分支名、查任务ID第三层配置声明把行为声明和脚本文件联系起来。开发时注意三点一是先确认API版本Claude Code的插件API升级较快不同版本的事件名和字段可能完全不同二是处理好异步与超时问题插件里任何阻塞式逻辑都会拖慢整个CLI的响应三是尽量让插件保持“薄”和“可失败”一段插件逻辑如果出错至少要能给用户一个明确的stderr输出不能静默堵死后续流程。4.4 插件与Skills的边界再梳理我见过有人把“技能”和“插件”混为一谈实际上可以这么区分Skill影响“模型的行为”输入的是文本说明输出的是更高质量的推理结果插件影响“程序的行为”输入的是事件和配置输出的是CLI的功能变化。一个简单的判定方法如果这个功能通过写一份说明文件就能实现那就是Skill如果必须依赖程序逻辑、监听事件、调用外部脚本那就是插件。用错概念会导致配置摆错位置排查问题时报错信息又对不上号白费很多时间。注意插件目前仍是一个变化较快的领域。建议没有一定JavaScript或CLI开发经验的朋友先从官方插件或社区成熟插件入手等摸清了事件机制再考虑自己写。插件目录结构写错、缺少依赖、入口路径不一致是常见的安装失败原因。5. MCP把外部系统和数据接进对话里5.1 MCP协议到底解决什么问题MCPModel Context Protocol是一个开放的通信协议它定义了一套Client/Server架构让AI应用能通过统一标准接入外部工具、数据源和自动化能力。在Claude Code中MCP被用作“外部工具总线”。模型不直接知道“怎么查某个数据库”而是通过MCP服务器暴露的“工具”来间接完成这件事。在MCP出现之前每个AI应用都要为每个外部系统写专门的集成代码接口各不相同、维护成本高、连通性差。MCP的价值就在于提供了统一标准一个MCP服务器可以被多个支持MCP的客户端复用一个客户端也能挂多个不同的MCP服务器。这是一种很典型的“面向协议编程”——先定义标准所有服务往标准上靠生态就能滚动起来。5.2 从架构上理解一次MCP调用的完整链路用户在对话中提出需求比如“查一下xx订单的状态”Claude Code识别出这需要外部工具把调用请求发给本地的MCP ClientMCP Client按协议将请求路由到对应的MCP ServerMCP Server执行真实的业务逻辑查数据库、发HTTP、执行命令执行结果通过MCP Client返回给Claude CodeClaude Code把结果放进对话上下文继续推理并组织回答。这个架构有一个明显的好处权限边界清晰。MCP Server只暴露经过编写的工具集而不是给AI一个SSH壳子。同时在多工具场景下模型可以通过“同一次调用发起多个工具请求”的方式并行处理多项操作再由Client按序分发整体效率会有显著提升。5.3 配置MCP服务器的两种方式与实战Claude Code中MCP服务器的配置通常有两种形态本地stdio型子进程交互和远程HTTP型网络请求。本地stdio型适合跑在开发机上的工具比如文件系统、数据库、命令行执行器远程HTTP型适合对接团队共享服务比如统一的代码搜索、集中式文档检索。下面给一份本地stdio型MCP服务器的配置示例以JSON格式配置{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/your/project] }, database: { command: node, args: [/path/to/your/mcp-db-server/index.js] } } }这份配置的含义是注册两个MCP服务器一个是官方文件系统服务把你的项目目录暴露给AI可以限定只读或可写另一个是你自己写的数据库查询服务在index.js里用MCP SDK封装了若干查询函数。配置完成后重启Claude Code输入“查一下这个项目的订单表有没有异常记录”它就会自动找到database服务器调用对应工具并返回结果。我自己的经验是刚上手MCP时先接一个本地文件系统filesystem练手就够了。跑通“AI调工具读文件→拿到内容→继续推理”这个闭环再逐步接数据库、浏览器自动化、代码搜索服务。一上来就接七八个服务器排查问题时反而分不清是哪个服务超时。5.4 MCP服务器开发速成如果现有生态里没有你需要的服务器自己写一个并不难。MCP SDK提供了一套成熟的能力层开发者只需要实现以下几个环节定义工具名称和输入Schema让模型能看懂参数实现工具处理函数执行真实动作启动服务器并监听端口/管道在配置里注册服务器设置合理的启动命令和参数。写MCP服务时输入Schema的描述质量直接影响模型调用的准确率。描述务必具体“函数接收订单ID格式ORD-2024-xxx”。还要考虑工具之间的依赖关系复杂的业务动作拆成多个简单工具比一个巨型工具更可控。提示MCP服务会执行真实操作权限设计一定要谨慎。只在配置里暴露必要的最小权限不要图方便给根目录的读写权限。真实环境中曾出现过配置了一个能写全盘的filesystem服务器结果AI一把梭把构建产物目录删了的情况。6. 组合应用与问题排查实录6.1 一套完整的扩展栈配置方案理解了四个组件的分工之后可以看看它们在真实项目里怎么组合成一个整体。以我维护的一个中大型Web应用为例整体配置长这样CLAUDE.md根目录定义技术栈、命令、目录结构、错误处理规范、代码风格CLAUDE.local.md个人机器不进仓库包含开发者自己的代理设置、个人工作目录偏好Skills目录code-review代码审查generate-changelog基于git log生成变更日志dependency-upgrade依赖升级与兼容性检查test-generation按项目惯例补测试插件自定义的提交信息命令强制从分支名提取任务ID并校验提交信息格式MCP服务器filesystem隔离到项目目录database只读查询线上库的表结构playwright浏览器自动化用于运行UI测试和视觉回归这套配置下来Claude Code的表现会有很明显的跃升。最直观的感受是它不再需要你在每个新会话里重复解释“这个项目的命令是什么、目录怎么组织、测试怎么跑”而是自动按照既有工作流走。它查数据库、跑UI测试、出变更日志全程不需要我手动切工具窗口。6.2 常见问题速查表现象根因解决方案CLAUDE.md规则没有生效文件位置放错或使用了被忽略的后缀确认放在正确的根目录且文件名完全匹配Skill一直无法触发description字段没有写触发场景重写description加入具体行为动词和场景名词插件安装后没反应apiVersion不匹配事件名写错检查插件配置与当前CLI版本看启动时控制台日志MCP服务器连接失败本地路径或环境变量不对直接手动运行启动命令查看报错输出MCP工具执行超时schema过于复杂服务端并发处理弱拆分工具粒度控制同步耗时操作模型频繁误用MCP工具工具描述写得不具体在工具的description里写明使用条件、参数格式会话开始时上下文太长CLAUDE.md或全局配置过于臃肿精简文件内容长说明迁入Skill按需加载多个规则冲突时行为不可控优先级机制不明确在CLAUDE.md顶部写明“如与全局配置冲突以本文件为准”排查问题有一个通用思路先把事件关掉再一个个加回来跑最短复现路径看哪一步断了。这条思路对CLAUDE.md、Skill、插件和MCP全都适用——四者叠加时出现的问题往往是最后一个加进来的组件引起的。6.3 组合使用的安全与维护心得扩展栈能提升多少效率就伴随多大风险。MCP服务器有真实执行权插件能监听事件CLAUDE.md能注入高优先级指令——这三者都在影响一个“不是人的执行体”。安全意识必须跟着升级。我自己定的几条安全底线文件系统MCP永远白名单目录不允许全局写权限任何MCP服务器不直接暴露生产环境写权限只读接口优先插件里不做高危操作高危动作只能在工具调用的授权流程里完成仓库里的CLAUDE.md和Skills全员可见写的每一句话都会被AI当成行为准则所以措辞要克制、准确定期审查扩展栈的更新版本插件和MCP服务器的依赖要锁版本避免上游更新破坏行为。最后再分享一个关于这套扩展栈的经验如果你打算正式把这套东西用起来我唯一的建议是不要一次性配齐。拿一个周末先只加CLAUDE.md跑一周。你会发现AI的“常识性错误”明显减少于是有动力加Skills再跑一周挑一个最痛的点比如提交信息总忘任务ID去试试插件最后才接MCP服务器。这个顺序能让每次变化都可感知、可回退、可复盘。还有一个我踩过好几回的坑改动CLAUDE.md或Skill之后没有清空会话。由于CLAUDE.md只在新会话开始时加载旧会话里你改了文件它也看不到。如果你改了配置却感觉AI没反应先起一个新会话再测而不要原地命令它“记住新规则”。这听起来像废话但我在这个问题上浪费过不少时间。这套东西上手之后还有一个意外收获对模型上下文和成本的感知会变得很敏锐。你开始知道哪些内容该常驻、哪些该按需加载甚至能根据单个Skill的description命中情况判断哪些场景被覆盖得好。这种“把模型当作一个真正的执行者来配置”的思路换个其他编程代理工具也一样适用。希望这篇长文能帮你把这套扩展栈在自己的项目里真正落地。