CLAUDE.md 写到 500 行还管不住 AI？Skills 分层食用指南 + AGENTS.md 跨工具吃遍天下

一个资深 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 的namedescription放进上下文当成目录。当 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.mdSkills加载时机进入项目就塞入 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 规则所有交互提示、分析过程用中文控制台输出每行末尾不要填充空格Java 类内部方法调用加this.前缀支付相关的 ini key 必须放到com.example.pay.enums.PayConfEnum枚举中按两层组织分一下规则归属理由① 中文输出用户级个人语言偏好跨所有项目一致② 行尾不留空格用户级通用编码卫生习惯③ Javathis.前缀用户级或项目级看是个人偏好还是团队约定④PayConfEnum枚举项目级只对order-svc有意义其他项目根本没这个类分完之后突然就清爽了 —— ①② 永远有效不管我切到哪个项目③ 放用户级对我所有 Java 项目默认生效④ 只在支付服务里加载其他项目的 AI 根本不会知道有这么个枚举也就不会瞎套用。2.2 再举一个数仓项目的例子我另一个数仓项目dw-platform写的是 ClickHouse SQL规则完全不一样中文别名用反引号包裹count(*) AS 订单数ReplacingMergeTree表查询必须加FINALfrom dwd.fact_payment as a final时间字段判空不能用IS NULL因为 CK 里 null 会变成1970-01-01 08:00:00要用a.pay_time 2000-01-01字符串判空要同时判和NULLSQL 语句之间不留空行这些规则只对 ClickHouse 生效放到其他项目会产生误导。所以它们应该躺在dw-platform/.claude/skills/clickhouse-sql-conventions/里别的项目看不见。三、处理重叠单一事实源 软链三层分好之后还会遇到一个现实问题有些规则介于通用和项目专属之间。比如 Javathis.前缀规则你有 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/javaln-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-platform3.3 这样做的好处✅改一处全局生效规则演进时只改真相源所有项目自动跟进✅版本化真相源可以 git 管理谁改的、什么时候改的、为什么改全都有迹可循✅按需拼装Go 项目压根不会链接 Java 目录描述都进不了 context数仓项目同理✅团队共享如果是团队规则真相源做成公司内部仓库每个人都能拉3.4 也有坑⚠️符号链接在团队里只对自己生效别人 checkout 项目时拿不到软链的目标路径skills 就失效了。所以如果规则要团队共享把.claude/skills/目录 gitignore然后让大家各自搭建软链或者直接把规则实体化提交。⚠️改完没提交就翻车真相源没推到远端的情况下切换机器就凉了。这事我干过。四、最扎心的问题换 AI 工具怎么办假设你哪天想试试 Codex CLI、Cursor、Aider 等等。问题来了这些辛辛苦苦写的 Skills在别的 AI 终端里能用吗很遗憾不能直接用。Skills 的文件布局和加载机制是 Claude Code 专属的别的工具有各自的约定工具规则文件位置格式Claude CodeCLAUDE.md.claude/skills/*/SKILL.mdYAML frontmatter MarkdownCodex CLIAGENTS.md项目根/~/.codex/AGENTS.md纯 MarkdownCursor.cursor/rules/*.mdcMDC 格式frontmatter MDAiderCONVENTIONS.md可自定义文件名纯 MarkdownGitHub Copilot.github/copilot-instructions.md纯 MarkdownWindsurf / Codeium.windsurfrules纯 MarkdownContinue.continue/rules/*.mdMarkdownZed AIAGENTS.md纯 Markdown看得你脑袋嗡嗡响先别慌有个好消息4.1 AGENTS.md20000 项目的共同选择业界正在快速向一个通用约定汇聚 ——AGENTS.md。这个文件现在已经是事实标准。根据 2026 年初公开的数据已有20000 开源项目采纳AGENTS.mdGitHub 官方博客分析了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.mdClaude 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.md20 工具都认CLAUDE.md 能多长建议200 行以内超了就拆到 SkillsSkills 怎么保证被触发description 写具体别写废话最后留一个问题给大家你现在的 CLAUDE.md 多少行了有没有遇到过 AI 在不相关的上下文里生搬硬套某条规则的情况欢迎在评论区分享你的规则管理心得咱们一起把 AI 调教得越来越顺手。如果这篇对你有帮助点个赞 收藏⭐ 再走感谢支持规则管理这事一次整理、长期受益越早做越省心。参考资料Claude Code Skills 官方文档AGENTS.md 官方网站GitHub Blog - 2500 项目 AGENTS.md 最佳实践HumanLayer - Writing a Good CLAUDE.mdBuilder.io - Claude.md GuideCursor Rules 文档