眼瞅着仓库里的 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.mdSKILL.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 迁移效果对比我自己整理了一张对比表可以直观看到变化配置项迁移前迁移后CLAUDE.md 行数约 500 行约 25 行每次对话自动携带的规则量非常大极小是否包含具体操作步骤包含大量步骤仅保留约束是否按需加载细节流程否是通过 Skills跨工具复用能力差好AGENTS.md 承担通用信息AI 遵循规则的稳定度一般明显提升日常对话的响应速度较慢更快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 管得太宽反而等于什么都没管。