【Claude Code-System Prompt实测】CLAUDE.md、工具定义与 MCP 描述的上下文膨胀：请求前缀的 token 生命周期
非线智能API经验 [Claude Code-System Prompt实测] 第12篇
摘要
Claude Code 的初始上下文会随着项目规则、工具定义和 MCP 描述持续膨胀。这里需要先纠正一个常见说法：不应简单写成“CLAUDE.md 注入 system prompt”。Claude Code 官方 memory 文档的表述更精确：CLAUDE.md 会进入初始上下文 / project context，并在 system prompt 之后作为 user message 提供，而不是 Anthropic 顶层 system 本体。
即便如此，CLAUDE.md、工具定义和 MCP 描述仍然属于请求前缀治理范围。它们会消耗输入 token，影响 prompt cache 边界，也会改变模型注意力分布。对 coding agent 来说，这些内容不是一次性配置，而是每个 session 甚至每轮请求都可能重复进入上下文的固定成本。
数据来源：非线智能Nonlinear 官网
证据层级
官方文档可支撑 CLAUDE.md 进入初始上下文 / project context、工具定义进入模型上下文、token counting 可估算请求 token、context engineering 应保持上下文 high-signal。Piebald-AI、dbreunig 等资料只能作为社区观测或逆向观察，用来说明工具 / MCP / system prompt 体积问题，不用于断言 Claude Code 当前内部实现。
初始上下文不等于顶层 system
Claude Code 请求前缀可以拆成多类内容：
| 内容 | 是否一定属于 Anthropic 顶层 system |
是否影响 token / cache |
|---|---|---|
| Claude Code 内置 agent 指令 | 通常是 system 级指令 | 是 |
CLAUDE.md |
官方更精确说法是 project context / system 后 user message | 是 |
| 工具定义 | 请求级 tools，模型上下文的一部分 | 是 |
| MCP 工具描述 | 通常进入工具 / 上下文描述 | 是 |
| beta 能力开关 | provider / request metadata | 可能 |
| cache control | provider cache hint | 是 |
| attribution block | 动态 metadata，不应进入稳定前缀 | 是，如果未剥离 |
因此，文章和实现都应使用“初始上下文 / 请求前缀”这个更宽的概念，而不是把所有膨胀都归到顶层 system 字段。
工具定义为什么会变成大头
Anthropic tool use 文档说明，工具定义通过 API 提供给模型；Claude API 会根据 tools 参数、tool config 和用户 system prompt 构造 tool-use system prompt，因此工具定义本身是模型上下文成本的一部分。一个工具不只是名字，还包括 description、JSON Schema、参数说明、枚举、嵌套对象、约束文本。coding agent 常见工具数量多，schema 复杂，description 为了提高模型调用准确率又会写得很长。
工具定义的 token 成本通常来自：
1、工具数量。
2、每个工具 description 的自然语言长度。
3、JSON Schema 嵌套层级。
4、枚举值和字段说明。
5、MCP server 自动暴露的大量工具。
6、工具列表排序不稳定导致 cache key 抖动。
如果每轮都把全部工具暴露给模型，即使用户只需要读文件，也可能携带部署、数据库、浏览器、云服务等完全无关工具。
MCP 描述的膨胀风险
MCP 的价值是让 agent 发现和使用外部能力，但它也会放大上下文体积。一个 MCP server 可能暴露：
• 工具列表。
• resource templates。
• 参数 schema。
• server 描述。
• 安全说明。
• 示例和错误语义。
多个 MCP server 同时启用时，system / tool 前缀可能从“几十个工具”膨胀到“上百个可选动作”。这会带来两类问题：
| 问题 | 表现 |
|---|---|
| 成本问题 | 输入 token、cache write token、延迟上涨 |
| 注意力问题 | 模型在大量无关工具之间选择，误调用概率上升 |
Anthropic 的 context engineering 建议可以概括为：上下文是有限资源，应保持 informative but tight。工具集和 MCP 描述越臃肿，模型越容易在低信号上下文中产生歧义；更好的目标是 high-signal、minimal viable tools，而不是“能暴露的全部暴露”。
token budget 应该分层
建议给请求前缀设置预算，而不是只看总上下文窗口：
type PrefixBudget = {
builtinSystemMaxTokens: number;
projectContextMaxTokens: number;
toolDefinitionsMaxTokens: number;
mcpDescriptorsMaxTokens: number;
liveWindowMaxTokens: number;
};
一个可操作的策略：
| Segment | 默认策略 |
|---|---|
| Builtin System | 固定版本，严禁运行时拼接动态信息 |
| Project Context | 使用文件 hash，超过预算时摘要 |
CLAUDE.md |
保留高优先级规则，移除长篇教程 |
| Tools | 按当前任务选择子集 |
| MCP | 按 server / namespace 懒加载 |
| Live Window | 保留最近状态，旧工具结果摘要化 |
按需暴露工具
“所有工具都给模型看”是最简单但成本最高的策略。更好的方式是两阶段：
1、Planner 阶段只暴露工具类别和少量核心工具。
2、执行阶段根据任务激活具体工具 schema。
例如：
用户：修复测试
第一轮暴露：read_file, search, run_tests
需要浏览器时再暴露：browser_navigate, browser_click, screenshot
需要部署时再暴露：deploy, canary_check
这样做的前提是兼容层有工具能力索引，而不是把工具数组当作不可分割的大 JSON。
兼容层应自建的观测指标
下面这些不是 Anthropic Token Counting 直接返回的官方字段。官方 token counting 可以估算包含 system / tools 等内容的请求 token；per-segment token 需要兼容层通过分段构造请求、差分计数、schema hash 和本地 tokenizer 估算组合得到。至少记录：
• prompt.total_tokens
• prompt.builtin_system_tokens
• prompt.project_context_tokens
• prompt.claude_md_tokens
• prompt.tool_definition_tokens
• prompt.mcp_descriptor_tokens
• tools.count
• mcp.server_count
• mcp.tool_count
• prefix.cacheable_tokens
• prefix.churn_tokens
当 tool_definition_tokens + mcp_descriptor_tokens 超过总输入的某个阈值时，应触发工具裁剪或 MCP 懒加载。
更完整的 token profile、prefix diff 和 HMAC 日志设计见第 14 篇 请求前缀可观测性。
失败模式
| 失败模式 | 触发原因 | 修复策略 |
|---|---|---|
| 输入 token 持续上涨 | CLAUDE.md、MCP、工具描述无预算 |
segment budget |
| cache miss 变多 | 工具 / MCP 顺序不稳定 | canonical sort |
| 模型误调用工具 | 暴露太多无关工具 | 按需工具暴露 |
| 规则被稀释 | CLAUDE.md 太长，关键信息埋没 |
提炼为项目约束摘要 |
| 文档表述不严谨 | 把 CLAUDE.md 写成顶层 system |
改成 project context / 初始上下文 |
验证清单
• 统计一个真实项目的 CLAUDE.md token 数，并在超过预算时给出摘要策略。
• 启用多个 MCP server，确认工具和 MCP 描述 token 数可单独观测。
• 打乱工具顺序，canonical hash 应保持不变。
• 按任务只暴露工具子集，确认模型仍能完成常见工作流。
• 构造长 CLAUDE.md，确认关键规则不会被摘要丢失。
• 记录 cache hit rate，比较全量工具暴露和按需暴露的差异。
参考链接
• Claude Code Memory
• Claude Code Modifying system prompts
• Anthropic Token Counting
• Anthropic Define Tools
• Anthropic Engineering: Effective context engineering for AI agents
• Piebald-AI/claude-code-system-prompts
• dbreunig: How Claude Code Builds a System Prompt
• On the Use of Agentic Coding Manifests
• Decoding the Configuration of AI Coding Agents
本文由非线智能API Claude Code 行业专家整理编写
