Chapter 06

上下文管理

如何在有限的 context window 中管理不断增长的对话 — 从 System Prompt 构建到 Memory 系统再到上下文压缩。

System Prompt 构建

System Prompt 通过多层组装构建（src/context.ts）：

基础 Prompt (DEFAULT_AGENT_PROMPT)

定义 Claude Code 的基本角色、行为规范、工具使用指南。位于 src/constants/prompts.ts。

环境信息注入

enhanceSystemPromptWithEnvDetails() 添加：当前目录、Shell 类型、Git 分支、OS 版本、模型信息。

CLAUDE.md 内容

从项目层级中发现并加载所有 CLAUDE.md 文件的内容。

用户/系统上下文

prependUserContext() 注入 memory 路径、文件根目录。appendSystemContext() 添加系统级上下文。

Cache-Eligible Block

最终的 System Prompt 作为 BetaSystemPromptBlock 传入 API，支持 prompt caching。

CLAUDE.md 加载机制

CLAUDE.md 是项目级指令文件，src/utils/claudemd.ts 负责发现和加载：

// CLAUDE.md 搜索顺序 (从高优先级到低)
搜索路径:
1. 当前目录/CLAUDE.md         ── 项目级指令
2. 当前目录/.claude/CLAUDE.md  ── .claude 子目录
3. 父目录/CLAUDE.md           ── 向上遍历
4. ~/.claude/CLAUDE.md         ── 用户级指令

// 加载到 System Prompt 中
const claudeMdContent = await loadClaudeMd(projectRoot);
systemPrompt += formatClaudeMdSection(claudeMdContent);

CLAUDE.md 的作用： 它是项目级别的"永久指令"，告诉 Claude Code 如何处理这个特定的代码库。比如构建命令、代码风格、架构约定等。每次对话都会自动加载。

Memory 系统

Claude Code 有一个基于文件的持久化记忆系统，存储在 ~/.claude/projects/ 目录下：

Memory 类型

user (用户记忆)

记录用户角色、偏好、知识背景。帮助后续对话个性化响应。

feedback (反馈记忆)

用户对 Claude 行为的纠正和确认。避免重复犯同样的错误。

project (项目记忆)

进行中的工作、目标、Bug、截止日期等项目信息。

reference (参考记忆)

外部系统中信息的指针 — Linear 项目、Grafana 仪表盘等。

// Memory 文件结构
// ~/.claude/projects/{project-hash}/memory/
---
name: user_role
description: 用户是高级后端开发，熟悉 Go 和 Rust
type: user
---

用户是高级后端开发，主要使用 Go 和 Rust。
在 React 方面是新手，需要更详细的前端解释。

// MEMORY.md — 索引文件 (始终加载到上下文)
- [用户角色](user_role.md) — 高级后端开发，Go/Rust 专长
- [测试偏好](feedback_testing.md) — 集成测试优先，不要 mock DB

Compaction 压缩策略

随着对话增长，上下文会超出 token 限制。Claude Code 有多种压缩策略：

Auto Compact

触发条件： Token 数超过动态计算的阈值，且已经过至少 20 个 turn
执行过程： 调用模型生成对话摘要 → 替换历史消息 → 在消息中插入 SystemCompactBoundaryMessage 标记
Hook 集成： PreCompact hook 可以追加压缩指令或阻止压缩

Snip Compact

轻量级： 不需要模型推理，直接删除中间消息
保留关键消息： 最后几条消息 + 工具结果被保护
速度快： 适合在每个 turn 开始前快速执行

Reactive Compact

主动式： 实时监控 token 预算
提前介入： 在接近 max_output_tokens 限制前触发
Feature-gated： 需要特定功能标志开启

正常对话

Token < 阈值

→

Snip Compact

删除中间消息

→

Auto Compact

模型生成摘要

→

Reactive

紧急压缩

Token Budget 管理

Claude Code 有两种不同的预算概念：

Token Budget (会话级)

整个会话的 token 使用预算。超过时会触发 auto-continue 功能（+500k token）或停止对话。通过 query/tokenBudget.ts 跟踪。

Task Budget (Turn 级)

单个 Agent turn 的预算。Beta 功能 (task-budgets-2026-03-13)。预算用完时提前结束 turn。

Thinking 模式

Claude Code 支持模型的"思考"能力 — 让模型在回答前先进行推理：

Adaptive (默认)： 模型自行决定是否需要思考
Explicit： 用户通过 /think 或系统提示请求思考
Disabled： 不生成 thinking blocks
Max Thinking Length： 默认 10,000 tokens，可配置

Extended Thinking： Thinking blocks 会被保留在消息历史中（有规则限制：不能是最后一个 block），用于维护模型的推理链。在上下文压缩时也会被纳入摘要。