你有没有遇到过这种情况——CLAUDE.md 写了 300 多行把团队的编码规范、命名规则、部署流程全塞进去了结果 Claude Code 执行的时候该忘还是忘。换个复杂点的任务它甚至开始自相矛盾。我之前也是这么干的。直到某天在 Anthropic 官方文档里看到一句话大意是「CLAUDE.md 只是 7 种自定义方式之一不是唯一的。」7 种我数了数自己用过的只有 CLAUDE.md 和.claude/commands/两种。剩下 5 种听都没听过。后来我花了一周把这 7 种方式全部摸透发现一个扎心的事实大多数人把所有规则一股脑塞进 CLAUDE.md就像把所有衣服扔进一个抽屉——看起来都在找的时候全乱。这篇文章不是再做一遍「7 种方式逐一介绍」的平铺结构——那种文章已经有不少了。我要做的是先给你 5 个真实场景让你对号入座再给你一个决策框架帮你以后自己判断最后逐一拆解每种方式的原理、用法和反模式。说白了「什么时候不该用」比「怎么用」更重要。先看 5 个场景你中了几个在讲「怎么用」之前先对号入座。以下 5 个场景如果你踩过任何一个说明你可能用错了方式。场景一CLAUDE.md 膨胀症你的 CLAUDE.md 已经超过 200 行。编码规范 50 行、架构说明 80 行、部署流程 60 行、各种零碎规则 40 行。每次开会后还要往里加。结果 Claude 的遵从率越来越低——它不是不想遵守是上下文窗口就那么大塞太多规则它根本「看不过来」。场景二每次都要手敲同一段指令每次让 Claude Code 做 Code Review你都要粘贴同一段话「按照我们团队的规范检查……重点关注这几个维度……输出格式是……」粘了 20 次之后你开始怀疑人生。场景三Claude 总是忘记「有些目录不能碰」你在 CLAUDE.md 里写了「不要修改 legacy/ 目录的代码」但 Claude 偶尔还是会手痒去改。不是它故意违规是 CLAUDE.md 的规则是「建议」性质的不是强制的。场景四需要 Claude 访问外部系统你想让 Claude 直接查 Jira 看 ticket 描述、查 Sentry 看线上报错、查数据库看表结构。但 Claude Code 原生不支持这些你只能手动复制粘贴。场景五复杂任务耗尽上下文一个大重构任务Claude 需要同时参考 10 个文件、跑测试、改代码。聊到一半发现上下文被压缩了之前讨论的架构决策全忘了。如果你中了 2 个以上接下来的内容对你很有价值。一张表7 种方式速览先给一张全局图后面逐一展开。方式一句话说明配置文件作用域强制力CLAUDE.md持久化指令每次会话自动加载CLAUDE.mdMarkdown组织/用户/项目/本地软上下文注入非强制Skills可复用工作流按需加载SKILL.md目录形式企业/个人/项目/插件软调用时才加载Hooks生命周期钩子硬性执行settings.jsonJSON组织/用户/项目/本地硬exit code 2 阻断Rules路径级条件规则.claude/rules/*.md项目级软CLAUDE.md 子系统Sub-agents专用子智能体隔离上下文.claude/agents/*.md组织/CLI/项目/用户硬工具限制生效MCP Servers连接外部工具和数据源.mcp.json/ CLI本地/项目/用户硬连接必须建立Settings全局配置权限、模型、环境变量settings.jsonJSON组织/用户/项目/本地硬客户端强制执行关键区分CLAUDE.md/Skills/Rules 是「建议」——Claude 会看到这些内容但可以自行判断是否遵守。Hooks/Sub-agents/MCP/Settings 是「规则」——违反就会被阻断或无法执行。图7 种自定义方式的强制力和作用域对比——「建议」和「规则」的本质区别决策框架该用哪个拿到一个自定义需求时按以下 3 个问题走决策树问题 1这条规则需要「每次会话都生效」还是「特定场景才需要」每次都要 → 问题 2A特定场景 → 问题 2B问题 2A规则是「告诉 Claude 怎么做」还是「强制 Claude 不能做某事」告诉怎么做 →CLAUDE.md编码规范、命名习惯、项目架构强制不能做 →Hooks禁止执行rm -rf、自动格式化或Settings权限 deny 规则问题 2B这个场景是「一个可复用的工作流」还是「连接外部工具」可复用工作流 →SkillsCode Review 流程、发布检查清单、文档生成连接外部工具 →MCP ServersJira、Sentry、数据库、Figma问题 3规则只适用于代码库的某个子目录吗是 →Rules.claude/rules/配合paths字段不是 → 回到问题 2A/2B额外判断需要隔离上下文、并行执行、限制工具权限 →Sub-agents需要配置模型、权限白名单、环境变量 →Settings快速自定义命令团队已有历史存量 →Commands.claude/commands/已合并入 Skills 生态用一句大白话总结CLAUDE.md 管「是什么」Skills 管「怎么做」Hooks 管「不能做」Rules 管「哪里适用」Sub-agents 管「谁来做」MCP 管「能连什么」Settings 管「全局开关」。“ 你目前用得最多的是哪种自定义方式A. 只用 CLAUDE.md所有规则都往里塞B. 用过 Skills 或 Commands但没深入配置C. Hooks / MCP / Sub-agents 都配过已经是进阶玩家D. 还没开始自定义Claude Code 开箱即用就够了评论区说说码哥猜选 A 的最多 图3 个问题走完决策树——拿到自定义需求时按这个流程选方式逐一拆解每种方式的原理 用法 反模式1. CLAUDE.md记忆系统原理CLAUDE.md 是 Claude Code 的「长期记忆」。每次会话启动时Claude 会自动加载这些文件的内容到上下文窗口。它不是一次性指令而是贯穿整个会话的持久化上下文。加载顺序从广到窄内容拼接而非覆盖组织级最高优先级macOS 在/Library/Application Support/ClaudeCode/CLAUDE.mdLinux 在/etc/claude-code/CLAUDE.md用户级~/.claude/CLAUDE.md项目级./CLAUDE.md或./.claude/CLAUDE.md本地个人级./CLAUDE.local.mdgitignore 掉不提交同一层级的CLAUDE.md和CLAUDE.local.md会拼接不会互相覆盖。子目录下的 CLAUDE.md 文件在 Claude 读取该目录文件时按需加载。支持path/to/file语法导入其他文件内容最多 4 层跳转。这个功能很实用——你可以把不同主题的规则拆成独立文件用引入避免单文件过大。用法示例# CLAUDE.md ## 项目架构 本项目是 Spring Boot 3.2 单体Java 17。 模块结构api/接口层、service/业务层、dao/数据层 ## 编码规范 - 使用 2 空格缩进 - 命名规范类名 PascalCase方法名 camelCase常量 UPPER_SNAKE_CASE - Controller 不放业务逻辑只做参数校验和路由 ## 构建与测试 - 构建./gradlew build - 测试./gradlew test - Lint./gradlew spotlessCheck ## 引入子规则 docs/database-conventions.md api/rest-standards.md反模式反模式 1文件超过 200 行CLAUDE.md 的内容每次会话都会注入上下文窗口。文件越大留给实际任务的上下文空间越小。超过 200 行之后Claude 的遵从率会明显下降——不是它不想遵守是注意力被稀释了。解法拆分。把长规则移到.claude/rules/里用paths字段做路径级匹配或用语法引入子文件。反模式 2写模糊指令# 差的写法 格式化代码保持风格统一。 # 好的写法 使用 2 空格缩进。行宽 120 字符。导入顺序java.* → javax.* → 第三方 → 本项目。Claude 不怕长指令怕模糊指令。「格式化代码」这种话它理解不了你具体要什么格式。反模式 3在 CLAUDE.md 里写流程步骤如果你发现自己在 CLAUDE.md 里写了「第一步做 X第二步做 Y第三步做 Z」——这不是 CLAUDE.md 该干的事。流程步骤应该用 Skills 封装按需调用不占日常上下文。2. Skills可复用工作流原理Skills 是 Claude Code 的「剧本」。把一个可重复执行的工作流打包成一个 Skill需要的时候调用不需要的时候不占上下文。这是和 CLAUDE.md 最关键的区别CLAUDE.md 的内容每次会话都在上下文里Skills 的内容只有被调用时才加载。Skill 的描述description会一直留在上下文中供 Claude 判断是否需要调用但完整内容按需加载。配置格式.claude/skills/ └── code-review/ └── SKILL.mdSKILL.md 由 YAML frontmatter Markdown body 组成--- name: code-review description: 按团队规范执行 Code Review检查安全、性能、可读性 when_to_use: 用户要求 review 代码或提交 PR 前 argument-hint: [file-or-pr] model: sonnet effort: high paths: [src/**/*.ts] allowed-tools: Read, Grep, Glob, Bash(git *) --- ## Code Review 清单 1. 安全检查SQL 注入、XSS、硬编码密钥 2. 性能检查N1 查询、大对象循环创建 3. 可读性方法不超过 30 行、命名自解释 $ARGUMENTS 指定要 review 的文件或 PR。几个实用的 frontmatter 字段context: fork— 在隔离的子智能体中运行不污染主对话上下文disable-model-invocation: true— 只能用户手动/skill-name调用Claude 不会自动触发user-invocable: false— 反过来只有 Claude 能自动调用用户不能手动触发model: haiku— 用更快更便宜的模型执行这个 Skill适合搜索、探索类任务动态上下文注入在 SKILL.md 中用!git diff HEAD语法Claude 看到内容前会先执行 shell 命令把输出注入上下文。这个功能非常强大——你可以让 Skill 在执行时自动获取当前 git 状态、最近的变更、测试结果等实时信息。反模式反模式 1把所有 Skill 都设成disable-model-invocation: true你可能觉得「我不想让 Claude 自动调用 Skill万一调错了怎么办」。但如果你全部禁用了自动调用Claude 永远不知道你有这些 Skill——description 虽然在上下文里但 Claude 判断「用户没明确要求我不应该自动调用」。结果就是你的 Skills 库变成了摆设。解法大部分 Skill 保持默认允许自动调用只对有副作用的 Skill如部署、删除设disable-model-invocation: true。反模式 2Skill body 太长Skill 的完整内容在调用后会留在上下文中。如果你写了一个 5000 token 的 Skill每次调用后这 5000 token 就一直占着上下文窗口。Compaction 之后会重新附加但有上限单个 Skill 最多 5000 token总计 25000 token。解法把参考材料放在 Skill 目录的辅助文件里SKILL.md 只放核心流程。用references/xxx.md引入。反模式 3用context: fork跑纯指南类 Skillcontext: fork会创建一个隔离的子智能体来执行 Skill。如果你的 Skill 只是「告诉 Claude 某些规范」而不是「让 Claude 执行一系列操作」fork 出来的子智能体会拿到指南但没有明确的执行 prompt效果反而不如不 fork。3. Hooks生命周期钩子原理Hooks 是 Claude Code 的「自动执行器」。它在特定生命周期事件发生时自动运行你配置的脚本、HTTP 请求、甚至 LLM 提示。和 CLAUDE.md 最大的区别Hooks 是强制执行的——exit code 2 会直接阻断操作不是建议。配置位置settings.json的hooks字段用户级或项目级。支持 30 种事件最常用的几种事件触发时机典型用途PreToolUse工具执行前阻止危险命令、安全校验PostToolUse工具执行后自动格式化、自动 lintSessionStart会话初始化加载环境变量、检查依赖StopClaude 完成回复后发送通知、记录日志UserPromptSubmit用户输入后输入预处理、关键词替换5 种 Hook 类型commandShell 命令、httpPOST 请求、mcp_tool调用 MCP 工具、prompt单轮 LLM 评估、agent子智能体评估。用法示例在文件编辑后自动运行 Prettier 格式化{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx prettier --write, args: [${CLAUDE_FILE_PATH}], timeout: 30 } ] } ] } }exit code 的含义这是最容易搞错的exit 0成功继续执行exit 1非阻断性错误记录日志不影响主流程exit 2阻断性错误直接阻止操作反模式反模式 1用 exit 1 以为能阻止操作这是最常见的误解。你在 Hook 脚本里检测到危险命令exit 1退出——结果 Claude 照样执行了。原因很简单exit 1 只是非阻断性错误Claude 收到一个「Hook 报了个错」的提示但它可以选择忽略。解法要阻止操作必须exit 2。或者在 stdout 输出 JSON{decision: block, reason: 不允许执行 rm -rf}。反模式 2不加if过滤器每个工具调用都触发 Hook{ matcher: *, hooks: [{ type: command, command: my-script.sh }] }这会每次工具调用都 spawn 一个新进程。Claude 一次对话可能调用几十次工具你的脚本就跑几十次。轻则浪费时间重则拖慢整个对话。解法用matcher精确匹配工具名如Bash、Edit|Write用if字段进一步缩小范围如if: Bash(rm *)。反模式 3在 Hook 里做复杂逻辑Hook 的设计初衷是「短平快」的自动化操作。如果你发现自己在 Hook 脚本里写了 200 行 Python——停下来这应该是 Skills 或 Sub-agents 干的事。4. Rules路径级规则原理Rules 是 CLAUDE.md 系统的子功能解决一个具体问题不同目录需要不同的规则。在单体仓库monorepo里前端目录和后端目录的编码规范可能完全不同。用一个 CLAUDE.md 写两套规则会很混乱。Rules 允许你为不同路径配置不同规则只有 Claude 访问到对应目录时才加载。配置方式在.claude/rules/目录下创建.md文件用 YAML frontmatter 的paths字段指定适用路径。--- paths: [src/api/**, tests/api/**] --- ## API 层规范 - Controller 方法必须有 Validated 注解 - 返回值统一用 ResponseEntity 包装 - 异常用 RestControllerAdvice 全局处理--- paths: [src/dao/**, resources/mapper/**] --- ## 数据层规范 - 禁止在 DAO 层拼接 SQL必须用 MyBatis XML - 分页用 PageHelper不要手写 LIMIT反模式反模式 1Rules 和 CLAUDE.md 写了重复甚至矛盾的规则Rules 在 CLAUDE.md 之后追加加载如果两边写了矛盾的内容Claude 的行为会不可预测。解法CLAUDE.md 只写全局规则Rules 写路径特化规则。全局和局部不要有交集。反模式 2paths写得太宽泛paths: [**]等于没写——这和直接放 CLAUDE.md 里没区别。Rules 的价值就在于精准匹配。5. Sub-agents子智能体原理Sub-agents 是 Claude Code 的「分身术」。当你有一个复杂任务时可以创建一个专用的子智能体来处理。它有自己独立的上下文窗口不会污染主对话。执行完毕后把结果返回主智能体。核心价值上下文隔离子智能体的执行过程不会撑大主对话的上下文工具限制可以限制子智能体只能用 Read/Grep 等只读工具防止它乱改代码并行执行多个子智能体可以同时跑最多 5 层嵌套深度模型路由可以让探索任务用便宜快速的 Haiku深度任务用 Sonnet/Opus配置方式在.claude/agents/目录下创建.md文件。--- name: code-reviewer description: 审查代码质量、安全性和最佳实践 tools: Read, Glob, Grep, Bash disallowedTools: Write, Edit model: sonnet maxTurns: 50 isolation: worktree --- 你是一个代码审查专家。分析代码并提供具体、可执行的反馈。 重点关注安全性、性能、可维护性。三种调用方式自然语言在对话中描述任务Claude 自行判断是否委派给子智能体提及code-reviewer 看看 auth 模块的改动保证运行一次会话级--agent code-reviewer整个会话使用该子智能体内置子智能体不需要你创建ExploreHaiku 模型只读用于快速搜索和探索跳过 CLAUDE.md 和 git status 加载速度最快Plan继承当前模型只读用于规划和研究general-purpose所有工具用于复杂多步任务反模式反模式 1description 字段写得太模糊# 差的写法 description: 帮我处理一些任务 # 好的写法 description: 审查 TypeScript 代码的质量、安全性和性能问题输出结构化的 review 意见Claude 靠 description 判断什么时候该委派任务给这个子智能体。写得模糊它就不知道什么时候用。反模式 2复制内置子智能体的功能你不需要创建一个「explorer」子智能体来做搜索——内置的 Explore 已经做了而且用了更便宜的 Haiku 模型。自定义子智能体应该做内置子智能体做不了的事。反模式 3子智能体嵌套太深子智能体可以生成子智能体最多 5 层。但每多一层就多一个上下文窗口的开销。除非确实需要否则 1-2 层就够了。6. MCP Servers外部工具连接原理MCPModel Context Protocol是 Anthropic 推出的开放协议让 Claude Code 能连接外部工具、数据库和 API。它解决了 Claude Code 原生「只能操作本地文件和终端」的限制。有了 MCP ServerClaude 可以直接查 Jira ticket、查 Sentry 报错、查数据库表结构、操作 Figma 设计稿——不需要你手动复制粘贴。配置方式CLI 方式推荐一行命令搞定# 远程 HTTP 服务 claude mcp add --transport http notion https://mcp.notion.com/mcp # 本地 stdio 进程 claude mcp add --transport stdio airtable -- npx -y airtable-mcp-serverJSON 方式.mcp.json可提交到仓库共享给团队{ mcpServers: { github: { type: http, url: https://api.githubcopilot.com/mcp/, headers: { Authorization: Bearer ${GITHUB_TOKEN} } }, database: { command: /path/to/db-server, args: [--config, config.json], env: { DB_URL: ${DB_URL} } } } }三种传输协议http推荐适合远程服务自动重连支持 OAuthstdio适合本地进程Claude 启动子进程通信wsWebSocket适合需要推送事件的场景反模式反模式 1在.mcp.json里硬编码 API Key// 千万别这么写 headers: { Authorization: Bearer sk-xxxxx } // 用环境变量 headers: { Authorization: Bearer ${GITHUB_TOKEN} }.mcp.json通常会提交到 Git 仓库。硬编码的密钥会被所有 clone 仓库的人看到。反模式 2不信任远程 MCP Server 的安全性MCP Server 本质上是给 Claude 注入外部数据和工具。如果远程 Server 被攻击者控制它可以往 Claude 的上下文里注入恶意指令prompt injection。企业环境里用allowedMcpServers/deniedMcpServers做白名单控制。反模式 3用 SSE 传输已废弃SSEServer-Sent Events已经被标记为 deprecated官方推荐用http替代。如果你在文档里看到 SSE 的配置示例直接换成 http。7. Settings配置系统原理Settings 是 Claude Code 的「控制面板」。它管理全局行为权限规则、模型选择、环境变量、UI 偏好等。配置层级优先级从高到低组织级managed settings管理员配置个人无法覆盖CLI 参数命令行传入临时生效本地项目级.claude/settings.local.jsongitignore项目级.claude/settings.json提交到仓库用户级~/.claude/settings.json最广优先级最低权限规则的特殊合并逻辑其他设置是「高优先级覆盖低优先级」但权限规则是跨层级合并的。也就是说项目级的allow规则和用户级的allow规则会合并在一起不会互相覆盖。用法示例{ $schema: https://json.schemastore.org/claude-code-settings.json, permissions: { allow: [ Bash(npm run lint), Bash(npm run test *), Read(~/.zshrc) ], deny: [ Bash(curl *), Read(./.env), Read(./secrets/**) ] }, model: claude-sonnet-4-6, language: chinese, autoCompactEnabled: true }反模式反模式 1直接编辑~/.claude.json这个文件是 Claude Code 内部管理的手动编辑可能导致不可预期的行为。用户级设置应该改~/.claude/settings.json。反模式 2不用$schema做校验Settings 是 JSON 格式少一个逗号就解析失败。加上$schema字段后编辑器会自动校验字段名和类型提前发现错误。反模式 3在 Settings 里写行为指令Settings 管的是「配置」——权限、模型、环境变量。如果你在 settings.json 里写了「请使用 2 空格缩进」这种行为指令它不会生效。行为指令应该放 CLAUDE.md。实战组合一个真实项目的配置光讲理论不够给一个我实际在用的项目配置结构my-project/ ├── CLAUDE.md # 全局规则 100 行 ├── .claude/ │ ├── settings.json # 权限规则 Hooks │ ├── rules/ │ │ ├── api-rules.md # API 层专用规则 │ │ └── dao-rules.md # 数据层专用规则 │ ├── skills/ │ │ ├── code-review/ │ │ │ └── SKILL.md # Code Review 工作流 │ │ └── deploy-check/ │ │ └── SKILL.md # 部署前检查清单 │ ├── agents/ │ │ └── security-auditor.md # 安全审计子智能体 │ └── mcp.json # MCP Server 配置 └── .claude/settings.local.json # 本地个人覆盖gitignoreCLAUDE.md 里只放全局的、简短的规则 100 行。路径特化的规则拆到rules/里。可复用的工作流拆到skills/里。需要隔离执行的任务用agents/处理。外部工具用mcp.json连接。权限和 Hooks 放settings.json。这样每个文件各司其职不会出现一个 500 行的 CLAUDE.md 把所有东西塞在一起的情况。常见问题Q: CLAUDE.md 和.claude/CLAUDE.md有什么区别放哪个位置更好A: 两个位置都会被加载效果一样。区别在于文件系统的位置项目根目录的CLAUDE.md更显眼.claude/CLAUDE.md更整洁不污染根目录。如果你的项目根目录已经有 README.md、package.json 等一堆文件建议放.claude/CLAUDE.md。两种都行选一个团队统一就好。Q: Skills 和.claude/commands/是什么关系我之前的 commands 还能用吗A: Skills 是 commands 的升级版。Anthropic 已经把两者统一了——commands 文件仍然有效但新功能如context: fork、paths匹配、辅助文件只在 Skills 里支持。如果你已有 commands不需要迁移它们会继续工作。但新的自定义命令建议用 Skills。Q: Hooks 和 CLAUDE.md 的规则有什么本质区别A:CLAUDE.md 是「建议」Hooks 是「规则」。CLAUDE.md 写「不要修改 legacy/ 目录」Claude 会尽量遵守但偶尔可能违反。Hook 配置PreToolUse检测到对legacy/目录的写操作时返回 exit 2操作会被直接阻断——Claude 根本没有机会违反。如果你的规则必须被严格遵守安全、合规、防误操作用 Hooks。如果是编码风格、偏好建议用 CLAUDE.md。Q: 我需要为每个项目都配置 MCP Server 吗A: 不一定。MCP Server 有三个作用域本地.mcp.json在项目目录只对当前项目生效、项目.mcp.json提交到仓库团队共享、用户~/.claude.json配置所有项目通用。像 GitHub MCP 这种通用的放用户级项目特定的数据库 Server放项目级。Q: 7 种方式会不会互相冲突A: 会最常见的冲突有两种。一是 CLAUDE.md 和 Rules 写了矛盾的内容——解法是 CLAUDE.md 只写全局规则Rules 写路径特化规则不重叠。二是 Hooks 和 Settings 的权限规则冲突——Hooks 在 settings.json 里配置如果项目级 Hook 阻止了某个操作但用户级 Settings 的 allow 规则放行了结果取决于合并逻辑。建议团队统一在一个层级配置不要分散。图每种方式最常见的反模式——踩过才知道为什么不能这么干说到底Claude Code 的 7 种自定义方式不是「哪个更好」的问题是「什么场景用什么」的问题。把所有规则塞进 CLAUDE.md就像把所有衣服扔进一个抽屉——你当然能塞进去但找的时候全乱。拆开来各司其职Claude 的表现会好很多。这篇文章把每种方式的原理、用法和反模式都拆了一遍但最核心的其实是那个决策框架——下次遇到自定义需求先问自己三个问题答案自然就出来了。下一篇打算拆 Claude Code 的 Hooks 实战——30 多种事件怎么选、5 种 hook 类型怎么搭配、真实的自动化工作流怎么搭。感兴趣的关注一下说实话公众号算法越来越不按常理出牌了把码哥字节设为星标至少保证你能收到更新不会错过。如果你身边有同事在用 Claude Code 但还没搞清楚这些配置方式这篇可以直接甩给他省他踩一遍。如果这篇对你有帮助转发给你的程序员朋友— 大家都在摸索 Claude Code 的正确用法你的分享可能帮他省很多时间。
Claude Code 里的 7 种自定义方式，90% 的人只用了 CLAUDE.md 一种
你有没有遇到过这种情况——CLAUDE.md 写了 300 多行把团队的编码规范、命名规则、部署流程全塞进去了结果 Claude Code 执行的时候该忘还是忘。换个复杂点的任务它甚至开始自相矛盾。我之前也是这么干的。直到某天在 Anthropic 官方文档里看到一句话大意是「CLAUDE.md 只是 7 种自定义方式之一不是唯一的。」7 种我数了数自己用过的只有 CLAUDE.md 和.claude/commands/两种。剩下 5 种听都没听过。后来我花了一周把这 7 种方式全部摸透发现一个扎心的事实大多数人把所有规则一股脑塞进 CLAUDE.md就像把所有衣服扔进一个抽屉——看起来都在找的时候全乱。这篇文章不是再做一遍「7 种方式逐一介绍」的平铺结构——那种文章已经有不少了。我要做的是先给你 5 个真实场景让你对号入座再给你一个决策框架帮你以后自己判断最后逐一拆解每种方式的原理、用法和反模式。说白了「什么时候不该用」比「怎么用」更重要。先看 5 个场景你中了几个在讲「怎么用」之前先对号入座。以下 5 个场景如果你踩过任何一个说明你可能用错了方式。场景一CLAUDE.md 膨胀症你的 CLAUDE.md 已经超过 200 行。编码规范 50 行、架构说明 80 行、部署流程 60 行、各种零碎规则 40 行。每次开会后还要往里加。结果 Claude 的遵从率越来越低——它不是不想遵守是上下文窗口就那么大塞太多规则它根本「看不过来」。场景二每次都要手敲同一段指令每次让 Claude Code 做 Code Review你都要粘贴同一段话「按照我们团队的规范检查……重点关注这几个维度……输出格式是……」粘了 20 次之后你开始怀疑人生。场景三Claude 总是忘记「有些目录不能碰」你在 CLAUDE.md 里写了「不要修改 legacy/ 目录的代码」但 Claude 偶尔还是会手痒去改。不是它故意违规是 CLAUDE.md 的规则是「建议」性质的不是强制的。场景四需要 Claude 访问外部系统你想让 Claude 直接查 Jira 看 ticket 描述、查 Sentry 看线上报错、查数据库看表结构。但 Claude Code 原生不支持这些你只能手动复制粘贴。场景五复杂任务耗尽上下文一个大重构任务Claude 需要同时参考 10 个文件、跑测试、改代码。聊到一半发现上下文被压缩了之前讨论的架构决策全忘了。如果你中了 2 个以上接下来的内容对你很有价值。一张表7 种方式速览先给一张全局图后面逐一展开。方式一句话说明配置文件作用域强制力CLAUDE.md持久化指令每次会话自动加载CLAUDE.mdMarkdown组织/用户/项目/本地软上下文注入非强制Skills可复用工作流按需加载SKILL.md目录形式企业/个人/项目/插件软调用时才加载Hooks生命周期钩子硬性执行settings.jsonJSON组织/用户/项目/本地硬exit code 2 阻断Rules路径级条件规则.claude/rules/*.md项目级软CLAUDE.md 子系统Sub-agents专用子智能体隔离上下文.claude/agents/*.md组织/CLI/项目/用户硬工具限制生效MCP Servers连接外部工具和数据源.mcp.json/ CLI本地/项目/用户硬连接必须建立Settings全局配置权限、模型、环境变量settings.jsonJSON组织/用户/项目/本地硬客户端强制执行关键区分CLAUDE.md/Skills/Rules 是「建议」——Claude 会看到这些内容但可以自行判断是否遵守。Hooks/Sub-agents/MCP/Settings 是「规则」——违反就会被阻断或无法执行。图7 种自定义方式的强制力和作用域对比——「建议」和「规则」的本质区别决策框架该用哪个拿到一个自定义需求时按以下 3 个问题走决策树问题 1这条规则需要「每次会话都生效」还是「特定场景才需要」每次都要 → 问题 2A特定场景 → 问题 2B问题 2A规则是「告诉 Claude 怎么做」还是「强制 Claude 不能做某事」告诉怎么做 →CLAUDE.md编码规范、命名习惯、项目架构强制不能做 →Hooks禁止执行rm -rf、自动格式化或Settings权限 deny 规则问题 2B这个场景是「一个可复用的工作流」还是「连接外部工具」可复用工作流 →SkillsCode Review 流程、发布检查清单、文档生成连接外部工具 →MCP ServersJira、Sentry、数据库、Figma问题 3规则只适用于代码库的某个子目录吗是 →Rules.claude/rules/配合paths字段不是 → 回到问题 2A/2B额外判断需要隔离上下文、并行执行、限制工具权限 →Sub-agents需要配置模型、权限白名单、环境变量 →Settings快速自定义命令团队已有历史存量 →Commands.claude/commands/已合并入 Skills 生态用一句大白话总结CLAUDE.md 管「是什么」Skills 管「怎么做」Hooks 管「不能做」Rules 管「哪里适用」Sub-agents 管「谁来做」MCP 管「能连什么」Settings 管「全局开关」。“ 你目前用得最多的是哪种自定义方式A. 只用 CLAUDE.md所有规则都往里塞B. 用过 Skills 或 Commands但没深入配置C. Hooks / MCP / Sub-agents 都配过已经是进阶玩家D. 还没开始自定义Claude Code 开箱即用就够了评论区说说码哥猜选 A 的最多 图3 个问题走完决策树——拿到自定义需求时按这个流程选方式逐一拆解每种方式的原理 用法 反模式1. CLAUDE.md记忆系统原理CLAUDE.md 是 Claude Code 的「长期记忆」。每次会话启动时Claude 会自动加载这些文件的内容到上下文窗口。它不是一次性指令而是贯穿整个会话的持久化上下文。加载顺序从广到窄内容拼接而非覆盖组织级最高优先级macOS 在/Library/Application Support/ClaudeCode/CLAUDE.mdLinux 在/etc/claude-code/CLAUDE.md用户级~/.claude/CLAUDE.md项目级./CLAUDE.md或./.claude/CLAUDE.md本地个人级./CLAUDE.local.mdgitignore 掉不提交同一层级的CLAUDE.md和CLAUDE.local.md会拼接不会互相覆盖。子目录下的 CLAUDE.md 文件在 Claude 读取该目录文件时按需加载。支持path/to/file语法导入其他文件内容最多 4 层跳转。这个功能很实用——你可以把不同主题的规则拆成独立文件用引入避免单文件过大。用法示例# CLAUDE.md ## 项目架构 本项目是 Spring Boot 3.2 单体Java 17。 模块结构api/接口层、service/业务层、dao/数据层 ## 编码规范 - 使用 2 空格缩进 - 命名规范类名 PascalCase方法名 camelCase常量 UPPER_SNAKE_CASE - Controller 不放业务逻辑只做参数校验和路由 ## 构建与测试 - 构建./gradlew build - 测试./gradlew test - Lint./gradlew spotlessCheck ## 引入子规则 docs/database-conventions.md api/rest-standards.md反模式反模式 1文件超过 200 行CLAUDE.md 的内容每次会话都会注入上下文窗口。文件越大留给实际任务的上下文空间越小。超过 200 行之后Claude 的遵从率会明显下降——不是它不想遵守是注意力被稀释了。解法拆分。把长规则移到.claude/rules/里用paths字段做路径级匹配或用语法引入子文件。反模式 2写模糊指令# 差的写法 格式化代码保持风格统一。 # 好的写法 使用 2 空格缩进。行宽 120 字符。导入顺序java.* → javax.* → 第三方 → 本项目。Claude 不怕长指令怕模糊指令。「格式化代码」这种话它理解不了你具体要什么格式。反模式 3在 CLAUDE.md 里写流程步骤如果你发现自己在 CLAUDE.md 里写了「第一步做 X第二步做 Y第三步做 Z」——这不是 CLAUDE.md 该干的事。流程步骤应该用 Skills 封装按需调用不占日常上下文。2. Skills可复用工作流原理Skills 是 Claude Code 的「剧本」。把一个可重复执行的工作流打包成一个 Skill需要的时候调用不需要的时候不占上下文。这是和 CLAUDE.md 最关键的区别CLAUDE.md 的内容每次会话都在上下文里Skills 的内容只有被调用时才加载。Skill 的描述description会一直留在上下文中供 Claude 判断是否需要调用但完整内容按需加载。配置格式.claude/skills/ └── code-review/ └── SKILL.mdSKILL.md 由 YAML frontmatter Markdown body 组成--- name: code-review description: 按团队规范执行 Code Review检查安全、性能、可读性 when_to_use: 用户要求 review 代码或提交 PR 前 argument-hint: [file-or-pr] model: sonnet effort: high paths: [src/**/*.ts] allowed-tools: Read, Grep, Glob, Bash(git *) --- ## Code Review 清单 1. 安全检查SQL 注入、XSS、硬编码密钥 2. 性能检查N1 查询、大对象循环创建 3. 可读性方法不超过 30 行、命名自解释 $ARGUMENTS 指定要 review 的文件或 PR。几个实用的 frontmatter 字段context: fork— 在隔离的子智能体中运行不污染主对话上下文disable-model-invocation: true— 只能用户手动/skill-name调用Claude 不会自动触发user-invocable: false— 反过来只有 Claude 能自动调用用户不能手动触发model: haiku— 用更快更便宜的模型执行这个 Skill适合搜索、探索类任务动态上下文注入在 SKILL.md 中用!git diff HEAD语法Claude 看到内容前会先执行 shell 命令把输出注入上下文。这个功能非常强大——你可以让 Skill 在执行时自动获取当前 git 状态、最近的变更、测试结果等实时信息。反模式反模式 1把所有 Skill 都设成disable-model-invocation: true你可能觉得「我不想让 Claude 自动调用 Skill万一调错了怎么办」。但如果你全部禁用了自动调用Claude 永远不知道你有这些 Skill——description 虽然在上下文里但 Claude 判断「用户没明确要求我不应该自动调用」。结果就是你的 Skills 库变成了摆设。解法大部分 Skill 保持默认允许自动调用只对有副作用的 Skill如部署、删除设disable-model-invocation: true。反模式 2Skill body 太长Skill 的完整内容在调用后会留在上下文中。如果你写了一个 5000 token 的 Skill每次调用后这 5000 token 就一直占着上下文窗口。Compaction 之后会重新附加但有上限单个 Skill 最多 5000 token总计 25000 token。解法把参考材料放在 Skill 目录的辅助文件里SKILL.md 只放核心流程。用references/xxx.md引入。反模式 3用context: fork跑纯指南类 Skillcontext: fork会创建一个隔离的子智能体来执行 Skill。如果你的 Skill 只是「告诉 Claude 某些规范」而不是「让 Claude 执行一系列操作」fork 出来的子智能体会拿到指南但没有明确的执行 prompt效果反而不如不 fork。3. Hooks生命周期钩子原理Hooks 是 Claude Code 的「自动执行器」。它在特定生命周期事件发生时自动运行你配置的脚本、HTTP 请求、甚至 LLM 提示。和 CLAUDE.md 最大的区别Hooks 是强制执行的——exit code 2 会直接阻断操作不是建议。配置位置settings.json的hooks字段用户级或项目级。支持 30 种事件最常用的几种事件触发时机典型用途PreToolUse工具执行前阻止危险命令、安全校验PostToolUse工具执行后自动格式化、自动 lintSessionStart会话初始化加载环境变量、检查依赖StopClaude 完成回复后发送通知、记录日志UserPromptSubmit用户输入后输入预处理、关键词替换5 种 Hook 类型commandShell 命令、httpPOST 请求、mcp_tool调用 MCP 工具、prompt单轮 LLM 评估、agent子智能体评估。用法示例在文件编辑后自动运行 Prettier 格式化{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx prettier --write, args: [${CLAUDE_FILE_PATH}], timeout: 30 } ] } ] } }exit code 的含义这是最容易搞错的exit 0成功继续执行exit 1非阻断性错误记录日志不影响主流程exit 2阻断性错误直接阻止操作反模式反模式 1用 exit 1 以为能阻止操作这是最常见的误解。你在 Hook 脚本里检测到危险命令exit 1退出——结果 Claude 照样执行了。原因很简单exit 1 只是非阻断性错误Claude 收到一个「Hook 报了个错」的提示但它可以选择忽略。解法要阻止操作必须exit 2。或者在 stdout 输出 JSON{decision: block, reason: 不允许执行 rm -rf}。反模式 2不加if过滤器每个工具调用都触发 Hook{ matcher: *, hooks: [{ type: command, command: my-script.sh }] }这会每次工具调用都 spawn 一个新进程。Claude 一次对话可能调用几十次工具你的脚本就跑几十次。轻则浪费时间重则拖慢整个对话。解法用matcher精确匹配工具名如Bash、Edit|Write用if字段进一步缩小范围如if: Bash(rm *)。反模式 3在 Hook 里做复杂逻辑Hook 的设计初衷是「短平快」的自动化操作。如果你发现自己在 Hook 脚本里写了 200 行 Python——停下来这应该是 Skills 或 Sub-agents 干的事。4. Rules路径级规则原理Rules 是 CLAUDE.md 系统的子功能解决一个具体问题不同目录需要不同的规则。在单体仓库monorepo里前端目录和后端目录的编码规范可能完全不同。用一个 CLAUDE.md 写两套规则会很混乱。Rules 允许你为不同路径配置不同规则只有 Claude 访问到对应目录时才加载。配置方式在.claude/rules/目录下创建.md文件用 YAML frontmatter 的paths字段指定适用路径。--- paths: [src/api/**, tests/api/**] --- ## API 层规范 - Controller 方法必须有 Validated 注解 - 返回值统一用 ResponseEntity 包装 - 异常用 RestControllerAdvice 全局处理--- paths: [src/dao/**, resources/mapper/**] --- ## 数据层规范 - 禁止在 DAO 层拼接 SQL必须用 MyBatis XML - 分页用 PageHelper不要手写 LIMIT反模式反模式 1Rules 和 CLAUDE.md 写了重复甚至矛盾的规则Rules 在 CLAUDE.md 之后追加加载如果两边写了矛盾的内容Claude 的行为会不可预测。解法CLAUDE.md 只写全局规则Rules 写路径特化规则。全局和局部不要有交集。反模式 2paths写得太宽泛paths: [**]等于没写——这和直接放 CLAUDE.md 里没区别。Rules 的价值就在于精准匹配。5. Sub-agents子智能体原理Sub-agents 是 Claude Code 的「分身术」。当你有一个复杂任务时可以创建一个专用的子智能体来处理。它有自己独立的上下文窗口不会污染主对话。执行完毕后把结果返回主智能体。核心价值上下文隔离子智能体的执行过程不会撑大主对话的上下文工具限制可以限制子智能体只能用 Read/Grep 等只读工具防止它乱改代码并行执行多个子智能体可以同时跑最多 5 层嵌套深度模型路由可以让探索任务用便宜快速的 Haiku深度任务用 Sonnet/Opus配置方式在.claude/agents/目录下创建.md文件。--- name: code-reviewer description: 审查代码质量、安全性和最佳实践 tools: Read, Glob, Grep, Bash disallowedTools: Write, Edit model: sonnet maxTurns: 50 isolation: worktree --- 你是一个代码审查专家。分析代码并提供具体、可执行的反馈。 重点关注安全性、性能、可维护性。三种调用方式自然语言在对话中描述任务Claude 自行判断是否委派给子智能体提及code-reviewer 看看 auth 模块的改动保证运行一次会话级--agent code-reviewer整个会话使用该子智能体内置子智能体不需要你创建ExploreHaiku 模型只读用于快速搜索和探索跳过 CLAUDE.md 和 git status 加载速度最快Plan继承当前模型只读用于规划和研究general-purpose所有工具用于复杂多步任务反模式反模式 1description 字段写得太模糊# 差的写法 description: 帮我处理一些任务 # 好的写法 description: 审查 TypeScript 代码的质量、安全性和性能问题输出结构化的 review 意见Claude 靠 description 判断什么时候该委派任务给这个子智能体。写得模糊它就不知道什么时候用。反模式 2复制内置子智能体的功能你不需要创建一个「explorer」子智能体来做搜索——内置的 Explore 已经做了而且用了更便宜的 Haiku 模型。自定义子智能体应该做内置子智能体做不了的事。反模式 3子智能体嵌套太深子智能体可以生成子智能体最多 5 层。但每多一层就多一个上下文窗口的开销。除非确实需要否则 1-2 层就够了。6. MCP Servers外部工具连接原理MCPModel Context Protocol是 Anthropic 推出的开放协议让 Claude Code 能连接外部工具、数据库和 API。它解决了 Claude Code 原生「只能操作本地文件和终端」的限制。有了 MCP ServerClaude 可以直接查 Jira ticket、查 Sentry 报错、查数据库表结构、操作 Figma 设计稿——不需要你手动复制粘贴。配置方式CLI 方式推荐一行命令搞定# 远程 HTTP 服务 claude mcp add --transport http notion https://mcp.notion.com/mcp # 本地 stdio 进程 claude mcp add --transport stdio airtable -- npx -y airtable-mcp-serverJSON 方式.mcp.json可提交到仓库共享给团队{ mcpServers: { github: { type: http, url: https://api.githubcopilot.com/mcp/, headers: { Authorization: Bearer ${GITHUB_TOKEN} } }, database: { command: /path/to/db-server, args: [--config, config.json], env: { DB_URL: ${DB_URL} } } } }三种传输协议http推荐适合远程服务自动重连支持 OAuthstdio适合本地进程Claude 启动子进程通信wsWebSocket适合需要推送事件的场景反模式反模式 1在.mcp.json里硬编码 API Key// 千万别这么写 headers: { Authorization: Bearer sk-xxxxx } // 用环境变量 headers: { Authorization: Bearer ${GITHUB_TOKEN} }.mcp.json通常会提交到 Git 仓库。硬编码的密钥会被所有 clone 仓库的人看到。反模式 2不信任远程 MCP Server 的安全性MCP Server 本质上是给 Claude 注入外部数据和工具。如果远程 Server 被攻击者控制它可以往 Claude 的上下文里注入恶意指令prompt injection。企业环境里用allowedMcpServers/deniedMcpServers做白名单控制。反模式 3用 SSE 传输已废弃SSEServer-Sent Events已经被标记为 deprecated官方推荐用http替代。如果你在文档里看到 SSE 的配置示例直接换成 http。7. Settings配置系统原理Settings 是 Claude Code 的「控制面板」。它管理全局行为权限规则、模型选择、环境变量、UI 偏好等。配置层级优先级从高到低组织级managed settings管理员配置个人无法覆盖CLI 参数命令行传入临时生效本地项目级.claude/settings.local.jsongitignore项目级.claude/settings.json提交到仓库用户级~/.claude/settings.json最广优先级最低权限规则的特殊合并逻辑其他设置是「高优先级覆盖低优先级」但权限规则是跨层级合并的。也就是说项目级的allow规则和用户级的allow规则会合并在一起不会互相覆盖。用法示例{ $schema: https://json.schemastore.org/claude-code-settings.json, permissions: { allow: [ Bash(npm run lint), Bash(npm run test *), Read(~/.zshrc) ], deny: [ Bash(curl *), Read(./.env), Read(./secrets/**) ] }, model: claude-sonnet-4-6, language: chinese, autoCompactEnabled: true }反模式反模式 1直接编辑~/.claude.json这个文件是 Claude Code 内部管理的手动编辑可能导致不可预期的行为。用户级设置应该改~/.claude/settings.json。反模式 2不用$schema做校验Settings 是 JSON 格式少一个逗号就解析失败。加上$schema字段后编辑器会自动校验字段名和类型提前发现错误。反模式 3在 Settings 里写行为指令Settings 管的是「配置」——权限、模型、环境变量。如果你在 settings.json 里写了「请使用 2 空格缩进」这种行为指令它不会生效。行为指令应该放 CLAUDE.md。实战组合一个真实项目的配置光讲理论不够给一个我实际在用的项目配置结构my-project/ ├── CLAUDE.md # 全局规则 100 行 ├── .claude/ │ ├── settings.json # 权限规则 Hooks │ ├── rules/ │ │ ├── api-rules.md # API 层专用规则 │ │ └── dao-rules.md # 数据层专用规则 │ ├── skills/ │ │ ├── code-review/ │ │ │ └── SKILL.md # Code Review 工作流 │ │ └── deploy-check/ │ │ └── SKILL.md # 部署前检查清单 │ ├── agents/ │ │ └── security-auditor.md # 安全审计子智能体 │ └── mcp.json # MCP Server 配置 └── .claude/settings.local.json # 本地个人覆盖gitignoreCLAUDE.md 里只放全局的、简短的规则 100 行。路径特化的规则拆到rules/里。可复用的工作流拆到skills/里。需要隔离执行的任务用agents/处理。外部工具用mcp.json连接。权限和 Hooks 放settings.json。这样每个文件各司其职不会出现一个 500 行的 CLAUDE.md 把所有东西塞在一起的情况。常见问题Q: CLAUDE.md 和.claude/CLAUDE.md有什么区别放哪个位置更好A: 两个位置都会被加载效果一样。区别在于文件系统的位置项目根目录的CLAUDE.md更显眼.claude/CLAUDE.md更整洁不污染根目录。如果你的项目根目录已经有 README.md、package.json 等一堆文件建议放.claude/CLAUDE.md。两种都行选一个团队统一就好。Q: Skills 和.claude/commands/是什么关系我之前的 commands 还能用吗A: Skills 是 commands 的升级版。Anthropic 已经把两者统一了——commands 文件仍然有效但新功能如context: fork、paths匹配、辅助文件只在 Skills 里支持。如果你已有 commands不需要迁移它们会继续工作。但新的自定义命令建议用 Skills。Q: Hooks 和 CLAUDE.md 的规则有什么本质区别A:CLAUDE.md 是「建议」Hooks 是「规则」。CLAUDE.md 写「不要修改 legacy/ 目录」Claude 会尽量遵守但偶尔可能违反。Hook 配置PreToolUse检测到对legacy/目录的写操作时返回 exit 2操作会被直接阻断——Claude 根本没有机会违反。如果你的规则必须被严格遵守安全、合规、防误操作用 Hooks。如果是编码风格、偏好建议用 CLAUDE.md。Q: 我需要为每个项目都配置 MCP Server 吗A: 不一定。MCP Server 有三个作用域本地.mcp.json在项目目录只对当前项目生效、项目.mcp.json提交到仓库团队共享、用户~/.claude.json配置所有项目通用。像 GitHub MCP 这种通用的放用户级项目特定的数据库 Server放项目级。Q: 7 种方式会不会互相冲突A: 会最常见的冲突有两种。一是 CLAUDE.md 和 Rules 写了矛盾的内容——解法是 CLAUDE.md 只写全局规则Rules 写路径特化规则不重叠。二是 Hooks 和 Settings 的权限规则冲突——Hooks 在 settings.json 里配置如果项目级 Hook 阻止了某个操作但用户级 Settings 的 allow 规则放行了结果取决于合并逻辑。建议团队统一在一个层级配置不要分散。图每种方式最常见的反模式——踩过才知道为什么不能这么干说到底Claude Code 的 7 种自定义方式不是「哪个更好」的问题是「什么场景用什么」的问题。把所有规则塞进 CLAUDE.md就像把所有衣服扔进一个抽屉——你当然能塞进去但找的时候全乱。拆开来各司其职Claude 的表现会好很多。这篇文章把每种方式的原理、用法和反模式都拆了一遍但最核心的其实是那个决策框架——下次遇到自定义需求先问自己三个问题答案自然就出来了。下一篇打算拆 Claude Code 的 Hooks 实战——30 多种事件怎么选、5 种 hook 类型怎么搭配、真实的自动化工作流怎么搭。感兴趣的关注一下说实话公众号算法越来越不按常理出牌了把码哥字节设为星标至少保证你能收到更新不会错过。如果你身边有同事在用 Claude Code 但还没搞清楚这些配置方式这篇可以直接甩给他省他踩一遍。如果这篇对你有帮助转发给你的程序员朋友— 大家都在摸索 Claude Code 的正确用法你的分享可能帮他省很多时间。
