上下文工程：别再教 AI 说话，开始给它设计信息环境

任务跑到第 40 轮，你发现 agent 正在改一个它二十轮前已经改过的文件，还把你们刚删掉的旧接口调用又加了回来。

你没换模型。你没改提示词。你只是让它跑得久了一点。

这不是错觉，也不是模型今天状态不好。它是一个有名字、有机制、有对策的工程问题。过去两年，行业把大部分精力花在”怎么把话说清楚”上——提示词工程。但当 agent 开始连续跑几十轮工具调用、读上百个文件、跨越几个小时，决定成败的已经不是你那句话写得好不好，而是每一轮送进模型的那几万个 token 里，到底装了什么。

这就是上下文工程要管的事。

这份教程会给你什么

读完之后，你能做四件现在做不了的事：

1. 诊断：看到 agent 开始犯蠢，你能说出具体是哪一类问题——是状态丢了、检索脏了、结论被埋了，还是上下文里两份规范在互相打架。
2. 盘点：你能说清自己的上下文窗口里装了什么、谁占了大头、哪些是常驻成本、哪些是每轮累积。
3. 动手：你会用四个动作——写、选、压、隔——对症下药，而不是一遇到问题就清空重开。
4. 落地：你能为一个真实仓库产出一份可执行的上下文预算方案，并用一张量规自检。

全书围绕同一个项目展开：shopfront，一个多人维护的 Node + React 电商前台，约 1200 个文件。任务是把结算流程从内部 v1 API 迁到 v2 并补齐测试——一个典型的、会跨越几十轮和几个小时的长任务。四个动作在这个仓库里全都用得上。

需要什么前置

你会用终端和 git，用过至少一个 AI 编程 agent（Claude Code、Codex CLI、Cursor 都行），知道 token 和上下文窗口大概是什么意思。不假设你读过任何官方文档，也不假设你了解模型内部结构。

如果”上下文窗口”这个词你还没什么概念，可以先读主站那篇《什么是上下文窗口》，十分钟。

怎么读

第 1、2 章建立判断力：先弄明白为什么会变笨，再学会盘点。这两章不动手，但后面九章都建立在它们之上，不要跳。

第 3 章是全书的枢纽，给出一张症状-动作决策矩阵。第 4、5 章处理常驻成本（系统提示、工具定义），第 6 到 9 章逐个展开四个动作，每章一个可复用的产物。

第 10 章把所有东西装进一次三小时的真实任务，第 11 章是实战演练——你自己的仓库，你自己的方案。

本书涉及的工具字段名、命令名和默认阈值都会随版本变化。正文里凡是提到具体字段或数值的地方，都会提醒你去核对当前版本的官方文档。方法本身比字段名活得久。