1. 当 CLAUDE.md 从 20 行长到 200 行问题才真正开始CLAUDE.md 是 Claude Code 每次对话都会自动加载的项目级上下文文件它决定了模型在打开项目时默认知道什么。Skill 则是按需加载的能力模块只有被显式调用或语义匹配命中时才会进入上下文。两者配合得好项目规则既稳定又轻量配合得不好CLAUDE.md 会变成一个什么都往里塞的杂物间。我见过太多项目走到这一步最初 CLAUDE.md 只有二十来行写着技术栈、包管理器、提交规范干净利落。三个月后它膨胀到两百行前端设计规范、API 审查清单、数据库操作注意事项、部署流程、性能优化 checklist 全挤在一起。结果就是——你今天只是改一个按钮颜色那两百行照样全部加载进上下文。这就像每天上班背着一个装满所有工具的大书包其实今天只需要一支笔。这篇文章解决一个非常具体的问题CLAUDE.md 里哪些内容该留下哪些该拆成 Skill拆分后目录和引用怎么组织以及怎么用 TaoToken 统一 Key 跑一次验证确认拆分后调用链正常。适合已经在用 Claude Code、CLAUDE.md 开始变臃肿、想动手整理但不确定边界的开发者。2. 拆分判断四个问题决定一段内容的归属面对 CLAUDE.md 里的每一块内容依次问自己四个问题答案会自然浮现。2.1 每次对话都需要吗这是最关键的判断标准。CLAUDE.md 是始终在线的所以里面应该放始终需要的内容。“我们用 TypeScript包管理用 pnpm”——每次都需要留在 CLAUDE.md。“部署到生产环境时先跑 smoke test再切流量切流量分三步……”——只在部署时需要候选 Skill。如果某段内容只在特定场景触发它就不该占用每次对话的上下文。2.2 内容有多长即使某段内容不是每次都用如果它只有两三行留在 CLAUDE.md 也无妨上下文代价很小。比如“数据库查询必须使用参数化查询禁止字符串拼接 SQL”这种一两行的规则不值得单独做成 Skill。但一份四十行的 API 审查清单只在做 API 审查时才需要这就是典型的 Skill 候选。2.3 是约定还是流程约定是简短的、声明式的规则变量命名用 camelCase、组件文件用 PascalCase、CSS 类名用 kebab-case。约定适合放在 CLAUDE.md简短、通用、始终有效。流程是有步骤的、过程式的操作指南切到 release 分支、运行构建、执行 smoke test、滚动更新、观察监控、全量发布、更新 CHANGELOG。流程适合做成 Skill详细、场景化、按需调用。2.4 多个项目需要复用它吗如果某段内容只在当前项目用按前三个问题判断就够了。但如果你发现自己在好几个项目的 CLAUDE.md 里写了类似内容比如通用的代码审查规范、Git 工作流、性能优化清单那就值得做成全局 Skill放在~/.claude/skills/下所有项目共享。3. TaoToken 前置统一 Key 与 API 通道拆分之后Skill 和 CLAUDE.md 都会触发模型调用。如果每个项目、每个工具各配一套 Key验证调用链时会非常混乱。我的做法是用 TaoToken 做统一入口一个 Key 覆盖模型对话、编码计划和 API 调用。TaoToken 是一个大模型 API 聚合平台提供统一的 Key 和兼容 OpenAI 的接口格式适合需要多模型切换、又不想在多个后台之间来回配置的开发者。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要先拿到 Key。进入控制台创建 API Key控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理pegehttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建后把 Key 写进环境变量不要硬编码进项目文件。下面所有配置都基于这个统一 Key。4. 可复制配置CLAUDE.md 骨架与 Skill 目录4.1 瘦身后的 CLAUDE.md 骨架拆分后 CLAUDE.md 控制在 50 到 100 行之间只保留始终需要的约定。下面是一个可直接复制的骨架# 项目说明 技术栈React 18 TypeScript Tailwind CSS 包管理pnpm 测试框架Vitest 部署平台AWS ECS # 编码规范 - 变量命名 camelCase组件 PascalCase - 禁止 any必须显式类型标注 - 函数最大行数 50 行 - import 顺序外部库 → 内部模块 → 类型 → 样式 # Git 提交规范 - 使用 Conventional Commits 格式 - feat: 新功能 | fix: 修复 | refactor: 重构 - 提交信息用英文首字母小写 # 数据库约定 - 查询必须参数化禁止字符串拼接 SQL - 所有 API 响应必须包含 request_id 字段 # Skill 索引 - 前端设计审查/frontend-review - API 安全审查/api-review - 数据库操作/db-ops - 部署流程/deploy - 性能优化/perf-check最后那段 Skill 索引很关键。它让模型知道有哪些能力可以调用同时不把具体内容塞进上下文。4.2 Skill 目录结构项目级 Skill 放在.claude/skills/下每个 Skill 一个目录目录里放SKILL.md.claude/skills/ ├── frontend-review/ │ └── SKILL.md ├── api-review/ │ └── SKILL.md ├── db-ops/ │ └── SKILL.md ├── deploy/ │ └── SKILL.md └── perf-check/ └── SKILL.md全局共享的 Skill 放在~/.claude/skills/下结构相同。项目级优先于全局级同名时项目级覆盖。4.3 SKILL.md 的 frontmatter 写法每个 SKILL.md 开头必须有 YAML frontmattername和description是必填项。description 会参与语义匹配写得越准确自动加载越稳定--- name: frontend-review description: 审查前端代码的设计规范合规性包括间距、字体、配色、响应式和交互状态 --- ## 间距系统 - 基础单位 4px所有间距必须是 4 的倍数 - 组件内间距8px / 12px / 16px - 组件间间距16px / 24px / 32px ## 字体层级 - H1: 32px/40px bold - H2: 24px/32px semibold - Body: 16px/24px regular - Caption: 14px/20px regular ## 配色规范 - 主色#1a73e8 - 语义色success #34a853 / error #ea4335 / warning #fbbc04 ## 审查要点 - [ ] 间距是否对齐 4px 网格 - [ ] 字体层级是否正确 - [ ] 按钮是否有 hover/active/disabled 状态 - [ ] 是否适配移动端断点640px / 768px / 1024px4.4 settings.json 配置片段在项目.claude/settings.json里配置模型通道指向 TaoToken 的统一端点{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的_TaoToken_Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Write, Bash(pnpm *), Bash(git *) ] } }如果你更习惯用环境变量而不是写进 settings.json可以在 shell 里导出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKEN你的_TaoToken_Key注意不要把 Key 提交到 Git。settings.json 建议加入.gitignore或者用settings.local.json存放敏感配置。5. 验证请求确认拆分后调用链正常配置完成后需要跑一次验证确认 CLAUDE.md 加载、Skill 调用、模型请求三条链路都通。5.1 验证模型通道先用 curl 直接打一次 API确认 Key 和端点没问题curl https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: 你的_TaoToken_Key \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }返回里能看到content字段和正常文本说明通道通了。如果返回 401检查 Key返回 404检查端点路径。5.2 验证 CLAUDE.md 加载打开 Claude Code输入一个简单问题比如“这个项目用什么包管理器”。如果 CLAUDE.md 正常加载模型应该直接回答 pnpm而不需要你去翻文件。5.3 验证 Skill 调用手动调用一个 Skill/frontend-review 帮我审查一下 src/components/Header.tsx 的样式如果 Skill 配置正确模型会加载 frontend-review 的内容并按里面的审查要点逐条检查。你也可以测试自动匹配在对话里说“审查一下这个 API 的安全性”description 写得准确的话api-review 会被自动加载。5.4 验证结果对照验证项预期结果失败时检查API 通道返回正常文本Key、端点、模型名CLAUDE.md 加载直接答出项目约定文件位置、文件名拼写Skill 手动调用按 Skill 内容执行frontmatter、目录结构Skill 自动匹配语义命中自动加载description 是否准确6. 本篇常见错排查6.1 Skill 不生效斜杠命令没反应最常见的原因是目录层级错了。Skill 必须是.claude/skills/skill-name/SKILL.md不能是.claude/skills/SKILL.md也不能是.claude/skills/skill-name.md。每个 Skill 一个独立目录目录名和 frontmatter 里的name保持一致最稳妥。6.2 frontmatter 格式错误导致解析失败YAML frontmatter 必须用三个短横线开头和结尾中间不能有 Tab 缩进。name和description缺一不可。如果 description 里包含冒号要用引号包起来否则 YAML 解析会报错。6.3 CLAUDE.md 拆分后模型“失忆”拆得太狠了。高频、简短的约定就该留在 CLAUDE.md 里它们的上下文代价很小但缺失会让模型每次都可能犯错。判断标准很简单如果这条规则几乎每个任务都相关就留在 CLAUDE.md。6.4 自动匹配不稳定description 写得太模糊。比如只写“代码审查”模型无法区分是前端审查还是 API 审查。description 要包含触发场景和具体范围比如“审查前端代码的设计规范合规性包括间距、字体、配色”。6.5 API 请求返回 401 或 403检查 Key 是否复制完整有没有多余空格。如果用 settings.json 配置确认 JSON 格式合法没有尾随逗号。环境变量和 settings.json 同时存在时settings.json 优先级更高容易覆盖掉你刚设的环境变量。6.6 上下文反而变重了把所有东西都拆成了 Skill每次对话手动加载好几个比一个 CLAUDE.md 还麻烦。Skill 不是越多越好只拆真正低频、长内容、流程化的部分。一个健康的配置通常是一个精炼的 CLAUDE.md 打底加上三到五个针对特定场景的 Skill。7. 按场景选择下一步拆分完成后日常使用方式几乎没有变化反而更清爽。打开 Claude CodeCLAUDE.md 自动加载三十五行的核心约定轻量精准要做前端审查时输入/frontend-review要部署时输入/deploy按需调用。如果你还在调试接入配置建议先看接入文档把 Key 和端点确认清楚接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite如果你想先验证模型通道是否正常可以直接在模型对话里发一条测试消息模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite如果你打算长期用 Claude Code 做编码和 Agent 任务Coding Plan 更适合按量使用Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite最后说一点实操经验不需要一步到位。你不必今天就把 CLAUDE.md 拆得完美。正常使用等你觉得它太长了、某些内容明显只在特定场景用到再拆出来就好。渐进式优化比一开始就过度设计更实际。CLAUDE.md 是常识Skill 是专家让常识始终在线让专家按需登场。