Context Engineering Fundamentals

Context 指的是 language model 在 inference time 能看到的完整输入状态，包含 system instructions、tool definitions、retrieved documents、message history 和 tool outputs。理解 Context Fundamentals 是 Context Engineering 的前置能力。

在学习层面，可以把 Context 理解为“模型当前能看到的一切”。你越能控制它的结构与质量，就越能获得稳定、可复现的输出。

• Context 不只是 prompt，而是完整输入状态（system、tools、docs、history、outputs）。
• Attention budget 是有限的，Context 过长会稀释信号。
• Progressive disclosure 用“按需加载”保持 Context 精简。
• 关键信息优先放在开头或结尾。
• 目标是“最小高信号 token 集合”，不是“最大长度”。

你将学到什么

• 如何拆分 Context 的核心构成，并知道各自的风险点
• 为什么长 Context 会变“糊”，以及如何用结构降低风险
• 如何用 progressive disclosure 控制 Context 成本
• 如何用模板化结构提升稳定性

When to Activate

Activate this skill when:

• Designing new agent systems or modifying existing architectures
• Debugging unexpected agent behavior that may relate to context
• Optimizing context usage to reduce token costs or improve performance
• Onboarding new team members to context engineering concepts
• Reviewing context-related design decisions

当你在做 agent 系统设计、排查“模型为什么不听话”、或者 token 成本飙升，这一章是起点。

Core Concepts

Context 由多个组件构成，每个组件的特点与约束不同。Attention mechanism 提供了有限的 attention budget，这会限制有效 Context 的长度。Progressive disclosure 通过“按需加载”管理这个限制。Context Engineering 的核心任务是：筛出最小但高信号的 token 集合。

关键思想是：Context 不是越多越好，而是“高信号、小集合”。

Detailed Topics

The Anatomy of Context

System Prompts System prompts 建立 agent 的身份、约束与行为准则。它们在会话开始时加载，通常贯穿整个对话。System prompts 应该清晰、直接，并保持正确的“高度（altitude）”。

正确的高度需要平衡两种极端：一端是过度硬编码导致脆弱与维护成本；另一端是过于抽象导致缺乏可执行信号。最优点是：足够具体以指导行为，同时保留可扩展的启发式。

建议用 XML 标签或 Markdown headers 分区，拆成 background、instructions、tool guidance、output description。模型能力越强，格式影响越小，但结构清晰依然有价值。

Tool Definitions Tool definitions 定义 agent 可执行的动作。每个 tool 包含 name、description、parameters 与 return format。它们通常位于 Context 前部（system prompt 前后）。

Tool descriptions 会直接影响 agent 行为。描述差会迫使模型猜；描述好包含 usage context、examples 和 defaults。Consolidation principle 指出：如果人类工程师都无法确定该用哪个 tool，模型就更不可能正确选择。

Retrieved Documents Retrieved documents 提供领域知识与任务相关信息。RAG 的核心是运行时检索，而不是一次性加载全部资料。

Just-in-time 的方式保留轻量引用（file paths、stored queries、web links），需要时再加载。这与人类的认知方式一致：通过索引系统按需检索，而不是记住整个语料库。

Message History Message history 记录 user 与 agent 的对话，包括问题、回答与推理过程。长任务时，history 往往成为 Context 的最大开销。

Message history 是一种 scratchpad memory，用于跟踪进度与状态。管理不好会拖累长任务执行质量。

Tool Outputs Tool outputs 是 agent 行动的结果：文件内容、搜索结果、命令输出、API response 等。研究表明 tool outputs 可占 83.9% 的 Context tokens。

无论是否相关，tool outputs 都会消耗 Context，这推动了 observation masking、compaction、selective retention 等策略的必要性。

Context Windows and Attention Mechanics

The Attention Budget Constraint LLM 的 attention 需要处理 n² 级的 token 关系。Context 越长，关系越多，attention 预算越被拉薄。

模型在训练中更常见短序列，因此在超长 Context 下对远距离依赖的建模能力更弱，体现为“attention budget depletion”。

Position Encoding and Context Extension Position encoding interpolation 让模型支持更长序列，但会带来位置理解的精度下降。即使 context window 更大，长距离检索与推理能力仍会下降。

The Progressive Disclosure Principle Progressive disclosure 的原则是：只在需要时加载信息。启动时只加载 skill names + descriptions，任务需要时再加载全文。它适用于 skill 选择、文档加载、tool output 获取等多层级场景。

Context Quality Versus Context Quantity

“更大 Context 能解决记忆问题”的假设已被实证推翻。Context Engineering 的目标是找到最小的高信号 token 集合。

随着 Context 增长，成本会呈指数级上升，模型性能也会下降，即使 context window 允许更长 tokens。Prefix caching 也无法消除长输入成本。

核心原则是 informativity over exhaustiveness：只放“决策需要的信息”，其余信息按需获取。

Context as Finite Resource

Context 是有限资源，边际收益递减。每增加一个 token 都会消耗 attention budget。工程问题是：在既定限制内最大化效用。

Context Engineering 不是一次性 prompt 写作，而是持续的 Context 管理流程。

Practical Guidance

File-System-Based Access

有 filesystem access 的 agent 可以自然使用 progressive disclosure。把资料放在文件系统里，需要时再读取，而不是直接塞进 Context。

文件系统本身提供结构线索：文件大小、命名、时间戳都能作为 relevance 的代理信号。

Hybrid Strategies

最佳实践通常是 hybrid：预加载少量稳定 Context（如 CLAUDE.md、项目规则），再按需探索其它信息。边界取决于任务性质与动态性。

Context Budgeting

设计时要有明确 Context budget。监控 token usage，设置 compaction triggers。假设 Context 会退化，而不是假设一切正常。

注意 attention 分布：中间段最容易被忽略，关键信息应放在头尾。

Minimal Context Template

下面是一个可直接套用的最小 Context 模板：

<SYSTEM>
Role, constraints, output format
</SYSTEM>

<TASK>
Objective, success criteria, constraints
</TASK>

<TOOLS>
Tool list + usage notes
</TOOLS>

<FACTS>
Structured facts / IDs / sources
</FACTS>

<HISTORY>
Short summary of relevant turns
</HISTORY>

Examples

Example 1: Organizing System Prompts

<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 code blocks with syntax highlighting.
Explain non-obvious decisions in comments.
</OUTPUT_DESCRIPTION>

Example 2: Progressive Document Loading

# Instead of loading all documentation at once:

# Step 1: Load summary

docs/api_summary.md # Lightweight overview

# Step 2: Load specific section as needed

docs/api/endpoints.md # Only when API calls needed
docs/api/authentication.md # Only when auth context needed

Guidelines

1. Treat Context as a finite resource with diminishing returns
2. Place critical info at attention-favored positions (beginning/end)
3. Use progressive disclosure to defer loading until needed
4. Organize system prompts with clear section boundaries
5. Monitor Context usage during development
6. Implement compaction triggers at 70-80% utilization
7. Design for Context degradation rather than hoping to avoid it
8. Prefer smaller high-signal Context over larger low-signal Context

Practice Task

• 选一个你正在做的 agent/项目，把它的 Context 拆成 5 个区块
• 用上面的模板写一版“最小 Context”
• 对比原方案，标出可以删除的低信号内容

Related Pages

• Claude Code Examples
• Context Degradation Patterns
• Context Compression Strategies
• Tool Design for Agents

Integration

This skill provides foundational context that all other skills build upon. It should be studied first before exploring:

• context-degradation - Understanding how Context fails
• context-optimization - Techniques for extending Context capacity
• multi-agent-patterns - How Context isolation enables multi-agent systems
• tool-design - How tool definitions interact with Context

References

Internal reference:

• Context Components Reference - Detailed technical reference

Related skills in this collection:

• context-degradation - Understanding Context failure patterns
• context-optimization - Techniques for efficient Context use

External resources:

• Research on transformer attention mechanisms
• Production engineering guides from leading AI labs
• Framework documentation on Context window management

---

Skill Metadata

Created: 2025-12-20 Last Updated: 2025-12-20 Author: Agent Skills for Context Engineering Contributors Version: 1.0.0