个人总结的超详细的Claude Code学习笔记：从CLAUDE.md到SKILL.md的配置骨架

1. 为什么我把 Claude Code 的配置拆成四层来学刚接触 Claude Code 的时候我踩过一个很典型的坑把所有规则、偏好、项目说明全塞进一个CLAUDE.md结果文件越写越长AI 反而越来越不听话。后来翻了不少资料才明白Claude Code 的上下文工程其实是一个分层体系——CLAUDE.md管项目规则MEMORY.md存自动记忆SKILL.md封装任务流程Plugins 负责打包分发。这四类东西各管一摊混在一起写只会互相打架。这篇笔记就是把我自己从零搭配置体系的过程整理出来面向的是刚上手 Claude Code、还没搞清楚这几个文件到底该放什么的新手。读完之后你应该能做到三件事写出一个能用的CLAUDE.md骨架、配出一个带参数和脚本的SKILL.md、知道MEMORY.md和 Plugins 分别在什么场景下才值得动。文中所有配置都可以直接复制我会在每一步后面给出验证动作确保你改完能立刻看到效果。需要提前说明一点CLAUDE.md和MEMORY.md最终是以 user-role 上下文消息的形式注入对话历史的不是 system prompt。这意味着它们的约束力没有想象中那么强AI 有权判断这条规则和当前任务是否相关。想让规则变成硬约束得靠 Hooks 或权限配置这个后面会单独讲。2. 前置准备把 TaoToken 接进 Claude Code在开始写配置文件之前得先让 Claude Code 能正常发请求。我这边用的是 TaoToken 做模型接入它的接口格式和 Anthropic 官方兼容配置起来比较省事。先去控制台拿一个 API Key地址是 https://taotoken.net/api-keys 登录后新建一个密钥复制出来备用。注意这个 Key 只在创建时完整显示一次记得存好。拿到 Key 之后通过环境变量注入。Windows PowerShell 下这样写$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_AUTH_TOKEN sk-你的密钥macOS 或 Linux 下换成export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的密钥如果你想让配置持久化Windows 用setx写进用户环境变量macOS 写进~/.zshrc或~/.bash_profile。这里有个细节ANTHROPIC_BASE_URL后面不要带/v1Claude Code 会自己拼路径多写一层会 404。配好之后跑一下claude命令能进交互界面就说明接入通了。如果报 401八成是 Key 复制时带了空格如果报连接超时检查一下ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/末尾多了斜杠有时也会出问题。想先验证模型能不能正常对话可以直接用网页版的模型对话入口试一句确认账号和额度都没问题再去折腾本地配置。3. CLAUDE.md项目规则的第一层骨架3.1 它到底该放什么CLAUDE.md是写给 AI 看的项目说明书内容分三块项目介绍目录结构、模块职责、常用命令、开发规范命名、代码风格、Git 提交格式、注意事项特殊约束、踩坑记录。官方建议把它用在 coding standards、workflows、project architecture 这类稳定信息上。放置位置有多个层级新手先记住最常用的两个就够了项目根目录下的CLAUDE.md以及项目根目录下.claude/CLAUDE.md。前者适合放团队共享的通用规则后者适合放和这个项目强绑定的配置。再往上还有用户级~/.claude/CLAUDE.md和组织级那是团队规模大了之后才需要考虑的事。3.2 可复制的骨架下面这个骨架我用了大半年结构清晰又不啰嗦你可以直接改成自己的项目# 项目概述 这是一个基于 Next.js 14 的电商后台管理系统使用 App Router。 主要模块 - src/app 页面路由 - src/components 通用组件 - src/lib 工具函数和 API 封装 - src/server 服务端逻辑 # 常用命令 - 安装依赖pnpm install - 本地开发pnpm dev - 运行测试pnpm test - 类型检查pnpm typecheck - 代码格式化pnpm lint:fix # 开发规范 - 包管理器统一用 pnpm不要用 npm 或 yarn - 组件文件名用 PascalCase工具函数用 camelCase - Git 提交遵循 Conventional Commitsfeat: fix: chore: - 所有 API 请求必须走 src/lib/request.ts 封装不要直接 fetch # 注意事项 - 数据库迁移文件不要手动改用 pnpm db:generate - 环境变量新增后要同步更新 .env.example - 提交前必须跑通 pnpm typecheck 和 pnpm test3.3 验证它有没有生效写完CLAUDE.md后在项目目录下启动 Claude Code输入/memory命令。这个命令会列出当前会话加载的所有CLAUDE.md、CLAUDE.local.md和 rules 文件。如果你刚写的文件没出现在列表里检查两点文件名大小写是否完全一致必须是全大写CLAUDE.md以及文件是否在项目根目录或.claude/目录下。再做一个行为验证问 AI 这个项目用什么包管理器如果它回答 pnpm说明规则被读进去了。如果它答 npm那多半是文件没被加载或者你的问题触发了它自己的先验知识。3.4 一个必须知道的限制CLAUDE.md的内容最终是作为一条 user message 插到对话历史最前面的末尾还会跟一句写死的提示大意是这段上下文可能和你的任务相关也可能不相关除非高度相关否则不要响应。所以当 AI 忽略了你写的某条规则时不一定是它不听话而是源码层面就允许它这么做。想让某条规则变成硬约束有两个方向一是用 Hooks 在工具调用前后做程序级拦截二是用权限配置限制它能碰哪些文件。CLAUDE.md更适合放希望它尽量遵守的软规则。4. MEMORY.md让 AI 记住踩过的坑4.1 它和 CLAUDE.md 的分工CLAUDE.md是你手写的项目规则MEMORY.md是 Claude 自己沉淀的工作笔记。每次会话开始时Claude Code 会加载MEMORY.md的前 200 行或前 25KB取先到者超出部分不会自动加载。详细内容会被它挪到同目录下的其他主题文件里比如debugging.md、api-conventions.md需要时再按需读取。存放路径是~/.claude/projects/project/memory/MEMORY.mdproject通常根据 Git 仓库名派生。同一个仓库下的所有 worktree 共享同一份记忆。4.2 怎么让它记住东西最直接的方式是在对话里说记住这个项目的 API 测试需要本地 Redis 实例。Claude 会把这条信息写进 Auto Memory。你也可以手动打开记忆文件夹编辑用/memory命令能看到入口。我遇到过一个典型场景让 AI 写接口用例时它总是漏掉必须写的注释格式。我没有直接改CLAUDE.md而是反问它这次为什么漏了以后怎么避免它自己总结出一条记忆写进了MEMORY.md。下次再写用例时这条格式要求就被自动带上了。4.3 关掉它的方法Auto Memory 默认开启。如果你觉得它记的东西不靠谱可以在settings.json里关掉{ autoMemoryEnabled: false }或者用环境变量$env:CLAUDE_CODE_DISABLE_AUTO_MEMORY 1关掉之后MEMORY.md就不再自动加载但CLAUDE.md不受影响。4.4 验证记忆是否生效在会话里说一句记住本项目用 pnpm然后退出重进问它这个项目用什么包管理器。如果它答 pnpm 并且提到是从记忆里读到的说明 Auto Memory 工作正常。如果答错去~/.claude/projects/下找对应的记忆目录看看MEMORY.md里有没有写进去。5. SKILL.md把重复流程封装成技能5.1 什么时候该写 Skill判断标准很简单如果某个操作是多步骤流程或者只对代码库的某一部分重要就该写成 Skill而不是塞进CLAUDE.md。比如生成 PR 摘要、做代码审查、按公司规范写接口用例这些都是典型的 Skill 场景。Skill 的存放位置有两个项目级在.claude/skills/skill-name/SKILL.md用户级在~/.claude/skills/skill-name/SKILL.md。注意必须是目录加SKILL.md的形式直接放一个my-skill.md文件是不会被加载的这是新手最容易踩的坑。5.2 最小可用的 SKILL.md一个 Skill 必须包含 frontmatter 里的name和descriptiondescription要写清楚什么时候用这个技能因为 AI 就是靠它来判断是否触发的。--- name: pr-review description: 当用户要求审查 Pull Request 或检查代码变更时使用。适用于查看 diff、检查测试覆盖、识别安全风险。 --- # PR 审查流程 按以下步骤执行 1. 用 git diff main...HEAD 查看本次变更 2. 检查新增代码是否有对应的测试用例 3. 扫描是否有硬编码密钥、SQL 拼接等安全风险 4. 检查是否遵循了 CLAUDE.md 里的命名规范 5. 输出一份 review summary包含变更概述、发现的问题、建议 输出格式 - 变更概述一句话说明这次改了什么 - 问题列表按严重程度排序每条注明文件和行号 - 建议可选的改进方向5.3 带参数和脚本的进阶写法Skill 支持参数占位符。$ARGUMENTS是用户传进来的全部内容$0$1$2是按位置取参数$ARGUMENTS[0]是$0的全名版。注意$ARGUMENTS必须全大写写成$arguments不会被替换。如果想给参数起名字在 frontmatter 里用arguments字段按顺序声明--- name: create-task description: 创建一个开发任务 arguments: - 任务内容 - 优先级 - 负责人 --- 任务内容$任务内容 优先级$优先级 负责人$负责人调用时/create-task 修复登录bug 高 张三三个参数会按位置对应。名字只是方便阅读本质还是按顺序匹配位置错了名字救不了你。另外参数名不能用纯数字会和$1$2的语法打架。引用同目录下的脚本要用${CLAUDE_SKILL_DIR}它会替换成当前 Skill 所在的目录路径运行检查脚本 !${CLAUDE_SKILL_DIR}/scripts/check.sh注意花括号不能省。$CLAUDE_SKILL_DIR少了花括号不会被替换这是另一个高频坑。同理还有${CLAUDE_SESSION_ID}用来给临时文件起不重名的名字。5.4 验证 Skill 是否被加载启动 Claude Code 后输入/如果 Skill 配置正确你会在斜杠命令列表里看到它的name。手动触发一次观察 AI 是否按你写的步骤执行。如果没出现在列表里检查目录结构是不是.claude/skills/pr-review/SKILL.md这种形式以及 frontmatter 的---有没有写对。还有一个限制要知道Skill 的清单有上下文预算默认约占上下文窗口的 1%。单个 Skill 的description超过 250 字符会被截断。所以description要写得精准别堆砌关键词。6. Plugins把一堆能力打包分发6.1 它和 Skill 的区别Skill 本质上是一个.md文件加上配套的脚本和参考文档Plugins 则是一个自包含目录里面可以装 Skills、Commands、Agents、Hooks、MCP Servers、LSP Servers 等。简单说Skill 是一本书Plugin 是一个图书馆。什么时候需要 Plugin当你想把前端开发规范 自动格式化命令 提交前 Hook MCP 接入这一整套东西打包给团队用时就该上 Plugin 了。它支持通过 Marketplace 一键安装自带版本号和作者信息还能按 user / project / local 三种作用域控制生效范围。6.2 最小 Plugin 结构一个 Plugin 必须有一个.claude-plugin/plugin.json{ name: my-plugin, version: 1.0.0, description: 团队前端开发规范插件, author: { name: 张三, email: zhangsanexample.com } }完整的目录结构大概是这样my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── commands/ │ └── deploy.md ├── agents/ │ └── reviewer.md ├── skills/ │ └── my-skill/ │ └── SKILL.md ├── hooks/ │ └── hooks.json └── .mcp.json新手阶段其实用不到 Plugin先把CLAUDE.md和SKILL.md玩熟等有跨项目复用的需求了再考虑打包。7. 本篇常见错误排查配置过程中最容易卡住的几个点我按出现频率排一下。CLAUDE.md写了但 AI 不遵守先用/memory确认文件被加载了。如果加载了但行为不对多半是规则写得太泛比如代码要写得好这种没法执行的描述。改成具体可验证的比如所有 API 请求必须走src/lib/request.ts。Skill 不出现在斜杠命令列表九成是目录结构错了。必须是.claude/skills/name/SKILL.md不能是.claude/skills/name.md。另外检查 frontmatter 的name和description是否都填了。参数没被替换$ARGUMENTS必须全大写${CLAUDE_SKILL_DIR}必须带花括号。这两条各对应一类语法写混了就不会替换。MEMORY.md记了错误信息Auto Memory 是 AI 自己判断该记什么的偶尔会记错。定期用/memory打开记忆目录审计一下把过期的条目删掉。如果某个项目根本不需要自动记忆直接在settings.json里关掉。改了配置但没生效Claude Code 在会话启动时读取配置改完文件要退出重进。settings.json的改动同理。请求报 401 或超时回到第 2 节检查ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。Base URL 不要带/v1Key 不要带空格。如果本地怎么都调不通可以先用网页版模型对话确认账号状态排除是配置问题还是账号问题。8. 接下来怎么走配置体系搭起来之后日常使用中你会慢慢发现哪些规则该放CLAUDE.md、哪些该抽成 Skill。我的经验是先写CLAUDE.md用一两周把反复出现的多步骤操作抽成 Skill等 Skill 攒到五六个、需要在多个项目间复用时再考虑打包成 Plugin。如果你打算长期用 Claude Code 做开发可以了解一下 Coding Plan它在长会话和 Agent 场景下的额度更宽松适合把 Claude Code 当成日常编码助手来用的同学。接入文档在 https://taotoken.net/doc 里面有各语言的调用示例和常见问题配置上遇到卡点可以先翻这里。