本节目标

1. 掌握上下文工程的四种核心操作：Select（选择）、Write（写入）、Compress（压缩）、Isolate（隔离）

2. 学会通过 .claudeignore 精确控制上下文注入

3. 理解 Prompt Caching 机制并达到 90%+ 缓存命中率

4. 理解上下文"哑区"理论（低于 40% 容量时质量最优）

5. 理解 Claude Code 相比其他工具的 Token 效率优势（5.5x）

---

核心知识点

1. 上下文工程四操作

上下文工程不是"把文件塞进 prompt"，而是一个精细的信息管理过程，包含四个核心操作：

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  SELECT  │ -> │  WRITE   │ -> │ COMPRESS │ -> │ ISOLATE  │
│  选择     │    │  写入     │    │  压缩     │    │  隔离     │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
  挑出相关的      组织成结构      压缩冗余信息      隔离一次任务
  文件和知识      化的上下文      提高信息密度      的独立上下文

1.1 Select（选择）

决定"哪些内容进入上下文窗口"。这是最重要的一步——选对了事半功倍，选错了万劫不复。

// Claude Code 的 Select 策略（v2.1.x）
interface ContextSelectionStrategy {
  // 1. 显式引用：用户在 CLAUDE.md 中声明的文件
  explicit: {
    rules: "~/.claude/rules/**/*.md";
    memory: ".claude/memory/*.md";
    docs: ".claude/docs/*.md";
  };
​
  // 2. 自动检测：基于当前工作目录和任务
  auto: {
    gitStatus: "检测变更文件";        // 只注入已修改的文件
    importGraph: "分析依赖关系";      // 被引用但未修改的文件也纳入
    toolOutput: "工具调用结果";       // Bash / Grep 的输出
  };
​
  // 3. 按需加载：Agent 主动检索
  onDemand: {
    grep: "搜索相关代码片段";
    glob: "匹配文件模式";
    memory: "搜索记忆库";
  };
}

核心原则：能少则少。每个进入上下文的内容都必须有"为什么在这里"的理由。

1.2 Write（写入）

不只是"贴上去"，而是结构化组织：

# 差：平铺直叙地把所有文件内容贴在 prompt 里
[文件A全文]
[文件B全文]
[文件C全文]
​
# 好：有层次、有标注的结构化上下文
## 任务上下文
<task>修复 auth.ts 中的 JWT 过期未处理问题</task>
​
## 直接相关文件
<file path="src/auth/auth.ts" relevance="primary">
// 只展示相关函数而非整个文件
export async function verifyToken(token: string) { ... }
</file>
​
<file path="src/auth/types.ts" relevance="types">
// 类型定义
interface JwtPayload { sub: string; exp: number; }
</file>
​
## 间接相关文件（引用链）
<file path="src/middleware/auth-guard.ts" relevance="caller">
// 调用了 verifyToken 的中间件
</file>

1.3 Compress（压缩）

在信息不丢失的前提下提高密度：

// 压缩策略示例
const compressStrategies = {
  // 策略 1：摘要（Summarize）
  "0-30% capacity": "保留完整内容",           // 空间充足，不压缩
  "30-60% capacity": "函数级摘要 + 关键代码块", // 开始压缩非核心函数
  "60-85% capacity": "文件级摘要 + 接口定义",   // 大幅压缩
  "85%+ capacity": "仅保留摘要，代码转为引用",   // 极限压缩
​
  // 策略 2：去重（Deduplicate）
  deduplicate: {
    similarCode: "合并相似代码块，用注释标注差异",
    repeatedErrors: "合并重复的错误日志",
    boilerplate: "用 `// ...标准导入` 替代大段 import",
  },
​
  // 策略 3：优先级截断（Priority Truncation）
  priorityTruncation: {
    critical: "全部保留",          // 核心业务逻辑
    high: "保留前 200 行",         // 重要工具函数
    medium: "保留签名 + 注释",     // 辅助函数
    low: "仅保留文件名引用",       // 配置文件
  },
};

1.4 Isolate（隔离）

每个 Agent / 每个子任务拥有独立的上下文空间，避免相互污染：

# 上下文隔离配置
isolation:
  per_agent_context: true         # 每个 Agent 独立的上下文窗口
  shared_context:
    - project-context.md          # 共享：项目基础信息
    - task-description.md         # 共享：当前任务描述
  isolated_context:
    planner:                      # Planner 专属
      - architecture-decisions.md
      - tech-stack-reference.md
    coder:                        # Coder 专属
      - src/**/*.ts               # 相关源码
      - api-specs.md
    reviewer:                     # Reviewer 专属
      - coding-standards.md
      - security-rules.md

2. .claudeignore 精确控制

.claudeignore 是上下文工程的"守门员"——决定哪些内容永远不进入上下文：

# .claudeignore 示例
# ============================================
# 1. 大型二进制文件
*.zip
*.tar.gz
*.mp4
*.mov
*.pdf           # PDF 太大，用摘要替代
​
# 2. 依赖和构建产物
node_modules/
dist/
build/
.next/
.gradle/
target/
​
# 3. 日志和临时文件
*.log
logs/
tmp/
.cache/
​
# 4. 大型数据文件
*.csv           # 数据文件通常不需要全文上下文
*.json          # 大 JSON 除外
!package.json   # 但要保留 package.json
!tsconfig.json
​
# 5. 加密和敏感文件
.env
*.pem
*.key
secrets/
​
# 6. IDE 和工具配置
.idea/
.vscode/
*.swp
*.swo
​
# 7. 非核心文档
CHANGELOG.md    # 通常不需要注入
CONTRIBUTING.md
LICENSE
​
# 8. 大型静态资源
public/assets/
static/images/
*.png
*.jpg
*.svg

验证 .claudeignore 是否生效：

# 查看当前会话注入了多少文件
/claude context stats
​
# 输出示例：
# Files loaded: 47 (filtered from 2,381 total files)
# Tokens consumed: 15,200 / 200,000
# Ignored by .claudeignore: 1,893 files
# Memory files loaded: 3

3. Prompt Caching 机制

Claude Code 会自动缓存不常变化的内容。理解并优化缓存，是达到 90%+ 命中率的关键：

// Prompt Caching 工作原理
interface PromptCache {
  // 可缓存的内容类型
  cacheableTypes: [
    "system_prompt",       // CLAUDE.md + rules/ 的内容
    "memory_files",        // .claude/memory/ 下的文件
    "static_tools",        // 工具定义
    "project_structure",   // 项目文件树
  ];
​
  // 不可缓存的内容
  uncacheable: [
    "conversation_history", // 每次对话的上下文不同
    "tool_outputs",         // 工具调用的结果
    "dynamic_context",      // Agent 运行时产生的上下文
  ];
​
  // 缓存失效触发条件
  invalidation: [
    "file_modified",        // 被缓存的文件被修改
    "tool_set_changed",     // 工具集变更
    "model_switched",       // 模型切换
    "session_timeout",      // 会话超时（默认 1 小时）
  ];
}

提升缓存命中率的技巧：

# 技巧 1：将不常变的内容放在 prompt 前部
# Claude API 的缓存是前缀缓存（prefix caching）
# 变动频繁的内容放后面，不变的内容放前面
​
# 技巧 2：减少 CLAUDE.md 的修改频率
# 尽量避免在对话中修改 CLAUDE.md
# 将其视为"项目宪法"——稳定、不常变
​
# 技巧 3：Memory 文件使用单独引用
# 用 @memory/project-context.md 按需注入
# 而非在 CLAUDE.md 中全文嵌入
​
# 技巧 4：监控缓存命中率
# 在 Claude Code 运行日志中查看
grep "cache_hit" ~/.claude/logs/session-*.log

4. 上下文"哑区"理论

研究表明，上下文窗口存在一个"哑区"（Dumb Zone）。当上下文填充超过一定比例后，模型性能反而下降：

模型性能曲线：
​
  A+ │  ★
     │    ★
  A  │      ★
     │        ★
  B  │          ★
     │            ★
  C  │              ★ ★ ★ ★ ★ ★ ★ ★ （哑区开始）
     │                              ★
  F  │                                ★
     └──────────────────────────────────────
     0%   20%   40%   60%   80%   100%
               ↑                  ↑
          最佳区间             崩溃区间
​
最佳实践：永远让上下文使用率保持在 40% 以下
警告线：60% 时开始压缩或重新规划
危险线：85% 以上，模型开始出现幻觉和遗漏

为什么会出现哑区？ 模型在长上下文中面临"注意力稀释"问题——它被迫在大量信息中分配有限的注意力资源，导致：

• 遗漏上下文中间部分的信息（"中间丢失"现象）

• 混淆不同文件的归属关系

• 遵循早期指令而忽略后期纠正

5. Token 效率对比

Claude Code 与 Cursor 在 token 消耗上存在显著差异：

// 同一任务（"为 auth 模块添加 JWT 刷新逻辑"）的 Token 消耗对比
const comparison = {
  claudeCode: {
    totalTokens: 45_000,
    inputTokens: 38_000,
    outputTokens: 7_000,
    mechanism: "文件引用 + 工具检索",
    description: "Claude Code 通过工具读取文件，而非注入全文"
  },
  cursor: {
    totalTokens: 248_000,
    inputTokens: 230_000,
    outputTokens: 18_000,
    mechanism: "全量文件注入到上下文",
    description: "Cursor 将所有相关文件全文注入 prompt"
  },
  ratio: "5.5x",  // Claude Code 节省 5.5 倍 Token
};
​
// 效率来源：
// 1. 工具检索替代全量注入：Claude Code 只注入它"决定要看"的文件
// 2. 结构化组织减少冗余
// 3. 增量更新而非全量刷新

---

实操步骤

步骤 1：审计当前项目的上下文使用

# 查看当前会话中注入了哪些内容
/claude context show
​
# 查看 Token 使用分布
/claude context breakdown
​
# 输出示例：
# System prompt:      3,200 tokens  (1.6%)
# Rules:             12,100 tokens  (6.1%)
# Memory:             2,800 tokens  (1.4%)
# Project files:     45,300 tokens (22.7%)
# Conversation:      28,600 tokens (14.3%)
# Available:        108,000 tokens (54.0%)
# --- 健康状态：上下文使用率 46.0% ---

步骤 2：创建最优 .claudeignore

# 基于项目特征生成 .claudeignore
cat > .claudeignore << 'EOF'
# 依赖
node_modules/
.pnpm-store/
​
# 构建产物
dist/
.next/
build/
coverage/
​
# 日志
*.log
logs/
​
# 环境文件
.env
.env.*
!.env.example
​
# IDE
.idea/
.vscode/
*.swp
​
# 大型文件
*.zip *.tar.gz *.mp4 *.mov
*.png *.jpg *.svg
​
# 测试 fixtures（通常不需要上下文注入）
test/fixtures/
tests/__fixtures__/
​
# 自动生成的文件
*.generated.*
*-lock.json
EOF

步骤 3：启用缓存监控

# 在 ~/.claude/settings.json 中开启缓存日志
cat >> ~/.claude/settings.json << 'EOF'
{
  "contextEngineering": {
    "cacheLogging": true,
    "warnThreshold": 60,
    "compressThreshold": 85,
    "autoTruncate": true
  }
}
EOF

步骤 4：定期检查上下文健康度

# 每周运行一次上下文健康检查
/claude context health
​
# 输出：
# Context Health Report (2026-05-26)
# ==================================
# Average usage: 38.2% ✓ (target: <40%)
# Cache hit rate: 91.4%  ✓ (target: >90%)
# Files loaded avg: 52    (filtered from 3,120 files)
# .claudeignore effectiveness: 98.3%
# Rating: EXCELLENT

---

避坑指南

坑 1：把 CLAUDE.md 当"万能配置文件"

现象：把所有配置、规则、偏好、文档全部塞进 CLAUDE.md，文件膨胀到 2000+ 行，每次对话光加载 CLAUDE.md 就消耗 15,000 tokens。 解法：CLAUDE.md 应该只是一个"指针文件"——引用 rules/、memory/、skills/ 中的内容，而非包含它们。CLAUDE.md 本身不超过 100 行。

坑 2：忽略工具调用本身的上下文成本

现象：一个 Grep 返回 500 行结果，全部注入上下文，瞬间吃掉 20,000 tokens。 解法：在提示词中约束工具使用——"Grep 结果超过 50 行时，只展示前 10 行和后 10 行，中间用...省略"。

坑 3：没有设置上下文压缩阈值

现象：默认设置下，Claude Code 在上下文使用率达到 80% 才触发压缩，此时模型已经进入"哑区"。 解法：在 settings.json 中将 compressThreshold 设为 85% 以下（建议 60-70%），提前触发压缩。

坑 4：Memory 文件不区分场景全部加载

现象：Memory 有 15 个文件，MEMORY.md 把它们全部标记为"全量加载"，导致基础上下文就占了 10,000 tokens。 解法：严格分级。只有 user-preferences 和 project-context 是全量加载，其余全部标记为"按需加载"。

---

课后作业

1. 基础练习：运行 /claude context breakdown 查看当前项目的上下文分布。找出最大的 3 个 Token 消耗源，逐一制定优化方案并执行。

2. 进阶练习：为你的项目编写一份极致精简的 .claudeignore，目标是过滤掉至少 90% 的非必要文件。然后对比过滤前后的 Token 消耗差异。

3. 挑战练习：设计一套上下文工程自动化脚本，在每次提交前自动执行：

   • 检查 CLAUDE.md 是否超过 100 行

   • 检查 Memory 文件是否有过期内容

   • 统计 .claudeignore 的过滤效率

   • 生成上下文健康报告 将脚本集成到 pre-commit hook 中。

---

总结

上下文工程是 AI 工程的"隐形竞争力"——它不会让你的代码输出更漂亮，但会让你的 Claude Code 始终保持在最佳性能区间。

四个核心原则：

1. Select 要狠：不是"可能有用的都放进去"，而是"没明确理由的都不放"

2. Write 要有结构：上下文不是堆砌，是排版

3. Compress 要早：60% 就开始压缩，不要等到 90% 再救火

4. Isolate 要彻底：每个任务有独立的上下文空间，避免信息交叉污染

记住最关键的一句话：Claude Code 的能力上限不是你写了多好的 prompt，而是你给它构造了多好的上下文。