Ask an engineering leader how to get more value from AI coding agents, and the conversation usually turns to models. They’ll talk about newer models, larger context windows, stronger reasoning, or more capable agent architectures. That focus is understandable; models supply much of the visible intelligence in an AI system.问一位工程领导者如何从 AI 编码 Agent 中获得更多价值,谈话通常会转向模型。他们会谈论更新的模型、更大的上下文窗口、更强的推理能力或更强大的 Agent 架构。这种关注是可以理解的,因为模型提供了 AI 系统中大部分可见的智能。
But organizations are increasingly discovering that model capability alone does not determine the result. The same model can perform very differently depending on the information it receives.1 Give an agent an unclear objective, incomplete requirements, outdated architectural guidance, or irrelevant documentation, and it may spend its time (and tokens) making a plausible but incorrect assumption or confidently produce the wrong result. Give it a clear task, relevant supporting information, and appropriate constraints, and the outcome can be dramatically better.但各组织正日益发现,仅凭模型能力并不能决定结果。同一个模型根据其接收到的信息,表现可能会大相径庭。如果给 Agent 一个模糊的目标、不完整的需求、过时的架构指南或不相关的文档,它可能会花费时间(和 Token)做出合理但错误的假设,或者自信地产生错误的结果。如果给它一个明确的任务、相关的支持信息和适当的约束,结果可能会好得多。 This is not an entirely new problem. Software organizations have long struggled to document decisions, preserve institutional knowledge, keep information current, and help people find what they need. Knowledge management,7 information retrieval,22 requirements engineering,32 and technical communication all address important parts of that challenge. AI agents do not make those disciplines obsolete. In many ways, they expose the cost of neglecting them.这并非一个全新的问题。软件组织长期以来一直在为记录决策、保留机构知识、保持信息更新以及帮助人们找到所需内容而苦恼。知识管理、信息检索、需求工程和技术交流都在解决这一挑战的重要部分。AI Agent 并未使这些学科过时。在许多方面,它们反而暴露了忽视这些学科的代价。 What is new is the role that assembled context now plays in the engineering system. An agent may draw from source code, specifications, issue trackers, chat histories, architectural documents, tool output, and user instructions, then act on that combination with limited human supervision. Information that was written for different audiences, at different times, and for different purposes is brought together into a temporary operating environment for a particular task. Whether each source is individually useful does not reveal whether the resulting context is fit for the work the agent is being asked to do.新变化在于组装的上下文在工程系统中现在所扮演的角色。Agent 可能会从源代码、规范、问题跟踪器、聊天记录、架构文档、工具输出和用户指令中获取信息,然后在有限的人工监督下对这些信息组合采取行动。为不同受众、在不同时间、出于不同目的编写的信息,被汇集到一个特定任务的临时运行环境中。每个源本身是否有用,并不能说明由此产生的上下文是否适合 Agent 被要求执行的工作。
That creates a gap between several established concerns. Knowledge management asks whether useful information exists and is maintained. Retrieval systems determine whether that information can be found. Context engineering focuses on selecting and assembling it for a model. Less clearly defined is how to evaluate the quality of the assembled context itself. Is it clear enough to interpret? Does it support action? Does it accurately represent current reality? Is it focused enough to be useful? Is it safe and appropriate for the agent to consume?这在几个既定关注点之间造成了差距。知识管理关注是否有用的信息存在并得到维护。检索系统确定是否能找到这些信息。上下文工程专注于为模型选择和组装信息。而如何评估组装的上下文本身的质量,定义尚不明确。它是否足够清晰以便解释?它是否支持操作?它是否准确反映了当前的现实?它是否足够聚焦以发挥作用?它是否安全且适合 Agent 使用?
These questions matter, because software engineering is becoming a collaborative system in which a human developer works together with agents to deliver software. When the working context is poor, developers compensate by locating missing information, clarifying requirements, correcting misunderstandings, and recovering from avoidable errors. When it is good, agents become more reliable collaborators, and developers can spend more of their effort on the engineering judgment that requires them most.这些问题很重要,因为软件工程正在成为一种协作系统,人类开发人员与 Agent 协同交付软件。当工作上下文质量较差时,开发人员通过查找缺失信息、澄清需求、纠正误解和从可避免的错误中恢复来弥补。当上下文质量良好时,Agent 会成为更可靠的协作者,开发人员可以将更多的精力投入到最需要他们的工程判断上。
This article proposes CAFE(S), a framework for describing the quality of context assembled for an AI system. CAFE(S) is organized around five dimensions: clarity, actionability, fidelity, efficiency, and security. It does not prescribe a retrieval architecture or a particular method of context engineering. Instead, it provides a shared language for asking whether the resulting context gives a human-agent system the conditions it needs to work effectively. The parenthetical S reflects that security complements the other four dimensions by asking a different question about the same context. We return to that distinction later.本文提出了 CAFE(S),这是一个用于描述为 AI 系统组装的上下文质量的框架。CAFE(S) 围绕五个维度组织:清晰度、可操作性、保真度、效率和安全性。它不规定检索架构或特定的上下文工程方法。相反,它提供了一种共享语言,用于询问所产生的上下文是否为人机系统提供了有效工作所需的条件。括号中的 S 反映了安全性通过对同一上下文提出不同的问题来补充其他四个维度。我们稍后会回到这一区别。
CAFE(S) is deliberately a definition for high-quality context; it is not a measurement system. The goal of this article is to describe these properties clearly enough that teams can discuss them, review context for them, and intervene when they are missing. A clearer definition may also create the foundation for future work to measure context quality and examine its relationship to agent performance, developer experience, and software outcomes.CAFE(S) 特意定义了高质量上下文;它不是一个测量系统。本文的目标是足够清晰地描述这些属性,以便团队可以讨论它们、针对它们审查上下文,并在它们缺失时进行干预。更清晰的定义也可能为未来评估上下文质量并研究其与 Agent 性能、开发人员体验和软件成果之间的关系奠定基础。
The sections that follow explain why context quality has become an operational concern, define what is meant by context and where it sits in the larger AI system, describe each CAFE(S) property, examine common failure patterns, and offer practical guidance for individuals and teams.接下来的章节将解释为什么上下文质量已成为一个运营问题,定义上下文的含义及其在大型 AI 系统中的位置,描述每个 CAFE(S) 属性,检查常见的故障模式,并为个人和团队提供实践指导。
Why Context Quality Matters Now为什么上下文质量现在很重要
AI does not create a new need for good knowledge management; it dramatically increases the cost of poor knowledge management. Context has always mattered. What has changed is not its importance, but that its consequences are now experienced immediately, at scale, and in ways that are often directly measurable. Poor context now carries a bill you can read on an invoice, a liability you can be sued over, and a drag on developer experience that compounds every day.AI 并没有产生对良好知识管理的新需求,而是极大地增加了糟糕的知识管理的代价。上下文一直很重要。改变的不是其重要性,而是其后果现在被立即、大规模地体验到,且往往是直接可衡量的。糟糕的上下文现在带来了一张你可以从发票上读到的账单、一项你可能被起诉的责任,以及一种每天都在累积的对开发人员体验的拖累。
Three forces—developer experience, cost, and liability—have turned what was once an abstract organizational concern into a first-order engineering problem.三种力量——开发人员体验、成本和责任——已经将曾经抽象的组织问题转变为首要的工程问题。
Developer Experience开发人员体验
The most common cost of poor context is also the least visible, because it appears as friction rather than a line item. When context is unclear, an agent guesses. When it is incomplete, the agent produces something plausible but wrong. When it is stale, the agent confidently applies a policy that no longer exists. Every one of those failures lands on a developer, who now has to notice the problem, diagnose it, re-explain what they wanted, and try again.糟糕上下文最常见的代价也是最不明显的,因为它表现为摩擦而非具体的项目支出。当上下文不清晰时,Agent 会进行猜测。当上下文不完整时,Agent 会产生看似合理但错误的结果。当上下文过时时,Agent 会自信地应用不再存在的策略。每一个这样的失败都落到了开发人员身上,他们现在必须发现问题、诊断问题、重新解释他们的需求并再次尝试。
The collaboration has broken down, not because either participant lacks capability, but because they were not operating from the right information. Developers have always spent time compensating for poor knowledge, documentation, and communication. AI changes the scale and frequency of those interactions by making context the input to nearly every task an agent performs. The agent is supposed to remove toil, but poor context hands it back.协作破裂了,不是因为任何一方缺乏能力,而是因为他们没有基于正确的信息进行操作。开发人员一直花费时间来弥补糟糕的知识、文档和沟通。AI 通过使上下文成为 Agent 执行几乎每项任务的输入,改变了这些交互的规模和频率。Agent 本应消除繁琐工作,但糟糕的上下文又将其带回。
This is why context quality is not simply an infrastructure concern or an optimization for AI systems. It is a direct input to developer experience.9 Healthy context creates the conditions under which humans and agents can collaborate effectively. Poor context forces humans to spend their time compensating for avoidable mistakes.这就是为什么上下文质量不仅仅是一个基础设施问题或 AI 系统的优化。它是开发人员体验的直接输入。健康的上下文创造了人类和 Agent 可以有效协作的条件。糟糕的上下文迫使人类花费时间来弥补可避免的错误。 Cost成本
Context is also where the economics of agentic software become visible. Every token sent to an agent carries a cost, and context is where those tokens accumulate. When Notion engineered its context for reuse through prompt caching, its costs dropped by roughly 90 percent while maintaining output quality, because reading cached context costs substantially less than repeatedly transmitting the same information.2 Relevance pays as well as reuse. When Meta precomputed concise context files for a data pipeline spanning multiple repositories and more than 4,100 files, agents completed tasks using roughly 40 percent fewer tool calls and tokens.12上下文也是 Agent 软件经济学显现的地方。发送给 Agent 的每个 Token 都有成本,而上下文正是这些 Token 积累的地方。当 Notion 通过提示缓存 (prompt caching) 设计其可重用的上下文时,其成本降低了约 90%,同时保持了输出质量,因为读取缓存的上下文成本远低于重复传输相同的信息。相关性与重用同样有价值。当 Meta 为跨越多个存储库和超过 4,100 个文件的代码库预计算简洁的上下文文件时,Agent 使用的工具调用和 Token 减少了约 40%。 Organizations that repeatedly send large, redundant, or poorly structured context are paying more than organizations that engineer context to be lean, reusable, and task-specific. As agents tackle longer-running workflows and more autonomous tasks, the financial consequences of context quality grow alongside them.那些反复发送庞大、冗余或结构不良上下文的组织,其支付的成本高于那些将上下文设计得精简、可重用且特定于任务的组织。随着 Agent 处理更长期的工作流和更自主的任务,上下文质量的财务后果也随之增长。
Liability责任
Poor context also creates organizational risk. Whether the underlying failure is stale information, incomplete context, or hallucination, organizations remain accountable for what their agents communicate. In February 2024, the British Columbia Civil Resolution Tribunal found Air Canada liable for a refund its customer-service chatbot promised but the company’s actual policy did not provide.6 Air Canada argued that the chatbot was effectively responsible for its own statements. The tribunal disagreed, holding that the company remained accountable for information presented through its chatbot just as it would be for information on any other part of its website. The damages were modest. The precedent was not.糟糕的上下文也会产生组织风险。无论潜在的失败是信息过时、上下文不完整还是幻觉,组织仍对其 Agent 的沟通负责。2024 年 2 月,卑诗省民事调解法庭裁定加拿大航空对其聊天机器人承诺但公司实际政策未提供的退款负责。加拿大航空辩称聊天机器人实际上对其自身的陈述负责。法庭不同意,裁定该公司对其通过聊天机器人呈现的信息负责,就像对其网站任何其他部分的信息负责一样。赔偿金额不大,但先例并非如此。 The stakes rise further when the context itself is compromised. In June 2025, researchers disclosed EchoLeak (CVE-2025-32711), the first documented prompt-injection attack to achieve real-world data exfiltration from a production AI system.29 A single crafted email, never opened by the user, caused Microsoft 365 Copilot to retrieve sensitive internal documents into its working context and leak their contents. Months later, CamoLeak (CVE-2025-59145) demonstrated the same class of attack against GitHub Copilot Chat using hidden instructions embedded within a pull request.24当上下文本身受到损害时,风险会进一步上升。2025 年 6 月,研究人员披露了 EchoLeak (CVE-2025-32711),这是第一个被记录的从生产 AI 系统中实现现实数据泄露的提示注入攻击。一封精心制作的电子邮件(用户从未打开)导致 Microsoft 365 Copilot 将敏感的内部文档检索到其工作上下文中并泄露其内容。几个月后,CamoLeak (CVE-2025-59145) 展示了针对 GitHub Copilot Chat 的同类攻击,利用了嵌入在拉取请求中的隐藏指令。 Neither system was “hacked” in the traditional sense. Untrusted information simply became part of the agent’s context, and the agent faithfully acted upon it. If the context is compromised, the reasoning built on top of it will be compromised as well.两个系统都没有在传统意义上被“黑”。不受信任的信息只是成为了 Agent 上下文的一部分,而 Agent 忠实地根据它采取了行动。如果上下文受到损害,建立在它之上的推理也会受到损害。
This broader concern also connects to prior work on a Triple Debt Model by Storey.30 The model argues that, in addition to technical debt技术债务, a project may accumulate cognitive debt认知债务 when a team’s understanding of the system’s behavior, structure, and history is never fully established or gradually erodes over time.这种更广泛的关注也与 Storey 之前关于三重债务模型 (Triple Debt Model) 的工作有关。该模型认为,除了技术债务外,当团队对系统行为、结构和历史的理解从未完全建立或随着时间推移逐渐侵蚀时,项目可能会积累认知债务。 It also describes intent debt意图债务, which is the erosion of explicit rationale, goals, and constraints that are needed by developers and agents to evolve the system effectively over time. CAFE(S) may be useful in identifying when intent debt is manifesting to the point that the context provided to the agents is insufficient and causing operational issues. An organization can carry intent debt invisibly for years, but the moment someone delegates work to an agent, only the knowledge present in the assembled context remains available. Whatever intent was never made explicit is simply absent.它还描述了意图债务 (intent debt),即开发人员和 Agent 随着时间的推移有效地演进系统所需的显式基本原理、目标和约束的侵蚀。CAFE(S) 可能有助于识别意图债务何时表现到提供给 Agent 的上下文不足并导致运营问题的程度。一个组织可以隐形地承担意图债务多年,但一旦有人将工作委派给 Agent,只有组装的上下文中存在的知识仍然可用。任何从未明确表达的意图都只是缺失了。
None of this suggests that better context is a cure-all or that a well-provisioned agent can safely operate without oversight. The claim is narrower, and we believe, more useful. Context quality has become a first-order determinant of what agentic software costs, how safely it behaves, and whether humans can rely on it as an effective collaborator. That is reason enough to define what good context actually is.这些都没有暗示更好的上下文是万灵药,或者配置良好的 Agent 可以在没有监督的情况下安全运行。这一主张更狭窄,我们认为也更有用。上下文质量已成为 Agent 软件成本、行为安全性以及人类是否可以将其作为有效协作者依赖的首要决定因素。这足以定义什么是好的上下文。
What Is Context?什么是上下文?
The rapid rise of AI engineering has introduced a growing vocabulary: prompt engineering, retrieval-augmented generation (RAG), context engineering, harness engineering, agent frameworks, memory systems, and model evaluation. Each addresses a different part of building effective AI systems, yet they all assume a more fundamental question that has received comparatively little attention.AI 工程的迅速兴起引入了越来越多的词汇:提示工程、检索增强生成 (RAG)、上下文工程、Harness 工程、Agent 框架、记忆系统和模型评估。每一个都解决了构建有效 AI 系统的不同部分,但它们都假设了一个受到相对较少关注的更基本的问题。
To answer the question of what makes context “good” first requires being precise about what is meant by context上下文.要回答什么使上下文“好”的问题,首先需要准确定义上下文的含义。
At its most basic level, context is the set of information available to an agent while it performs a task. For a language model, it is the collection of tokens considered during inference. It is the instructions it receives, the task description, code and documentation, retrieved knowledge, tool outputs, memory from previous interactions, and any other information presented before generating a response. Everything an agent produces is ultimately a function of that context.在最基本的层面上,上下文是 Agent 在执行任务时可用的信息集。对于语言模型,它是推理过程中考虑的 Token 集合。它是它接收的指令、任务描述、代码和文档、检索到的知识、工具输出、来自先前交互的记忆以及在生成响应之前呈现的任何其他信息。Agent 产生的一切最终都是该上下文的函数。
Context engineering上下文工程 is the practice of deciding what belongs in that set. As the field has matured, attention has shifted from prompt engineering—crafting individual instructions—to the broader challenge of assembling, maintaining, and updating the right information throughout an agent’s workflow. Anthropic describes context engineering as ensuring the optimal set of tokens during inference.1 Context engineering is fundamentally a practice. It describes how如何 context is assembled; it does not tell us whether the resulting context is actually good.上下文工程是决定什么属于该集合的实践。随着该领域的发展,注意力已从提示工程(制作个人指令)转移到在 Agent 工作流中组装、维护和更新正确信息的更广泛挑战。Anthropic 将上下文工程描述为确保推理过程中 Token 的最佳集合。上下文工程本质上是一种实践。它描述了上下文是如何组装的;它并没有告诉我们由此产生的上下文是否真的好。 Before context quality can be evaluated, more fundamental knowledge-management concerns must already have been addressed. Information must exist, be accessible, be connected to the agent, and be discoverable through retrieval. These have been central concerns of knowledge management and information retrieval for decades,7,22 and AI amplifies rather than replaces them. CAFE(S) deliberately begins after those prerequisites have been satisfied. It asks how to evaluate quality once the relevant information has been assembled into an agent’s working context.在评估上下文质量之前,必须已经解决了更基本的知识管理问题。信息必须存在、可访问、连接到 Agent,并通过检索可发现。几十年来,这些一直是知识管理和信息检索的核心关注点,而 AI 放大而非取代了它们。CAFE(S) 特意在这些先决条件得到满足后开始。它询问一旦相关信息被组装到 Agent 的工作上下文中,如何评估质量。 To understand where that missing question fits, it helps to separate the major layers of an AI system.为了理解那个缺失的问题在哪里适合,将 AI 系统的主要层分开会有所帮助。
Intent → Context → Harness → Model
意图 → 上下文 → Harness → 模型
This simple pipeline describes how human intent becomes machine behavior.这个简单的管道描述了人类意图如何成为机器行为。
Intent意图 is what a person ultimately wants to accomplish. That intent must then be translated into context, which is the information that represents the task, its constraints, and the surrounding knowledge. A harnessHarness applies that context through orchestration, retrieval, tools, memory, and execution logic before passing it to a model模型, which supplies the underlying intelligence that produces a result.意图是人最终想要完成的事情。该意图必须转换为上下文,即代表任务、其约束和周围知识的信息。Harness 通过编排、检索、工具、记忆和执行逻辑应用该上下文,然后将其传递给模型,模型提供产生结果的基础智能。
Each layer has become the focus of its own engineering discipline. Advances in machine learning improve models. Agent and harness engineering improve how those models are orchestrated.4 Product and software engineering improve how human intent is captured, refined, and communicated. Yet relatively little work has focused on the translation between intent and the context that captures and represents it, despite that translation increasingly determining whether even highly capable agents succeed or fail.每一层都已成为其自身工程学科的重点。机器学习的进步改进了模型。Agent 和 Harness 工程改进了这些模型的编排方式。产品和软件工程改进了人类意图的捕获、细化和沟通方式。然而,相对较少的工作集中在意图与捕获并代表它的上下文之间的转换上,尽管这种转换日益决定了即使是能力很强的 Agent 是成功还是失败。 CAFE(S) deliberately focuses on one layer of that pipeline: the translation from intent to context. It is a framework neither for evaluating models nor for designing harnesses. Instead, it provides a way to reason about whether the context handed to an agent faithfully represents what a human is actually trying to accomplish.CAFE(S) 特意关注该管道的一层:从意图到上下文的转换。它既不是评估模型的框架,也不是设计 Harness 的框架。相反,它提供了一种方式来推理传递给 Agent 的上下文是否忠实地代表了人类实际上试图完成的事情。
What Makes Context Good?什么使上下文好?
Before handing anything to an agent, you can ask what a capable person would need to do the same task well. They would need to understand the goal, have the relevant background, know the constraints that apply, and have some way to recognize when the work is correct. An agent needs much the same information, usually in much the same form. Rather than thinking of good context as an exotic new artifact, you can think of it as what a competent colleague would need to do the job, if that colleague could not easily lean over and ask a follow-up question.在将任何东西交给 Agent 之前,你可以询问一个有能力的人需要什么才能很好地完成同样的任务。他们需要理解目标、有相关的背景、知道适用的约束,并有一种方法来识别工作何时是正确的。Agent 需要大致相同的信息,通常以大致相同的形式。与其将好的上下文视为一种奇异的新工件,不如将其视为一个称职的同事如果不能轻易地凑过来问后续问题时需要什么才能完成工作。
Good context好的上下文 is defined by what it enables. Context is good when it lets a human–agent system accomplish its intended task correctly, efficiently, and safely. It gives the agent enough information to reason instead of guess, grounds its work in current and trustworthy information, keeps its attention on what matters, and avoids exposing information it should never have received. With poor context, agents compensate by guessing, reasoning from stale or conflicting information, wasting effort searching through noise, or acting on information they should never have been given.好的上下文由它所能实现的功能定义。当上下文使人机系统能够正确、高效且安全地完成其预期任务时,它就是好的。它为 Agent 提供了足够的信息进行推理而不是猜测,将其工作建立在当前且值得信赖的信息基础上,使其注意力集中在重要的事情上,并避免暴露它本不应该收到的信息。在上下文较差的情况下,Agent 通过猜测、基于过时或冲突的信息进行推理、浪费精力搜索噪声或根据本不应该给出的信息采取行动来弥补。
Because good context is ultimately defined by the results it produces, CAFE(S) does not replace that definition; instead, it answers the narrower and more useful question of what context tends to look like when it reliably leads to good outcomes. The framework in the next section is our answer to that question. Rather than prescribing how context should be assembled, CAFE(S) names five enduring properties that separate healthy context from unhealthy—the characteristics most likely to produce good outcomes—and gives teams a shared language for evaluating the information that agents are asked to work from.因为好的上下文最终由它产生的结果定义,CAFE(S) 不会取代该定义;相反,它回答了更狭窄且更有用的问题,即当上下文可靠地导致良好结果时,它看起来是什么样的。下一节中的框架是我们对该问题的回答。CAFE(S) 没有规定上下文应该如何组装,而是命名了五个持久的属性,这些属性将健康的上下文与不健康的上下文区分开来——最有可能产生良好结果的特征——并为团队提供了一种共享语言,用于评估要求 Agent 根据其工作的信息。
The CAFE(S) FrameworkCAFE(S) 框架
CAFE(S) names five properties of good context: clarity, actionability, fidelity, efficiency, and security (table 1表 1). The first four describe whether context lets an agent do good work; the fifth, set slightly apart in parentheses, describes whether that context is safe to use at all. Together they form a checklist you can hold a piece of context against, the way you might hold a pull request against a set of review criteria. They allow you to ask if any given context is good enough to hand to an agent.CAFE(S) 命名了好的上下文的五个属性:清晰度、可操作性、保真度、效率和安全性(表 1)。前四个描述了上下文是否让 Agent 做好工作;第五个,稍微放在括号中,描述了该上下文是否完全安全使用。它们共同构成了一个你可以对照上下文进行检查的清单,就像你可能根据一套审查标准来对照拉取请求一样。它们允许你询问任何给定的上下文是否足够好,可以交给 Agent。 The properties are meant to be largely independent, with each dimension naming a distinct way context can succeed or fail. Context can be clear but not faithful, describing the system as it was过去, rather than as it is. It can be faithful and secure but not efficient, burying the one detail that matters. It can be efficient and faithful but not actionable, never saying what finishing looks like. Independence across the dimensions does not mean a given failure maps to exactly one pillar. A single bad instruction can fail several at once, but each pillar isolates a dimension you can reason about, review for, and fix on its own.这些属性旨在在很大程度上是独立的,每个维度命名了上下文可以成功或失败的一种不同方式。上下文可以清晰但不忠实,描述的是系统过去的样子,而不是现在的样子。它可以忠实且安全,但效率不高,掩盖了唯一重要的细节。它可以高效且忠实,但不可操作,从不说完成是什么样的。各维度之间的独立性并不意味着给定的失败映射到一个支柱。单个糟糕的指令可以同时导致多个支柱失败,但每个支柱隔离了一个你可以推理、审查和自行修复的维度。
Each property has a definition, the question it answers, and the characteristic way it breaks. Throughout the framework, the properties of context are deliberately separated from the mechanisms that create them and the outcomes they influence. This keeps the definitions stable even as engineering practices, tools, and models continue to evolve.每个属性都有一个定义、它回答的问题以及它破坏的特征方式。在整个框架中,上下文的属性被特意与创建它们的机制以及它们影响的结果分离开来。这使得定义保持稳定,即使工程实践、工具和模型继续发展。
Clarity: Can the Agent Interpret the Request as Intended?清晰度:Agent 能否按预期解释请求?
Clarity is the property of context being unambiguous for the task at hand and for the party that has to act on it. Clear context resolves the same way for the author and the agent. Unclear context admits several interpretations, and the agent has no reliable way of knowing which reading was intended. Context need not be unambiguous in some absolute sense, only in ways that affect the work. A term the task never touches can stay loose. A term the task turns on is different. If the context does not settle which system, environment, or policy is meant, the agent will settle it for you, plausibly and silently.清晰度是上下文对于手头的任务以及必须对其采取行动的一方而言不含糊的属性。清晰的上下文对于作者和 Agent 的解析方式相同。不清晰的上下文允许几种解释,而 Agent 没有可靠的方法知道哪种解读是预期的。上下文不需要在某种绝对意义上不含糊,只需在影响工作的方式上不含糊即可。任务从未触及的术语可以保持宽松。任务所依赖的术语则不同。如果上下文没有确定指的是哪个系统、环境或策略,Agent 将为你确定它,合理且静默地。
The practical consequence of poor clarity is avoidable variation. When context is up for interpretation, different executions may produce different outcomes. This is not because the task itself changed or because of the normal variability inherent in probabilistic models, but because the context left important decisions open to interpretation.清晰度差的实际后果是可避免的变异。当上下文有待解释时,不同的执行可能会产生不同的结果。这不是因为任务本身发生了变化,也不是因为概率模型固有的正常变异,而是因为上下文将重要的决策留给了解释。
Clarity failures are easy to miss because they are invisible to the author. The person who created the context usually knows what they meant, so the ambiguity is visible only to a reader or agent who does not already share their intent or their conventions. Teams develop local vocabularies, and a term that is precise inside one group can admit several readings outside it. Language, domain, and cultural convention all shape what counts as an obvious reading, and an agent shares none of them by default.12清晰度故障很容易被遗漏,因为它们对作者来说是不可见的。创建上下文的人通常知道他们的意思,因此歧义仅对没有共享他们的意图或惯例的读者或 Agent 可见。团队发展出本地词汇,在一个群体内精确的术语在外部可以有几种解读。语言、领域和文化惯例都塑造了什么是明显的解读,而 Agent 默认不共享其中的任何一个。 When context is clear, agents spend less time interpreting requests and more time solving the intended problem.当上下文清晰时,Agent 花费更少的时间解释请求,而花费更多的时间解决预期的任务。
Actionability: Can the Agent Proceed and Know When it is Done?可操作性:Agent 能否继续并知道何时完成?
Actionability is the property of context supplying enough direction to act. That means describing the objective, the constraints that bear on it, and a definition of what “done” looks like. Actionable context lets an agent proceed without guessing and recognize when the task is complete. Context that lacks actionability leaves the agent working toward a target that was never fully specified.可操作性是上下文提供足够方向以采取行动的属性。这意味着描述目标、影响它的约束以及“完成”是什么样的定义。可操作的上下文让 Agent 无需猜测即可继续,并识别任务何时完成。缺乏可操作性的上下文使 Agent 在从未完全指定的目标上工作。
Where clarity asks whether the context can be read one way, actionability asks whether enough was said. The two are independent. A request can be perfectly unambiguous and still leave out the goal, say too little about the constraints, or give no way to tell that the work is finished.当清晰度询问上下文是否可以以一种方式读取时,可操作性询问是否说了足够多。两者是独立的。请求可以完全不含糊,但仍然遗漏目标,对约束说得太少,或者没有方法说明工作已经完成。
Poor actionability has three practical consequences: (1) The agent may never really start, spending its effort reconstructing an objective that was never stated; (2) it may never stop, because nothing in the context defines what finished looks like; or (3) it may stop in the wrong place, declaring success against a target it inferred rather than one it was given. The third is the most expensive, because the work looks like progress.可操作性差有三个实际后果:(1) Agent 可能永远不会真正开始,花费精力重建一个从未说明的目标;(2) 它可能永远不会停止,因为上下文中没有任何东西定义完成是什么样的;或 (3) 它可能在错误的地方停止,针对它推断出的目标而不是给定的目标宣布成功。第三个是最昂贵的,因为工作看起来像进展。
Actionability is easy to underspecify because the author is closest to the work. When the goal and the finish line are already settled in your own head, stating them feels redundant, so they go unwritten, and the agent is left with nothing to go on.可操作性很容易被低估,因为作者最接近工作。当目标和终点线已经在你自己的脑海中确定时,陈述它们感觉是多余的,因此它们没有被写下来,Agent 也就没有什么可依据的了。
Fidelity: Can the Agent Trust That the Context is True?保真度:Agent 能否相信上下文是真实的?
Fidelity is the property of context being accurate. Is it a faithful representation of the system, the organization, and the task the agent is being asked to perform? Context with poor fidelity may contain outdated documentation, conflicting instructions, unsupported assumptions, or information from unreliable sources. An agent reasoning over inaccurate context may produce something that appears internally consistent while being fundamentally wrong because it was grounded in an incorrect understanding of reality.保真度是上下文准确的属性。它是系统、组织和 Agent 被要求执行的任务的忠实代表吗?保真度差的上下文可能包含过时的文档、冲突的指令、不受支持的假设或来自不可靠来源的信息。在不准确的上下文上进行推理的 Agent 可能会产生看起来内部一致但从根本上是错误的东西,因为它基于对现实的不正确理解。
Fidelity also covers what the context does not say. A gap rarely stays a gap, often forcing an agent to make a guess that then becomes indistinguishable from fact.保真度也涵盖了上下文没有说的内容。差距很少保持为差距,通常迫使 Agent 做出猜测,然后变得与事实无法区分。
Maintaining fidelity is particularly challenging because the systems, organizations, and goals that context describes evolve continuously.30 Code changes, APIs are deprecated, architectural decisions are revisited, and organizational policies shift over time. Context that was once an accurate representation of reality can quietly become stale, leading agents toward obsolete implementations or invalid assumptions.保持保真度特别具有挑战性,因为上下文所描述的系统、组织和目标在不断演进。代码发生变化,API 被弃用,架构决策被重新审视,组织策略随时间推移而转移。曾经是现实准确代表的上下文可以静默地变得过时,导致 Agent 走向过时的实现或无效的假设。 This is why fidelity is inseparable from verification. The question is not only whether the context is accurate today, but whether there is a mechanism for keeping it accurate as the system evolves. Source-of-truth documents, freshness checks, attribution, and regular review all help preserve fidelity over time.这就是为什么保真度与验证密不可分。问题不仅在于上下文今天是否准确,还在于是否有机制在系统演进时保持其准确。事实来源文档、新鲜度检查、归因和定期审查都有助于长期保持保真度。
Efficiency: Is the Context Lean Enough to be Usable and Affordable?效率:上下文是否足够精简以至于可用且负担得起?
Efficiency is the property of context maximizing signal while minimizing irrelevant information. Efficient context gives the agent what matters without burdening it with information that is unnecessary. It matters for two reinforcing reasons. The first is that irrelevant context does not merely consume space; it competes with relevant information for the model’s attention, making it harder to reason effectively.20 The second reason is cost. Every unnecessary token is paid for, and that cost compounds across every session.效率是上下文最大化信号同时最小化不相关信息的属性。高效的上下文给 Agent 重要的是,而不给它负担不必要的信息。它出于两个强化原因而重要。首先,不相关的上下文不仅消耗空间;它还与相关信息竞争模型的注意力,使其更难有效推理。第二个原因是成本。每个不必要的 Token 都是有代价的,而且该成本在每个会话中都会累积。 You ask about one small piece of a system and hand the agent the whole codebase anyway. Almost everyone does this, and most know they are doing it. Working out what is relevant takes effort. Including everything takes none. Efficiency is the discipline of resisting that, and it is worth stressing that it is not brevity for its own sake. The goal is not the smallest possible context, but the highest signal-to-noise ratio.12,21 Every token that competes for attention without helping the task should go.你询问系统的一小部分,却还是把整个代码库交给了 Agent。几乎每个人都这样做,大多数人知道他们正在这样做。弄清楚什么是相关的需要努力。包括一切则不需要。效率是抵制这种行为的纪律,值得强调的是,它不是为了简洁而简洁。目标不是尽可能小的上下文,而是最高的信噪比。每个在没有帮助任务的情况下竞争注意力的 Token 都应该去掉。 Security: Is the Context Safe and Compliant to Use?安全性:上下文是否安全且合规以供使用?
The first four properties ask whether context enables an agent to do good work. Security asks a more fundamental question: Should the agent have been given this context in the first place? It belongs alongside the other dimensions because it evaluates the same artifact, the assembled context, even though it asks a different question about it. Failures of the first four dimensions make agents less effective. Failures of security make them unsafe. Sensitive information can be exposed, policies can be violated, or an attacker may manipulate the agent through the context it receives when this dimension fails.前四个属性询问上下文是否使 Agent 做好工作。安全性询问了一个更基本的问题:Agent 首先应该被给予这个上下文吗?它属于其他维度,因为它评估相同的工件,即组装的上下文,即使它对它提出了不同的问题。前四个维度的失败使 Agent 效率降低。安全性的失败使它们不安全。敏感信息可能会被暴露,策略可能会被违反,或者攻击者可能会通过它接收到的上下文操纵 Agent,当这个维度失败时。
Two broad classes of failure dominate. The first is untrusted context不可信的上下文. Information retrieved from sources an attacker can influence may carry instructions, or simply false assertions, intended to steer the agent. Model defenses against this are improving, but whether a given model can defend the attack is not the point. The point is whether attacker-controlled content was in the context in the first place. This is the mechanism behind the exfiltration attacks described earlier, and it echoes the lesson software engineers learned from SQL injection. Information cannot be trusted simply because it arrives through a legitimate channel.两大类失败占据主导地位。首先是不可信的上下文。从攻击者可以影响的来源检索到的信息可能带有指令,或者仅仅是错误的断言,旨在引导 Agent。模型对此的防御正在改善,但给定的模型是否能防御攻击并不是重点。重点是攻击者控制的内容首先是否在上下文中。这是前面描述的泄露攻击背后的机制,它呼应了软件工程师从 SQL 注入中学到的教训。信息不能仅仅因为通过合法渠道到达就受到信任。
The second is overshared context过度共享的上下文. Agents can receive secrets, personal data, or regulated information they do not actually need to perform the task. Once included in the working context, that information may be logged, cached, transmitted, or surfaced in ways the organization never intended. Security therefore concerns both keeping malicious information out of an agent’s context and keeping unnecessary sensitive information out.其次是过度共享的上下文。Agent 可能会收到它们执行任务实际上不需要的秘密、个人数据或受监管信息。一旦包含在工作上下文中,该信息可能会以组织从未打算的方式被记录、缓存、传输或表面化。因此,安全性既涉及将恶意信息排除在 Agent 的上下文之外,也涉及将不必要的敏感信息排除在外。
Why These Five为什么是这五个
A fair question is why the framework stops at five when there are other candidates such as timeliness, cost, provenance, and accessibility. Our test is that a property earns its own pillar only if it is not derivable from the others, can be acted on independently, and names a failure the others miss. Most candidates fold cleanly into an existing pillar. Stale context is simply context that is no longer true, making timeliness a facet of fidelity. Cost is a downstream consequence of efficiency, not a separate property of the artifact. Provenance is how you keep context trustworthy, which falls under fidelity.一个公平的问题是,为什么框架在有其他候选者(如及时性、成本、出处和可访问性)时止步于五个。我们的测试是,一个属性只有在不能从其他属性中推导出来、可以独立采取行动并命名其他属性遗漏的失败时,才赢得自己的支柱。大多数候选者干净地折叠到现有的支柱中。过时的上下文只是不再真实的上下文,使得及时性成为保真度的一个方面。成本是效率的下游后果,而不是工件的独立属性。出处是你如何保持上下文值得信赖,这属于保真度。
Accessibility is intentionally outside the scope of CAFE(S). Whether information can be located and retrieved is a prerequisite concern of knowledge management and retrieval systems. CAFE(S) assumes that the relevant information has already been assembled and evaluates the quality of that assembled context.可访问性特意在 CAFE(S) 的范围之外。信息是否可以定位和检索是知识管理和检索系统的先决条件关注点。CAFE(S) 假设相关信息已经被组装,并评估该组装上下文的质量。
These five are not the only defensible cuts, and we expect edge cases. But these dimensions are independent, actionable, and, collectively, they sufficiently cover the ways context succeeds or fails without redundant overlap.这五个并不是唯一可辩护的切分,我们预计会有边缘情况。但这些维度是独立的、可操作的,并且总的来说,它们充分涵盖了上下文成功或失败的方式,而没有冗余的重叠。
When Context Goes Wrong当上下文出错时
One useful way to understand the CAFE(S) dimensions is to look at what happens when they break down. Poor context does not produce random failures. The same patterns appear repeatedly across different models, tools, and organizations. Naming those patterns gives teams something concrete to review for and discuss, much like software engineers use terms such as code smell代码异味 to describe recurring design problems. In fact, you could think of these failure patterns as context smells上下文异味.理解 CAFE(S) 维度的一种有用方法是查看它们分解时发生了什么。糟糕的上下文不会产生随机失败。相同的模式在不同的模型、工具和组织中反复出现。命名这些模式为团队提供了具体的东西来审查和讨论,就像软件工程师使用诸如代码异味 (code smell) 之类的术语来描述反复出现的设计问题一样。事实上,你可以认为这些故障模式是上下文异味 (context smells)。
The examples that follow are illustrative rather than exhaustive, and each primarily highlights one or more CAFE(S) dimensions.接下来的例子是说明性的而非详尽的,每个例子主要突出了一个或多个 CAFE(S) 维度。
Confident Hallucination (Fidelity)自信的幻觉 (保真度)
Hallucinations are often described as model failures, but they are just as often failures of fidelity. A model can distinguish supported claims from unsupported ones only if the surrounding context gives it a way to do so. Lawyers have now been sanctioned for submitting briefs that cited cases that never existed.23 The immediate cause was a model hallucination, but the deeper failure was that nothing in the workflow treated those citations as claims requiring verification. When confidence substitutes for evidence, fabricated information becomes difficult to distinguish from fact.幻觉通常被描述为模型失败,但它们同样经常是保真度的失败。模型只有在周围上下文提供方法时,才能区分支持的声明和不支持的声明。律师现在因提交引用从未存在过的案例的摘要而受到制裁。直接原因是模型幻觉,但更深层的失败是工作流中没有任何东西将这些引用视为需要验证的声明。当自信代替证据时,伪造的信息就变得难以与事实区分。 Zero-Click Leak and Silent Exfiltration (Security)零点击泄露和静默外泄 (安全性)
Security failures often begin when agents cannot distinguish trusted information from untrusted instructions. In the previously mentioned EchoLeak, a crafted email that was never opened by the user caused Microsoft 365 Copilot to retrieve internal information and leak it.29 In the previously mentioned CamoLeak, hidden instructions embedded in a pull request caused GitHub Copilot Chat to expose secrets from private repositories.24 In both cases, the attack succeeded because hostile content became part of the agent’s working context. The boundary between data and instructions disappeared.安全失败通常始于 Agent 无法区分受信任信息和不受信任指令时。在前面提到的 EchoLeak 中,用户从未打开的精心制作的电子邮件导致 Microsoft 365 Copilot 检索内部信息并泄露它。在前面提到的 CamoLeak 中,嵌入在拉取请求中的隐藏指令导致 GitHub Copilot Chat 暴露来自私有存储库的秘密。在这两种情况下,攻击都成功了,因为敌对内容成为了 Agent 工作上下文的一部分。数据和指令之间的界限消失了。 Weekend Runaway (Efficiency + Actionability)周末失控 (效率 + 可操作性)
Give an agent a task without a definition of success and it may never discover that it is finished. Instead, it retries, expands scope, or continues exploring an objective that cannot actually be completed. The result is wasted time, unnecessary token consumption, and sometimes surprisingly large bills after an agent spends hours or days pursuing an underspecified goal.5 The problem is both one of efficiency, because resources are consumed without bound, and one of actionability, because the context never defined what “done” looked like.如果给代理(agent)分配一个任务却不定义何为成功,它可能永远无法发现任务已经完成。相反,它会不断重试、扩大范围,或者继续探索一个实际上无法完成的目标。其结果是时间的浪费、不必要的 Token 消耗,有时甚至会在代理花费数小时或数天追求一个定义不明的目标后产生令人惊讶的高额账单。这个问题既关乎效率(因为资源被无限制地消耗),也关乎可操作性(因为上下文从未定义过“完成”的标准是什么)。 Lost in the Middle (Efficiency)迷失在中间(效率)
More context is not always better. Model performance degrades as input length grows, and it does so unevenly. What matters is not only whether the required information is present, but also how much competing material surrounds it.5,20 Nothing is technically missing. The agent has access to the required information, yet it still fails because the signal has been overwhelmed by noise. This illustrates why efficiency is not simply about reducing token costs. A smaller, more focused context can produce better results than a larger one.上下文并非越多越好。模型性能会随着输入长度的增加而下降,而且这种下降是不均匀的。重要的不仅是所需信息是否存在,还在于它周围有多少竞争性干扰信息。从技术上讲,信息并没有丢失。代理可以访问所需信息,但它仍然失败了,因为信号被噪声淹没了。这说明了为什么效率不仅仅是减少 Token 成本的问题。一个更小、更聚焦的上下文往往能比更大的上下文产生更好的结果。 Specification Ambiguity (Clarity)规范模糊(清晰度)
Faced with an obviously underdetermined request, an agent may stop and ask for clarification. Faced with a semi-ambiguous request, agents generally do something much more dangerous. They choose an interpretation and proceed.19 If that initial assumption is wrong, every subsequent step compounds the error. The failure is not that information is missing, but that the existing context admits more than one reasonable interpretation.面对一个明显定义不足的请求,代理可能会停下来请求澄清。但面对一个半模糊的请求,代理通常会采取更危险的做法:它们会选择一种解释并继续执行。如果最初的假设是错误的,那么随后的每一步都会加剧错误。失败的原因不在于信息缺失,而在于现有的上下文允许存在不止一种合理的解释。 Impossible Task (Actionability)不可能的任务(可操作性)
Agents are often asked to do things that cannot actually be done. Rather than recognizing that no solution exists, they may continue searching, retrying, or inventing increasingly implausible approaches because nothing in the context established the boundaries of what was achievable or what success would look like.5代理经常被要求做一些实际上无法完成的事情。它们可能不会意识到根本不存在解决方案,而是继续搜索、重试或发明越来越不可信的方法,因为上下文中没有任何内容规定了可实现性的边界或成功的标准。 Contradictory and Fragmented Context (Clarity + Efficiency)矛盾且碎片化的上下文(清晰度 + 效率)
Adding more context does not necessarily make an agent better informed.18 Two documents may disagree about how a system behaves. A design document may conflict with the implementation. Critical information may exist but only when pieces are assembled from multiple repositories, documents, and conversations that are never viewed together. The raw information exists, yet the assembled context lacks a coherent picture of reality. The agent spends effort reconciling inconsistencies or searching for missing connections instead of solving the problem it was asked to address.增加更多上下文并不一定能让代理获得更好的信息。两份文档可能对系统的行为方式描述不一致。设计文档可能与实现冲突。关键信息可能存在,但只有当从多个从未被放在一起查看的存储库、文档和对话中拼凑出碎片时才能发现。原始信息确实存在,但拼凑出的上下文缺乏对现实的一致性认知。代理将精力花在协调不一致之处或寻找缺失的联系上,而不是解决被要求处理的问题。 Table 2表 2 summarizes these failure patterns, together with additional recurring context failures and the CAFE(S) dimensions they primarily violate.表 2 总结了这些失败模式,以及其他反复出现的上下文失败问题,并指出了它们主要违反的 CAFE(S) 维度。 Taken together, these examples illustrate an important point. In many cases, the necessary information was already in the assembled context. The problem was that the information was stale, ambiguous, contradictory, buried in noise, or mixed with content that should never have been trusted in the first place. Asking whether an agent has some某些 context is therefore the wrong question. The more useful question is whether the assembled context is actually fit for the task at hand. That is precisely the question the CAFE(S) framework is intended to help answer.综上所述,这些例子说明了一个重要观点。在许多情况下,必要的信息已经存在于汇总的上下文中。问题在于这些信息陈旧、模糊、矛盾、被噪声掩盖,或者混杂了本不该被信任的内容。因此,询问代理是否拥有“某些”上下文是错误的问题。更有用的问题是,汇总后的上下文是否真正适合当前的任务。这正是 CAFE(S) 框架旨在回答的问题。
What Good Context Looks Like in Practice好的上下文在实践中是什么样的
Before a team can worry about whether its context is clear, actionable, faithful, efficient, and secure, it has to clear a more basic set of hurdles.在团队担心其上下文是否清晰、可操作、忠实、高效和安全之前,必须先跨越一套更基本的障碍。
The first precondition is simply accessibility可访问性. The most common context problem today is not that context is low quality but that the agent cannot reach it. The sources exist, but they have not been wired into the agent, often because of real security constraints or the ordinary difficulty of change inside a large organization. Context that exists but is unreachable helps no one.第一个前提是可访问性。如今最常见的上下文问题不是质量低,而是代理无法获取它。源文件存在,但它们没有接入到代理中,这通常是因为现实的安全限制或大型组织内部变革的普遍困难。存在但无法访问的上下文对任何人都没有帮助。
The second precondition is cutting through the noise排除噪声. Once the sources are connected, the agent has to find the relevant slice. If 100 Slack channels share a prefix, which should it read, and how much can it read before it exhausts the window or the budget? A keyword search may suffice in simple cases, but what if the needed context lives across many systems of record rather than the one being worked in?第二个前提是排除噪声。一旦源文件连接起来,代理必须找到相关的部分。如果 100 个 Slack 频道共享一个前缀,它应该读取哪一个?在耗尽窗口或预算之前它能读取多少?在简单的情况下,关键字搜索可能就足够了,但如果所需的上下文存在于多个记录系统中,而不是正在工作的那个系统中,该怎么办?
The third precondition is the hardest: The fact the context has to exist存在 at all. A great deal of organizational knowledge has never been written down—it lives in hallway conversations, unrecorded meetings, and private messages an agent cannot (and often should not) see. No amount of context engineering can retrieve what was never captured.12第三个前提是最难的:上下文必须存在。大量的组织知识从未被记录下来——它们存在于走廊谈话、未记录的会议和代理无法(且通常不应该)看到的私信中。无论进行多少上下文工程,都无法找回从未被捕获的信息。 Only after those three hurdles are cleared do the CAFE(S) dimensions become the operative constraint. This is worth stating plainly because it reframes where most teams should start. Not with a scoring rubric but with the unglamorous work of connecting sources, making them searchable, and writing down what only lives in people’s heads.只有在跨越了这三个障碍之后,CAFE(S) 维度才会成为起作用的约束。这一点值得明确指出,因为它重新定义了大多数团队应该从哪里开始。不是从评分标准开始,而是从连接数据源、使其可搜索、以及记录那些仅存在于人们脑海中的知识这些枯燥的工作开始。
Importantly, “good” does not mean perfect. Context should be good enough for the task at hand. A slightly verbose context is usually preferable to one that is missing critical information or that contains inaccurate guidance. In practice, teams should first eliminate missing, incorrect, and stale context before optimizing for elegance or brevity.重要的是,“好”并不意味着完美。上下文应该足以胜任当前的任务。稍微冗长一点的上下文通常优于缺少关键信息或包含不准确指导的上下文。在实践中,团队应首先消除缺失、错误和陈旧的上下文,然后再追求优雅或简洁。
Context Quality is Relative to Where It Lives上下文质量取决于它所处的位置
One principle cuts across everything that follows: The quality of a piece of context depends on where it lives and when it is used. The same instruction can be excellent in one location and harmful in another.一个原则贯穿了以下所有内容:一段上下文的质量取决于它存储在哪里以及何时使用。同一条指令在一个位置可能是极好的,而在另一个位置则可能是有害的。
Consider an AGENTS.md file at the root of a repository—a file whose contents are loaded into every agent session. An instruction about how to run the test suite may belong there, because nearly every session needs it. However, an instruction about one rarely touched file does not—it will be injected into thousands of sessions that have nothing to do with that file, spending tokens and attention on noise.21 That same instruction, placed as a comment inside the file it describes, is suddenly high quality—clear, efficient, and available exactly when relevant. Nothing about the words changed; only their location did. Where context lives is one of its most important properties, and evaluating context means evaluating it in situ, not in the abstract.考虑存储库根目录下的 AGENTS.md 文件——该文件的内容会被加载到每个代理会话中。关于如何运行测试套件的指令可能属于这里,因为几乎每个会话都需要它。然而,关于某个很少触及的文件的指令则不属于这里——它会被注入到数千个与该文件无关的会话中,将 Token 和注意力浪费在噪声上。同样的指令,如果作为注释放在它所描述的文件内部,质量会瞬间提高——清晰、高效,且在相关时准确可用。文字本身没有改变,改变的只是它们的位置。上下文存储在哪里是其最重要的属性之一,评估上下文意味着在原位(in situ)进行评估,而不是抽象地评估。 What Individuals Can Do个人能做什么
The highest-leverage move for an individual is to be rigorous about the human-written text they hand to agents and to recognize that creating and maintaining good context is itself part of software engineering. It is not something done after the “real work” is finished. A prompt is context. But so is a code comment, an architecture document, a README, a checked-in specification. Any of these can be read by an agent as instruction or as fact, and any of them, if stale or ambiguous, can send the agent down a wrong path—an expensive one. An architecture document that no longer matches the code will not just mislead the agent; it will burn tokens as the agent chases files that no longer exist. So, the discipline is to treat everything you write that an agent might read as being subject to the same standards you would apply to the context itself. Is it clear, is it current, is it scoped to where it lives, does it avoid telling the agent to trust something it should not?个人能做的杠杆率最高的事情,是对自己交给代理的人类编写的文本保持严谨,并认识到创建和维护良好的上下文本身就是软件工程的一部分。这不是在“真正的工作”完成后才做的事情。提示词(Prompt)是上下文,代码注释、架构文档、README、已签入的规范也是上下文。代理可以将其中任何一个读取为指令或事实,如果它们陈旧或模糊,任何一个都可能引导代理走入歧途——而且代价高昂。一份不再与代码匹配的架构文档不仅会误导代理,还会因为代理追逐不存在的文件而消耗 Token。因此,准则就是把你写给代理阅读的每一段内容,都视为与上下文本身适用相同的标准。它清晰吗?它是最新的吗?它的范围是否符合其所在位置?它是否避免了引导代理去信任不该信任的东西?
The second move for an individual to make is to write good context deliberately, the way a senior engineer briefs a junior one. This is not the arcane “prompt engineering” of a few years ago; it is a straightforward discipline of stating what you are trying to accomplish, how you would know it was solved, what is off limits and why, where the relevant code lives (if you are confident in it), and under what circumstances the agent should come back to you. Notably, this does not require elaborate prompt templates or systems that force developers into a rigid format—those tend to lose their value as models improve. The durable investment is educating engineers in the craft of writing clear, honest, well-scoped context, the same way they have been taught to write readable code and good comments.个人可以做的第二件事是深思熟虑地编写良好的上下文,就像资深工程师指导初级工程师那样。这不是几年前那种晦涩的“提示词工程”;而是一种直截了当的准则:说明你试图完成什么、如何判断它已解决、什么是不允许的及其原因、相关代码在哪里(如果你确定的话),以及在什么情况下代理应该回来找你。值得注意的是,这不需要复杂的提示词模板或强迫开发人员使用刚性格式的系统——随着模型的改进,这些东西往往会失去价值。持久的投资在于培养工程师编写清晰、诚实、范围明确的上下文的技能,就像教导他们编写可读的代码和好的注释一样。
What Teams Can Do团队能做什么
Individual rigor scales into team practice through shared, consistent sources of context. Specifications stored as code, AGENTS.md files, checked-in skills and examples, architecture documents, shared glossaries, and the other artifacts a whole team relies on are all important practices. Maintaining those artifacts should be treated as ordinary software maintenance. Like tests, build systems, or code itself, shared context degrades unless teams continuously invest in it.个人的严谨性可以通过共享、一致的上下文来源扩展为团队实践。存储为代码的规范、AGENTS.md 文件、已签入的技能和示例、架构文档、共享词汇表以及整个团队依赖的其他工件,都是重要的实践。维护这些工件应被视为日常软件维护的一部分。像测试、构建系统或代码本身一样,共享上下文如果不持续投入维护就会退化。
Because context is shared, its defects are amplified. A stale architecture document or an ambiguous AGENTS.md file is not read by one developer; it is read by every agent session that consumes it. That is why one of the highest-leverage team practices is a context-review discipline. Just as code review catches defects early and reinforces shared standards, reviewing important context artifacts against the CAFE(S) dimensions before they are broadly reused catches ambiguity, staleness, unnecessary complexity, and unsafe instructions before they propagate.由于上下文是共享的,其缺陷会被放大。陈旧的架构文档或模糊的 AGENTS.md 文件不仅会被一个开发人员读取,还会被每一个消耗它的代理会话读取。这就是为什么团队最高杠杆率的实践之一是上下文审查准则。正如代码审查可以及早发现缺陷并强化共享标准一样,在重要的上下文工件被广泛重用之前,对照 CAFE(S) 维度对其进行审查,可以在模糊、陈旧、不必要的复杂性和不安全的指令传播之前就将其捕获。
Not every artifact requires the same level of scrutiny, however. A repository-wide AGENTS.md file that shapes thousands of sessions deserves far more review than a working note shared between two engineers. Review effort should be proportional to the impact context has when it is reused.然而,并非每个工件都需要相同程度的审查。一个塑造了数千个会话的存储库级 AGENTS.md 文件,比两个工程师之间共享的工作笔记更值得审查。审查力度应与上下文被重用时产生的影响成正比。
Teams should also establish conventions for where different kinds of context belong. Because context quality depends on where it is consumed, agreeing where design documents, operational runbooks, architectural decisions, coding conventions, and repository-wide instructions live makes it easier for both humans and agents to discover and maintain them. The goal is not rigid standardization for its own sake but creating predictable places where important knowledge can be found.团队还应建立关于不同类型的上下文属于哪里的约定。由于上下文质量取决于它在哪里被消耗,就设计文档、操作手册、架构决策、编码约定和存储库级指令的存放位置达成一致,可以使人类和代理更容易发现和维护它们。目标不是为了标准化而标准化,而是创造可预测的地方,以便能够找到重要的知识。
There is a balance to strike, though. Not all context should be forced through public review or shared repositories. A great deal of it is genuinely personal, such as how someone likes to work, their own priorities, or notes to themselves, and publishing all of it would both reduce individual productivity and pollute everyone else’s context with irrelevant information. The team’s responsibility is to identify the context that should be shared, reviewed, and maintained as common knowledge.不过,需要取得平衡。并非所有上下文都应强制通过公共审查或共享存储库。其中很大一部分确实是私人的,例如某人喜欢的工作方式、他们自己的优先级或给自己的笔记,发布所有这些内容既会降低个人生产力,也会用无关信息污染其他人的上下文。团队的责任是识别那些应该作为共同知识共享、审查和维护的上下文。
What Organizations Can Do组织能做什么
At the organizational level, the challenge expands beyond individual repositories to infrastructure, education, policy, and long-term stewardship. Organizations need the infrastructure that allows agents to retrieve information safely from companywide systems, the governance that prevents sensitive or malicious context from being introduced into agent workflows, and clear ownership so important context does not quietly decay as systems and teams evolve.在组织层面,挑战超越了单个存储库,扩展到了基础设施、教育、政策和长期管理。组织需要能够让代理安全地从全公司系统检索信息的基础设施,需要防止敏感或恶意上下文进入代理工作流的治理机制,以及明确的所有权,以确保重要的上下文不会随着系统和团队的演进而悄然衰退。
Every major shared context source—runbooks, architecture documents, policies, glossaries, schemas, and platform guidance—should have a clear owner and an expected review cadence so fidelity does not silently erode over time. Ownership should follow teams rather than individuals wherever possible, ensuring that important context survives reorganizations and personnel changes. Likewise, retrieval infrastructure should make high-quality context discoverable while keeping restricted information appropriately protected.每一个主要的共享上下文来源——手册、架构文档、政策、词汇表、模式和平台指南——都应该有明确的所有者和预期的审查节奏,以确保其保真度不会随时间推移而悄然流失。所有权应尽可能跟随团队而非个人,确保重要的上下文在重组和人员变动中得以留存。同样,检索基础设施应使高质量的上下文可被发现,同时使受限信息得到适当保护。
Organizations should also invest in education. Writing and maintaining good context is an engineering skill, much like writing maintainable code or conducting effective code reviews. Engineers should understand not only how to work effectively with agents, but also why context quality matters and how the CAFE(S) dimensions can be applied when creating or reviewing shared context.组织还应投资于教育。编写和维护良好的上下文是一种工程技能,就像编写可维护的代码或进行有效的代码审查一样。工程师不仅应该了解如何与代理有效合作,还应该了解为什么上下文质量很重要,以及在创建或审查共享上下文时如何应用 CAFE(S) 维度。
Finally, organizations should recognize context as an engineering asset rather than a by-product of feature delivery. Capturing architectural rationale, documenting important decisions, and maintaining shared understanding all require time, yet they compound in value as both humans and agents increasingly rely on them. Organizations that reward only short-term feature delivery will watch their shared context gradually decay, while those that invest in maintaining high-quality shared context will create healthier environments for both human developers and AI agents.最后,组织应将上下文视为一种工程资产,而不是功能交付的副产品。捕获架构基本原理、记录重要决策以及维护共享理解都需要时间,但随着人类和代理越来越依赖它们,其价值会不断累积。只奖励短期功能交付的组织会眼睁睁看着其共享上下文逐渐衰退,而那些投资于维护高质量共享上下文的组织,将为人类开发人员和 AI 代理创造更健康的环境。
Good Context Enables Autonomy—It Does Not Guarantee It良好的上下文能够实现自主性——但不能保证它
It would be easy to read this framework as a checklist that, once satisfied, clears an agent for autonomy. It does not. Healthy context is a prerequisite for trusting an agent with more autonomy, but it is not a guarantee of it. Clear, actionable, faithful, efficient, and secure context creates the conditions under which higher autonomy becomes reasonable; whether to grant that autonomy still depends on the stakes of the task, the organization’s tolerance for risk, and where accountability sits when something goes wrong.将此框架解读为一份清单很容易,仿佛一旦满足了它,就赋予了代理自主权。事实并非如此。健康的上下文是信任代理拥有更多自主权的前提,但不是保证。清晰、可操作、忠实、高效和安全的上下文创造了合理提高自主性的条件;是否授予该自主权仍然取决于任务的利害关系、组织对风险的容忍度,以及当出现问题时由谁承担责任。
CAFE(S) describes what good context is. It does not claim that good context, by itself, is sufficient to hand an agent the keys—only that without it, you should not.CAFE(S) 描述了什么是好的上下文。它并不声称良好的上下文本身就足以将控制权交给代理——只是说如果没有它,你不应该这样做。
Where CAFE(S) Fits with What You Already UseCAFE(S) 与你现有工具的契合点
An engineering leader reading this has a reasonable question: I already measure delivery, I run retrieval evaluations, I follow security guidance, and my platform team has an observability stack—do I need this too? The answer is yes, and the reason is that none of those tools evaluates what CAFE(S) does. They explore adjacent parts of the system; CAFE(S) describes the quality of the context artifact itself.阅读本文的工程领导者可能会有一个合理的问题:我已经衡量了交付情况,我运行了检索评估,我遵循了安全指导,我的平台团队也有可观测性栈——我还需要这个吗?答案是肯定的,原因在于这些工具都没有评估 CAFE(S) 所评估的内容。它们探索的是系统的相邻部分;而 CAFE(S) 描述的是上下文工件本身的质量。
The distinctions are easiest to see side by side, as shown in table 3表 3.如表 3 所示,这些区别并列时最容易看出来。 The pattern throughout table 3 is that CAFE(S) is orthogonal and complementary. It is not a replacement for any of these; it is a quality scorecard for the context artifact designed to sit on top of the stack you already run. It runs on your observability tooling rather than against it, and it evaluates the context that standards such as the Model Context Protocol (MCP) help you assemble—MCP standardizes how context is gathered, while CAFE(S) asks whether what is gathered is any good.表 3 的模式表明,CAFE(S) 是正交且互补的。它不是这些框架的替代品;它是为坐在你现有栈之上的上下文工件设计的质量记分卡。它运行在你的可观测性工具之上,而不是针对它们,它评估的是模型上下文协议(MCP)等标准帮助你组装的上下文——MCP 标准化了如何收集上下文,而 CAFE(S) 则询问收集到的内容是否有用。 The relationship worth examining more closely is the one with Storey’s work,30 because it is the closest in spirit. Where the triple debt model describes intent debt as the erosion of the goals and rationale a system needs to evolve safely, it also describes cognitive debt as the erosion of the team’s understanding, structure, and history of the project.值得更仔细审视的关系是与 Storey 的工作之间的关系,因为它们在精神上最接近。三倍债务模型将意图债务描述为系统进化所需的目标和基本原理的侵蚀,它还将认知债务描述为团队对项目理解、结构和历史的侵蚀。 CAFE(S) focuses on a point at which these longer-term forms of debt may become operationally visible. When a task is delegated to an agent, the agent can draw only on the context made available to it. Intent that was never externalized or that has become outdated, fragmented, or misaligned over time may therefore be absent or poorly represented, while cognitive debt may limit the team’s ability to recognize and correct those deficiencies. In this sense, CAFE(S) offers a way to assess the immediate context in which cognitive and intent debt may have practical consequences rather than measuring either form of debt directly.CAFE(S) 关注的是这些长期债务形式可能在操作上变得可见的点。当任务委托给代理时,代理只能利用提供给它的上下文。因此,从未外化或随着时间推移变得过时、碎片化或错位的意图可能会缺失或表示不佳,而认知债务可能会限制团队识别和纠正这些缺陷的能力。从这个意义上说,CAFE(S) 提供了一种评估直接上下文的方法,在这种上下文中,认知债务和意图债务可能会产生实际后果,而不是直接衡量这两种债务。
Conclusion结论
It is worth returning to the chain this article started with:值得回到本文开头提到的链条:
Intent → Context → Harness → Model
The model supplies raw intelligence, and it is improving at a pace that dominates the headlines. The harness applies that intelligence through orchestration, tools, and memory, and it is the focus of intense engineering effort. Both matter enormously. Yet both are ultimately bounded by the quality of the context they receive. No matter how capable the model or how sophisticated the harness, an agent can reason only from the information available to it.模型提供原始智能,并且其改进速度占据了头条新闻。工具链(Harness)通过编排、工具和记忆来应用这种智能,这是密集工程工作的重点。两者都非常重要。但两者最终都受到它们接收到的上下文质量的限制。无论模型多么强大,工具链多么复杂,代理只能根据可用的信息进行推理。
CAFE(S) complements established disciplines such as knowledge management, information retrieval, and context engineering. Those disciplines determine whether the right information can be found and assembled. Instead, CAFE(S) asks a narrower question of whether the assembled context is actually good enough for an agent to do its best work.CAFE(S) 补充了知识管理、信息检索和上下文工程等既定学科。这些学科决定了是否可以找到并组装正确的信息。相反,CAFE(S) 提出了一个更狭窄的问题:汇总的上下文是否真的足以让代理发挥出最佳水平。
Our claim is intentionally modest. We argue that context quality can be described in terms of five durable properties—clarity, actionability, fidelity, efficiency, and security—and that naming those properties gives teams a shared language for reasoning about context as a first-class engineering artifact. Like code, context can be reviewed, owned, improved, and allowed to decay. Unlike code, however, it has largely escaped systematic evaluation despite increasingly determining how effectively humans and agents work together.我们的主张是有意保持谦逊的。我们认为上下文质量可以用五个持久的属性来描述——清晰度、可操作性、忠实度、效率和安全性——并且命名这些属性为团队提供了一种共同语言,用于将上下文视为一等工程工件进行推理。像代码一样,上下文可以被审查、拥有、改进并任其衰退。然而,与代码不同的是,尽管它日益决定了人类和代理协同工作的有效性,但它在很大程度上逃避了系统性的评估。
We have also been deliberate about scope. This article defines a framework; it does not introduce a measurement system. Future work will be needed to develop reliable ways of assessing these properties empirically and to understand how improvements in context quality influence collaboration, software delivery, and organizational outcomes. Meaningful measurement requires a shared definition of what is being measured. Before teams can improve context quality, they need a vocabulary for discussing it.我们对范围也进行了深思熟虑。本文定义了一个框架;它没有引入度量系统。未来需要开展工作来开发评估这些属性的可靠经验方法,并了解上下文质量的改进如何影响协作、软件交付和组织成果。有意义的度量需要对所度量的内容有共同的定义。在团队改进上下文质量之前,他们需要一种讨论它的词汇表。
The broader implication extends beyond any particular model, framework, or generation of AI systems. Models will continue to improve. Harnesses will become more sophisticated. The tools and techniques of context engineering will continue to evolve. The need for context that is clear, actionable, faithful, efficient, and secure will not. Those qualities are properties of effective communication, not of any specific technology.更广泛的影响超出了任何特定的模型、框架或一代 AI 系统。模型将继续改进。工具链将变得更加复杂。上下文工程的工具和技术将继续演进。对清晰、可操作、忠实、高效和安全的上下文的需求不会改变。这些品质是有效沟通的属性,而不是任何特定技术的属性。
As software engineering increasingly becomes a collaborative activity between humans and AI agents, the quality of that collaboration will depend on not only the intelligence of our models, but also the quality of the information environment created for them. Improving human-agent collaboration therefore requires more than building smarter agents. It requires building healthier contexts. Treating context as a first-class engineering artifact and giving teams a common language for reasoning about its quality is an important step toward that future.随着软件工程日益成为人类与 AI 代理之间的协作活动,这种协作的质量不仅取决于我们模型的智能,还取决于为它们创造的信息环境的质量。因此,改善人机协作需要的不仅仅是构建更聪明的代理。它需要构建更健康的上下文。将上下文视为一等工程工件,并为团队提供一种推理其质量的通用语言,是迈向未来的一项重要步骤。
Related Material相关材料
DevEx: What Actually Drives ProductivityDevEx:什么真正驱动了生产力
The developer-centric approach to measuring and improving productivity.以开发人员为中心的衡量和提高生产力的方法。
Abi Noda Margaret-Anne Storey, Nicole Forsgren, Michaela GreilerAbi Noda, Margaret-Anne Storey, Nicole Forsgren, Michaela Greiler
DevEx in ActionDevEx 实战
A study of its tangible impacts对其切实影响的研究
Nicole Forsgren, et al.Nicole Forsgren 等人
Assessing IT Project Success: Perception vs. Reality评估 IT 项目成功:感知与现实
We would not be in the digital age if it were not for the recurrent success of IT projects.如果不是因为 IT 项目的反复成功,我们就不会处于数字时代。
João Varajão and António TrigoJoão Varajão 和 António Trigo
Brian Houck is a distinguished scientist at DX. His work combines large-scale telemetry analysis, field experiments, surveys, and qualitative research to uncover the technical, cultural, environmental, and organizational factors that shape developer productivity and well-being. He is best known for his work on the SPACE framework for developer productivity and for measuring and improving developer experience in large engineering organizations.是 DX 的杰出科学家。他的工作结合了大规模遥测分析、现场实验、调查和定性研究,以揭示影响开发人员生产力和幸福感的技术、文化、环境和组织因素。他最出名的是在开发人员生产力的 SPACE 框架方面的工作,以及在大型工程组织中衡量和改善开发人员体验方面的工作。
Max Kanat-Alexander is an executive distinguished engineer for developer experience at Capital One, where he leads technical strategy for AI-assisted developer experience for more than 14,000 technologists. He is the author of是 Capital One 开发人员体验的执行杰出工程师,他在那里为超过 14,000 名技术人员领导 AI 辅助开发人员体验的技术战略。他是以下书籍的作者: Code Simplicity and和 Understanding Software and has previously led code health initiatives at Google and the Bugzilla Project.此前曾在 Google 和 Bugzilla 项目领导代码健康计划。 Max Kanat-Alexander 是 Capital One 开发人员体验的执行杰出工程师,他在那里为超过 14,000 名技术人员领导 AI 辅助开发人员体验的技术战略。他是《Code Simplicity》和《Understanding Software》的作者,此前曾在 Google 和 Bugzilla 项目领导代码健康计划。
Eirini Kalliamvakou is a research advisor at GitHub and leads research that deciphers developers’ motivations, needs, behavior, and how tools support them. Her insights shape product thinking, strategic storytelling, and leadership decisions across the company. She holds a Ph.D. in computer science from the University of Victoria and speaks about developer productivity, happiness, and the impact of AI on individuals, teams, and organizations.是 GitHub 的研究顾问,领导旨在解读开发人员动机、需求、行为以及工具如何支持他们的研究。她的见解塑造了整个公司的产品思维、战略叙事和领导决策。她拥有维多利亚大学计算机科学博士学位,并就开发人员生产力、幸福感以及 AI 对个人、团队和组织的影响发表演讲。
Margaret-Anne Storey is a professor of computer science at the University of Victoria and a Canada research chair in human and social aspects of software engineering. She is coauthor of the SPACE framework and a leading researcher in developer experience (DevEx). Her research focuses on how developers and teams understand complex software systems and how tools, AI, and collaborative practices shape that understanding. Her recent work examines how generative AI is transforming software engineering by changing how understanding is created, shared, and maintained. She collaborates with industry partners including Microsoft and DX. She holds an honorary doctorate from Lund University.是维多利亚大学计算机科学教授,也是软件工程人文和社会方面的加拿大研究主席。她是 SPACE 框架的合著者,也是开发人员体验 (DevEx) 领域的领先研究员。她的研究重点是开发人员和团队如何理解复杂的软件系统,以及工具、AI 和协作实践如何塑造这种理解。她最近的工作研究了生成式 AI 如何通过改变理解的创建、共享和维护方式来改变软件工程。她与包括 Microsoft 和 DX 在内的行业合作伙伴合作。她拥有隆德大学荣誉博士学位。
Nicole Forsgren is the senior director of developer intelligence at Google. She is an expert in DevOps and the author of the Shingo Publication Award-winning book是 Google 开发人员智能高级总监。她是 DevOps 专家,也是荣获 Shingo 出版奖的书籍 Accelerate: The Science of Lean Software and DevOps. Her work on technical practices and development has been published in industry and academic journals and is used to guide organizational transformations around the world.的作者。她在技术实践和开发方面的工作已在行业和学术期刊上发表,并被用于指导世界各地的组织转型。 Nicole Forsgren 是 Google 开发人员智能高级总监。她是 DevOps 专家,也是荣获 Shingo 出版奖的书籍《Accelerate: The Science of Lean Software and DevOps》的作者。她在技术实践和开发方面的工作已在行业和学术期刊上发表,并被用于指导世界各地的组织转型。
Acknowledgments致谢
We would like to thank Collin Green, Josh Beitler, Autumn Faust and Grace Fu, along with all of the other reviewers who helped shape this article in its final form.我们要感谢 Collin Green、Josh Beitler、Autumn Faust 和 Grace Fu,以及所有帮助本文最终成型的其他审稿人。
COPYRIGHT © 2026 HELD BY OWNER/AUTHOR. PUBLICATION RIGHTS LICENSED TO ACM. This work is licensed under a Creative Commons Attribution International 4.0 License.版权所有 © 2026 归所有者/作者所有。出版权授权给 ACM。本作品采用知识共享署名国际 4.0 许可协议进行许可。