CLAUDE.md 与 .claude 配置

CLAUDE.md 是给 Claude Code 的”项目 onboarding 文档”，每次会话启动时自动读取。它不是装饰，而是行为契约——但必须写得对、写得短。这页整合了来自 Anthropic 官方原文、社区实测和中文一线开发者的最新发现。2026-06-16 新增：Anthropic 官方《Best practices for Claude Code》原文核心要点、12 条 CLAUDE.md 规则完整解读（新增 8 条进阶规则）、.claude/rules/ 路径级规则三层路由体系。

源头纠正：Karpathy 从没写过 CLAUDE.md 规则

一个广泛传播的误解：Karpathy 写了 4 条 CLAUDE.md 规则。事实是——他 2026 年 1 月在 X 上抱怨了 3 个问题（沉默错误假设、过度工程化、附带损伤），Forrest Chang 把这些抱怨翻译成 4 条规则，仓库已从 120K+ 涨到 134K+ stars。中文社区绝大部分二次传播搞错了这个核心事实。[[raw/2026-05-12/朗朗晴空/CLAUDE.md 原则大审查：Karpathy 没写过的真相.md|来源: CLAUDE.md 原则大审查: Karpathy 没写过的真相]]

四条规则的精确定位：每条规则对应 AI 的一种默认失败模式——盲目猜测（Think Before Coding）、过度设计（Simplicity First）、随意改动（Surgical Changes）、缺少验收（Goal-Driven Execution）。关键是这四条规则改善的是”行为分布”而非保证每个行为一定发生——比网上流传的”准确率提升 20%“的说法更诚实。[[raw/2026-05-21/ChallengeHub/最佳 Claude Code 配置：Andrej Karpathy 的 CLAUDE.md，134+k star了！.md|来源: ChallengeHub Karpathy四条规则]]

这不是约束 AI，而是改变人机交互流程：四条规则让人类在 agent 行动前先暴露意图、在改动后验证结果——改善的是人的行为触发时机，不只是模型的输出质量。65 行、粘贴 30 秒，通用性极强（不含项目特定信息），Cursor 同样适用。传播的关键不是对文件本身投票，而是对”AI 编程默认行为带来的挫败感”投票。[[raw/2026-05-21/ChallengeHub/最佳 Claude Code 配置：Andrej Karpathy 的 CLAUDE.md，134+k star了！.md|来源: ChallengeHub Karpathy定位]]

实证数据：CLAUDE.md 的效应区间

Mnilax 在 30 个代码库 / 50 个代表性任务 / 6 周交叉测试 得出：

条件	错误率	规则遵循率
无规则	41%	—
Karpathy 4 条	11%	78%
+8 条补充规则（共 12 条）	3%	76%
超过 18 条	—	暴跌至 52%

从 4 条到 12 条，遵循率仅降 2%（78%→76%），但错误率再降 8 个百分点——新旧规则不抢同一块注意力。但超过 14 条 / 200 行 后遵循率从 76% 暴跌至 52%——不仅新规则无效，所有既有规则都被削弱。[[raw/2026-05-12/AI兴观点/Claude Code 错误率从 41% 降到 3%，就靠Karpathy大神给出的这份 CLAUDE.md.md|来源: 错误率从 41% 降到 3% 实测]]

Claude Code 的系统提示约含 50 条指令，留给用户的指令预算约 100-150 条。Anthropic 文档明确 CLAUDE.md 只是建议性的，约 80% 时间会听。这是 feature 不是 bug——模型”考虑”规则但不”服从”，意味着在规则不适用时可灵活处理。[[raw/2026-05-12/三元同学/CLAUDE.md 写不好，效率至少下降一半.md|来源: CLAUDE.md 写不好效率下降一半]] [[raw/2026-05-12/朗朗晴空/CLAUDE.md 原则大审查：Karpathy 没写过的真相.md|来源: 原则大审查]]

12 条 CLAUDE.md 规则完整解读（原始 4 条 + 新增 8 条）

Mnilax 在原始 Karpathy 4 条基础上补充 8 条进阶规则，形成完整的 12 条规范，每条对应真实线上事故。GitHub 星标已从 12 万涨到 134K+。[[raw/2026-06-14/维度攻防/从 41% 降至 3%！这套 12 条 CLAUDE.md 规则，彻底根治 Claude Code 写代码翻车问题.md|来源: 12 条规则完整解读]] [[raw/2026-06-14/来杯凉白开同学/CLAUDE.md 的12条规则，让编程错误率从 41% 降至 3%.md|来源: 12条规则55%→90%]]

原始 4 条基础规则（解决基础编码问题，直击 40% 失败场景）

Think Before Coding（先思考再编码）：杜绝无声假设，编码前主动说明判断与取舍，不确定时提问
Simplicity First（简约优先）：只写解决当下问题的最少代码，不为一次性代码做通用抽象
Surgical Changes（外科手术式修改）：仅改动必要代码区域，绝不顺手优化周边，严格匹配现有风格
Goal-Driven Execution（目标驱动执行）：提前定义成功标准，循环迭代直至验证通过

新增 8 条进阶规则（适配 2026 年 5 月后 Agent 复杂场景）

别让模型承担非语言类决策：API 重试、路由分发等确定性逻辑必须用代码实现，不交给模型判断。案例：AI 接管 503 重试后因上下文波动导致策略随机化
硬性 Token 预算：为每个任务设置 Token 上限。案例：未设限制导致单次 Debug 90 分钟，AI 反复迭代同一错误
直面代码冲突，拒绝和稀泥：代码库存在两种对立模式时选其一贯彻。案例：async/await 与全局异常捕获混用，异常被重复拦截
先通读代码，再动手编写：编写新代码前研读周边文件。案例：AI 在同名函数旁新建重复代码，覆盖线上稳定函数
测试是底线但绝非最终目标：杜绝浅层无效测试。案例：12 个全量通过的测试，函数却仅返回固定常量
长周期任务必须设置检查点：跨文件重构每步校验中间状态。案例：6 步重构第 4 步出错未拦截，最终代码混乱
遵循项目惯例，摒弃自作创新：优先适配已有风格。案例：传统 Class 项目中 AI 擅自用 React Hooks，测试体系崩溃
错误显性暴露，拒绝静默失效：异常、数据缺失必须明确提示。案例：数据库迁移 AI 提示成功实则跳过 14% 冲突数据，11 天后才被发现

原始 4 条规则的 4 大隐性缺陷

即便没有新增规则，Karpathy 4 条在当下复杂场景中也存在短板：① 长任务管控缺失（仅约束单次编码）；② 多代码库适配不足（Monorepo 无法规范统一风格）；③ 测试质量无要求（“测试通过”无法规避无效测试）；④ 无法区分场景（原型阶段需要大量脚手架快速试错，“简约规则”会拖累）。[[raw/2026-06-14/维度攻防/从 41% 降至 3%！这套 12 条 CLAUDE.md 规则，彻底根治 Claude Code 写代码翻车问题.md|来源: 4大隐性缺陷]]

Anthropic 官方最佳实践原文核心要点

Anthropic 官方《Best practices for Claude Code》是一切 CLAUDE.md 指南的源头。核心判断：大多数最佳实践基于一个约束——Claude 的上下文窗口填满得很快，且随着填满性能下降。 单次调试或代码库探索可能消耗数万 token。上下文窗口是最重要的需要管理的资源。[[Best practices for Claude Code|来源: Anthropic 官方最佳实践原文]]

官方 CLAUDE.md 编写指南

官方对 CLAUDE.md 的定位极其精确：

/init 分析代码库自动检测构建系统、测试框架和代码模式，生成 starter CLAUDE.md
每行都要回答一个问题：“删掉这行会导致 Claude 犯错吗？” 如果不会，删掉它。臃肿的 CLAUDE.md 导致 Claude 忽略你真正的指令
include/exclude 清单：include Bash 命令（Claude 猜不到的）、偏离默认的代码风格、测试指令、仓库礼仪、架构决策、开发环境怪癖、常见 gotchas；exclude Claude 读代码就能搞清楚的、标准语言约定、详细 API 文档（改为链接）、频繁变更的信息、长篇教程、逐文件描述、不言自明的实践
如果 Claude 一直做你不想做的事，即使有规则禁止——文件可能太长了，规则被淹没。如果 Claude 问你 CLAUDE.md 里已回答的问题——措辞可能歧义
CLAUDE.md 应当代码一样对待：出错时审查，定期修剪，通过观察 Claude 行为是否实际改变来测试

官方五条避免的失败模式

Kitchen sink session（厨房水槽会话）：一个任务里问无关问题 → /clear 之间切换任务
反复纠正：同一会话纠正两次以上 → /clear 写更好的初始 prompt
过度规范的 CLAUDE.md：太长导致 Claude 忽略一半 → 无情修剪，Claude 已正确做的事删掉或转成 hook
信任-验证鸿沟：看似合理但不处理边界条件的实现 → 始终提供验证（测试、脚本、截图）
无限探索：不限定范围就让 Claude “调查” → 限定调查范围或用子代理

官方验证闭环四层强度

官方将”给 Claude 验证手段”按强度分为四层：① 单 prompt 内：让 Claude 运行检查并迭代；② 跨会话：将检查设为 /goal 条件，独立评估器每轮重检；③ 确定性门禁：Stop hook 脚本运行检查，连续阻断 8 次后 Claude Code 覆盖 hook 结束回合；④ 第二意见：验证子代理或动态工作流让新模型尝试反驳结果。每层用更多设置换取更少注意力。[[Best practices for Claude Code|来源: 验证闭环四层]]

官方 CLAUDE.md 文件位置体系

官方明确了 5 个放置位置：① ~/.claude/CLAUDE.md（所有会话）；② 项目根 ./CLAUDE.md（签入 git 共享团队）；③ 项目根 ./CLAUDE.local.md（个人项目笔记，加 .gitignore）；④ 父目录（Monorepo 自动拉入 root/CLAUDE.md + root/foo/CLAUDE.md）；⑤ 子目录（Claude 读取文件时按需拉入子目录 CLAUDE.md）。官方还支持 @path/to/import 语法导入额外文件。[[Best practices for Claude Code|来源: 官方文件位置]]

.claude/rules/ 路径级规则：从一锅粥到三层路由

.claude/rules/ 目录配合 paths frontmatter 是 Claude Code 项目治理的重大升级。从 2.0.64 版本（2025 年 12 月 10 日） 开始正式支持。[[raw/2026-06-14/井底之硅/还在往 CLAUDE.md 里堆规则？开发者翻出「.claude-rules」目录，Claude Code 项目治理已经细到文件路径级！.md|来源: .claude/rules/ 路径级规则]]

核心机制

普通 CLAUDE.md 在每次 session 开始时整份加载，哪怕当前不需要。paths frontmatter 通过 glob 模式限定规则只在特定路径下生效——只有 Claude 读取匹配文件时才触发加载，不是每次工具调用都触发。

---
paths:
  - src/api/**/*.ts
  - src/backend/**
---

Anthropic 官方原文：“Rules can also be scoped to specific file paths, so they only load into context when Claude works with matching files, reducing noise and saving context space.”

三级规则体系

Claude Code 的项目规则体系已分成三个层级：

CLAUDE.md —— 全局常驻规则，每次 session 加载，适合项目级核心约束
.claude/rules/ —— 按主题和路径触发的规则文件，只在匹配文件被处理时进入上下文
Skills —— 按任务调用的能力模块，官方文档明确”不需要常驻上下文的任务指令”应用 Skills

从全量加载到按路径触发，再到按任务调用——Claude Code 的规则加载正从”全都装进去”进入”该装什么装什么”的阶段。

“闹鬼”问题与解法

开发者 Timur Yessenov 评论：“Path-scoped rules are the boring thing that makes Claude Code feel less haunted in a real repo.” Claude 改前端代码时突然冒出后端命名规范，改测试时突然遵守 API 文档格式——根因就是全量加载的 CLAUDE.md 混入了无关指令。建议在高风险修改前要求 Claude 列出当前加载了哪些局部规则，如果答不出就不该动那个文件。[[raw/2026-06-14/井底之硅/还在往 CLAUDE.md 里堆规则？开发者翻出「.claude-rules」目录，Claude Code 项目治理已经细到文件路径级！.md|来源: 闹鬼问题]]

被数据证伪的做法

说 “be careful” / “think hard”（不可测试，遵循率约 30%）
让 Claude 当 “senior engineer”（无效，Claude 已经觉得自己是 senior）
放示例代替规则（示例重 3 倍，模型过拟合）
依赖可能不存在的工具（如 “always use eslint”）
超过 14 条 / 200 行（遵循率崩盘）

唯一真正普适的原则：每条规则必须回答一个具体问题——它防止什么错误？ 四条可操作判定标准：可测试、具体、来自真实错误、有上限。[[raw/2026-05-12/朗朗晴空/CLAUDE.md 原则大审查：Karpathy 没写过的真相.md|来源: 原则大审查]]

CLAUDE.md 维护治理：准入标准、精简信号与隔离方案

CLAUDE.md 会自然膨胀，每行都是常驻上下文成本。多来源独立证实：CLAUDE.md 的核心工作量不是”写什么”而是”删什么”——它是维护出来的，不是写出来的。

三条件准入漏斗

判断一条指令该不该进 CLAUDE.md 的核心框架是三条件漏斗，三个条件同时满足才放入：

高频——这条指令每轮会话都可能用到，不是某个特定场景才触发
稳定——指令内容不频繁变化，写下来后不需要经常改
跨会话——跨多个会话仍然成立，不是一次性的临时安排

不满足三条件的情况：低频成套的做 Skill，临时的留在对话上下文，大段文档用 @ 路径引入。[[raw/2026-06-19/吴师兄/面试官皱眉：Claude Code 你用了半年，CLAUDE.md 多少行了？.md|来源: 三条件漏斗]]

对 /init 自动生成的批判立场

官方 /init 命令会自动分析代码库生成 starter CLAUDE.md，但社区一线实践对此持强烈批判态度：拿到 /init 生成的初稿后，第一件事是大删特删而非保留使用。自动生成的内容往往塞满了 Claude 读代码就能搞清楚的冗余信息，违背”每行都要回答一个具体问题”的核心原则。[[raw/2026-06-19/吴师兄/面试官皱眉：Claude Code 你用了半年，CLAUDE.md 多少行了？.md|来源: /init批判]]

注意力被稀释的隐蔽代价

当 CLAUDE.md 过长时，关键指令会被淹没在噪音中。一个亲身验证的案例：备份指令从第 1500 行附近移到文件开头硬约束区后，模型从”偶尔忽视”变为”立刻遵守”——证实指令的位置权重远高于”写了就行”。这就是注意力稀释（attention dilution）：CLAUDE.md 不是越全越好，每条指令都与其它指令竞争模型的注意力资源，放得越靠后、越冗余，被遵守的概率越低。[[raw/2026-06-19/吴师兄/面试官皱眉：Claude Code 你用了半年，CLAUDE.md 多少行了？.md|来源: 注意力稀释]]

定期精简信号与维护节奏

CLAUDE.md 需要定期审查和精简，出现以下信号时就是该动手了：

行数越界——超过 100-200 行（项目级建议 100 行出头，全局级几十行）
指令被忽略——模型反复不遵守某条你确定写了的规则
出现临时字眼——有”暂时就这样先加了”、“临时处理”之类的 patch 痕迹
同一件事写了多遍——多条规则在解决同一个问题，说明需要合并或下沉

维护节奏：建议每两到三周做一次精简，像审代码一样审 CLAUDE.md 变更，指定明确的 owner。[[raw/2026-06-19/吴师兄/面试官皱眉：Claude Code 你用了半年，CLAUDE.md 多少行了？.md|来源: 精简信号]] [[raw/2026-06-19/Anthropic/调教 Claude Code 的七种方法.md|来源: 七种方法]]

Git Worktree 与 CLAUDE.md 隔离方案

Git Worktree 是实现任务级上下文隔离的关键基础设施。每个 worktree 携带各自的 CLAUDE.md，使得并行开发、高风险探索和日常维护可以拥有完全独立的指令体系，互不串味。这在多 Agent 并行场景下尤其重要——不同 worktree 针对不同任务维护专属的 CLAUDE.md，切换任务即切换上下文。[[raw/2026-06-19/吴师兄/面试官皱眉：Claude Code 你用了半年，CLAUDE.md 多少行了？.md|来源: Worktree隔离]] [[raw/2026-06-19/扶苏/Claude Code 深度实战：半年单兵重构 30 万行代码的硬核工程化指南.md|来源: 扶苏]]

面试回答框架：成本本质 -> 准入标准 -> 分层策略 -> 隔离方案

CLAUDE.md 治理问题如果在面试中被问到，推荐的回答结构是一个四步递进框架：① 成本本质（CLAUDE.md 是常驻上下文成本，注意力资源竞争模型）→ ② 准入标准（三条件漏斗：高频、稳定、跨会话）→ ③ 分层策略（全局级/项目级/子目录级/Skill 级各自职责）→ ④ 隔离方案（Worktree + claudeMdExcludes + 路径限定的 Rules）。[[raw/2026-06-19/吴师兄/面试官皱眉：Claude Code 你用了半年，CLAUDE.md 多少行了？.md|来源: 面试框架]]

矛盾：CLAUDE.md 写得越全越好，项目 /init 自动生成即可使用 vs CLAUDE.md 不是越全越好，每行都有常驻成本；/init 生成的初稿应大删特删来自 [[raw/2026-06-19/吴师兄/面试官皱眉：Claude Code 你用了半年，CLAUDE.md 多少行了？.md|来源: /init矛盾]]

五类常见错误

写得太长——超过 200 行后遵循率急剧下降；项目级建议控制在 100 行出头，全局级几十行
当 Linter 用——格式规则交给工具（Prettier/ESLint），不要写进 CLAUDE.md
嵌入大段代码/文档——应只写指引告诉何时读哪个文件
只写”不要做什么”不写”应该做什么”——负面约束需要正面替代
用 /init 生成后不再维护——Boris Cherny 团队把 CLAUDE.md 当”错题本”维护，每当 Claude 犯了错就加一条

Boris Cherny 自己的 CLAUDE.md 仅 2.5k tokens（约 100 行），同时跑 5 个 Claude 实例。核心框架：WHAT/WHY/HOW——只写 Claude 猜不到的东西。[[raw/2026-05-12/三元同学/CLAUDE.md 写不好，效率至少下降一半.md|来源: CLAUDE.md 写不好]]

只堆不删，只写不治——CLAUDE.md 不是写出来的，是维护出来的。每两到三周做一次精简审查，把该下沉到 Skill 的下沉、该移到 Rules 的移走、该删掉的删掉。不维护的 CLAUDE.md 和没有一样。

配置的层级架构

Anthropic 官方七层扩展体系（按构建顺序）

CLAUDE.md —— 基础行为约定
Hooks —— 生命周期注入（更有价值的用法是”自我进化”：stop hook 反思并建议更新 CLAUDE.md）
Skills —— 按需加载专业能力（渐进式披露）
Plugins —— 知识分发与团队共享
LSP —— 符号级精准导航
MCP —— 外部工具与数据源连接
子 Agent —— 探索与编辑分离

核心金句：”模型能力是地板，配置质量才是天花板。”配置需要随模型升级而迭代，每 3-6 个月做一次配置审查。为旧模型写的约束可能变成新模型的枷锁。[[raw/2026-05-15/AI兴观点/Claude Code征服大型代码库的7层心法？官方一文全公开.md|来源: 七层心法]] [[raw/2026-05-15/Anthropic/Anthropic 博客又双叒叕更新了：Claude Code 大型代码库最佳实践.md|来源: Anthropic 大型代码库最佳实践]]

Monorepo 反直觉实践：从子目录初始化

官方最佳实践明确建议从子目录初始化 Claude（而非根目录），依赖 Claude 自动向上遍历加载所有 CLAUDE.md 文件。这精确限定了 Agent 的工作范围。[[raw/2026-05-15/AI兴观点/Claude Code征服大型代码库的7层心法？官方一文全公开.md|来源: 七层心法]]

企业部署三阶段

基础设施（小团队打地基）→ 试点（有限访问+审批流程）→ 规模（建立治理体系后大面积推广）。需要指定 Agent Manager（智能体管理员） 作为直接责任人，不能纯靠自发采用。[[raw/2026-05-15/Anthropic/Anthropic 博客又双叒叕更新了：Claude Code 大型代码库最佳实践.md|来源: Anthropic 大型代码库最佳实践]]

开源模板 `claude-init`

黑客松冠军的配置模板：三层文档架构（Tier 1 永久约束 / Tier 2 组件规范 / Tier 3 当前状态）+ 9 个专用子智能体 + 8 条强制安全规则。核心价值在”把偏好固化成规则”的组织方式。[[raw/2026-05-15/Sam/黑客松冠军的 Claude Code 配置，我扒出来用了两周.md|来源: 黑客松冠军配置]]

“CLAUDE.md 小、Skill 详”的分层架构

扶苏团队的实践提炼出一种稳定的分层模式：项目根目录 CLAUDE.md 仅保持约 200 行，聚焦项目级核心配置和构建命令；所有编码知识逐层下沉到 Skills 中。CLAUDE.md 通过 @ import 指向 PROJECT_KNOWLEDGE.md 和 TROUBLESHOOTING.md 等补充文档，实现”路线图”与”操作手册”分离。Skills 采用渐进式披露结构——一个前端 Skill 可达 398 行正文 + 10 个资源文件，后端 Skill 304 行 + 11 个资源文件，正文在调用时才加载，不消耗常驻上下文预算。[[raw/2026-06-19/扶苏/Claude Code 深度实战：半年单兵重构 30 万行代码的硬核工程化指南.md|来源: 扶苏小CLAUDE.md大Skill]]

Scripts Attached to Skills：与其在 Skill 文档中文字描述如何测试，不如直接嵌入可执行脚本（如 node scripts/test-auth-route.js [url]），Claude 能直接运行而非阅读文字——将文档从”被动阅读材料”变为”主动执行单元”。[[raw/2026-06-19/扶苏/Claude Code 深度实战：半年单兵重构 30 万行代码的硬核工程化指南.md|来源: 扶苏脚本附加]]

Skill Listing Budget：隐蔽的 1% 截断机制

Claude Code 有一个隐蔽的 skill description 预算机制：默认只分配上下文窗口的 1%（200K 上下文约 2000 tokens）用于加载 skill description。超出后按使用频率排序自动砍掉低频 skill。装了 90+ skill 时实际已超额近 3 倍。排查方法：跑 /context 看 skill 明细——70-110 tokens 表示正常，~40tokens 表示被截短，<20 tokens 表示几乎只剩名字、自动触发基本失效。[[raw/2026-05-15/问答/你装的 skill，Claude Code 可能就看不到.md|来源: 你装的 skill 可能看不到]]

单条 Description 截断上限：源码常量为 MAX_LISTING_DESC_CHARS=250，单条 skill description 超过 250 字符会被直接截断。这意味着一条超过 250 字符的描述，后半部分不会被模型读到——描述必须在前 250 字符内完成触发判断，不能依赖后面补充。[[raw/2026-06-19/吴师兄/一个月给 Claude Code 烧了 1.5 万美金，我才搞懂 skill 到底该怎么写.md|来源: 1.5万美金 Skill 截断]]

Skill 文件夹资产化：Skill 不只是 SKILL.md 文件，而是完整文件夹（SKILL.md + references + scripts + assets + config.json）。其中 config.json 可实现跨会话记忆——CDN bucket 名、缓存接口地址、域名配置等一次性写入后永久记住，无需每次重新描述。[[raw/2026-06-19/吴师兄/一个月给 Claude Code 烧了 1.5 万美金，我才搞懂 skill 到底该怎么写.md|来源: 1.5万美金 Skill 文件夹]]

临时 Hook 保险丝：可在 Skill 激活期间使用临时 StopEvent Hook 作为”保险丝”——限定 Skill 只能操作指定目录内的文件，修改超出范围时自动拦截并报错。相当于给每个 Skill 附加一个临时的安全护栏，确保有权限边界的 Skill 不会越界操作。[[raw/2026-06-19/吴师兄/一个月给 Claude Code 烧了 1.5 万美金，我才搞懂 skill 到底该怎么写.md|来源: 1.5万美金保险丝]]

多层加载机制解密（2026-05 新增）

CLAUDE.md 远不止大家熟知的”项目根目录一份、用户主目录一份”这么简单。实际加载机制有四层来源、三条主线、多处陷阱：

四层来源与三条加载主线

四层来源：组织级 → 用户级（~/.claude/CLAUDE.md）→ 项目级（项目根目录）→ 本地级（CLAUDE.local.md）。所有来源的 CLAUDE.md 全部拼接（非覆盖叠加），Claude 一次性收到所有内容。[[raw/2026-05-21/问答/CLAUDE.md 不只有两份：多层加载机制解密和实战技巧.md|来源: 问答多层加载四层来源]]

三条加载主线：向上遍历（从工作目录向根目录逐级搜索 CLAUDE.md）→ 固定位置（~/.claude/）→ 子目录懒加载（进入子目录时才挂载该目录的 CLAUDE.md）。[[raw/2026-05-21/问答/CLAUDE.md 不只有两份：多层加载机制解密和实战技巧.md|来源: 问答多层加载三条主线]]

三个隐蔽陷阱

CLAUDE.md 不在系统提示词里：它是作为用户消息追加的，而非系统指令——这解释了它”不保证严格遵守”的根本原因。[[raw/2026-05-21/问答/CLAUDE.md 不只有两份：多层加载机制解密和实战技巧.md|来源: 问答不在系统提示词]]
多份 CLAUDE.md 冲突时不会报错也不会询问：Claude 随机挑一个执行。作者亲历 HTML vs Markdown 输出格式指令冲突，每次执行结果随机，排查了大半天才发现是多份 CLAUDE.md 在打架。[[raw/2026-05-21/问答/CLAUDE.md 不只有两份：多层加载机制解密和实战技巧.md|来源: 问答冲突随机]]
子目录懒加载在 /compact 后可能丢失：compact 只保留当前已加载的内容，子目录中尚未访问过的 CLAUDE.md 会被丢弃——这是隐蔽的上下文丢失源。[[raw/2026-05-21/问答/CLAUDE.md 不只有两份：多层加载机制解密和实战技巧.md|来源: 问答 compact丢失]]

高级用法：条件加载与 @import

.claude/rules/ + paths frontmatter：按文件路径 glob 匹配条件加载规则。只有修改匹配文件时，对应规则才注入上下文——不匹配规则的会话完全不占 token。这意味着可以为不同模块、不同语言维护专用规则而不必担心塞爆上下文。[[raw/2026-05-21/问答/CLAUDE.md 不只有两份：多层加载机制解密和实战技巧.md|来源: 问答 rules+paths]]

@import 语法：在 CLAUDE.md 中使用 @import rules/coding.md 展开拼接其它文件。省维护（一份规则多处引用），不省 token（展开后等价于直接写入）。最多嵌套 5 层。[[raw/2026-05-21/问答/CLAUDE.md 不只有两份：多层加载机制解密和实战技巧.md|来源: 问答 @import]]

排查三件套

/memory：查看 Claude 实际加载了哪些 CLAUDE.md
claudeMdExcludes 配置：排除特定路径的 CLAUDE.md，防止干扰
InstructionsLoaded hook：在指令加载完成后触发，可用于审计实际加载内容

[[raw/2026-05-21/问答/CLAUDE.md 不只有两份：多层加载机制解密和实战技巧.md|来源: 问答排查三件套]]

关键组件

CLAUDE.md 负责声明执行准则、效率边界和项目约束
CLAUDE.local.md 用于个人偏好，不污染团队共享规则
.claude/ 承载 rules/commands/agents/settings.json 分层体系

.claude 文件夹作为项目协议（X 来源补充）

Akshay Pachaar 的 .claude 结构解析把 Claude Code 项目配置拆成几个可治理部件：commands/ 是显式调用的快捷工作流，hooks/ 是生命周期门禁，skills/ 是可附带支持文件的按需工作流，agents/ 是带独立系统提示、工具权限和模型偏好的专用子代理，settings.json 则管理权限、hooks 和工具边界。它补强了本页的分层判断：.claude 不是杂物目录，而是一套告诉 Claude “你是谁、项目做什么、遵守什么规则”的协议。[[raw/X/@akshay_pachaar/Anatomy of the .claude folder .claude 文件夹的结构解析.md|来源: .claude folder anatomy]]

该来源对 Hooks 的工程边界尤其具体：PreToolUse 适合拦截 Bash 危险命令，PostToolUse 适合格式化和 lint，Stop 适合质量门禁（如测试必须通过），UserPromptSubmit 可做 prompt 校验，SessionStart/SessionEnd 可做上下文注入和清理。Stop hook 必须检查 stop_hook_active，否则可能形成 hook 阻断→Claude 重试→再次阻断的死循环。Hooks 不热重载、PostToolUse 不能撤销已发生动作、子代理动作也会递归触发，而且 hook 以用户完整权限执行，所以脚本必须验证 JSON 输入、引用 shell 变量并使用绝对路径。[[raw/X/@akshay_pachaar/Anatomy of the .claude folder .claude 文件夹的结构解析.md|来源: .claude hooks]]

.claude 的最小上手顺序也很清楚：先 /init 生成并精简 CLAUDE.md；再加 settings.json 的 allow/deny，至少允许项目运行命令、拒绝 .env；然后为高频工作建一两个 command；等 CLAUDE.md 拥挤后再拆到 .claude/rules/；最后把个人偏好放到 ~/.claude/CLAUDE.md。Skills 和 agents 只在复杂重复工作值得打包时再加。[[raw/X/@akshay_pachaar/Anatomy of the .claude folder .claude 文件夹的结构解析.md|来源: .claude practical setup]]

Anthropic 官方「七机制路由体系」（2026-06-19 新增）

Anthropic 官方《调教 Claude Code 的七种方法》给出了首份完整的「什么该写在哪里」权威路由表。这是对「别用 CLAUDE.md 干所有事」的官方背书和精确分工。 [[raw/2026-06-19/Anthropic/调教 Claude Code 的七种方法.md|来源: 调教 Claude Code 的七种方法]]

七机制三维对比（加载时机 / 压缩后存活 / 指令权重）：

机制	成本	压缩后	加载时机	最适合
CLAUDE.md（根）	高	保留	会话启动	构建命令、目录结构、编码约定
CLAUDE.md（子目录）	低	丢失	访问时	子目录专属约定
Rules	中	重新注入	启动/文件访问	具体约束「API handler 必须用 Zod」
Skills	低	FIFO 淘汰	调用时	程序化流程
Subagents	低	隔离	调用时	并行/隔离子任务
Hooks	可忽略	完全绕过	生命周期事件	确定性自动化
Output Styles	中-高	永不压缩	会话启动	角色/语气——权重最高

对 CLAUDE.md 的官方定位（与历史页面一致但更明确）：CLAUDE.md 只放构建命令、目录结构、编码约定这类会话级全局约定。以下四类内容不该进 CLAUDE.md：

程序化流程（「每次 X，都做 Y」）→ 用 Skills
硬性禁止/安全护栏（「永远不要做这个」）→ 用 Hooks + Permissions + Managed Settings
路径级领域约束（「改这个模块时必须遵守…」）→ 用 .claude/rules/ + paths frontmatter
长清单/冗余复述→ 精简或删除，遵守 200 行上限

Output Styles 陷阱：自定义 Output Styles 会替换整个默认 Output Style，除非设 keep-coding-instructions: true——否则会意外剥离 Claude Code 的软件工程身份。--append-system-prompt 是唯一追加而非替换的机制，但仅单次有效。 [[raw/2026-06-19/Anthropic/调教 Claude Code 的七种方法.md|来源: 七机制 Output Styles 陷阱]]

Plugin 打包：Skills、Subagents、Hooks、Output Styles 可打包为 Plugin 跨团队/项目共享——这是 Anthropic 推动的配置资产化与复用化方向。 [[raw/2026-06-19/Anthropic/调教 Claude Code 的七种方法.md|来源: 七机制 Plugin 打包]]

提示词说服 vs 代码执行：两条路径的根本区分

理解 Claude Code 配置体系的核心认识框架是分清两条本质不同的路径：

提示词说服路径（CLAUDE.md / Rules / Skills）——依赖模型理解和遵从，指令通过自然语言表达，质量受模型能力和注意力分布影响，做不到百分百保证
代码执行路径（Hooks + Permissions）——确定性自动化，完全绕过上下文窗口，配置在主上下文之外执行，不受提示注入干扰

前者的根本问题是”告诉 AI 应该怎么做”——AI 可能接受也可能忽略。后者的根本特点是”让事情确定性地发生”——只要触发条件满足就执行，模型无法拒绝、无法绕过。一套健壮的企业级配置应该两者混合使用：用 CLAUDE.md 和 Rules 指导行为方向，用 Hooks 和 Permissions 兜住不能越过的底线。[[raw/2026-06-19/邵猛/驾驭 Claude Code：CLAUDE.md 配置文件、Skills、Hooks、Rules、Subagents 等 7 种指令全解析.md|来源: 邵猛两条路径]]

机制选择决策框架

综合多个来源，七种机制的选择逻辑可归纳为一张场景对照表：

场景	首选机制	原因
代码库事实（构建命令、目录结构）	CLAUDE.md（根）	全局常驻，每次会话加载
局部领域约束	Rules + paths frontmatter	路径触发，不占无关会话 token
可复用流程	Skills	按需调用，可附带资源文件
隔离重活（并行/探索）	Subagents	独立上下文，结果回流
确定性自动化	Hooks	完全绕过上下文，无可拒绝
角色定位/语气控制	Output Styles	永不压缩，权重最高
个人偏好（不想签入 git）	CLAUDE.local.md 或 `~/.claude/`	不污染团队共享配置

[[raw/2026-06-19/TriAi翻译/掌控 Claude Code：CLAUDE.md、Skills、Hooks、Subagents….md|来源: TriAi翻译决策框架]] [[raw/2026-06-19/Anthropic/调教 Claude Code 的七种方法.md|来源: 七种方法]]

Managed Settings：组织级强制管控

Anthropic Managed Settings 是组织级配置管控手段——管理员部署的策略无法被个人配置排除。这意味着安全护栏（如”禁止访问生产数据库”、“必须经过 code review”）可以被强制执行，而非靠模型”愿意”遵守。这是 CLAUDE.md 从”建议性规则”走向”强制性规则”的组织级解决方案。[[raw/2026-06-19/Anthropic/调教 Claude Code 的七种方法.md|来源: 七种方法 Managed Settings]]

ClaudeMdExcludes 路径排除

claudeMdExcludes 配置项可以精确跳过不需要的子目录 CLAUDE.md 文件。在 Monorepo 中你不需要关心团队 A 的项目约定来运行团队 B 的代码——这项配置确保子目录的 CLAUDE.md 不会因向上遍历机制意外加载到当前会话。[[raw/2026-06-19/Anthropic/调教 Claude Code 的七种方法.md|来源: 七种方法 claudeMdExcludes]]

2026-07 更新：配置体系的存活边界

新增资料把 CLAUDE.md、AGENTS.md、rules、SPEC 和 Hooks 的职责边界讲得更硬：CLAUDE.md 是长期行为契约，AGENTS.md 是跨工具入口，.claude/rules/ 是路径/本地约束，SPEC/Goal 是当前任务契约，Hooks/Permissions 是确定性执行。别拿 CLAUDE.md 当垃圾桶，啥都塞进去就是找死。[[raw/2026-06-30/sky/Claude Code 可扩展性：Plugins、Subagents 与 Skills 完全指南.md|来源: 扩展体系]] [[raw/2026-06-30/吴师兄/面试官抓狂：-我的 Claude Code 怎么越用越笨？！-我看了一眼：-不是它笨，是 auto-compact 把记忆悄悄压没了-.md|来源: auto-compact]]

压缩后的存活规则：

root CLAUDE.md 和系统级记忆更容易重新注入。
子目录 CLAUDE.md、路径 rules、未调用 Skill 的正文细节容易消失。
Hooks/Permissions 因为走代码路径，不依赖上下文窗口，存活性最高。
当前任务 SPEC/Goal 若不外化到文件，长程任务中会被摘要稀释。

配置选择原则：稳定、高频、跨会话的放 CLAUDE.md；低频成套流程放 Skill；路径特定规则放 rules；当前任务约束放 SPEC/Goal；必须强制的放 Hook/Permission。[[raw/2026-06-24/道哥说AI/Claude Code 团队落地指南：一套可复制的配置方案.md|来源: 团队配置方案]]