This is the sixth article in a series on agentic engineering and AI-driven development. Read part one here, part two here, part three here, part four here, and part five here.这是关于代理工程和 AI 驱动开发系列的第六篇文章。阅读第一部分 here，第二部分 here，第三部分 here，第四部分 here，第五部分 here。
I think context management is one of the most important skills in AI-driven development, and it’s weird that compared to other AI-related topics, almost nobody talks about it. We talk about prompt engineering, about which model to use, about agentic workflows and tool use. But more than anything else, the thing that actually determines whether your AI session produces good work or mediocre work is how well you manage context (or if you even do it at all!).我认为上下文管理是 AI 驱动开发中最重要的技能之一，而奇怪的是，与其他 AI 相关主题相比，几乎没有人谈论它。我们讨论提示工程，讨论使用哪种模型，讨论代理工作流和工具使用。但最关键的是，决定你的 AI 会话产出好作品还是平庸作品的，正是你对上下文的管理程度（或者根本没有管理！）。
A lot of developers using AI tools treat all this “context” talk as AI jargon that can be dismissed, and it’s not hard to understand why. AI development tools have gotten so easy that an experienced developer can be incredibly effective by just combining vibe coding with critical thinking (that’s the central idea behind the Sens-AI Framework), and not really think about context at all. That’s ironic, because despite all the “I’m functionally illiterate but I just vibe coded an entire multitenant SaaS platform” articles, and despite everyone’s general concern that AI will put all developers out of work, the development skills you’ve been working on for years make you especially effective at writing code with AI—and context management is where those skills really shine.很多使用 AI 工具的开发者把所有的“上下文”讨论当作可以忽略的 AI 行话，这并不难理解。AI 开发工具已经变得如此易用，以至于有经验的开发者只需把即兴编码与批判性思维结合（这正是 Sens-AI 框架的核心理念），根本不必考虑上下文。这很讽刺，因为尽管有大量“我功能盲目但即兴编码完成了整个多租户 SaaS 平台”的文章，也尽管大家普遍担心 AI 会让所有开发者失业，你多年来锻炼的开发技能让你在使用 AI 编码时尤其高效——而上下文管理正是这些技能大放异彩的地方。
Just to make sure we’re all on the same page, context is (basically) everything the AI is thinking about right now: your prompt, the conversation so far, the files it’s read, the decisions you’ve made together. When you start a fresh session with an AI, its context is wiped clean, and it starts fresh with just the initial instructions it’s been given. Managing context is central for building AI agents and skills. But it’s also really important when you’re using tools like Claude Code, Cursor, or Copilot for day-to-day development work. Context is typically measured in tokens, and there’s a finite amount of it. When the context window, or the maximum amount of information (input and output tokens) an AI model can process and retain at once, fills up, the AI starts losing track of things, and that’s when you start to see it give wrong and weird answers.为了确保大家在同一页面上，上下文基本上就是 AI 此刻在思考的所有内容：你的提示、迄今为止的对话、它读取的文件、你们共同做出的决定。当你开启一个全新的 AI 会话时，它的上下文会被清空，只保留最初给出的指令。管理上下文是构建 AI 代理和技能的核心，但在使用 Claude Code、Cursor 或 Copilot 等日常开发工具时同样重要。上下文通常以 token 为单位衡量，且是有限的。当上下文窗口（即 AI 模型一次能够处理和保留的最大信息量，包括输入和输出 token）被填满时，AI 会开始失去对信息的跟踪，这时你会看到它给出错误或奇怪的答案。
Unfortunately a lot of developers read paragraphs like the last one and their eyes glaze over. Somehow it gets classified in the same part of our brains as learning how our build systems work: boring stuff we somehow don’t really want to think about because it takes us away from “real” programming. That’s a shame, because when we don’t understand the basics of how context works we waste a lot of time.不幸的是，很多开发者读到上面这段文字时会走神。它在我们的大脑中被归类为类似于学习构建系统的内容：枯燥的东西，我们不想去思考，因为它把我们从“真正的”编程中拉走。这很可惜，因为当我们不了解上下文的基本原理时，会浪费大量时间。
For example, here’s something I see developers do all the time that they absolutely shouldn’t. They’re deep into an AI coding session, and the AI has built up a detailed understanding of their codebase (e.g., it’s noticed patterns, it’s making good decisions, etc.). Then they start seeing “Compacting conversation” messages, or they notice the little context usage indicator in Cursor or Copilot filling up, and they don’t really know what that means. But they learned that closing the session and starting a new one seems to fix the problem. Unfortunately, all they’ve done is trade compaction for total amnesia. The new session just keeps going, producing output that looks fine, but it’s giving worse answers and generating worse code because it’s working from incomplete information.例如，我经常看到开发者做的事其实不该这么做。他们正深入一次 AI 编码会话，AI 已经对他们的代码库建立了详细的理解（比如注意到了模式，做出了不错的决定等）。随后他们看到“压缩对话”提示，或注意到 Cursor 或 Copilot 中的小上下文使用指示器快满了，却不太明白这意味着什么。但他们学到的经验是，关闭会话并重新开始似乎能解决问题。实际上，他们只是把压缩换成了彻底失忆。新会话虽然继续产生看似正常的输出，却因为信息不完整而给出更差的答案和代码。
The really weird thing is that I was writing about something really similar all the way back in 2006, long before AI was around, in Applied Software Project Management: Missing requirements are especially insidious because they’re difficult to spot. I was writing about requirements, not AI context, but the problem is the same. I’ve written about how prompt engineering is requirements engineering, and this is another place where the parallel holds up. When a requirement is missing, there’s no artifact to flag it, you just end up with code that doesn’t do what it’s supposed to do. When context is missing from an AI session, there’s no error message telling you what the AI forgot; you just end up with worse answers.真正奇怪的是，我早在 2006 年就在《应用软件项目管理》中写到类似的内容，那时 AI 还不存在。缺失的需求尤其隐蔽，因为它们难以被发现。我写的是需求，而不是 AI 上下文，但问题是一样的。我曾写过提示工程就是需求工程，这里同样适用。当需求缺失时，没有工件来标记它，你最终得到的代码并不能完成预期功能。当 AI 会话缺失上下文时，也没有错误信息告诉你 AI 忘了什么；你只会得到更差的答案。
The cost of poor context management is actually measurable. A developer on Microsoft’s Dev Blog recently timed his own reorientation overhead and found he was spending over an hour a day just reexplaining things to his AI that it had known in a previous session. He’s not alone. There are now entire frameworks and managed services dedicated to giving agents persistent memory, from lightweight CLIs that query Copilot’s local session database to managed memory services from Cloudflare. Some of these tools are genuinely useful, but they’re solutions you need to evaluate, integrate, and maintain before they help you.糟糕的上下文管理成本是可以量化的。Microsoft Dev Blog 的一位开发者最近测算了自己的重新定位开销，发现他每天花超过一小时向 AI 重新解释之前会话中已经知道的内容。他并非唯一如此。现在已有完整的框架和托管服务致力于为代理提供持久记忆，从查询 Copilot 本地会话数据库的轻量 CLI 到 Cloudflare 的托管记忆服务。这些工具确实有用，但它们是需要在帮助你之前进行评估、集成和维护的解决方案。
My goal in this article and the next is to give you four specific things you can do today, using whatever AI tools you’re already working with. This article covers the problem: why context management matters and how context loss affects the quality of your AI’s output. The next article covers the specific practices that emerged from building the Quality Playbook and Octobatch, things you can bring back to your own prompts, skills, and agents immediately. I’ll use real examples from those projects, because I think they’ve got some good examples that you can draw on.本文及下一篇的目标是给你四个今天就能使用的具体做法，使用你已经在用的任何 AI 工具。本文阐述问题：为什么上下文管理重要以及上下文丢失如何影响 AI 输出质量。下一篇则介绍从构建 Quality Playbook 和 Octobatch 中产生的具体实践，你可以立刻把它们带回自己的提示、技能和代理中。我会使用这些项目的真实案例，因为我认为它们提供了可以借鉴的好例子。
We get AI wrong in both directions我们在两个方向上都把 AI 用错了
I think the through line through all of this is that developers both overestimate and underestimate AI. We overestimate how much it can hold in its memory and its ability to remember things and make decisions for us. So we’ll just stuff a whole bunch of stuff in the context window and assume the AI will work it out, and then get annoyed when it hallucinates or forgets.我认为贯穿始终的线索是：开发者既高估又低估 AI。我们高估它能记住多少以及为我们做决定的能力。所以我们会把大量内容塞进上下文窗口，假设 AI 能自行处理，随后当它出现幻觉或忘记时就会恼火。
On the other hand, we massively underestimate its ability as an orchestrator. Your prompt doesn’t just have to ask a question or ask the AI to generate something. You can give it a multistep workflow where each step writes its results to files, and the AI will coordinate the whole thing, spinning off subtasks and picking up where it left off if something breaks.另一方面，我们极度低估它作为编排者的能力。你的提示不仅仅是提问或让 AI 生成内容。你可以给它一个多步骤工作流，让每一步把结果写入文件，AI 会协调整个过程，分派子任务，并在出现故障时继续上一次的工作。
When developers don’t take either of those things seriously, context management or orchestration, you get a specific cycle. They treat the context window as infinite and cram everything in. Then when the session gets too long and the AI starts losing track, they throw it all away and start fresh. They never consider the alternative, which is designing the workflow so the AI works from externalized files across independent sessions.当开发者不认真对待这两件事——上下文管理或编排时，就会出现特定的循环。他们把上下文窗口当作无限的，塞满所有内容。然后会话太长、AI 开始失去跟踪时，他们把所有东西丢掉重新开始，从不考虑另一种方式——即设计工作流，让 AI 在独立会话之间通过外部化文件工作。
I discovered this while building the Quality Playbook. The context management was working so well inside my sessions that I realized the sessions themselves were the bottleneck. I was running the playbook in a single prompt. I think I had a record of over 15 million tokens in a single Copilot GPT-5.4 session that ran for hours, and I did eight of them in parallel. Which incidentally is why I got rate-limited for 54 hours from Copilot, which is completely fair.我在构建 Quality Playbook 时发现了这一点。上下文管理在我的会话中运行得如此顺畅，以至于我意识到会话本身成了瓶颈。我在单个提示中运行了该手册。我记得在一次单独的 Copilot GPT-5.4 会话中累计超过 1500 万 token，持续数小时，并行运行了八个。顺带一提，这也是我被 Copilot 限流 54 小时的原因，这完全公平。
The playbook was writing everything down to files as it went, which is why those runs could last that long at all. But I didn’t want that behavior. Running 15 million tokens in a single session is expensive, and if you’re on pay-as-you-go API tokens instead of a flat-rate plan like Copilot or Claude Max or Cursor, that kind of usage can be a real shock. I wanted to make the playbook available to developers who don’t want to burn that much at once. And because the context was already externalized to files, splitting into independent phases turned out to be easy.手册会在运行时把所有内容写入文件，这也是这些运行能够持续如此之久的原因。但我并不想要这种行为。一次会话运行 1500 万 token 成本高昂，如果你使用按使用量计费的 API token 而不是像 Copilot、Claude Max 或 Cursor 那样的固定费率计划，这种使用量会让人吃惊。我想让手册对不想一次性消耗这么多资源的开发者也可用。而且因为上下文已经外部化到文件，拆分为独立阶段变得很容易。
Ask the AI to write its context down along the way让 AI 在过程中写下它的上下文
Before I get into how the pipeline splits things up, I want to talk about the practice that made the split possible in the first place: storing development context in files as you go.在讲解管道如何拆分之前，我想先谈谈最初让拆分成为可能的实践：在开发过程中将上下文存入文件。
I don’t mean asking the AI to export its notes at the end of a session, or writing up a “lessons learned” document after the fact. I mean baking it into the actual instructions you give the AI from the start, so it’s continually writing and updating context as it works. For Octobatch, the batch LLM orchestrator that was my first experiment in agentic engineering (I wrote about the development process in “The Accidental Orchestrator”), I had the AI write developer context in every folder, and that really made it easy to spin up a new session.我不是指让 AI 在会话结束时导出笔记，或事后写一份“经验教训”文档。我指的是从一开始就在给 AI 的指令中嵌入，让它在工作时不断写入和更新上下文。对于 Octobatch——我在代理工程中的首次实验（我在《意外的编排者》中写过开发过程），我让 AI 在每个文件夹中写入开发者上下文，这让启动新会话变得非常容易。
Here’s what that looks like in practice. Every new Claude Code session on Octobatch starts with a single line: “Read ai_context/DEVELOPMENT_CONTEXT.md and bootstrap yourself to continue development.” That file contains a loading sequence: read this first, then fan out to component-level CONTEXT.md files in scripts/, tui/, pipelines/, each describing its own subsystem at the right level of detail. By the time the AI finishes reading, it knows what the project is, how it’s built, what’s currently in progress, and what the active bugs are.实际操作如下。Octobatch 的每个新 Claude Code 会话都以一行开头：“读取 ai_context/DEVELOPMENT_CONTEXT.md 并自举以继续开发”。该文件包含加载顺序：先读取此文件，然后展开到 scripts/、tui/、pipelines/ 中的组件级 CONTEXT.md 文件，每个文件都在合适的细节层级描述其子系统。等 AI 读完后，它就知道项目是什么、如何构建、当前进展以及活跃的 bug。
I think of this as shifting left. Instead of putting constraints in every prompt (don’t use additionalProperties: false, always test with –limit 3), those rules live in the CONTEXT.md files. The prompt stays clean because the documentation does the heavy lifting.我把这称为左移。不是把约束写进每个提示（比如不要使用 additionalProperties: false，始终使用 –limit 3 测试），而是把这些规则放在 CONTEXT.md 文件中。提示保持简洁，因为文档承担了繁重的工作。
And updating context files is part of every task. Before we commit anything, I have the AI review the context files and make sure they reflect what we just did. If we added a feature or fixed a bug, the context file should reflect that before we commit. Stale context causes the same kinds of problems as stale documentation, except it’s worse because the AI is actually relying on it to make decisions.更新上下文文件是每个任务的一部分。在提交任何内容之前，我让 AI 审核上下文文件，确保它们反映我们刚刚完成的工作。如果我们添加了功能或修复了 bug，上下文文件应在提交前更新。过时的上下文会导致与过时文档相同的问题，只是更糟，因为 AI 实际上依赖它来做决定。
I want to be clear exactly what I mean by “development context.” Specifically, it’s the information a new AI session needs to get up to speed: what the project is, how it’s built, and what decisions have been made along the way. Tools like Claude Code read development context from files like AGENTS.md (and you can actually go to that website to learn more) at the start of every session, and if you do a thorough enough job of building up your development context and keeping it up-to-date, you can get them fully bootstrapped. They’re the blueprints for your AI sessions. I wrote in Applied Software Project Management that building software without requirements is similar to building a house without blueprints. Running AI sessions without externalized context is the same mistake. You’re relying on what’s in someone’s head instead of what’s written down. And when you’re working with AI, “someone’s head” is a context window that’s going to get compacted or thrown away.我想明确说明我所说的“开发上下文”到底指什么。具体来说，它是新 AI 会话需要快速了解的信息：项目是什么、如何构建、以及已经做出的决定。Claude Code 等工具会在每个会话开始时从类似 AGENTS.md 的文件读取开发上下文（你甚至可以访问该网站了解更多），如果你充分且及时地构建并维护你的开发上下文，它们就能完全自举。它们相当于 AI 会话的蓝图。我在《应用软件项目管理》中写道，没有需求的开发软件就像没有蓝图的建房。没有外部化上下文运行 AI 会话是同样的错误。你依赖的是某个人脑中的信息，而不是书面的记录。而当你与 AI 合作时，“某个人的脑子”就是会被压缩或丢弃的上下文窗口。
The most important thing is that what’s in my head matches what’s in the AI’s head. The context file is just a convenient way to help us figure out whether or not we agree. When I start a new Claude Code session on a folder that has a good DEVELOPMENT_CONTEXT.md, the AI reads it and we’re immediately aligned. When I start a session without one, the AI has to rediscover everything from scratch, and it always misses things. Rediscovery is always lossy.最重要的是，我脑中的内容要与 AI 脑中的内容保持一致。上下文文件只是帮助我们判断是否一致的便利方式。当我在一个包含良好 DEVELOPMENT_CONTEXT.md 的文件夹中启动新的 Claude Code 会话时，AI 读取它，我们立刻保持一致。若没有该文件，AI 必须从头重新发现一切，往往会遗漏信息。重新发现总是有损失的。
If you’re not already writing context files as part of your workflow, none of the fancier techniques I’m about to describe matter. This is the foundation.如果你还没有把上下文文件写入工作流，那么我接下来要描述的各种高级技巧都没有意义。这是基础。
Include the why, or the AI will undo your decisions加入原因，否则 AI 会撤销你的决定
There’s a specific thing that has to go into these context files, and it took me a while to learn why it matters so much: the reasoning behind every decision.这些上下文文件必须包含一件特定的内容，我花了一段时间才明白它为何如此重要：每个决定背后的推理。
Octobatch’s DEVELOPMENT_CONTEXT.md has a section called “Key Technical Learnings” with 49 entries, each in a specific format: What happened, Why it matters, When we discovered it, and Where in the code it applies. At the top of that section is a note in bold: “IMPORTANT: Always include the REASONING (the ‘Why’) for each learning. This prevents future sessions from ‘refactoring’ a deliberate decision.”Octobatch 的 DEVELOPMENT_CONTEXT.md 有一节叫“关键技术学习”，包含 49 条条目，每条遵循特定格式：发生了什么、为什么重要、何时发现、以及代码中的位置。该节顶部有一条加粗提示：“重要：始终为每条学习记录包含推理（‘为什么’）。这可以防止未来的会话‘重构’有意的决定。”
That note is there because without it, the AI will do exactly that. I had a case with Octobatch where we used recursive set_timer() instead of set_interval() for auto-refresh because Textual’s set_interval() callbacks aren’t reliably serviced on pushed screens. Without the “Why” in the context file, a future session would look at that code, see a “cleaner” alternative, and helpfully refactor it right back to the broken approach.之所以加这条提示，是因为如果没有它，AI 会真的这么做。我曾在 Octobatch 中使用递归 set_timer() 而不是 set_interval() 来实现自动刷新，因为 Textual 的 set_interval() 回调在推送屏幕上并不可靠。如果上下文文件中没有“为什么”，后续会话会看到这段代码，发现一个“更干净”的替代方案，并好心地把它重构回有缺陷的实现。
The same principle applies to quality standards. Don’t just say “90% coverage for core logic.” Say “90% coverage for core logic, because expression evaluation touches randomness and seeding, where subtle bugs produce plausible-but-wrong output. The drunken sailor reseeding bug passed all visual inspection. Only statistical verification caught that sequential seeds created correlation bias (77.5% fell in water instead of a theoretical 50/50).” Without the “why,” a future AI session will argue the coverage target down. Any standard or architectural decision or unusual code pattern that doesn’t have its rationale attached is vulnerable to being optimized away by an AI that doesn’t know what problem it was solving.同样的原则适用于质量标准。不要只写“核心逻辑 90% 覆盖率”。要写“核心逻辑 90% 覆盖率，因为表达式求值涉及随机性和种子设置，细微的 bug 会产生看似合理却错误的输出。酗酒的水手重新种子 bug 通过所有视觉检查，只有统计验证发现顺序种子导致相关性偏差（77.5% 落入水中，而理论上应为 50/50）”。没有“为什么”，未来的 AI 会话会削弱覆盖目标。任何没有附带理由的标准、架构决定或异常代码模式，都容易被不懂问题背景的 AI 优化掉。
The garbage collection problem垃圾回收问题
A lot of people like to talk about the context window as your AI’s short-term or working memory, and context that’s persisted to disk as long-term memory. Personally, I’m not sure those analogies to human memory work all that well. I think it’s a lot more useful to find ways to think about context that are similar to how we manage memory in our code.很多人喜欢把上下文窗口比作 AI 的短期或工作记忆，而把持久化到磁盘的上下文比作长期记忆。个人而言，我并不认为这些类比与人类记忆完全匹配。更有用的是把上下文想象成我们在代码中管理内存的方式。
I find it especially helpful to compare context compaction to garbage collection—again, not a perfect analogy but a useful one. When you look at a GC graph in Java, you see the memory slowly fill up and then suddenly drop after each GC. That drop is the runtime figuring out what’s still being referenced and freeing everything else.我尤其喜欢把上下文压缩比作垃圾回收——同样不是完美的类比，但很有帮助。当你在 Java 中查看 GC 图时，会看到内存慢慢填满，然后在每次 GC 后突然下降。下降的部分是运行时判断哪些仍被引用并释放其余的内存。
The context window does the same thing. Your conversation accumulates tokens, the AI’s context window fills up, and then compaction happens. The tool (or the model) decides what to keep and what to throw away. Compaction is lossy and automatic, and you don’t control what survives.上下文窗口的工作方式类似。你的对话累计 token，AI 的上下文窗口被填满，然后进行压缩。工具（或模型）决定保留什么、丢弃什么。压缩是有损且自动的，你无法控制哪些信息会被保留。
Java developers spent decades learning to design their allocation patterns so garbage collection wouldn’t destroy anything important. AI developers need to learn the same thing, and the learning curve should be shorter because the concepts transfer directly.Java 开发者花了数十年学习如何设计分配模式，以免垃圾回收破坏重要数据。AI 开发者也需要学习同样的东西，而且学习曲线应该更短，因为概念可以直接迁移。
When you ask the AI to write important state to files, you’re promoting it out of that volatile space. It’s surprisingly easy to do this. Just pass the AI to write its context to a Markdown file. For example, you can put all of the context related to a specific domain into a particular file, like if the AI noticed a behavioral contract, you could have it write all the related context to a file called CONTRACTS.md. If it made a design decision, that could go into DEVELOPMENT_CONTEXT.md—that’s a pattern I use all the time to write down all the important contacts needed to bootstrap a new AI session to work on the code. Those files live on disk, outside the context window, and compaction can’t touch them. But if you start a new session without externalizing any of this, you’re shutting down the application and losing everything that was in memory.当你让 AI 将重要状态写入文件时，就把它提升出了易失的空间。这非常容易实现。只需让 AI 将上下文写入 Markdown 文件。例如，你可以把与特定领域相关的所有上下文写入一个文件，如果 AI 发现了行为契约，就让它把所有相关上下文写入 CONTRACTS.md。如果它做出设计决定，就写入 DEVELOPMENT_CONTEXT.md——这是我常用的模式，用来记录启动新 AI 会话所需的所有关键上下文。这些文件存放在磁盘上，位于上下文窗口之外，压缩无法触及。但如果你在没有外部化这些内容的情况下启动新会话，就相当于关闭应用并失去所有内存中的信息。
The first time I built Octobatch’s batch orchestrator, it was a Python script with in-memory state and a lot of hope. It worked for small batches but fell apart at scale, which is pretty much what most developers are doing with their AI context right now: keeping everything in the context window and hoping it holds together, even though that stops working once sessions get long and codebases get complex.我第一次构建 Octobatch 的批处理编排器时，它是一个带有内存状态的 Python 脚本，充满了希望。它在小批量时还能工作，但在规模扩大时就崩溃了，这正是大多数开发者目前对 AI 上下文的做法：把所有内容都放在上下文窗口中并寄希望于它能保持完整，然而一旦会话变长、代码库变复杂，这种方式就失效了。
It’s way too easy to fall into one context management extreme or the other很容易在两种极端的上下文管理之间跌入陷阱
The Quality Playbook exists in part because of this problem. When I was building the requirements pipeline, I discovered that single-pass requirement generation runs out of attention after about 70 requirements. The model forgets behavioral contracts it noticed earlier. And it’s completely invisible. You don’t get a stack trace or an error message or any kind of warning, just incomplete output and no way to know what’s missing.Quality Playbook 的出现正是为了解决这个问题。当我构建需求管线时，发现单遍需求生成在大约 70 条需求后注意力就会耗尽。模型会忘记之前注意到的行为契约。而且这完全不可见。你不会得到堆栈跟踪、错误信息或任何警告，只会得到不完整的输出，却不知道缺失了什么。
The longer a defect goes uncorrected, the more entrenched it becomes and the more things get built on top of it. Context drift works the same way. When the AI loses track of a design decision early in a session, everything built on that lost context compounds the error. And just like a late-discovered defect, you don’t know what went wrong because the original context is gone.缺陷存在的时间越长，就越根深蒂固，越多的东西会在其上构建。上下文漂移也是同理。当 AI 在会话早期失去对设计决定的跟踪时，所有基于该失踪上下文的后续工作都会放大错误。就像后期才发现的缺陷，你也不知道哪里出错，因为原始上下文已经消失。
I had a concrete example when I was running the playbook against virtio-win. Version 1.3.32 found four bugs. Version 1.3.33, after some changes, found only one. That regression was only diagnosable because I had EXPLORATION.md, an externalized intermediate state file that captures what the AI observed during its exploration phase. Without it, the only observable output would have been “fewer bugs this time.” I had no way to tell whether the playbook was worse, or the bugs were harder, or it had just missed something. Without externalized state, I couldn’t have answered any of those questions.我在对 virtio-win 运行手册时有一个具体例子。1.3.32 版发现了四个 bug。1.3.33 版在做了一些改动后只发现了一个。之所以能够诊断出这次回归，是因为我有 EXPLORATION.md——一个外部化的中间状态文件，记录了 AI 在探索阶段观察到的内容。没有它，唯一可见的输出就是“这次 bug 更少”。我无法判断手册是否变差、bug 是否更难找，还是它只是漏掉了什么。没有外部化状态，我根本无法回答这些问题。
The contracts file in the pipeline exists specifically to solve this. When the model forgets about a behavioral contract it noticed earlier, that forgetting is normally invisible. But with a contracts file, every observation is written down before any requirements work begins. If a contract is in the file but has no corresponding requirement, that’s a visible, greppable gap. You can see what was forgotten and fix it.管线中的 contracts 文件正是为了解决这个问题。当模型忘记之前注意到的行为契约时，这种遗忘通常是不可见的。但有了 contracts 文件，每一次观察都会在开始需求工作前记录下来。如果文件中有契约却没有对应的需求，这就是一个可见、可 grep 的缺口。你可以看到被遗忘的内容并加以修复。
But it’s just as easy to overcompensate. If the LLM has to constantly hop between eight different reference files, its context window fragments and you start getting hallucinations. I’ve seen this happen. You load all your context files and requirements documents and design docs into the session, and the AI gets worse, not better. It spends all its attention navigating between reference files instead of thinking about the problem.但同样容易过度补偿。如果 LLM 必须在八个不同的参考文件之间不断跳转，它的上下文窗口会被碎片化，进而产生幻觉。我见过这种情况。你把所有上下文文件、需求文档和设计文档都加载进会话，AI 反而变得更差，因为它把全部注意力花在在参考文件之间切换，而不是思考问题本身。
I hit this with the Quality Playbook when I expanded the scope of a run against virtio-win from 10 files to about 60. The result was 6x more files analyzed but 75% fewer bugs found. The model burned its context on device drivers instead of going deep on the transport layer where the bugs actually were. Wider scope meant shallower analysis.我在扩展对 virtio-win 的运行范围时遇到了这种情况：从 10 个文件扩大到约 60 个。结果分析的文件增加了 6 倍，但发现的 bug 减少了 75%。模型把上下文消耗在设备驱动上，而没有深入传输层——真正的 bug 所在。范围扩大导致分析变浅。
The goal isn’t to save everything. You have to decide what to externalize, what to keep in context, and what to let go. The best context file contains exactly what the AI needs for this session and nothing more.目标不是保存所有东西。你必须决定哪些外部化、哪些保留在上下文、哪些舍弃。最佳的上下文文件恰好包含 AI 本次会话所需的全部信息，且不多余。
Helping your AI manage its context helps you too帮助你的 AI 管理上下文也会帮助你
The interesting thing about all of this is that good context management really makes use of your development expertise, and it’s one of those things that makes you a better developer the more you do it. Every practice I’ve described in this article, writing down your decisions, recording why you made them, being deliberate about what goes into a session and what doesn’t, is something developers have always been told to do. We write ADRs and design docs and inline comments explaining nonobvious choices, and we all know we should do more of it. When you’re working with AI, the cost of not doing it becomes immediate and visible. Your context files end up being the project documentation you should have been writing all along, except now there’s something on the other end that will actually go wrong if you skip it.有趣的是，良好的上下文管理实际上利用了你的开发专长，这也是让你在实践中变得更好的因素。本文中描述的每项实践——记录你的决定、记录为何做出这些决定、有意识地决定会话中包含什么、不包含什么——都是开发者一直被告知要做的事。我们写 ADR、设计文档和内联注释来解释不显而易见的选择，我们都知道应该多做这些。当你与 AI 合作时，不做这些的代价会立刻显现。你的上下文文件最终会成为你本应一直在写的项目文档，只是现在有了一个会真正因为你跳过它而出错的对手。
And once you start thinking about context as something you actively manage, you can start designing your workflows around it. That’s what happened with the Quality Playbook, when it went from a single 15-million-token session to a set of independent phases with clean handoffs between them, and the whole split worked on the first try because the context was already externalized to files.一旦你把上下文视为需要主动管理的东西，就可以围绕它设计工作流。这正是 Quality Playbook 的转变：从单个 1500 万 token 会话拆分为一系列独立阶段，并在它们之间进行干净的交接，之所以一次成功，就是因为上下文已经外部化到文件。
In the next article, I’ll get into the specific techniques you can use today in your AI agents, but also in your day-to-day AI development work.
The Quality Playbook is open source and works with GitHub Copilot, Cursor, and Claude Code. It’s also available as part of awesome-copilot.在下一篇文章中，我将介绍你今天就能在 AI 代理以及日常 AI 开发工作中使用的具体技术。Quality Playbook 是开源的，兼容 GitHub Copilot、Cursor 和 Claude Code。它也在 awesome‑copilot 中可用。
Disclosure: Aspects of the approach described in this article are the subject of US Provisional Patent Application No. 64/044,178, filed April 20, 2026 by the author. The open-source Quality Playbook project (Apache 2.0) includes a patent grant to users of that project under the terms of the Apache 2.0 license.披露：本文所述方法的部分内容已于 2026 年 4 月 20 日由作者提交美国临时专利申请号 64/044,178。开源的 Quality Playbook 项目（Apache 2.0）在 Apache 2.0 许可证条款下向该项目的用户授予专利许可。
