一个资深 Claude Code 用户的心路历程：从写 CLAUDE.md 写到手抽筋，到三层 Skills 按需拼装，再到一份规则走通 Codex、Cursor、Aider 全家桶。这篇把坑都给你踩平。

写在前面

场景还原一下：

你在项目 A 里精心写了一份 CLAUDE.md，叮嘱 AI “用中文输出、Java 内部方法调用加 this.、支付相关的 ini key 必须定义在枚举里”。AI 答应得很好，第二天老老实实。

然后你跳到项目 B，发现忘了带规则。AI 信马由缰地写出了你最讨厌的风格。你提桶跑路的念头第八次升起来了。

你拷贝了一份 CLAUDE.md 到项目 B，又拷贝到 C、D、E。几个月后你在项目 C 改了一条规则，忘了同步回去，AI 在不同项目里表现得像精分患者 —— 通用规则和项目专属规则在同一个文件里缠成一团麻，谁都不敢动。

这就是我最近遇到的问题。折腾一圈下来，总结出一套"分层 + 软链 + 跨工具兼容"的玩法，拿来和大家分享。

一、先搞清楚：Skills 到底是 CLAUDE.md 2.0 吗？

不是。

这俩是互补关系，职责分工完全不同。

1.1 CLAUDE.md 的定位

CLAUDE.md 是常驻 context 的"长期记忆"。只要进入这个项目，所有内容都自动塞进对话上下文里。好处是 AI 永远记得；坏处是占 token。

HumanLayer 那篇广为流传的文章给了一条经验法则：CLAUDE.md 最好控制在 200 行以内。超了就开始劣化 —— AI 会忽略后半部分，或者在不相关的上下文里过度应用某条规则。

1.2 Skills 的定位

Skills 是按需触发的"瞬时记忆"。Claude Code 不会一股脑加载所有 skill 正文，而是只把每个 skill 的 name + description 放进上下文当成"目录"。当 AI 判断某个任务和某个 skill 相关时，才会主动调用这个 skill，把正文加载进来。

一个典型的 SKILL.md 长这样：

---
name: java-this-prefix
description: Java 类内部方法调用必须使用 this. 前缀。TRIGGER when writing or editing Java code, especially when calling instance methods from within the same class.
---

# Java 内部方法调用规范
（正文略）

关键在那个 description 字段 —— 它决定了 AI 什么时候会"想起"这个 skill。所以写 description 的姿势很重要，要把触发场景说清楚，别整那种"这是一个很棒的 Java 规范"的废话。

1.3 一句话区分

	CLAUDE.md	Skills
加载时机	进入项目就塞入 context	任务相关时才调用
占 token	持续占用	只占目录，按需放正文
适合放	高频规则、项目背景、技术栈说明	中低频规则、专项知识、工具用法
规模	< 200 行	没上限（但单个 skill 建议聚焦）

二、两层组织：别把所有鸡蛋放一个篮子里

想通了 Skills 和 CLAUDE.md 的分工，下一个问题就来了：多个项目之间重复的规则怎么办？

答案是两层组织：

┌───────────────────────────────────────┐
│  用户级 ~/.claude/skills/              │  所有项目都加载
│  - 个人编码风格                         │
│  - 通用输出偏好（中文、行尾不留空格等）     │
│  - 跨语言的基本功（命名、注释等）          │
├───────────────────────────────────────┤
│  项目级 <project>/.claude/skills/      │  仅当前项目加载
│  - 领域模型术语                         │
│  - 特定框架/ORM 用法                    │
│  - 项目专属的枚举类、基类约束              │
└───────────────────────────────────────┘

Claude Code 进入项目时，会把这两层合并加载到 skill 目录里，同名时项目级优先。规则很简单：通用的往上提，专属的下沉。

💡 这里容易和斜杠命令（slash command）混淆。斜杠命令是用户手动敲 /xxx 触发的，Skills 是 AI 根据任务自动触发的，两者的机制和用途完全不同。别混为一谈。

2.1 一个真实的例子

前段时间我整理了 4 条 Java 规则：

1. 所有交互提示、分析过程用中文
2. 控制台输出每行末尾不要填充空格
3. Java 类内部方法调用加 this. 前缀
4. 支付相关的 ini key 必须放到 com.example.pay.enums.PayConfEnum 枚举中

按两层组织分一下：

规则	归属	理由
① 中文输出	用户级	个人语言偏好，跨所有项目一致
② 行尾不留空格	用户级	通用编码卫生习惯
③ Java this. 前缀	用户级或项目级	看是个人偏好还是团队约定
④ PayConfEnum 枚举	项目级	只对 order-svc 有意义，其他项目根本没这个类

分完之后突然就清爽了 —— ①② 永远有效，不管我切到哪个项目；③ 放用户级，对我所有 Java 项目默认生效；④ 只在支付服务里加载，其他项目的 AI 根本不会知道有这么个枚举，也就不会瞎套用。

2.2 再举一个数仓项目的例子

我另一个数仓项目 dw-platform，写的是 ClickHouse SQL，规则完全不一样：

• 中文别名用反引号包裹：count(*) AS `订单数`
• ReplacingMergeTree 表查询必须加 FINAL（from dwd.fact_payment as a final）
• 时间字段判空不能用 IS NULL（因为 CK 里 null 会变成 1970-01-01 08:00:00），要用 a.pay_time > '2000-01-01'
• 字符串判空要同时判 '' 和 NULL
• SQL 语句之间不留空行

这些规则只对 ClickHouse 生效，放到其他项目会产生误导。所以它们应该躺在 dw-platform/.claude/skills/clickhouse-sql-conventions/ 里，别的项目看不见。

三、处理重叠：单一事实源 + 软链

三层分好之后，还会遇到一个现实问题：有些规则介于"通用"和"项目专属"之间。比如 Java this. 前缀规则，你有 5 个 Java 项目、3 个 Go 项目。放用户级吧，Go 项目白白加载一条没用的；放项目级吧，5 个 Java 项目各拷一份同样的东西。

我最后用了一个懒人方案：真相源放一个仓库里，各项目通过软链按需引用。

3.1 目录结构

我把所有 skills 源文件放在一个私有的文档仓库里：

~/docs/team-docs/skills/                       ← 单一事实源
  ├── common/
  │   ├── chinese-output/
  │   └── trailing-whitespace/
  ├── java/
  │   ├── this-prefix/
  │   └── lombok-usage/
  ├── order-svc/                              ← 项目专属
  │   └── pay-ini-key/
  └── dw-platform/
      └── clickhouse-sql-conventions/

3.2 各项目按需软链

# 用户级（所有项目共享）
ln -s ~/docs/team-docs/skills/common  ~/.claude/skills

# order-svc 项目：用 common + java + 项目专属
ln -s ~/docs/team-docs/skills/java             /path/to/order-svc/.claude/skills/java
ln -s ~/docs/team-docs/skills/order-svc        /path/to/order-svc/.claude/skills/order-svc

# dw-platform 项目：只用 common + 数仓专属
ln -s ~/docs/team-docs/skills/dw-platform      /path/to/dw-platform/.claude/skills/dw-platform

3.3 这样做的好处

• ✅ 改一处全局生效：规则演进时只改真相源，所有项目自动跟进
• ✅ 版本化：真相源可以 git 管理，谁改的、什么时候改的、为什么改，全都有迹可循
• ✅ 按需拼装：Go 项目压根不会链接 Java 目录，描述都进不了 context；数仓项目同理
• ✅ 团队共享：如果是团队规则，真相源做成公司内部仓库，每个人都能拉

3.4 也有坑

• ⚠️ 符号链接在团队里只对自己生效：别人 checkout 项目时拿不到软链的目标路径，skills 就失效了。所以如果规则要团队共享，把 .claude/skills/ 目录 gitignore，然后让大家各自搭建软链，或者直接把规则实体化提交。
• ⚠️ 改完没提交就翻车：真相源没推到远端的情况下，切换机器就凉了。这事我干过。

四、最扎心的问题：换 AI 工具怎么办？

假设你哪天想试试 Codex CLI、Cursor、Aider 等等。问题来了：这些辛辛苦苦写的 Skills，在别的 AI 终端里能用吗？

很遗憾，不能直接用。Skills 的文件布局和加载机制是 Claude Code 专属的，别的工具有各自的约定：

工具	规则文件位置	格式
Claude Code	CLAUDE.md + .claude/skills/*/SKILL.md	YAML frontmatter + Markdown
Codex CLI	AGENTS.md（项目根）/ ~/.codex/AGENTS.md	纯 Markdown
Cursor	.cursor/rules/*.mdc	MDC 格式（frontmatter + MD）
Aider	CONVENTIONS.md（可自定义文件名）	纯 Markdown
GitHub Copilot	.github/copilot-instructions.md	纯 Markdown
Windsurf / Codeium	.windsurfrules	纯 Markdown
Continue	.continue/rules/*.md	Markdown
Zed AI	AGENTS.md	纯 Markdown

看得你脑袋嗡嗡响？先别慌，有个好消息：

4.1 AGENTS.md：20000+ 项目的共同选择

业界正在快速向一个"通用约定"汇聚 —— AGENTS.md。

这个文件现在已经是事实标准。根据 2026 年初公开的数据：

• 已有 20000+ 开源项目 采纳 AGENTS.md
• GitHub 官方博客分析了 2500+ 个高质量样本，总结出最佳实践
• 支持 AGENTS.md 的工具包括：Codex CLI、Cursor、Zed、Windsurf、Google Jules、Gemini CLI、Factory、Roo Code 等 20+ 个工具
• 它的设计思路就一个词：轻量。纯 Markdown、无额外依赖、支持 monorepo 嵌套

换句话说，只要你写一份 AGENTS.md 放在项目根，大半数 AI 工具都能直接读。

4.2 那 Claude Code 怎么用 AGENTS.md？

Claude Code 主要认 CLAUDE.md，但你可以在 CLAUDE.md 里直接引用其他文件：

# CLAUDE.md
本项目的通用编码规则见 @AGENTS.md
支付模块专项规则见 @.claude/skills/pay-ini-key/SKILL.md

这样 AGENTS.md 成为多工具共享的"主干"，CLAUDE.md 只做薄薄一层转发 + Claude 专属补充。

4.3 我的实际做法

最终我的分层变成了这样：

1. 高频核心规则   →  AGENTS.md              （所有 AI 工具共享）
2. Claude 专属    →  CLAUDE.md              （引用 AGENTS.md + 几条 Claude 独有的）
3. 按需触发规则   →  .claude/skills/*/      （Claude Code 的精细化控制）
4. Cursor 专属    →  .cursor/rules/*.mdc    （软链自 AGENTS.md 的分片）

日常 90% 的规则都放 AGENTS.md，真正需要按需触发的才做成 Skills。

五、几个避坑建议

工作了一段时间，总结几条经验：

5.1 别把 Skills 当成 CLAUDE.md 的替身

如果一条规则是"每次都必须遵守"（比如输出语言、基础命名规范），放 CLAUDE.md 或 AGENTS.md，不要放 Skills。Skills 是触发式的，有可能没被触发，你就看不到那条规则生效。

5.2 Skills 的 description 一定要写得"像广告词"

因为 AI 是靠 description 判断要不要加载这个 skill 的。写得模糊就不会触发。几个 pattern：

• ✅ TRIGGER when writing or editing Java code, especially when calling instance methods.
• ✅ Use this skill when adding or using payment-related ini config keys.
• ❌ Java 规范（废话）
• ❌ 一些有用的规则（到底有啥用？）

5.3 定期"体检" skills 目录

参考 ClaudeLog 的建议，每月审查一次 CLAUDE.md 和 Skills，删掉过时规则。否则 AI 会用两年前的过期约定来指导今天的代码，你还纳闷它怎么突然发神经。

5.4 别为了层级化而层级化

不是所有项目都需要 Skills。如果一个项目只有十几条规则，一份 200 行以内的 CLAUDE.md 就够了，搞 Skills 反而复杂。简单优先。

5.5 软链方案不适合团队共享

再强调一遍：软链只对搭建者本人生效。团队里别的成员 checkout 代码后，软链指向一个他机器上不存在的路径，skills 直接消失。团队场景要么直接提交规则实体文件，要么用 git submodule，要么用 CI 去把规则从中心仓库同步下来。

六、总结

问题	答案
Skills 是 CLAUDE.md 2.0 吗？	不是。CLAUDE.md 是常驻记忆，Skills 是按需触发
怎么避免规则重复？	三层分 —— 用户级 / 项目级 / 按需调用
多个项目共享规则怎么玩？	单一事实源 + 软链，真相源在中心仓库
换 AI 工具了怎么办？	核心规则写 AGENTS.md，20+ 工具都认
CLAUDE.md 能多长？	建议 200 行以内，超了就拆到 Skills
Skills 怎么保证被触发？	description 写具体，别写废话

最后留一个问题给大家：

你现在的 CLAUDE.md 多少行了？有没有遇到过 AI 在不相关的上下文里生搬硬套某条规则的情况？

欢迎在评论区分享你的规则管理心得，咱们一起把 AI 调教得越来越顺手。

---

如果这篇对你有帮助，点个赞👍 + 收藏⭐ 再走，感谢支持！
规则管理这事，一次整理、长期受益，越早做越省心。

参考资料

• Claude Code Skills 官方文档
• AGENTS.md 官方网站
• GitHub Blog - 2500+ 项目 AGENTS.md 最佳实践
• HumanLayer - Writing a Good CLAUDE.md
• Builder.io - Claude.md Guide
• Cursor Rules 文档