Claude Code 最佳实践：上下文管理与上下文工程——Anthropic 官方指南

影响团队 AI 成本模型的关键决策，不是选哪个模型——而是单次 coding agent 会话实际消耗了多少 token。Anthropic 在 code.claude.com/docs/en/best-practices 发布的 Claude Code 官方最佳实践指南，首次明确给出了一个统领全局的约束：上下文窗口填充很快，LLM 性能随填充程度下降。对通过 API 网关路由 Claude Code 的团队而言，这不是 UX 建议，而是成本与可靠性信号，直接影响 token 预算建模、会话可观测性和 fallback 路由策略。

发生了什么

Anthropic 发布了 Claude Code 的全面官方最佳实践指南，该工具是其基于终端的自主编程环境。这份指南权威、覆盖 Anthropic 内部工程工作流，并围绕一个核心资源约束构建：上下文窗口预算。

指南明确的核心模式：

上下文窗口是首要管理资源。 Claude Code 会话中的每次文件读取、每条命令输出、每条消息都会累积到上下文窗口。一次调试或代码探索会话可能消耗数万 token。随着窗口填满，模型开始遗忘早期指令并产生更多错误。指南明确要求工程师通过自定义状态栏持续跟踪上下文使用情况。

探索-规划-编码分阶段减少无效上下文消耗。 推荐的四阶段工作流（在只读"规划模式"探索 → 生成计划 → 实现 → 提交）不只是为了提升输出质量，也是为了减少实现开始前积累的文件读取和工具调用。每次不必要的读取都是不可回收的 token 消耗。

CLAUDE.md 是运营者配置的核心原语。 /init 命令生成一个跨会话持久化的 CLAUDE.md 文件。指南明确指出：保持简短，删除模型可从代码中推断的内容，并通过观察 Claude 行为变化来验证效果。臃肿的 CLAUDE.md 会在每次会话启动时浪费 token，并可能导致 Claude 忽略真正重要的规则。

并行子 Agent 会将上下文成本倍增。 指南支持同时运行多个 Claude Code Agent 处理独立任务。每个并行会话有自己的上下文窗口、独立的模型调用，并累积独立的 token 消耗。三个并行 Agent 进行大型代码库探索时，可能以 3 倍单会话的速率消耗 token——且没有跨会话的 token 共享。

Skills 是按需注入的上下文。 Skills（从 CLAUDE.md 引用的领域特定 .md 文件）仅在调用时加载，不在会话启动时全部加载。这是指南处理大型知识库的推荐方式——只加载当前任务所需内容。

为什么对 AI 工程团队重要

Claude Code 最佳实践指南实质上是一份以工作流指南形式呈现的 token 消耗架构文档。每条建议都可以用成本语言重新表达：

验证循环减少重跑次数。 指南中杠杆效益最高的建议是给 Claude 提供自我验证的方式——测试、预期输出、Lint 结果。路由层面的含义：没有验证循环，失败的会话需要完全重启，每次重启都从头消耗一个新的上下文窗口。一个团队运行 10 次 Claude Code 会话才产出一个好结果，实际支付的是 10 个上下文预算，而非 1 个。

规划模式是廉价的预读。 规划模式阻止 Claude 在探索过程中执行编辑。从 token 角度看，这很重要，因为它避免了工具调用响应（文件写入、命令确认）的累积——这些内容比纯读取更快膨胀上下文。团队可以将"先规划"作为一种成本规范推广。

并行会话需要独立计费归因。 大多数 API 计费只显示汇总 token 使用量。如果你的团队使用 sub-agent 运行 Claude Code，网关遥测需要按会话而非按请求归因 token 消耗。一个启动 5 个并行 Claude Code Agent 的用户会产生 5 路并发 token 流——若可观测层不按会话 ID 分段，每路都将不可见。

CLAUDE.md 漂移是隐性成本。 如果工程师只往 CLAUDE.md 添加内容而不删减，每次会话启动成本会越来越高。在大规模管理 Claude Code 的团队应像对待依赖清单一样对待 CLAUDE.md——作为具有每次会话 token 成本的配置工件来审计。

路由与运营视角

对通过路由网关路由 Claude Code API 调用的团队：

上下文触发的 fallback 是一个新需求。 标准路由 fallback 逻辑在 provider 报错、限速或延迟阈值时触发。Claude Code 引入了一个新的触发条件：上下文窗口耗尽。当会话上下文填满、模型开始退化时，正确的响应可能不是重试同一模型——而是路由到上下文窗口更大的模型，或通知 harness 启动新会话。这要求网关具备上下文窗口感知能力，而不仅仅是错误感知。

Agent 会话的 token 成本建模与对话会话不同。 对话 API 调用通常是有界的——用户发送消息、获取响应。Claude Code 会话在设计上是无界的：Agent 读取文件、运行命令、迭代，可能持续数分钟或数小时。在对话场景下看起来廉价的 $0.003/千 token 模型，如果 Agent 在实现前探索了大型代码库，可能每次编程会话产生 $2–$5 的账单。基于单请求成本假设制定预算的团队会显著低估实际消耗。

会话可观测性需要跟踪上下文填充速率，而非仅请求数量。 指南建议通过自定义状态栏持续显示上下文填充百分比。网关层面的等价指标是将每次会话的上下文窗口使用率作为时间序列记录，而不仅仅是每次请求的总 token 数。这些数据能让你在失控会话耗尽配额前及时发现——并在会话上下文填充率超过 70%（性能开始下降的临界点）时发出告警。

并行 Agent 工作流需要按 Agent 计费归因。 如果团队为每位开发者分配独立 API Key 使用 Claude Code，可以获得按开发者的消耗，但无法区分会话或任务粒度。如果通过共享网关 Key 路由，则只能获得汇总消耗而失去个人归因。正确的设置是网关同时按用户身份和会话 ID 分段——这样才能在不手动解析日志的情况下回答"上周哪个任务消耗的上下文最多"。

CLAUDE.md 的路由类比：系统提示管理。 指南中的 CLAUDE.md 模式在网关层有直接对应物：系统提示管理。以环境特定 CLAUDE.md 配置 Claude Code 的团队（生产 vs. 预发布、前端 vs. 后端 monorepo）实际上是在不同情境下设置不同的系统提示。如果这些会话通过网关路由，网关应将 CLAUDE.md 衍生的配置视为一个策略维度，而不是不可见的用户端配置。

值得关注和尝试的事项

• 按会话而非按请求衡量上下文填充率。 如果你的网关日志只显示总 token 而不显示会话内的上下文窗口使用率，就错过了 Agent 工作负载的首要成本驱动因素。添加会话 ID 标签，并将上下文填充率作为指标追踪。

• 在并行工作流扩展前设置单会话消费告警。 指南明确支持并行 sub-agent。在你的团队开始同时运行 5 个 Agent 之前，先在网关层设置每用户或每会话的消费告警，以便在失控会话耗尽每日配额前及时发现。

• 每季度审计 CLAUDE.md 的 token 成本。 做一个粗略估算：CLAUDE.md 行数 × 每天平均会话数 × 每 token 成本。如果超过总消耗的 5%，就值得做一次删减。指南建议只保留 Claude 无法从代码中推断的内容——把这当成成本规范而不仅仅是清晰度原则。

• 配置上下文溢出路由策略。 如果你的路由层支持，定义当 Claude Code 会话请求超出模型上下文限制时应发生什么——是触发升级到更大上下文窗口的模型变体、重置会话，还是发出告警。优雅处理的上下文溢出对开发者不可见；处理不当则会产生难以调试的无声质量下降。

TheRouter 在模型提供商之间路由 API 调用，并按会话记录 token 级别使用情况。对于 Claude Code 工作流，关键的遥测补充是会话 ID 跟踪和每会话的上下文窗口使用率——使 token 成本模型能反映 Agent 的真实情况：单次开发者任务可能跨越数十次 API 调用，共享一个上下文预算。