阶段 1 · 上下文工程——决定 Claude Code 上限的核心内功

五个层级与加载顺序#

按从最宽到最窄排列，所有发现的文件拼接注入上下文，后面的文件在上下文中靠后出现（优先级更高）：

关键加载逻辑：

• Claude Code 从当前工作目录向上遍历目录树，找到的每个 CLAUDE.md / CLAUDE.local.md 都被拼接注入，父目录先于子目录。
• 项目根目录和祖先目录的 CLAUDE.md 在启动时全量加载。
• 子目录 CLAUDE.md 按需加载：Claude 读取该子目录中的文件时才触发。
• CLAUDE.local.md 紧跟同级 CLAUDE.md 之后加载（个人笔记优先覆盖）。

实例：你在 D:\proj\src\ 下启动 Claude Code，它会依次加载：

1
C:\Program Files\ClaudeCode\CLAUDE.md   (托管策略，如存在)
2
~/.claude/CLAUDE.md                      (用户级)
3
D:\CLAUDE.md                             (如存在)
4
D:\proj\CLAUDE.md                        (如存在)
5
D:\proj\CLAUDE.local.md                  (如存在)
6
D:\proj\src\CLAUDE.md                    (如存在)
7
D:\proj\src\CLAUDE.local.md              (如存在)

写有效指令的准则#

大小控制：每个 CLAUDE.md 目标 200 行以内。超过这个阈值，上下文消耗增加且遵循率下降。

具体性原则（最重要）：

1
# 好的写法
2
- 使用 2 空格缩进（TypeScript/JSON）
3
- 提交前运行 `pnpm test`
4
- API 处理器位于 `src/api/handlers/`
5

6
# 低效写法
7
- 正确格式化代码
8
- 测试你的更改
9
- 保持文件有组织

一致性检查：跨多个 CLAUDE.md 文件存在冲突指令时，Claude 会任意选择其一。要定期用 /memory 审查所有已加载文件。

HTML 注释技巧：块级 HTML 注释在注入上下文前会被剥离，适合留给人类维护者的说明，不消耗 token：

1
<!-- 维护者注意：下方规则 2024-12 更新，因迁移到 pnpm workspace 架构 -->
2
- 使用 pnpm，禁止使用 npm install

注意：代码块内的注释会被保留。

@path 导入语法#

在 CLAUDE.md 任意位置用 @路径 引用其他文件，启动时展开加载：

1
# 项目概述请参阅 @README.md
2
# 可用命令见 @package.json
3

4
## 工作流规范
5
- Git 操作规范: @docs/git-workflow.md
6
- 发布流程: @docs/release-checklist.md

规则：

• 相对路径相对于包含导入的文件解析，不是工作目录。
• 支持递归导入，最深 4 跳。
• 首次遇到外部导入时会弹出批准对话框，拒绝后该导入永久禁用。
• 导入的文件同样在启动时全量加载，不能用来节省上下文——分割为导入仅解决组织问题。

在 worktree 间共享个人指令（Windows 用绝对路径）：

1
- @C:\Users\你的用户名\.claude\my-project-prefs.md

.claude/rules/ 路径范围规则#

适合大型项目——把指令拆分为模块化文件，可按文件路径条件加载：

1
your-project/
2
├── .claude/
3
│   ├── CLAUDE.md           # 主项目指令
4
│   └── rules/
5
│       ├── code-style.md   # 代码风格（无 frontmatter → 启动时全量加载）
6
│       ├── testing.md      # 测试约定
7
│       └── api-design.md   # 只在读取 API 文件时加载（有 paths frontmatter）

带路径条件的规则（带 paths frontmatter 的只在匹配文件时注入）：

1
---
2
paths:
3
  - "src/api/**/*.ts"
4
  - "src/api/**/*.test.ts"
5
---
6

7
# API 开发规则
8

9
- 所有端点必须包含输入验证
10
- 使用标准错误响应格式 `{ error: string, code: number }`
11
- 包含 OpenAPI 文档注释

常用 glob 模式：

用户级全局规则（适用所有项目）：

1
~/.claude/rules/
2
├── preferences.md    # 个人编码偏好
3
└── workflows.md      # 惯用工作流

用户级规则在项目规则前加载，因此项目规则优先级更高。

在 monorepo 中排除无关的 CLAUDE.md：

1
{
2
  "claudeMdExcludes": [
3
    "**/monorepo/CLAUDE.md",
4
    "/path/to/other-team/.claude/rules/**"
5
  ]
6
}

它是什么#

Auto-memory 让 Claude 在工作中为自己做笔记，跨会话积累知识。你什么都不用写，Claude 自己决定什么值得记住：构建命令、调试经验、架构决策、代码风格偏好、工作流习惯。

版本要求：Claude Code v2.1.59+，用 claude --version 确认。

存储位置与结构#

每个 git 仓库共享一个记忆目录（同一仓库的所有 worktree 和子目录共享）：

1
~/.claude/projects/<project>/memory/
2
├── MEMORY.md          # 简洁索引，每次会话加载（前 200 行或 25KB）
3
├── debugging.md       # 调试模式详细笔记（按需读取）
4
├── api-conventions.md # API 设计决策
5
└── ...                # Claude 自动创建的主题文件

加载规则：

• MEMORY.md 的前 200 行或 25KB（以先到为准）在每个会话开始时注入。
• 主题文件（如 debugging.md）启动时不加载，Claude 在需要时按需读取。
• 自动记忆是机器本地的，不跨机器同步。

启用 / 禁用#

默认开启。关闭方式：

1
// settings.json（项目或用户级）
2
{
3
  "autoMemoryEnabled": false
4
}

或临时禁用（环境变量）：

1
$env:CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1"
2
claude

自定义存储目录：

1
{
2
  "autoMemoryDirectory": "C:/Users/你的用户名/my-claude-memory"
3
}

查看与编辑记忆#

运行 /memory，会列出当前会话加载的所有文件：CLAUDE.md、CLAUDE.local.md、规则文件，以及自动记忆文件夹链接。选择任意文件可在编辑器中打开。

# 快捷写入：在对话中以 # 开头的消息，Claude 会直接将其写入记忆，不用解释，不用多余确认：

1
# 这个项目的测试命令是 pnpm test:unit，集成测试是 pnpm test:e2e
2
# API 调用需要本地运行 Redis（端口 6379）
3
# 代码审查前必须运行 pnpm lint:fix

这是最高效的向记忆写入的方式，适合你想立刻固化下来的事实。

让 Claude 记住某事：直接说”记住……”，Claude 写入自动记忆。要写入 CLAUDE.md，明确说”将这条加入 CLAUDE.md”。

三层结构#

每次 API 请求，Claude Code 按如下顺序打包内容：

查看当前上下文：

1
/context

返回按类别的实时 token 使用量和优化建议。这是最直接的”诊断上下文健康度”工具。

/compact 手动压缩#

/compact 用结构化摘要替换对话历史，释放上下文空间。理解它的关键是知道哪些内容在压缩后存活：

压缩本身的成本：压缩时 Claude Code 先发一个”生成摘要”请求，这个请求命中现有缓存（共享同一前缀），成本很低。压缩的耗时主要在生成摘要的推理，不是缓存未命中。随后的回合因历史更短，反而更快更便宜。

最佳实践：在任务之间的自然断点主动运行 /compact，不要等到自动压缩在任务中途触发。自动压缩在上下文窗口快满时触发，时机由系统决定。

/clear 完全清空#

/clear 清除整个对话历史，重新开始一个全新会话。适用场景：

• 走上了完全错误的路，想彻底放弃当前路线
• 任务已完成，开始一个完全不相关的新任务
• 上下文被大量无关内容污染

与 /compact 的区别：/compact 保留摘要，连续性更好；/clear 彻底清除，成本最低，但之前的上下文全部丢失。

/rewind 补充：回退到对话中某个更早的回合，截断其后的所有历史。它回退到已缓存的前缀，不像压缩那样构建新前缀，缓存友好。

它如何工作#

没有缓存时，每个回合 API 都要重新处理完整的对话历史。有了缓存，API 将每个请求的前缀与最近处理过的内容精确匹配——匹配到的部分按标准输入价格约 10% 计费，只对末尾的新内容按正常价格计费。

关键约束：匹配是精确前缀匹配，前缀中任何地方的变化都会使其后的所有内容缓存失效。没有按文件或按段的粒度缓存。

缓存 TTL#

订阅用户如超过用量上限使用额度计费，系统自动降回 5 分钟 TTL。

会破坏缓存的操作（重要！）#

这些操作让下一个回合的缓存完全未命中，触发全量重算：

特别注意 opusplan 模式：使用 opusplan 设置时，Plan Mode 用 Opus，执行用 Sonnet，每次切换都是模型切换，每次都破坏缓存。

不会破坏缓存的操作#

验证缓存健康度#

用状态行脚本或在每个响应里观察两个字段：

• cache_creation_input_tokens：本回合写入缓存的 token（按缓存写入价格计费）
• cache_read_input_tokens：本回合命中缓存读取的 token（约标准价格 10%）

高 read / 低 creation 比率 = 缓存运转正常。如果 creation 在连续回合间持续偏高，说明前缀在频繁变化，检查上面的”破坏缓存”清单。