CLAUDE.md精简实战：分层配置、Skills按需加载与AGENTS.md跨工具复用

眼瞅着仓库里的 CLAUDE.md 一路从几十行涨到快 500 行，AI 反而越用越不听话，我一度以为是自己写指令的姿势不对。后来花了两个周末把配置彻底重做了一遍，把大部分内容从 CLAUDE.md 挪进 Skills，又补了一份 AGENTS.md 给其他工具复用，总算找回了当初“一句话就能驱动 AI 干活”的感觉。这篇就把分层配置的思路、SKILL.md 的写法、以及跨工具迁移的实操过程完整梳理一遍，希望能帮你少走弯路。

先说结论：CLAUDE.md 不是越详细越好，它的核心价值是“兜底约束”，而不是“操作手册”。真正让 AI 在正确时机调用正确流程的，是靠 Skills 做按需加载。而要让同一套项目规范在不同编程助手之间通用，AGENTS.md 才是那个跨工具标准。

1. 为什么 CLAUDE.md 越写越长，AI 反而越管不住

1.1 上下文窗口不是无限的

很多人忽略了一个硬约束：AI 处理对话时，能同时“看到”的内容是有限的。虽然各家模型的上下文窗口越开越大，但实际干活时，工具调用记录、代码文件内容、终端输出都会抢占上下文空间。CLAUDE.md 作为常驻指令，每多一行，就相当于从本就紧张的上下文里多分走一块。

想象一下，你让一个实习生干活，开工前塞给他一本 500 页的规章制度。他确实会努力读，但等他读到第 300 页的时候，前面讲什么已经忘得差不多了。AI 也有类似问题——注意力会被大量规则稀释，真正关键的约束反而沉底了。

1.2 指令越多，权重越分散

还有一层容易被忽略的机制：AI 对配置文件的处理不是“逐字严格执行”，而更像是在“理解意图”。当文件里同时存在 50 条规则，每条规则都会占据注意力。结果就是：每条规则都“知道”，但每条规则都不“重视”。

我以前就犯过这个错——为了约束 AI 的代码风格，把 TypeScript 的缩进、引号、命名规范、注释风格、文件组织方式全部塞进 CLAUDE.md，还专门写了一长段“禁止使用 any”。结果 AI 反而频繁犯错，因为在它的理解里，这些约束都只是“众多注意事项之一”。

1.3 规则冲突与优先级模糊

长文件最容易出现隐形冲突。比如前半段写道“优先使用函数组件”，后半段又写道“这个项目的老代码都是 class 组件，改的时候要保持统一”。AI 读到这两条时，没有能力判断哪条优先，于是每次表现都随缘。

我见过最典型的情况：CLAUDE.md 里写着“不要直接修改配置文件”，但某个具体指令里又写着“如果配置有问题，请直接修正”。两条规则互相矛盾，AI 有时候帮你改了，有时候又死活不动，非常折腾。

1.4 模板化书写让 AI 抓不住重点

另外，大多数人写 CLAUDE.md 喜欢用大段散文描述。比如：

“本项目是一个面向企业的数据中台系统，后端采用微服务架构，包含用户服务、订单服务、商品服务等，各服务之间通过 HTTP 接口通信，开发时请注意……”

问题在于，这种描述对 AI 来说信息密度太低了。它需要花力气从一大段话里提取“我到底要让 AI 做什么”。结果往往是：AI 记住了“这是微服务架构”，但完全不知道自己该遵守哪些具体规范。

所以，CLAUDE.md 的写法应该像给 AI 画一张“不许越过的警戒线”，而不是写一本“操作说明书”。

2. 别堆了：先搞懂 CLAUDE.md、AGENTS.md、Skills 的职责边界

2.1 CLAUDE.md 管“原则”，AGENTS.md 管“共识”，Skills 管“流程”

这三样东西经常被人混为一谈，实际上职责完全不同。

我的理解是这样的：

• CLAUDE.md 是“针对某个 AI 工具的长期记忆”，它会告诉模型这个项目的基础事实、硬性约束、工作偏好。它的核心特征是“每轮对话都会自动加载”。
• AGENTS.md 是“面向多个 AI 工具的通用项目说明”，它更像是一份给所有智能体看的入门文档：这个项目是什么、目录结构如何、构建命令是什么、代码规范有哪些。它不依赖某个具体的 AI 工具。
• Skills 是“按需加载的流程包”，它把“什么时候该做什么事、具体怎么做”拆成独立文件。AI 只在用户意图匹配到技能描述时，才会去读对应的 SKILL.md，这样就省下了大量上下文。

换句话说，CLAUDE.md 负责回答“我是谁、我不允许做什么”，AGENTS.md 负责回答“任何智能体来都能快速上手”，Skills 负责回答“具体任务来了该按什么步骤走”。

2.2 三层文件结构：全局层、项目层、记忆层

实际操作中，我会把配置拆成三层：

第一层是全局配置，放在用户目录下，里面只写所有项目通用的行为规范，比如“回答代码问题时先看现有代码风格再动手”“默认使用简洁中文注释”之类。这个文件不需要很长，二三十行足够。

第二层是项目配置，也就是仓库根目录的 CLAUDE.md。这层会写项目的技术栈、启动命令、目录结构、必须遵守的红线。我的建议是控制在 40 行以内，只保留“不可协商”的规则。

第三层是记忆和技能层，放在 .claude/ 目录下。这里可以放 Skills 子目录、记忆文件、脚本工具等。这一层的内容不需要全部加载，而是按需读取，所以可以做得非常详细。

2.3 一条黄金法则：只放“不可协商规则”

写 CLAUDE.md 时，我常用一个判断标准：如果这条规则可以写成一句“必须做”或“禁止做”，并且违反后会导致严重后果，就放进 CLAUDE.md。凡是需要解释“怎么选、怎么做、按什么步骤”的内容，一律挪到 Skills 或文档里。

比如下面这些适合放 CLAUDE.md：

• 禁止直接在生产环境执行任何命令
• 修改数据库结构前必须先走迁移流程
• 提交代码前必须运行测试命令
• 新增依赖前先征求确认

下面这些不适合放 CLAUDE.md：

• 如何新增一个 REST API 接口
• 如何调试某个服务的性能问题
• 如何发布新版本

这些更像是“操作流程”，放 Skills 里才合理。

3. Skills 分层食用指南：从零写一个能按需加载的技能

3.1 SKILL.md 的结构：让 AI 一眼知道“该不该读”

关于 Skills，核心机制并不复杂：你把一个技能做成一个目录，里面放一个 SKILL.md 文件，文件头部写清楚技能名称、描述、适用场景。当 AI 判断当前任务与某个技能描述匹配时，就会主动去读正文。

很多人的技能失效，问题就出在描述写得不好。比如：

--- name: coding-log description: 用于生成规范的提交日志。 ---

这种描述对我见过的大多数模型来说，触发率并不高。因为用户不会直接说“生成提交日志”，他可能会说“帮我总结一下改动记录”“把这次提交整理一下”“写个变更说明”。如果描述里没包含这些触发词，技能就永远不会被加载。

我的经验是，description 里要写清楚三个东西：

• 这个技能解决什么问题
• 什么场景下应该触发
• 哪些用户话术和它相关

一个更可用的写法：

--- name: add-log description: 当用户需要生成提交日志、变更记录、改动说明、commit message 时使用该技能。用户可能会说"总结一下改动""写个变更说明""整理提交信息"等。 ---

这样 AI 在遇到相关请求时，匹配成功的概率会高很多。

3.2 一个能直接抄的日志技能示例

完整技能目录如下：

.claude/skills/add-log/ ├── SKILL.md └── template.md

SKILL.md 的内容：

--- name: add-log description: 当用户需要生成提交日志、变更记录、改动说明、commit message 时使用该技能。用户可能会说"总结一下改动""写个变更说明""整理提交信息"等。 --- # 生成变更日志 ## 步骤 1. 运行 `git diff --stat` 查看本次改动的文件列表。 2. 运行 `git diff` 查看具体代码变化。 3. 根据改动内容，将变更分类到以下类型： - 新增功能 - 修复缺陷 - 重构优化 - 文档调整 - 依赖更新 4. 每条变更用一小段话描述，说明“改了什么”和“为什么改”。 5. 输出格式参照 template.md。 ## 注意事项 - 不要逐行复述代码，只总结对外表现的变化。 - 如果改动只涉及格式化或空白，标记为“无功能变化”。 - 描述时使用过去时。

template.md 里放一份参考格式：

## 变更日志 ### 新增 - 新增订单状态查询接口，支持按订单号和时间范围过滤。 ### 修复 - 修复并发场景下库存扣减超卖问题。 ### 优化 - 重构用户校验逻辑，减少无用查询。

这样一个技能就足够稳定，AI 不会因为“不知道格式”而自由发挥。

3.3 技能分层的三种粒度

技能不能一股脑全塞到一个目录里，我也经历过“技能数量一多，AI 反而选错”的阶段。后来我按粒度把技能分成三类：

第一类，通用技能，比如代码审查、生成测试用例、重构小函数、写提交信息。这类技能所有项目都可能用到，我放到全局技能目录里，和项目无关。

第二类，工具链技能，比如某框架的调试流程、某个 CLI 工具的常用操作、数据库迁移步骤。这类技能跟技术栈强相关，放在项目级 .claude/skills 里。

第三类，业务技能，比如这个项目里特有的模型训练流程、数据标注规范、发布前检查清单。只有当前业务需要，所以放在项目内甚至子目录内。

这样分层之后，AI 在匹配技能时能更快定位，不会因为几十个技能同时摆在面前而选中错误的那一个。

3.4 技能命名的三个误区

给技能命名，看起来简单，实际上踩坑率很高。第一个误区是名字太宽泛，比如“helper”“utils”，AI 根本猜不出它什么时候该用。第二个误区是名字和描述不一致，比如叫 database，内容却全是缓存清理，触发时对不上号。第三个误区是目录层级太多，一个技能套好几层子目录，AI 在探索时容易迷失。

我比较常用的命名方式是：动词开头、加上对象、再加上结果。比如generate-migration、refactor-component、check-lint。这样 AI 看到任务时，很容易先从名字层面排除不相关的技能。

4. AGENTS.md 跨工具吃遍天下：一份配置，多端复用

4.1 为什么需要 AGENTS.md

很多人只写了 CLAUDE.md，结果换到别的编程助手时发现完全不起作用。Claude Code 认 CLAUDE.md，但另一款工具未必认它。现在的编辑器级 Agent、命令行助手，越来越多的产品开始读取仓库根目录的 AGENTS.md 作为通用指令文件。

AGENTS.md 的意义在于：它是一份“工具无关”的项目说明。无论对方是哪个平台的编程助手，只要它支持读取 AGENTS.md，都能拿到项目的关键信息，快速进入干活状态。这不等于废弃 CLAUDE.md，而是让 CLAUDE.md 里的内容更精简，把通用信息放到 AGENTS.md 让所有工具共享。

4.2 AGENTS.md 写法和 CLAUDE.md 有什么不同

CLAUDE.md 里可以写“当我执行某类任务时，请先参照某个文件”“请使用某工具的子代理模式处理复杂任务”这类带工具属性的指令。AGENTS.md 则不能这么干，因为它面向多种工具，必须剥离工具特定语法，只保留项目自身的共识性信息。

举个例子，CLAUDE.md 里可以写“建模前先用 /plan 生成实施计划”，这条指令换个工具就失效了，因为人家没有 /plan 这个斜杠命令。AGENTS.md 里应该写成“对涉及数据库结构变更的任务，先输出实施计划，确认后再继续”，这样所有工具都能理解并执行。

还有一个差异：CLAUDE.md 可以写得比较口语化，比如“记住，任何改动都要先在本地跑一遍测试”。AGENTS.md 应该更中性，语言清晰、结构化，避免模型因为语气差异做出误解。

4.3 一份可跨工具的 AGENTS.md 模板

我整理了一份比较通用的模板，可以直接拿来改：

# 项目说明 这个仓库是一个订单管理服务，负责订单创建、支付回调、状态流转和查询。技术栈为 TypeScript + Node.js + PostgreSQL。 ## 常用命令 - 安装依赖：npm install - 本地开发：npm run dev - 运行测试：npm test - 类型检查：npm run typecheck - 构建：npm run build ## 目录结构 - src/controllers 接口层，处理入参和响应 - src/services 业务逻辑层，核心逻辑都在这 - src/models 数据模型定义 - src/migrations 数据库迁移脚本 - tests/ 测试文件，与 src 保持相同目录结构 ## 开发约定 - 数据库变更必须新增迁移文件，不允许直接手工改表结构。 - 所有对外接口返回结构统一为 { code, message, data }。 - 业务逻辑不要堆在控制器层，应该下沉到 service 中。 - 涉及金额计算必须使用整数类型，存储单位是分。 ## 测试要求 - 修改业务逻辑时，需要同步更新或新增对应测试。 - 提交前运行 npm test，确保所有测试通过。

这份文件既没有依赖具体 AI 工具，又提供了足够的上下文。任何支持 AGENTS.md 的助手读完之后，都能对项目有基本认知。

4.4 跨工具兼容的注意事项

想让 AGENTS.md 真正“吃遍天下”，有几个细节值得留意。第一，不要在里面写某个工具专属的指令，比如斜杠命令、特殊语法、私有标签。第二，不要放太长篇幅的历史背景，重点写“现在如何操作”。第三，尽量用简单的相对路径描述目录，不要用一串绝对路径。第四，如果同一仓库里 CLAUDE.md 和 AGENTS.md 都存在，要保证两者核心规则不冲突，否则不同工具在不同文件之间跳来跳去，容易产生不一致行为。

我自己会把 AGENTS.md 当作“唯一事实源”，CLAUDE.md 里只写 Claude 工具特性相关的增强指令。这样即便以后换工具，项目侧的规范依然能完整继承。

5. 实操迁移：把 500 行 CLAUDE.md 压到 30 行

5.1 迁移前：先做规则盘点

如果你已经有一份很长的 CLAUDE.md，不要直接删。第一步，把全文复制出来，逐条分类。我会用三个标签来分：

• A 类：不可协商的硬性约束，比如安全红线、提交前测试、禁止操作。
• B 类：按需执行的流程步骤，比如如何发布版本、如何生成迁移文件。
• C 类：背景说明和项目历史，比如为什么选择某个框架、架构演进记录。

分类之后你会发现，真正属于 A 类的规则通常不超过十条。剩下的 B 类和 C 类，才是让文件膨胀的真凶。

5.2 迁移后的 CLAUDE.md 实例

下面这份是我在某个模拟项目里实际整理出的精简版本，可以作为参考：

# CLAUDE.md 这个项目是订单管理服务，TypeScript + Node.js + PostgreSQL。完整项目背景见 AGENTS.md。 ## 硬性约束 - 禁止直接连接生产数据库执行写操作。 - 所有数据库结构变更必须新增迁移文件，不能修改历史迁移。 - 提交代码前必须运行 npm test，确保全部通过。 - 不允许直接关闭 eslint 报错。 - 涉及金额时使用整数类型按分存储，禁止浮点运算。 ## 工作偏好 - 修改文件前先查看目标文件的现有风格，保持一致性。 - 复杂逻辑编写完成后，顺手补上最小可运行的测试。 - 不确定业务语义时先提问，不要自己拍板。 ## 特殊约定 - 需要建模或改动多个文件的场景，先给出实施计划，经确认后再动手。

总共 20 多行，核心约束全部保留，背景信息全部移走。

5.3 迁移效果对比

我自己整理了一张对比表，可以直观看到变化：

5.4 迁移过程中踩过的三个坑

第一个坑是“删过头”。一开始我把所有命令和目录结构都从 CLAUDE.md 移走了，结果 AI 在执行任务时连项目怎么启动都不知道。后来我意识到，AGENTS.md 里要有一个最小化的“启动与测试命令”区，AGENTS.md 作为兜底，CLAUDE.md 才能放心精简。

第二个坑是“技能描述太抽象”。我第一次写技能描述时，总想着写得更概括、更像论文摘要，结果 AI 完全不会在正确时机加载。后来改用“用户可能会说xxx”这种具体话术，触发率一下子上来了。

第三个坑是“改了文件忘了清理旧规则”。迁移过程中很容易出现 CLAUDE.md 和本地文档相互矛盾的情况。我的习惯是，迁移完成后全局搜索“不要”“禁止”“一定”这类强度词，逐一确认每一条还有没有存在的必要。这个检查动作能避免很多新旧指令打架的隐性问题。

6. 常见问题与排查速查表

6.1 技能不生效

技能写了但 AI 不调用，这是最常遇到的问题。我一般按三步排查：

第一步，查看技能目录位置是否正确。全局技能和项目技能放在不同位置，如果放错了，工具根本扫描不到。

第二步，检查 SKILL.md 的 frontmatter 是否完整。name 必须唯一，description 必须包含清晰触发条件，正文第一段不要说废话。

第三步，测试触发词覆盖度。工具执行过程我一般打开日志观察，看看当前对话有没有实际读取这个技能文件。没有读取，就说明描述和目标任务匹配度不够，需要增加触发词。

6.2 CLAUDE.md 与 AGENTS.md 冲突

有时候两份文件放一起，AI 会不知道听谁的。比如 CLAUDE.md 里写“测试命令是 npm test”，AGENTS.md 里如果写着“运行项目使用 pnpm test”，那就冲突了。

我的做法是以 AGENTS.md 为准，把通用信息全部放进去，CLAUDE.md 只负责“补充当前工具特有行为”。如果发现两份文件有重复且不一致的信息，第一时间统一到 AGENTS.md，删除另一侧副本。

6.3 几个规避问题的写法建议

根据我个人的实操经验，还有几条比较实用的写法建议：

第一，少用否定句。写“禁止使用 any”不如写“所有类型必须显式定义，无法确定类型时先定义联合类型或者接口”。AI 更容易从“该做什么”里获得清晰指引，而不是靠“不该做什么”来猜边界。

第二，避免歧义数值。比如“控制函数长度在 50 行以内”，不如“当一个函数超过 50 行时，提取子函数，使主函数只保留控制流”。给出触发条件和动作，而不是留一个干巴巴的数字让 AI 自己纠结。

第三，给 AI 一条“最优路径”。要求“不要直接用循环拼接字符串”，不如写“优先使用数组的 map 和 join 方法处理字符串列表”。要求越具体，AI 的表现越稳定。

第四，常用命令放 AGENTS.md，不常有的复杂步骤放 Skills。本质上还是“常驻内容要精简，按需内容要完整”。只要把握住这个分层逻辑，配置管理的思路就不会跑偏。

最后再分享一个小技巧：写 CLAUDE.md 的时候，试着想象你是在给一个经验丰富但刚入职的同事写“第一天入职须知”，而不是在写法律条文。你只需要告诉他哪些底线不能碰、遇到困惑时问谁、常用命令在哪查，剩下的工作他自然会靠自己的经验搞定。CLAUDE.md 管得太宽，反而等于什么都没管。