Claude Code Skills 上手指南,2026 让 AI 编程助手记住你的项目规范

用过 Claude Code 的人多半都遇到过同一个烦恼:每开一个新会话,都得重新告诉它这个项目用什么技术栈 代码风格是什么 测试要求是什么 哪些目录不能动。重复几次后效率不升反降。Claude Code 提供的 Skills 机制(也叫项目规范文件 CLAUDE.md)就是为了解决这个问题。把项目的常识一次性写好放到约定位置,以后每次启动 Claude Code 它都会自动读到,不用再啰嗦一遍。这篇文章讲讲怎么写好一份 CLAUDE.md,让 AI 编程助手真正记住你的项目。

1 什么是 Claude Code Skills

Claude Code 是 Anthropic 出品的命令行 AI 编程工具,允许开发者在终端里通过自然语言和 Claude 模型交互来完成代码任务。Skills 是 Claude Code 提供的一种机制,让你能把项目级别的上下文 风格规范 操作约束写在一个固定的文件里,Claude Code 启动时自动加载。

这个文件的标准名字是 CLAUDE.md,放在项目根目录就能生效。除了项目级别,Claude Code 还支持用户全局级别的 Skills 配置,通常在用户主目录下的 .claude 文件夹里。前者作用于具体项目,后者作用于这个用户的所有项目。

Skills 不只是一个简单的 README。它更像是给 AI 助手看的工作手册,告诉它在这个项目里应该遵守哪些规矩 偏好哪些做法 避开哪些操作。写得好的 Skills 能让 Claude Code 的输出质量提升一个档次,因为它再也不会用错框架版本 写错命名风格 用错测试套件了。

2 为什么需要 Skills 重复说明的痛点

如果你每次和 Claude Code 开始新对话都要先说一遍"这个项目用 TypeScript 严格模式 不能用 any 测试用 Vitest 不能用 Jest",那你已经在用嘴硬编 Skills 了,只是没固化下来。

重复说明的成本不只是打字时间。更严重的是,人脑会忘事。今天你交代了不能用 any,明天可能就忘了再说一次,Claude Code 当然也就不知道。结果代码合并的时候你才发现一堆 any,要么改要么吵。把这些规则固化到 CLAUDE.md,就把人脑的不可靠环节给绕过去了。

更深一层的问题是团队协作。同一个项目可能有好几个人在用 Claude Code,每个人交代给它的口径都不一样。A 觉得函数名要驼峰,B 觉得要下划线,C 让 AI 直接按自己的喜好写。结果代码风格混乱,Review 时痛苦,质量参差不齐。共享的 CLAUDE.md 能把这种私下默契显性化,让 AI 在每个人的会话里都按同一套规则干活。

还有一类痛点是高频踩坑。某些操作在这个项目里就是不能做,比如直接改某个生成的文件 直接 git push 到 main 直接 drop 某个数据库表。这些都是教训堆出来的禁忌,但 AI 助手并不知道。写进 Skills 里就相当于给它装了护栏,出错概率显著下降。

3 CLAUDE.md 文件放在哪里

最常用的位置是项目根目录,文件名就叫 CLAUDE.md。Claude Code 启动时会自动从当前工作目录往上查找这个文件,找到就加载。这是项目级别的 Skills,作用范围只限于当前项目。

用户全局级别通常放在主目录下的 .claude/CLAUDE.md(具体路径以官方文档为准,版本不同可能略有差异)。全局 Skills 会在所有项目里生效,适合放那些和具体项目无关 但你个人风格强烈的偏好,比如代码注释语言 默认提交信息风格 一些通用的行为约束。

如果项目级和用户级都有 CLAUDE.md,一般是叠加生效。项目级的规则优先级更高,会覆盖全局里冲突的部分。具体合并规则以工具的最新行为为准。

子目录的 Skills 也是一种用法。某些大型 monorepo 里,不同子目录的技术栈和风格差别很大。可以在每个子目录单独放一份 CLAUDE.md,Claude Code 会根据当前工作目录加载对应的那份。这样既能照顾整体一致性,又能给每个模块留出灵活度。

CLAUDE.md 本身就是一个普通的 Markdown 文件,可以放进 git 一起版本管理。建议把项目级的 CLAUDE.md 纳入版本控制,这样团队成员拉代码下来就能直接用上同一套规则。用户级的全局文件则放在自己的 dotfiles 仓库里管理。

4 一个标准 CLAUDE.md 应该包含哪些内容

不同项目侧重点不同,但下面这几类内容是大多数项目都用得上的。

技术栈说明。一开头就写清楚这个项目用什么语言 什么框架 什么版本(大致版本,不必精确到补丁号)。比如 Node 18 加 TypeScript 严格模式 React 18 加 Vite 后端 Go 1.22 加 PostgreSQL。这几句能让 AI 跳过反复猜测的环节。

目录结构和职责。简短列一下主要目录的分工。比如 src/components 放 UI 组件 src/services 放业务逻辑 src/utils 放纯函数工具 tests 放测试文件 scripts 放部署脚本。AI 知道这些之后,新增文件时就会自动放到合理位置。

命名和代码风格。函数命名 文件命名 变量命名的约定写清楚。代码格式化用什么工具(Prettier ESLint Biome 之类)直接说明。如果项目里有禁止使用的语法或模式(比如不允许 default export 不允许 var 不允许 console.log 进 main 分支),都列在这里。

测试要求。测试框架是哪个 测试文件放在哪里 是否要求新功能必须带测试 测试覆盖率底线是多少。这些事情 AI 不问就不知道,告诉它就能避免大量返工。

禁忌操作。最重要的一类内容。明确写出哪些事情绝对不允许做。比如不允许直接 push 到 main 不允许跳过 pre-commit hook 不允许在 production 环境跑 migration 脚本 不允许删除某些目录。AI 看到这些会主动避开。

工作流约定。Git 分支命名规则 提交信息风格 PR 描述模板 Code Review 流程要点。这些都能写进 Skills,让 AI 在帮你创建分支或写提交信息时一次成型。

特殊背景知识。项目里那些口口相传的隐性约定,新人不教就不知道的事情。比如某个变量名其实是历史遗留缩写 某个接口的命名背后有特殊含义 某个常量绝对不能改值。把这类知识写下来,AI 才能像老员工一样工作。

5 写好 Skills 的 5 个原则

第一个原则,写规则不写理由。Skills 是给 AI 看的工作手册,不是给人看的设计文档。每一条规则用最短的句子表达,不要解释为什么。比如直接写"测试用 Vitest 不用 Jest",不要写"因为 Jest 配置复杂启动慢所以我们选了 Vitest"。AI 不需要理由,需要的是清晰的指令。

第二个原则,负面规则比正面规则更重要。"必须做什么"AI 自己也能猜个差不多,"绝对不能做什么"AI 不知道就会踩坑。把禁忌单独列出来,用明显的标识标注,效果最好。

第三个原则,具体到可执行。抽象的话没用。不要写"代码要有可读性",要写"函数不超过 50 行 嵌套不超过 3 层 变量名不用单字母(循环变量除外)"。可量化的规则才好执行。

第四个原则,定期更新。Skills 不是写完就一劳永逸的。项目会演进,技术栈会换,规则会改。建议每月或每季度过一遍 CLAUDE.md,删掉过时的 补上新出现的约定。和代码一样,Skills 也需要维护。

第五个原则,控制长度。一份 CLAUDE.md 太短就发挥不出作用,太长又会让 AI 的注意力被稀释。建议核心规则部分控制在 1000 到 3000 字之间,真正需要展开讲的内容可以单独放别的文档里,在 Skills 里只列一个引用链接。

6 个人开发者的 Skills 模板示例

下面是一个简化的个人项目模板,可以基于它改改用。

技术栈一栏写清楚:本项目使用 Python 3.11 加 FastAPI 加 SQLAlchemy 2.0 加 PostgreSQL,所有代码用 ruff 格式化,类型注解用 mypy 严格模式校验。

目录约定一栏:app/api 放路由 app/services 放业务逻辑 app/models 放数据模型 app/utils 放工具函数 tests 放测试代码 scripts 放一次性脚本。

代码风格一栏:函数和变量用 snake_case 类名用 PascalCase 常量用 UPPER_CASE。函数加完整类型注解,模块内函数不超过 50 行,文件不超过 500 行。

测试要求一栏:新功能必须带 pytest 测试,测试文件命名 test_*.py。涉及数据库的测试用 fixture 隔离,不连真实数据库。

禁忌一栏:不允许使用 print 调试(用 logging 代替) 不允许直接修改 alembic 已有的迁移文件 不允许跳过 pre-commit hook 不允许在 main 分支直接 push。

工作流一栏:每个功能开新分支,分支命名 feat/xxx 或 fix/xxx。提交信息用简短现在时态(英文或中文都行,但同一个项目内统一一种)。PR 必须包含简要说明和测试结果。

按这个模板写完,你会发现一份 CLAUDE.md 大概 800 到 1500 字之间,信息密度很高。AI 助手读完之后,产出代码的风格会和你一致很多。

7 团队协作里的 Skills 共享

团队协作场景下,CLAUDE.md 的价值放大数倍。一份共享 Skills 能让所有人和 AI 的协作口径保持一致。

第一步,把 CLAUDE.md 纳入 git 版本管理,放在仓库根目录。新成员 clone 下来就自动拥有项目规范,Claude Code 也会自动加载。这是最低成本的共享方式。

第二步,在团队 Wiki 或文档站点里维护一份长版的项目规范,CLAUDE.md 作为它的精简执行版。人看长版理解背景,AI 读精简版指导执行。两者互相补充,既不冗余也不缺失。

第三步,把 Skills 的变更纳入 Code Review 流程。修改 CLAUDE.md 也要走 PR 流程,有人 Review 通过才合并。这样能避免某个人随手改了规则导致团队内 AI 行为不一致。

第四步,定期回顾。建议团队每月或每季度过一次 CLAUDE.md,讨论哪些规则过时了 哪些新出现的踩坑要补上。把 Skills 当作团队工程文化的一部分来维护,而不是某个人的个人配置。

第五步,允许子模块差异化。大型项目里,前端 后端 数据 算法各组的规则可能差别很大。可以在主 CLAUDE.md 之外,各子目录放自己的 CLAUDE.md。Claude Code 会按工作目录优先加载最近的那份。

8 常见误区 不要把 Skills 写成什么样

第一个误区,写成项目介绍。CLAUDE.md 不是 README,不要花大段篇幅讲项目背景 业务价值 团队介绍。这些信息对 AI 写代码没帮助,反而占用了它的注意力。背景类内容放 README,工作约束放 Skills,职责分开。

第二个误区,写成空话堆砌。代码要简洁 注释要清晰 命名要准确 这种话写了等于没写。AI 本来就被训练成会追求这些品质,你写一遍只是浪费 token。要写就写具体可执行的规则。

第三个误区,事无巨细全列上。不是所有项目细节都需要写进 Skills。某个函数的实现细节 某个变量的取值范围 这种应该放代码注释里,不应该挤到 CLAUDE.md。Skills 关注的是项目级别的约定,不是单点的实现细节。

第四个误区,把 Skills 当 issue tracker 用。写"修一下登录页面的样式" "把数据库连接池调到 20 个连接"这种具体任务进 Skills 完全不合适。任务用 issue 系统管理,Skills 只放长期生效的规则。

第五个误区,写完不维护。一年前写的 Skills 里还提着早就替换掉的旧框架 旧规范,AI 按老规矩干活,结果一堆冲突。Skills 也是代码的一部分,要和代码同步演进。建议每次大版本升级或技术栈调整时一并更新 Skills。

第六个误区,用 Skills 表达情绪或私人偏好。比如"我特别讨厌 var 用 var 我会发火"。AI 看到这种语气会调整输出风格,但调整方向可能不是你想要的。直接写"不允许使用 var,变量声明用 const 或 let"就够了,情绪表达留给团队聊天。

9 进阶 多项目多 CLAUDE.md 切换技巧

当你同时维护多个项目时,Skills 管理可以更精细一些。

第一种技巧是层级化配置。把所有项目共同的偏好放进用户全局的 CLAUDE.md(比如代码注释语言偏好 通用安全要求),每个项目特有的规则放各自的 CLAUDE.md。这样能避免在每个项目里重复写同样的内容。

第二种技巧是模板复用。如果你有多个类似的项目(比如几个都是 Next.js 加 Tailwind 的前端项目),可以维护一份模板 CLAUDE.md,新项目直接复制改改就用。配合脚本可以做到一键生成新项目的初始 Skills。

第三种技巧是按角色切分。同一个仓库里前端目录和后端目录的工作模式完全不同,在子目录各放一份 CLAUDE.md 后,你在切换目录时 Claude Code 会自动适配。比手动告知 AI 当前在前端还是后端高效得多。

第四种技巧是临时覆盖。某次会话里你想暂时偏离 Skills 的某条规则(比如就这一次允许跳过测试),直接在对话里告诉 AI 即可,不必去改 CLAUDE.md。Skills 是默认规则,具体会话可以临时调整。

第五种技巧是审计变化。把 CLAUDE.md 当作工程资产,定期回顾历史变更。哪些规则被加上又被撤掉了 哪些规则的措辞被反复调整,这些信息能帮你看到团队工程文化的演进路径,也能帮你判断什么样的规则真正有效。

熟练之后,Skills 不只是省嘴的工具,而是把项目知识沉淀下来的一种结构化方式。新人入职 接手项目 在多个项目间切换,Skills 的存在都能让 AI 助手快速进入状态,这才是它真正的长期价值。

常见问题 FAQ

CLAUDE.md 写得越长越好吗

不是。太短发挥不出价值,太长会稀释 AI 的注意力。建议核心内容控制在 1000 到 3000 字之间,涵盖技术栈 目录结构 风格规范 测试要求 禁忌操作几个关键板块。需要展开讲的背景内容放别的文档里,在 Skills 里只放最精炼的执行规则。每隔一段时间过一遍,把过时的内容删掉,新出现的约定补上,长度自然能保持在合理范围。

没有 CLAUDE.md Claude Code 还能用吗

可以用。CLAUDE.md 不是强制要求,Claude Code 找不到这个文件也能正常工作。但没有 Skills 配置的情况下,AI 对项目的理解只能靠它读到的代码上下文猜,产出质量会有波动。建议至少写一个简版的 CLAUDE.md(技术栈加几条核心约定就行),后续随着项目演进逐步补充。投入的时间和换来的稳定性回报相比非常划算。

Skills 里的规则 AI 一定会遵守吗

大概率会,但不是百分之百。Skills 提供的是强烈引导,AI 在生成代码时会优先按照这些规则来,但偶尔仍会出现偏离。如果你发现某条规则反复被违反,可以调整写法,让规则更具体更明确更突出。也可以把违反成本高的规则做成 lint 或 pre-commit hook,从工具层强制执行,作为 Skills 的补充。两者结合效果最好。

公司项目的 CLAUDE.md 涉及内部信息会不会泄露

CLAUDE.md 里的内容在你和 Claude Code 交互时会作为上下文发送到 Anthropic 的服务,具体的数据处理和隐私政策以官方页面为准。涉及高敏感信息(比如内部接口签名 凭证 客户清单)的内容不要写进 Skills。可以把这类信息抽到环境变量或 secret manager 里,Skills 只引用变量名不暴露值。这样既能让 AI 知道有这么个东西,又不会泄露实际内容。

不同语言的项目 Skills 写法有差别吗

主要差别在技术栈和工具链相关的部分。Python 项目要写 ruff black mypy 之类,Go 项目要写 gofmt go vet 之类,前端项目要写 ESLint Prettier 之类。但是核心思路是通用的:写清楚技术栈 目录结构 命名规范 测试要求 禁忌操作。结构上各种语言的 Skills 看起来差不多,只是填入的具体规则不同。新接手一个语言的项目时,可以先借鉴别的项目的 Skills 框架,再按当前语言的工具链替换具体内容。