context-engineering

上下文工程基础

上下文是语言模型在推理时可用的完整状态。它包括模型在生成响应时可以关注的所有内容：系统指令、工具定义、检索到的文档、消息历史记录和工具输出。了解上下文基础知识是有效开展上下文工程的前提。

核心概念

上下文由多个不同的组成部分构成，每个部分都有不同的特征和限制。注意力机制会形成有限的预算，限制上下文的有效使用。渐进式披露通过仅在需要时加载信息来管理这一限制。上下文工程的核心是筛选出数量最少、信号最强且能实现预期结果的 token 集合。

详细主题

上下文的构成

系统提示词 系统提示词确立 Agent 的核心身份、约束和行为准则。它们在会话开始时加载一次，通常会在整个对话中持续存在。系统提示词应极其清晰，使用简单、直接的语言，并保持在适合 Agent 的恰当高度。

恰当的高度需要平衡两种失败模式。一种极端是，工程师硬编码复杂而脆弱的逻辑，造成脆弱性和维护负担。另一种极端是，工程师提供模糊的高层指导，无法为期望的输出给出具体信号，或错误地假设存在共享上下文。最优的高度应取得平衡：既足够具体以有效引导行为，又足够灵活以提供强有力的启发式。

使用 XML 标签或 Markdown 标题将提示词组织为不同部分，以划分背景信息、指令、工具指导和输出描述。随着模型能力增强，确切的格式变得不那么重要，但结构清晰仍然很有价值。

工具定义 工具定义明确 Agent 可以采取的行动。每个工具都包括名称、描述、参数和返回格式。工具定义在序列化后位于上下文靠前的位置，通常在系统提示词之前或之后。

工具描述共同引导 Agent 的行为。糟糕的描述会迫使 Agent 猜测；优化后的描述包含使用场景、示例和默认值。合并原则指出，如果人类工程师无法明确说出在给定情况下应使用哪个工具，就不能指望 Agent 做得更好。

检索到的文档 检索到的文档提供领域特定知识、参考资料或与任务相关的信息。Agent 使用检索增强生成在运行时将相关文档拉入上下文，而不是预先加载所有可能的信息。

即时方法维护轻量级标识符（文件路径、存储的查询、网页链接），并使用这些引用来动态地将数据加载到上下文中。这反映了人类认知：我们通常不会记住全部信息语料，而是使用外部组织和索引系统按需检索相关信息。

消息历史 消息历史包含用户与 Agent 之间的对话，包括先前的查询、响应和推理。对于长时间运行的任务，消息历史可能会增长到主导上下文使用量。

消息历史充当草稿本记忆，Agent 在其中跟踪进度、维护任务状态，并在多轮之间保留推理。有效管理消息历史对于长时程任务的完成至关重要。

工具输出 工具输出是 Agent 行动的结果：文件内容、搜索结果、命令执行输出、API 响应以及类似数据。工具输出在典型 Agent 轨迹中占据大部分 token，研究显示观察结果（工具输出）可达到总上下文使用量的 83.9%。

无论工具输出是否与当前决策相关，它们都会消耗上下文。这给观察掩蔽、压缩和选择性保留工具结果等策略带来了压力。

上下文窗口与注意力机制

注意力预算约束 语言模型通过注意力机制处理词元，在上下文中的所有词元之间建立两两关系。对于 n 个词元，这会产生 n^2 个需要计算和存储的关系。随着上下文长度增加，模型捕捉这些关系的能力会受到限制。

模型根据训练数据的分布形成注意力模式，而训练数据中较短的序列占多数。这意味着模型处理全局上下文依赖关系的经验较少，可用于此类任务的专用参数也较少。因此，随着上下文增长，“注意力预算”会逐渐耗尽。

位置编码与上下文扩展 位置编码插值可通过调整模型，使其处理比原始训练上下文更长的序列。不过，这种调整会降低模型对词元位置的理解能力。模型仍然能够很好地处理较长上下文，但与较短上下文下的表现相比，信息检索和长程推理的精确度有所下降。

渐进式披露原则 渐进式披露通过仅在需要时加载信息来高效管理上下文。启动时，Agent 只加载技能名称和描述，足以判断某项技能何时可能相关。只有在针对特定任务激活技能时，才会加载完整内容。

这种方法既能让 Agent 保持响应迅速，又能按需获取更多上下文。该原则适用于多个层面：技能选择、文档加载，甚至工具结果检索。

上下文质量与上下文数量

“更大的上下文窗口可以解决记忆问题”这一假设已被实证推翻。上下文工程意味着找出尽可能小的一组高信号词元，从而最大限度地提高获得预期结果的可能性。

多个因素都要求提高上下文效率。处理成本会随着上下文长度增长而不成比例地增加——词元数量翻倍，成本不只是翻倍，时间和计算资源的消耗还会呈指数级增长。即使窗口在技术上支持更多词元，模型性能也会在超过特定上下文长度后下降。即使采用前缀缓存，较长的输入仍然成本高昂。

指导原则是重视信息价值，而非面面俱到。只包含当前决策所需的信息，排除无关内容，并设计能够按需获取更多信息的系统。

将上下文视为有限资源

必须将上下文视为一种边际收益递减的有限资源。就像人类的工作记忆有限一样，语言模型在解析大量上下文时也会消耗注意力预算。

每引入一个新词元，都会在一定程度上消耗这份预算。因此，需要仔细筛选可用词元。工程上的难题是在固有限制下优化效用。

上下文工程是一个迭代过程，每次决定向模型传递哪些内容时，都会进行筛选。这不是一次性的提示词编写，而是一项持续进行的上下文管理工作。

实践指南

基于文件系统的访问

能够访问文件系统的 Agent 可以自然地采用渐进式披露。将参考资料、文档和数据存储在外部。只在需要时使用标准文件系统操作加载文件。这种模式可以避免将可能无关的信息塞入上下文。

文件系统本身提供了可供 Agent 浏览的结构。文件大小可以体现复杂程度；命名惯例可以提示用途；时间戳可以作为相关性的替代指标。文件引用的元数据提供了一种高效优化行为的机制。

混合策略

最高效的 Agent 会采用混合策略。预先加载部分上下文以提高速度（例如 CLAUDE.md 文件或项目规则），但也要支持自主探索，以便按需获取更多上下文。决策界限取决于任务特征和上下文的动态变化。

对于内容变化较少的上下文，预先多加载一些是合理的。对于快速变化或高度具体的信息，按需加载可以避免上下文过时。

上下文预算

设计时要明确考虑上下文预算。了解模型和任务的有效上下文上限。在开发期间监控上下文使用情况。设置恰当的压缩触发阈值。设计系统时要假设上下文会退化，而不是寄希望于它不会退化。

有效的上下文预算管理不仅需要了解原始 token 数量，还需要了解注意力分布模式。上下文中部获得的注意力少于开头和结尾。将关键信息放在更容易获得注意力的位置。

示例

示例 1：组织系统提示词

<BACKGROUND_INFORMATION>
You are a Python expert helping a development team.
Current project: Data processing pipeline in Python 3.9+
</BACKGROUND_INFORMATION>

<INSTRUCTIONS>
- Write clean, idiomatic Python code
- Include type hints for function signatures
- Add docstrings for public functions
- Follow PEP 8 style guidelines
</INSTRUCTIONS>

<TOOL_GUIDANCE>
Use bash for shell operations, python for code tasks.
File operations should use pathlib for cross-platform compatibility.
</TOOL_GUIDANCE>

<OUTPUT_DESCRIPTION>
Provide actionable feedback with specific line references.
Explain the reasoning behind suggestions.
</OUTPUT_DESCRIPTION>

示例 2：渐进式文档加载

# Instead of loading all documentation at once:

# Step 1: Load summary
docs/architecture_overview.md     # Lightweight overview

# Step 2: Load specific section as needed
docs/api/endpoints.md             # Only when API work needed
docs/database/schemas.md          # Only when data layer work needed

示例 3：技能描述设计

# Bad: Vague description that loads into context but provides little signal
description: Helps with code things

# Good: Specific description that helps model decide when to activate
description: Analyze code quality and suggest refactoring patterns. Use when reviewing pull requests or improving existing code structure.

指南

1. 将上下文视为有限资源，并考虑其边际收益递减
2. 将关键信息放在更容易获得注意力的位置（开头和结尾）
3. 使用渐进式披露，延迟加载直至需要时
4. 使用清晰的章节边界组织系统提示词
5. 在开发期间监控上下文使用情况
6. 在使用率达到 70-80% 时设置压缩触发条件
7. 针对上下文退化进行设计，而不是寄希望于避免退化
8. 优先使用更小但信号更强的上下文，而不是更大但信号更弱的上下文

上下文退化模式

随着上下文长度增加，大语言模型会呈现可预测的退化模式。了解这些模式对于诊断故障和设计弹性系统至关重要。上下文退化并非二元状态，而是一个性能逐渐下降的连续过程，会以几种不同的方式表现出来。

核心概念

上下文退化会呈现几种不同的模式。中间遗失现象会导致上下文中部的信息获得的注意力减少。上下文污染会在反复引用的过程中造成错误累积。上下文干扰会导致无关信息淹没相关内容。上下文混淆会导致模型无法确定应采用哪部分上下文。上下文冲突则会在信息累积后产生直接矛盾。

这些模式具有可预测性，可以通过压缩、屏蔽、分区和隔离等架构模式加以缓解。

详细主题

中间遗失现象

记录最充分的退化模式是“中间遗失”效应，模型会呈现 U 形注意力曲线。模型能够可靠地关注上下文开头和结尾的信息，而埋在中间的信息，其召回准确率会大幅下降。

实证证据 研究表明，与同一信息放在上下文开头或结尾相比，放在中间时，相关信息的召回准确率会低 10-40%。这并非模型失效，而是注意力机制和训练数据分布所致。

模型会将大量注意力分配给第一个 token（通常是 BOS token），以稳定内部状态。这会形成一个吸收注意力预算的“注意力汇”。随着上下文增长，有限的预算被进一步摊薄，中间的 token 无法获得足够的注意力权重，因而难以可靠地检索。

实际影响 设计上下文内容的排布时，应考虑注意力模式。将关键信息放在上下文开头或结尾。考虑信息是会被直接查询，还是需要用于支持推理——如果是后者，位置就没那么重要，但整体信号质量更重要。

对于较长的文档或对话，使用摘要结构，将关键信息置于注意力更偏好的位置。使用明确的章节标题和过渡语，帮助模型理解结构。

上下文污染

当幻觉、错误或不准确的信息进入上下文，并在反复引用中不断累积时，就会发生上下文污染。一旦上下文被污染，就会形成不断强化错误认知的反馈循环。

污染如何发生 污染通常通过三种途径进入。第一，工具输出可能包含错误或意料之外的格式，模型却将其当作真实依据。第二，检索到的文档可能包含错误或过时的信息，并被模型纳入推理。第三，模型生成的摘要或中间输出可能引入幻觉，并在上下文中持续存在。

累积效应十分严重。如果 Agent 的目标部分遭到污染，它就会制定难以纠正的策略。之后的每次决策都会引用被污染的内容，从而强化错误假设。

检测与恢复 留意以下症状：此前能够完成的任务现在输出质量下降；工具调用不匹配，Agent 调用了错误的工具或参数；以及即使尝试纠正，幻觉仍然持续。出现这些症状时，应考虑上下文污染。

恢复需要移除或替换被污染的内容。这可能需要将上下文截断到污染发生之前，在上下文中明确指出污染并要求重新评估，或者使用干净的上下文重新开始，只保留经过验证的信息。

上下文干扰

当上下文变得过长，以至于模型过度关注所提供的信息，而忽略其训练知识时，就会出现上下文干扰。模型会关注上下文中的所有内容，不论其是否相关，这会使模型倾向于使用所提供的信息，即使其内部知识更准确。

干扰项效应 研究表明，即使上下文中只有一份无关文档，也会降低模型在涉及相关文档的任务中的表现。多个干扰项会加剧性能下降。这种效应并非绝对意义上的噪声所致，而是注意力分配的问题——无关信息会与相关信息争夺有限的注意力资源。

模型没有“跳过”无关上下文的机制。它们必须关注提供的所有内容，即使无关信息显然毫无用处，这种义务也会造成干扰。

缓解策略 通过谨慎筛选进入上下文的信息来缓解干扰。在加载检索到的文档之前进行相关性筛选。使用命名空间和结构化组织，让无关部分在结构上易于忽略。考虑信息是否确实需要放入上下文，还是可以通过工具调用来获取。

上下文混淆

当无关信息以降低质量的方式影响响应时，就会出现上下文混淆。这与干扰有关，但两者并不相同——混淆关注上下文对模型行为的影响，而非注意力分配。

如果将内容放入上下文，模型就必须关注它。模型可能会纳入无关信息、使用不合适的工具定义，或应用来自其他上下文的约束。当上下文包含多种任务类型，或在单个会话中切换任务时，混淆尤其成问题。

混淆迹象 留意以下响应：回答了查询中错误的方面、调用了看似适用于其他任务的工具，或混合了来自多个来源的要求。这些迹象表明模型混淆了哪些上下文适用于当前情境。

架构层面的解决方案 架构层面的解决方案包括明确划分任务，为不同任务分配不同的上下文窗口，清晰地切换任务上下文，以及管理状态以隔离不同目标对应的上下文。

上下文冲突

当累积的信息直接矛盾并导致推理偏离时，就会出现上下文冲突。这与投毒不同：投毒是某一条信息有误；而冲突是多条正确的信息彼此矛盾。

冲突来源 冲突常见于多来源检索（不同来源的信息相互矛盾）、版本冲突（过时信息与当前信息同时出现在上下文中），以及观点冲突（不同观点各自成立，但彼此不兼容）。

解决方法 解决方法包括明确标记冲突并指出矛盾、请求澄清；制定优先级规则以确定哪个来源优先；以及通过版本筛选，从上下文中排除过时信息。

反直觉的发现

研究揭示了几种反直觉的模式，对上下文管理的常见假设提出了挑战。

打乱的干草堆优于连贯的干草堆 研究发现，打乱（不连贯）的干草堆比逻辑连贯的干草堆带来更好的表现。这表明，连贯的上下文可能会形成错误关联，干扰检索；而不连贯的上下文会迫使模型依赖精确匹配。

单个干扰项的影响远超预期 即使只有一份无关文档，也会显著降低表现。这种影响并不与噪声量成正比，而是呈阶跃变化：只要存在任何干扰项，表现就会下降。

针与问题的相似度关联 针与问题之间的相似度越低，表现随上下文长度增加而下降的速度越快。需要在不相似内容之间进行推理的任务尤其容易受到影响。

上下文更长何时会适得其反

更大的上下文窗口并不会一概提升表现。在许多情况下，更大的上下文会带来新的问题，其负面影响超过收益。

表现下降曲线 模型的表现会随上下文长度呈非线性下降。表现会在达到某个阈值前保持稳定，随后迅速下降。阈值因模型和任务复杂度而异。对许多模型而言，即使上下文窗口支持大得多的容量，显著下降也会在约 8,000-16,000 个 token 时开始。

成本影响 处理成本会随上下文长度大幅增加。处理 400K 个 token 上下文的成本并非处理 200K 个 token 上下文的两倍，而是在时间和计算资源方面呈指数级增长。对许多应用而言，这使得处理大上下文在经济上不切实际。

认知负荷的比喻 即使上下文无限，让单个模型在数十个互不相关的任务中始终保持稳定质量，也会形成认知瓶颈。模型必须不断在不同事项之间切换上下文、维持比较框架，并确保风格一致。这并不是增加上下文就能解决的问题。

实用指南

四类策略

四种策略分别应对上下文退化的不同方面：

写入：使用草稿区、文件系统或外部存储，在上下文窗口之外保存内容。这样既能保持活动上下文精简，又能保留对信息的访问能力。

选择：通过检索、筛选和优先排序，将相关上下文引入窗口。这可以通过排除无关信息来减少干扰。

压缩：通过摘要、抽象和观察结果屏蔽，在保留信息的同时减少 token 数量。这可以扩展有效上下文容量。

隔离：将上下文拆分到多个子 Agent 或会话中，避免任何单个上下文增长到足以造成退化的程度。这是力度最大的策略，但往往也是最有效的策略。

架构模式

通过特定架构模式实施这些策略。使用即时上下文加载，只在需要时检索信息。使用观察结果屏蔽，将冗长的工具输出替换为精简引用。使用子 Agent 架构，为不同任务隔离上下文。使用上下文压缩，在上下文增长到超出限制前对其进行摘要。

示例

示例 1：检测提示词设计中的退化

# Signs your command/skill prompt may be too large:

Early signs (context ~50-70% utilized):
- Agent occasionally misses instructions
- Responses become less focused
- Some guidelines ignored

Warning signs (context ~70-85% utilized):
- Inconsistent behavior across runs
- Agent "forgets" earlier instructions
- Quality varies significantly

Critical signs (context >85% utilized):
- Agent ignores key constraints
- Hallucinations increase
- Task completion fails

示例 2：通过提示词结构缓解中间信息丢失

# Organize prompts with critical info at edges

<CRITICAL_CONSTRAINTS>                    # At start (high attention)
- Never modify production files directly
- Always run tests before committing
- Maximum file size: 500 lines
</CRITICAL_CONSTRAINTS>

<DETAILED_GUIDELINES>                     # Middle (lower attention)
- Code style preferences
- Documentation templates
- Review checklists
- Example patterns
</DETAILED_GUIDELINES>

<KEY_REMINDERS>                           # At end (high attention)
- Run tests: npm test
- Format code: npm run format
- Create PR with description
</KEY_REMINDERS>

示例 3：子 Agent 上下文隔离

# Instead of one agent handling everything:

## Coordinator Agent (lean context)
- Understands task decomposition
- Delegates to specialized sub-agents
- Synthesizes results

## Code Review Sub-Agent (isolated context)
- Loaded only with code review guidelines
- Focuses solely on review task
- Returns structured findings

## Test Writer Sub-Agent (isolated context)
- Loaded only with testing patterns
- Focuses solely on test creation
- Returns test files

指南

1. 在开发过程中监控上下文长度与性能之间的关联
2. 将关键信息放在上下文的开头或结尾
3. 在性能严重下降之前设置压缩触发条件
4. 将检索到的文档添加到上下文之前，先验证其准确性
5. 使用版本控制，防止过时信息引发冲突
6. 对任务进行拆分，避免不同目标之间的上下文混淆
7. 针对平稳降级进行设计，而不是假设环境始终理想
8. 使用逐渐增大的上下文进行测试，以找到性能下降的临界点

上下文退化模式：多 Agent 工作流

本节将上下文退化的检测与缓解概念转化为适用于 Claude Code 的可执行多 Agent 工作流。构建命令、技能或复杂 Agent 流水线时，请使用这些模式来确保质量和可靠性。

幻觉检测工作流

Agent 输出中的幻觉可能会污染下游上下文，并在多步骤工作流中传播错误。此工作流会在错误累积之前检测幻觉。

适用场景

• 任何 Agent 完成会产生事实性陈述的任务后
• 提交 Agent 生成的代码或文档之前
• 输出将用作后续 Agent 的输入时
• 审查长时间运行的 Agent 会话期间

多 Agent 验证模式

步骤 1：生成输出

让主 Agent 正常完成任务。

步骤 2：提取陈述

使用以下提示词启动一个验证子 Agent：

<TASK>
Extract all factual claims from the following output. List each claim on a separate line.
</TASK>

<FOCUS_AREAS>
- File paths and their existence
- Function/class/method names referenced
- Code behavior assertions ("this function returns X")
- External facts about APIs, libraries, or specifications
- Numerical values and metrics
</FOCUS_AREAS>

<OUTPUT_TO_ANALYZE>
{agent_output}
</OUTPUT_TO_ANALYZE>

<OUTPUT_FORMAT>
One claim per line, prefixed with category:
[PATH] /src/auth/login.ts exists
[CODE] validateCredentials() returns a boolean
[FACT] JWT tokens expire after 24 hours by default
[METRIC] The function has O(n) complexity
</OUTPUT_FORMAT>

步骤 3：验证陈述

针对提取出的陈述组，启动一个验证 Agent：

<TASK>
Verify this claim by checking the actual codebase and context.
</TASK>

<CLAIM>
{claim}
</CLAIM>

<VERIFICATION_APPROACH>
- For file paths: Use file tools to check existence
- For code claims: Read the actual code and verify behavior
- For external facts: Cross-reference with documentation or web search
- For metrics: Analyze the code structure
</VERIFICATION_APPROACH>

<RESPONSE_FORMAT>
STATUS: [VERIFIED | FALSE | UNVERIFIABLE]
EVIDENCE: [What you found]
CONFIDENCE: [HIGH | MEDIUM | LOW]
</RESPONSE_FORMAT>

步骤 4：计算污染风险

汇总验证结果：

total_claims = number of claims extracted
verified_count = claims marked VERIFIED
false_count = claims marked FALSE
unverifiable_count = claims marked UNVERIFIABLE

poisoning_risk = (false_count * 2 + unverifiable_count) / total_claims

步骤 5：判定阈值

• 风险 < 0.1：输出可靠，正常继续
• 风险 0.1-0.3：继续之前，手动审查标记的陈述
• 风险 > 0.3：使用更明确的依据说明重新生成输出：

<REGENERATION_PROMPT>
Previous output contained {false_count} false claims and {unverifiable_count} unverifiable claims.

Specific issues:
{list of FALSE and UNVERIFIABLE claims with evidence}

Please regenerate your response. For each factual claim:
1. Explicitly verify it using tools before stating it
2. If you cannot verify, state "I cannot verify..." instead of asserting
3. Cite the specific file/line/source for verifiable facts
</REGENERATION_PROMPT>

中间信息遗失检测工作流

埋在长提示词中间的关键信息较不容易受到关注。此工作流通过运行多个 Agent，并根据原始指令验证其输出，来检测提示词中哪些部分可能会被忽略。

适用场景

• 设计带有长提示词的新命令或技能时
• Agent 在不同运行中未能始终如一地遵循指令时
• 将提示词部署到生产环境之前
• 优化提示词期间

多次运行验证模式

步骤 1：识别关键指令

从提示词中提取 Agent 必须遵循的所有关键指令：

Critical instructions to verify:
1. "Never modify files in /production"
2. "Always run tests before committing"
3. "Use TypeScript strict mode"
4. "Maximum function length: 50 lines"
5. "Include JSDoc for public APIs"
6. "Format output as JSON"
7. "Log all file modifications"

步骤 2：使用相同提示词运行多个 Agent

使用相同的提示词（正在测试的命令、技能或 Agent）启动 3-5 个 Agent。每个 Agent 使用相同的输入独立运行：

<AGENT_RUN_CONFIG>
Number of runs: 5
Prompt: {your_full_prompt_being_tested}
Task: {representative_task_that_exercises_all_instructions}

For each run, save:
- run_id: unique identifier
- agent_output: complete response from agent
- timestamp: when run completed
</AGENT_RUN_CONFIG>

步骤 3：根据原始提示词验证每项输出

对于每个 Agent 的输出，启动一个新的验证 Agent，检查其是否遵循每一条关键指令：

<VERIFICATION_AGENT_PROMPT>
<TASK>
You are a compliance verification agent. Analyze whether the agent output followed each instruction from the original prompt.
</TASK>

<ORIGINAL_PROMPT>
{the_full_prompt_being_tested}
</ORIGINAL_PROMPT>

<CRITICAL_INSTRUCTIONS>
{numbered_list_of_critical_instructions}
</CRITICAL_INSTRUCTIONS>

<AGENT_OUTPUT>
{output_from_run_N}
</AGENT_OUTPUT>

<VERIFICATION_APPROACH>
For each critical instruction:
1. Determine if the instruction was applicable to this task
2. If applicable, check whether the output complies
3. Look for both explicit violations and omissions
4. Note any partial compliance
</VERIFICATION_APPROACH>

<OUTPUT_FORMAT>
RUN_ID: {run_id}

INSTRUCTION_COMPLIANCE:
- Instruction 1: "Never modify files in /production"
  STATUS: [FOLLOWED | VIOLATED | NOT_APPLICABLE]
  EVIDENCE: {quote from output or explanation}

- Instruction 2: "Always run tests before committing"
  STATUS: [FOLLOWED | VIOLATED | NOT_APPLICABLE]
  EVIDENCE: {quote from output or explanation}

[... continue for all instructions ...]

SUMMARY:
- Instructions followed: {count}
- Instructions violated: {count}
- Not applicable: {count}
</OUTPUT_FORMAT>
</VERIFICATION_AGENT_PROMPT>

步骤 4：汇总结果并识别风险部分

收集所有运行的验证结果，并找出未能始终如一地遵循的指令：

<AGGREGATION_LOGIC>
For each instruction:
  followed_count = number of runs where STATUS == FOLLOWED
  violated_count = number of runs where STATUS == VIOLATED
  applicable_runs = total_runs - (runs where STATUS == NOT_APPLICABLE)

  compliance_rate = followed_count / applicable_runs

  Classification:
  - compliance_rate == 1.0: RELIABLE (always followed)
  - compliance_rate >= 0.8: MOSTLY_RELIABLE (minor inconsistency)
  - compliance_rate >= 0.5: AT_RISK (inconsistent - likely lost-in-middle)
  - compliance_rate < 0.5: FREQUENTLY_IGNORED (severe issue)
  - compliance_rate == 0.0: ALWAYS_IGNORED (critical failure)

AT_RISK instructions are the primary signal for lost-in-middle problems.
These are instructions that work sometimes but not consistently, indicating
they are in attention-weak positions.
</AGGREGATION_LOGIC>

<AGGREGATION_OUTPUT_FORMAT>
INSTRUCTION COMPLIANCE SUMMARY:

| Instruction | Followed | Violated | Compliance Rate | Status |
|-------------|----------|----------|-----------------|--------|
| 1. Never modify /production | 5/5 | 0/5 | 100% | RELIABLE |
| 2. Run tests before commit | 3/5 | 2/5 | 60% | AT_RISK |
| 3. TypeScript strict mode | 4/5 | 1/5 | 80% | MOSTLY_RELIABLE |
| 4. Max function length 50 | 2/5 | 3/5 | 40% | FREQUENTLY_IGNORED |
| 5. Include JSDoc | 5/5 | 0/5 | 100% | RELIABLE |
| 6. Format as JSON | 1/5 | 4/5 | 20% | ALWAYS_IGNORED |
| 7. Log modifications | 3/5 | 2/5 | 60% | AT_RISK |

AT-RISK INSTRUCTIONS (likely in lost-in-middle zone):
- Instruction 2: "Run tests before commit" (60% compliance)
- Instruction 4: "Max function length 50" (40% compliance)
- Instruction 6: "Format as JSON" (20% compliance)
- Instruction 7: "Log modifications" (60% compliance)
</AGGREGATION_OUTPUT_FORMAT>

步骤 5：给出建议

根据识别出的风险部分，提供具体的修复指导：

<RECOMMENDATIONS_OUTPUT>
LOST-IN-MIDDLE ANALYSIS COMPLETE

At-Risk Instructions Detected: {count}
These instructions are inconsistently followed, indicating they likely
reside in attention-weak positions (middle of prompt).

SPECIFIC RECOMMENDATIONS:

1. MOVE CRITICAL INFORMATION TO ATTENTION-FAVORED POSITIONS
   The following instructions should be relocated to the beginning or end of your prompt:
   - "Run tests before commit" -> Move to <CRITICAL_CONSTRAINTS> at prompt START
   - "Max function length 50" -> Move to <KEY_REMINDERS> at prompt END
   - "Format as JSON" -> Move to <OUTPUT_FORMAT> at prompt END
   - "Log modifications" -> Add to both START and END sections

2. USE EXPLICIT MARKERS TO HIGHLIGHT CRITICAL INFORMATION
   Restructure at-risk instructions with emphasis:

   Before: "Always run tests before committing"
   After:  "**CRITICAL:** You MUST run tests before committing. Never skip this step."

   Before: "Maximum function length: 50 lines"
   After:  "3. [REQUIRED] Maximum function length: 50 lines"

   Use numbered lists, bold markers, or explicit tags like [REQUIRED], [CRITICAL], [MUST].

3. CONSIDER SPLITTING CONTEXT TO REDUCE MIDDLE SECTION
   If your prompt has many instructions, consider:
   - Breaking into focused sub-prompts for different aspects
   - Using sub-agents with specialized, shorter contexts
   - Moving detailed guidance to on-demand sections loaded only when needed

   Current prompt structure creates a large middle section where
   {count} instructions are being lost. Reduce middle section by:
   - Moving 2-3 most critical items to edges
   - Converting remaining middle items to a numbered checklist
   - Adding explicit "verify these items" reminder at end
</RECOMMENDATIONS_OUTPUT>

完整工作流示例

# Example: Testing a Code Review Command

## Original Prompt Being Tested:
"Review the code for: security issues, performance problems,
code style, test coverage, documentation completeness,
error handling, and logging practices."

## Run 5 Agents:
Each agent reviews the same code sample with this prompt.

## Verification Results:
| Instruction | Run 1 | Run 2 | Run 3 | Run 4 | Run 5 | Rate |
|-------------|-------|-------|-------|-------|-------|------|
| Security | Y | Y | Y | Y | Y | 100% |
| Performance | Y | X | Y | X | Y | 60% |
| Code style | X | X | Y | X | X | 20% |
| Test coverage | X | Y | X | X | Y | 40% |
| Documentation | X | X | X | Y | X | 20% |
| Error handling | Y | Y | X | Y | Y | 80% |
| Logging | Y | Y | Y | Y | Y | 100% |

## Analysis:
- RELIABLE: Security, Logging (at edges of list)
- AT_RISK: Performance, Error handling
- FREQUENTLY_IGNORED: Code style, Test coverage, Documentation (middle of list)

## Remediation Applied:
"**CRITICAL REVIEW AREAS:**
1. Security vulnerabilities
2. Test coverage gaps
3. Documentation completeness

Review also: performance, code style, error handling, logging.

**BEFORE COMPLETING:** Verify you addressed items 1-3 above."

错误传播分析工作流

在多 Agent 链中，早期 Agent 的错误会沿后续 Agent 传播并不断放大。此工作流会追踪错误的来源。

适用场景

• 尽管中间步骤正确，最终输出仍包含错误时
• 调试复杂的多 Agent 工作流时
• 在 Agent 链中确定错误边界时
• 对失败的 Agent 任务进行事后分析时

错误追踪模式

步骤 1：捕获 Agent 链的输出

记录链中每个 Agent 的输出：

Agent Chain Record:
- Agent 1 (Analyzer): {output_1}
- Agent 2 (Planner): {output_2}
- Agent 3 (Implementer): {output_3}
- Agent 4 (Reviewer): {output_4}

步骤 2：识别错误症状

启动一个错误识别 Agent：

<TASK>
Analyze the final output and identify all errors, inconsistencies, or quality issues.
</TASK>

<FINAL_OUTPUT>
{output_from_last_agent}
</FINAL_OUTPUT>

<OUTPUT_FORMAT>
ERROR_ID: E1
DESCRIPTION: Function missing null check
LOCATION: src/utils/parser.ts:45
SEVERITY: HIGH

ERROR_ID: E2
...
</OUTPUT_FORMAT>

步骤 3：反向追踪每个错误

针对识别出的每个错误，启动一个追踪 Agent：

<TASK>
Trace this error backward through the agent chain to find its origin.
</TASK>

<ERROR>
{error_description}
</ERROR>

<AGENT_CHAIN_OUTPUTS>
Agent 1 Output: {output_1}
Agent 2 Output: {output_2}
Agent 3 Output: {output_3}
Agent 4 Output: {output_4}
</AGENT_CHAIN_OUTPUTS>

<ANALYSIS_APPROACH>
For each agent output (starting from the last):
1. Does this output contain the error?
2. If yes, was the error present in the input to this agent?
3. If error is in output but not input: This agent INTRODUCED the error
4. If error is in both: This agent PROPAGATED the error
</ANALYSIS_APPROACH>

<OUTPUT_FORMAT>
ERROR: {error_id}
ORIGIN_AGENT: Agent {N}
ORIGIN_TYPE: [INTRODUCED | PROPAGATED_FROM_CONTEXT | PROPAGATED_FROM_TOOL_OUTPUT]
ROOT_CAUSE: {explanation}
CONTEXT_THAT_CAUSED_IT: {relevant context snippet if applicable}
</OUTPUT_FORMAT>

步骤 4：计算传播指标

For each agent in chain:
  errors_introduced = count of errors this agent created
  errors_propagated = count of errors this agent passed through
  errors_caught = count of errors this agent fixed or flagged

propagation_rate = errors_at_end / errors_introduced_total
amplification_factor = errors_at_end / errors_at_start

步骤 5：设定错误边界

根据分析结果，添加验证检查点：

<ERROR_BOUNDARY_TEMPLATE>
After Agent {N} completes:

1. Spawn verification agent to check for common error patterns:
   - {error_pattern_1 that Agent N tends to introduce}
   - {error_pattern_2 that Agent N tends to introduce}

2. If errors detected:
   - Log error for analysis
   - Either: Fix inline and continue
   - Or: Regenerate Agent N output with explicit guidance

3. Only proceed to Agent {N+1} if verification passes
</ERROR_BOUNDARY_TEMPLATE>

上下文相关性评分工作流

提示词的各个部分对任务完成的贡献并不相同。此工作流可识别提示词中的干扰部分，这些部分会消耗注意力预算，却无法带来价值。

适用场景

• 优化提示词长度和内容时
• 决定在 CLAUDE.md 中包含哪些内容时
• 提示词显得臃肿，但不确定该删减哪些内容时
• 调试忽略所提供上下文的 Agent 时
• 部署新命令、技能或 Agent 提示词前

干扰内容识别模式

步骤 1：将提示词拆分为多个部分

将提示词（命令／技能／Agent）划分为逻辑部分。每个部分都应是一个完整的单元：

<PROMPT_PARTS>
PART_1:
  ID: background
  CONTENT: |
    You are a Python expert helping a development team.
    Current project: Data processing pipeline in Python 3.9+

PART_2:
  ID: code_style_rules
  CONTENT: |
    - Write clean, idiomatic Python code
    - Include type hints for function signatures
    - Add docstrings for public functions
    - Follow PEP 8 style guidelines

PART_3:
  ID: historical_context
  CONTENT: |
    The project was migrated from Python 2.7 in 2019.
    Original team used camelCase naming but we now use snake_case.
    Legacy modules in /legacy folder are frozen.

PART_4:
  ID: output_format
  CONTENT: |
    Provide actionable feedback with specific line references.
    Explain the reasoning behind suggestions.
</PROMPT_PARTS>

拆分指南：

• 每个 XML 部分或 Markdown 标题都作为一个部分
• 将概念上不同的指令分别拆分为独立部分
• 将相关指令放在一起（不要从一句话中间拆分）
• 根据提示词长度，将部分数量控制在 3-15 个

步骤 2：启动评分 Agent

并行启动多个评分 Agent：

<TASK>
Score how relevant this prompt parts is for accomplishing the specified task.
</TASK>

<TASK_DESCRIPTION>
{description of what the agent should accomplish}
Example: "Review a pull request for code quality issues and suggest improvements"
</TASK_DESCRIPTION>

<PROMPT_PARTS>
{contents of all the parts being evaluated}
</PROMPT_PARTS>

<SCORING_CRITERIA>
Score 0-10 based on these criteria:

ESSENTIAL (8-10):
- Part directly enables task completion
- Removing this part would cause task failure
- Part contains critical constraints that prevent errors
- Part defines required output format or structure

HELPFUL (5-7):
- Part improves output quality but is not strictly required
- Part provides useful context that guides better decisions
- Part contains preferences that affect style but not correctness

MARGINAL (2-4):
- Part has tangential relevance to the task
- Part might occasionally be useful but usually is not
- Part provides historical context rarely needed

DISTRACTOR (0-1):
- Part is irrelevant to the task
- Part could confuse the agent about what to focus on
- Part competes for attention without contributing value
</SCORING_CRITERIA>

<OUTPUT_FORMAT>
RELEVANCE_SCORE: [0-10]
JUSTIFICATION: [2-3 sentences explaining the score]
USAGE_LIKELIHOOD: [How often would the agent reference this part during task execution? ALWAYS | OFTEN | SOMETIMES | RARELY | NEVER]
</OUTPUT_FORMAT>

步骤 3：汇总相关性评分

收集所有评分 Agent 给出的分数：

PART_SCORES = [
  {id: "background", score: 8, usage: "ALWAYS"},
  {id: "code_style_rules", score: 9, usage: "ALWAYS"},
  {id: "historical_context", score: 3, usage: "RARELY"},
  {id: "output_format", score: 7, usage: "OFTEN"}
]

计算汇总指标：

total_parts = count(PART_SCORES)
high_relevance_parts = count(parts where score >= 5)
distractor_parts = count(parts where score < 5)

context_efficiency = high_relevance_parts / total_parts
average_relevance = sum(scores) / total_parts

步骤 4：识别干扰部分

应用干扰阈值（分数 < 5）：

DISTRACTOR_ANALYSIS:

Identified Distractors:
1. PART: historical_context
   SCORE: 3/10
   JUSTIFICATION: "Migration history from Python 2.7 is rarely relevant to reviewing current code. The naming convention note is useful but should be in code_style_rules instead."
   RECOMMENDATION: REMOVE or RELOCATE

Summary:
- Total parts: 4
- High-relevance parts (>=5): 3
- Distractor parts (<5): 1
- Context efficiency: 75%
- Average relevance: 6.75

Token Impact:
- Distractor tokens: ~45 (historical_context)
- Potential savings: 45 tokens (11% of prompt)

步骤 5：生成优化建议

根据干扰内容分析，提供可执行的建议：

OPTIMIZATION_RECOMMENDATIONS:

1. REMOVE: historical_context
   Reason: Score 3/10, usage RARELY. Migration history does not inform code review decisions.

2. RELOCATE: "we now use snake_case" from historical_context
   Target: code_style_rules section
   Reason: This specific rule is relevant but buried in irrelevant historical context.

3. CONSIDER CONDENSING: background
   Current: 2 sentences
   Could be: 1 sentence ("Python 3.9+ data pipeline expert")
   Savings: ~15 tokens

OPTIMIZED PROMPT STRUCTURE:
- background (condensed): 8 tokens
- code_style_rules (with snake_case added): 52 tokens
- output_format: 28 tokens
- Total: 88 tokens (down from 133 tokens)
- Efficiency improvement: 34% reduction

干扰阈值指南

默认阈值 5 可在全面性和效率之间取得平衡：

阈值	适用场景
< 3	在令牌受限的上下文中大幅删减
< 5	标准优化（推荐默认值）
< 7	对关键提示词进行保守删减

根据以下因素调整阈值：

• 上下文预算压力：接近限制时降低阈值
• 任务重要性：生产环境提示词使用较高阈值
• 提示词稳定性：实验性提示词使用较低阈值

评分 Agent 部署

为提高效率，可并行执行评分 Agent：

# Parallel execution pattern
spawn_parallel([
  scoring_agent(part_1, task_description),
  scoring_agent(part_2, task_description),
  scoring_agent(part_3, task_description),
  ...
])

# Collect and aggregate
scores = await_all(scoring_agents)
analysis = aggregate_scores(scores)

对于大型提示词（>10 个部分），将评分 Agent 分成每组 5-7 个进行批处理，以控制编排开销。

上下文健康监控工作流

长时间运行的 Agent 会话会不断累积上下文，导致性能随时间退化。此工作流用于监控上下文健康状况并触发干预。

适用场景

• 长时间运行的 Agent 会话期间（>20 轮）
• Agent 开始出现性能退化症状时
• 在 Agent 编排系统中定期进行健康检查时
• Agent 工作流中的关键决策点之前

健康检查模式

步骤 1：定期检测症状

每经过 N 轮（建议：每 10 轮），启动一个健康检查 Agent：

<TASK>
Analyze the recent conversation history for signs of context degradation.
</TASK>

<RECENT_HISTORY>
{last 10 turns of conversation}
</RECENT_HISTORY>

<SYMPTOM_CHECKLIST>
Check for these degradation symptoms:

LOST_IN_MIDDLE:
- [ ] Agent missing instructions from early in conversation
- [ ] Critical constraints being ignored
- [ ] Agent asking for information already provided

CONTEXT_POISONING:
- [ ] Same error appearing repeatedly
- [ ] Agent referencing incorrect information as fact
- [ ] Hallucinations that persist despite correction

CONTEXT_DISTRACTION:
- [ ] Responses becoming unfocused
- [ ] Agent using irrelevant context inappropriately
- [ ] Quality declining on previously-successful tasks

CONTEXT_CONFUSION:
- [ ] Agent mixing up different task requirements
- [ ] Wrong tool selections for obvious tasks
- [ ] Outputs that blend requirements from different tasks

CONTEXT_CLASH:
- [ ] Agent expressing uncertainty about conflicting information
- [ ] Inconsistent behavior between turns
- [ ] Agent asking for clarification on resolved issues
</SYMPTOM_CHECKLIST>

<OUTPUT_FORMAT>
HEALTH_STATUS: [HEALTHY | DEGRADED | CRITICAL]
SYMPTOMS_DETECTED: [list of checked symptoms]
RECOMMENDED_ACTION: [CONTINUE | COMPACT | RESTART]
SPECIFIC_ISSUES: [detailed description of problems found]
</OUTPUT_FORMAT>

步骤 2：自动干预

根据健康状态，触发适当的干预措施：

IF HEALTH_STATUS == "DEGRADED" or HEALTH_STATUS == "CRITICAL":
  <RESTART_INTERVENTION>
  1. Extract essential state to preserve and save to a file
  2. Ask user to start a new session with clean context and load the preserved state from the file after the new session is started
  </RESTART_INTERVENTION>

多 Agent 验证指南

1. 启动目标明确、用途单一的验证 Agent
2. 使用结构化输出格式，以便可靠地解析
3. 为执行操作或继续执行的决策设定明确阈值
4. 记录所有验证结果，以便调试和优化
5. 在验证开销与错误预防价值之间取得平衡
6. 在自然检查点实施验证，而不是每一轮都进行
7. 日常操作使用轻量级检查，关键操作使用更严格的检查
8. 设计验证机制，使其在时间紧迫的场景中可以跳过

上下文优化技术

上下文优化通过策略性压缩、遮蔽、缓存和分区，扩展有限上下文窗口的有效容量。目标不是神奇地扩大上下文窗口，而是更好地利用可用容量。有效的优化无需更大的模型或更长的上下文，就能将有效上下文容量提升一倍或三倍。

核心概念

上下文优化通过四种主要策略扩展有效容量：压缩（接近上限时总结上下文）、观察结果遮蔽（用引用替换冗长输出）、KV 缓存优化（复用缓存的计算结果）以及上下文分区（在相互隔离的上下文中拆分工作）。

关键在于，上下文质量比数量更重要。优化在减少噪声的同时保留有效信息。诀窍在于选择保留或舍弃哪些内容，以及何时应用每种技术。

详细主题

压缩策略

什么是压缩 压缩是指在接近上限时总结上下文内容，然后使用摘要重新初始化一个新的上下文窗口。这种方法能以高保真度提炼上下文窗口的内容，使 Agent 能够继续工作，同时最大限度地减少性能下降。

压缩通常是上下文优化中首先采用的手段。诀窍在于选择保留或舍弃哪些内容。

实际应用中的压缩 压缩的方式是识别可压缩的部分，生成概括要点的摘要，并用摘要替换完整内容。压缩优先级如下：

1. 工具输出 - 用关键发现替换冗长输出
2. 较早的对话轮次 - 总结早期交流
3. 检索到的文档 - 如果任务上下文已涵盖相关内容，则进行总结
4. 绝不压缩 - 系统提示词和关键约束

生成摘要 有效摘要会根据内容类型保留不同要素：

• 工具输出：保留关键发现、指标和结论。删除冗长的原始输出。
• 对话轮次：保留关键决策、承诺和上下文变化。删除填充内容和来回交流。
• 检索到的文档：保留关键事实和主张。删除佐证和展开说明。

观察结果遮蔽

观察结果问题 工具输出可能占 Agent 执行轨迹中 80% 以上的 token 用量。其中很多是已完成使命的冗长输出。Agent 使用工具输出作出决策后，保留完整输出带来的价值会逐渐降低，却仍会占用大量上下文。

观察结果遮蔽会用精简引用替换冗长的工具输出。需要时仍可访问相关信息，但不会持续占用上下文。

选择遮蔽策略 并非所有观察结果都应以相同方式遮蔽：

绝不遮蔽：

• 对当前任务至关重要的观察结果
• 最近一轮中的观察结果
• 用于当前推理的观察结果

考虑遮蔽：

• 3 轮或更早之前的观察结果
• 可提取关键要点的冗长输出
• 已完成使命的观察结果

始终遮蔽：

• 重复输出
• 模板化的页眉／页脚
• 已在对话中总结的输出

上下文分区

子 Agent 分区 最激进的上下文优化方式，是将工作分配给上下文相互隔离的子 Agent。每个子 Agent 都在干净的上下文中专注处理自己的子任务，不会携带其他子任务累积的上下文。

这种方式实现了关注点分离——详细的搜索上下文保留在子 Agent 内部，协调 Agent 则专注于综合和分析。

何时进行分区 以下情况可考虑进行分区：

• 任务可以自然拆分为彼此独立的子任务
• 不同子任务需要不同的专业上下文
• 上下文累积可能导致超出限制
• 不同子任务的要求相互冲突

结果汇总 按以下步骤汇总分区子任务的结果：

1. 确认所有分区均已完成
2. 合并兼容的结果
3. 如果合并后的结果仍然过长，则进行摘要
4. 解决各分区输出之间的冲突

实用指南

优化决策框架

何时进行优化：

• 对话延长后，响应质量下降
• 上下文过长导致成本增加
• 对话越长，延迟越高

应用哪些方法：

• 工具输出占主导：屏蔽观察结果
• 检索到的文档占主导：进行摘要或分区
• 消息历史占主导：通过摘要进行压缩
• 多个组成部分占主导：组合使用多种策略

将优化应用于 Claude Code 提示词

命令优化 命令按需加载，因此应重点确保每条命令都专注明确：

# Good: Focused command with clear scope
---
name: review-security
description: Review code for security vulnerabilities
---
# Specific security review instructions only

# Avoid: Overloaded command trying to do everything
---
name: review-all
description: Review code for everything
---
# 50 different review checklists crammed together

技能优化 技能描述默认会加载，因此描述必须简洁：

# Good: Concise description
description: Analyze code architecture. Use for design reviews.

# Avoid: Verbose description that wastes context budget
description: This skill provides comprehensive analysis of code
architecture including but not limited to class hierarchies,
dependency graphs, coupling metrics, cohesion analysis...

子 Agent 上下文设计 启动子 Agent 时，应提供聚焦的上下文：

# Coordinator provides minimal handoff:
"Review authentication module for security issues.
Return findings in structured format."

# NOT this verbose handoff:
"I need you to look at the authentication module which is
located in src/auth/ and contains several files including
login.ts, session.ts, tokens.ts... [500 more tokens of context]"

指南

1. 优化前先测量——了解当前状态
2. 尽可能先进行压缩，再进行屏蔽
3. 使用一致的提示词来设计稳定的缓存
4. 在上下文开始出现问题之前进行分区
5. 随时间推移监控优化效果
6. 在节省 Token 和保持质量之间取得平衡
7. 在生产规模下测试优化效果
8. 针对边缘情况实现平稳降级