Claude Code 的 CLAUDE.md 与技能

“到底什么信息该写进 CLAUDE.md什么信息又该写进 Skills”说实话这不是一个小问题。恰恰相反如果你开始认真、长期、规模化地使用 Claude Code这几乎就是最关键的架构决策之一。很多团队前期觉得无所谓先堆着写等项目一多、协作一复杂就会发现整个上下文体系开始打架规则到处都是流程互相覆盖Claude 每次干活都像在不同版本的脑回路里来回横跳。所以这篇文章会把这两个概念彻底讲清楚CLAUDE.md 到底是什么Skill 又到底是什么什么时候该用前者什么时候该用后者以及它们到底该怎么配合才不会把项目越做越乱。先说结论如果非要用一句话去区分我会这样想CLAUDE.md 项目的大脑Skills 可复用的能力模块这两个东西看起来都像“给 Claude 的说明”可它们解决的根本不是同一类问题。CLAUDE.md 负责的是让 Claude 理解这个项目到底是什么、该遵守什么、边界在哪里。Skills 负责的是让 Claude 在某一类任务上能反复调用一套成熟、稳定、可执行的方法。一个偏“项目认知层”一个偏“执行能力层”。如果你从一开始就没把这两层分开后面十有八九会写乱。CLAUDE.md你可以把 CLAUDE.md 理解成一句话“凡是 Claude 为了理解这个具体项目而必须知道的东西都应该放在这里。”判断方法其实特别简单。当你在想某条信息该放哪里时只要你脑子里冒出来的开头是“在这个项目里……”或者“对于这个项目来说……”那这条信息大概率就应该写进 CLAUDE.md。因为它本质上是项目专属知识而不是某种能跨项目复用的通用能力。CLAUDE.md 一般放在哪里通常它就放在项目根目录下。也就是说当 Claude 进入这个项目时最先接触到、也最该优先建立上下文的就是这个文件。CLAUDE.md 里到底该写什么这个文件本身是 Markdown 格式所以结构上很自由但真正重要的不是你分多少标题而是你有没有把项目的关键认知信息讲清楚。比如下面这些内容就是非常典型、也非常适合写进 CLAUDE.md 的部分## Project Overview Short explanation of what the project is. ## Tech Stack - TypeScript - Next.js - Tailwind - ShadCN ## Architecture Explain folders and patterns. ## Coding Rules - Use functional React components - Prefer server components - Use Tailwind utilities instead of custom CSS ## Design System - Follow ShadCN patterns - Use tokens from /styles/tokens.ts ## Commands npm run dev你会发现这里面写的都不是“某个任务该怎么做”而是“这个项目本身是什么样、该按什么方式被理解和执行”。比如项目概览告诉 Claude 这项目到底是在解决什么问题技术栈告诉它你在这个项目里到底用什么架构说明告诉它目录、模式、组织方式怎么理解编码规则告诉它你在这个项目里有哪些明确偏好设计系统告诉它 UI 和样式层该遵守什么常用命令则是为了让它真正执行任务时别犯低级错误。说白了CLAUDE.md 的任务不是“教 Claude 干活”而是先把这个项目的世界观塞进它脑子里。Skills如果说 CLAUDE.md 解决的是“这个项目是什么”那 Skills 解决的就是“Claude 遇到某类任务时该怎么做得更稳定、更像熟练工”。所以我更喜欢把 Skills 理解成可按需调用的、可执行的专业能力。它特别适合那种反复出现、流程清晰、最好每次都别从头摸索的任务。比如这些就非常适合做成 Skill生成 PRD创建 landing page重构组件做设计审计编写 API handler这些事情的共同点在于它们不是只属于某一个项目而是你在很多项目里都会反复遇到。既然如此就没必要每个项目都从头写一遍流程说明。Skills 一般放在哪里Skills 可以分成两类本地 Skills和全局 Skills。本地 Skills 属于某个具体项目通常会放在项目里的/skills目录下。例如project-root/ ├── CLAUDE.md ├── skills/ │ ├── ux/ │ │ ├── run-ux-audit.md │ │ └── analyze-user-flow.md │ ├── coding/ │ │ ├── build-component.md │ │ └── refactor-code.md │ ├── research/ │ │ └── competitor-analysis.md │ └── content/ │ └── write-linkedin-post.md这种本地 Skill 的意义在于它只服务这个项目或者说它的使用场景强依赖这个项目当前的工作流。而如果你发现某项能力在很多项目里都能复用那它就更适合做成全局 Skill。全局 Skills 通常会放在 Claude Code 的工具目录里比如~/claude-skills/ ├── front-end-design/ ├── ux-audit/ └── content-writing/你可以把它理解成本地 Skill 更像“项目内部工具”全局 Skill 更像“你自己的长期武器库”。顺手提一句如果你根本不知道当前项目里 Claude 能用哪些 Skills可以直接问它What skills I haveSkill 里应该写什么和 CLAUDE.md 一样Skill 文件本身通常也是 Markdown。但 Skill 不是普通说明文档它更像一个带触发条件和执行说明的“能力封装”。通常一个完整的 Skill 至少要包含两部分第一部分是 YAML frontmatter也就是写在---标记之间的元信息。它的作用是告诉 Claude这是什么 Skill、它适合什么时候被使用。第二部分是 Markdown 格式的执行说明。也就是当这个 Skill 被调用时Claude 到底该按什么步骤做。比如一个用于生成 landing page 的 Skill可以写成这样name: create-landing-page description: Generate a landing page using project conventions steps: - Analyze CLAUDE.md for design system - Generate layout - Create components - Apply styling rules - Validate accessibility这里最值得注意的一点是Skill 不是在替代 CLAUDE.md而是在读取 CLAUDE.md 的前提下执行任务。也就是说Skill 更像一个熟练工的操作流程而 CLAUDE.md 则像工地总规范。没有总规范熟练工可能乱干可只有规范、没有流程Claude 又容易每次都发挥不稳定。CLAUDE.md 与技能如何协同工作很多人一开始总想二选一 要么全写进 CLAUDE.md觉得这样集中 要么疯狂造 Skills觉得这样模块化。其实最合理的方式从来不是二选一而是让它们各守自己的位置再互相配合。我自己的理解是CLAUDE.md 负责给出底层规则、项目边界和基础约束Skill 则在这些规则之内执行具体工作流。举个很典型的例子。如果你在 CLAUDE.md 里这样写## Tech Stack - React version 19.2 - Use TypeScript 5.9.3这就属于项目级约束。它告诉 Claude这个项目里React 和 TypeScript 的版本就是这些别乱来。而与此同时你又做了一个可复用的 Skill叫build-component内容像这样Workflow: 1. Generate component in React 2. Use TypeScript types 3. Ensure 200 lines 4. Document component usage in markdown format那么当build-component这个 Skill 被触发时它会照着自己的流程去生成组件但它在生成过程中又必须尊重 CLAUDE.md 里已经写好的项目约束比如 React 版本、TypeScript 版本、目录模式、设计系统等等。这才是最健康的配合关系项目规则在 CLAUDE.md任务方法在 Skill。谁也别越界。你甚至可以在 CLAUDE.md 里直接列出可用 Skills这也是一种很实用的做法。比如你可以在 CLAUDE.md 里单独写一个 “Available Skills” 区域给项目里的常用 Skill 做快捷索引## Available Skills - run-ux-audit → ./skills/ux/run-ux-audit.md - build-component → ./skills/coding/build-component.md这样做的好处是Claude 在读取项目脑子的时候就已经顺手知道这个项目里有哪些现成能力可以调用。对于复杂项目来说这能明显减少“明明有 Skill 却没用上”的情况。最容易踩的 3 个坑真的很多团队都中过说到这里其实大方向已经很清楚了。但真正把系统用顺之前还有几个特别常见的坑最好一开始就避开。坑一把流程全写进 CLAUDE.md很多人写着写着就会忍不住在 CLAUDE.md 里塞这种东西To create a landing page: 1. Do this 2. Do that表面上看这好像也没错。但问题在于这已经不是“项目背景信息”了而是一个具体任务流程。这类内容应该被放进 Skill 里如果你不打算复用那至少也该做成一个单独的 workflow.md文件在需要的时候引用而不是直接塞进 CLAUDE.md 里。因为一旦你把流程和项目脑子混写在一起后面 CLAUDE.md 会越来越像一个什么都装的杂物间。结果就是看起来信息很多实际上层次全乱了。坑二把项目专属规则写进 Skill再比如有人会在 Skill 里直接写Use Next.js 16.1.1这就属于典型的放错地方。因为 Skill 应该尽量是通用、可复用的。像某个框架的具体版本、某个项目特有的目录结构、某个产品专属的设计 token这些都应该放在 CLAUDE.md 里而不是塞进 Skill 里。否则今天这个 Skill 在 A 项目可用明天拿到 B 项目还得改一遍最后它根本不配叫“可复用能力”只是一个伪装成 Skill 的项目片段而已。坑三重复写逻辑越写越冲突还有一种更隐蔽、也更烦的错误就是重复定义。比如某条规则你已经在 CLAUDE.md 里写过了结果又在 Skill 里再写一遍甚至写得还不完全一样。短期看你可能觉得“更保险”可一旦后续改动发生两个地方不同步Claude 就会开始在冲突指令之间摇摆。所以原则一定要记住Skills 应该读取 CLAUDE.md而不是重写 CLAUDE.md。能引用就引用能继承就继承不要重复造一套几乎一样的规则。最后如果你想把这篇内容真正记住其实只需要记住一句话CLAUDE.md 讲的是身份、上下文和边界Skill 讲的是动作、流程和能力。换句话说CLAUDE.md 回答的是“这个项目到底是什么在这里该怎么理解世界”Skill 回答的是“遇到这类任务时我应该按什么成熟方法执行”一个定义环境一个定义招式。一旦你把这两个层次彻底分开Claude Code 的可控性会明显提升。项目不会再越做越乱Skill 也不会越积越废。你会发现Claude 开始更像一个真正能协作的系统而不是一个每次都要重新讲规则的临时工。真正会在 Claude Code 上规模化做事的人最后拼的从来不是 prompt 写得多花而是这套结构到底搭得清不清楚。而 CLAUDE.md 和 Skills 的边界就是这套结构里最不能糊涂的一刀。最后精通 React 面试从零到中高级CSS终极指南Vue 设计模式实战指南20个前端开发者必备的响应式布局深入React:从基础到最佳实践完整攻略python 技巧精讲React Hook 深入浅出CSS技巧与案例详解vue2与vue3技巧合集全栈AI·探索涵盖动效、React Hooks、Vue 技巧、LLM 应用、Python 脚本等专栏案例驱动实战学习点击二维码了解更多详情。