# Context Engineering

设计 Agent 系统提示词、上下文结构或按需加载的 Skill 时使用, , 覆盖 API 消息角色与「静态前缀 +...

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill context-engineering -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill context-engineering -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill context-engineering -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill context-engineering -g -a gemini-cli -y`

## Description

设计 Agent 系统提示词、上下文结构或按需加载的 Skill 时使用, , 覆盖 API 消息角色与「静态前缀 + 轨迹」结构、系统提示词写法（结构化、SOP、业务规则细化、few-shot）、Agent Skills 渐进式披露与 SKILL.md 编写、提示注入的上下文层防御，以及注意力位置偏好等布局原则。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 上下文工程总纲

上下文是 Agent 在每个决策点实际「看到」的全部信息：系统提示词、工具定义、用户消息、模型回复、工具执行结果。上下文工程就是系统性设计、组织、供给这些信息, , 模型智力只是基础，**上下文质量才是 Agent 能力的真正关键**。一个中等能力的模型配上精心组织的上下文，往往胜过一个顶级模型在信息匮乏下的盲目摸索。

## 何时使用

- 设计或重构 Agent 的系统提示词、工具定义、消息列表结构
- 编写 / 审查一份 `SKILL.md`（元数据、路由描述、正文分层）
- 排查「Agent 行为不稳定、违反业务规则、重复犯错、忘记约束」
- 决定哪些知识该进系统提示词、哪些该做成按需加载的 Skill
- 评估外部内容（网页、文档、邮件）进入上下文后的安全风险

## 核心原则

- **API 无状态，上下文由框架每轮重建。** 模型不会「记住」上一轮，Agent 框架必须每次都把完整消息历史送回去。
- **上下文 = 四种消息角色 + `tools` 字段。** `system`（开发者规则，通常只有一条且在最前）、`user`（终端用户输入）、`assistant`（模型回复含 `tool_calls`）、`tool`（框架执行结果，靠 `tool_call_id` 与调用关联）；工具定义走请求顶层 `tools` 字段，不是消息角色。
- **静态前缀 + 动态轨迹。** system prompt 与 tool definitions 全程不变，对话历史（trajectory）随交互持续增长。所有后续技术都在优化这个列表的内容与结构。
- **模型决策、框架执行。** 模型只发出工具调用请求，真正执行工具的是 Agent 框架；循环「请求 → tool_calls → 执行 → 送回结果 → 再请求」就是 ReAct 循环的 API 实现。
- **最低信息需求三件套**：代码信息（结构、职责、规范）、流程规范（分支、提交、评审、CI/CD）、环境信息（配置、数据库、密钥管理）。缺哪一类，Agent 就在哪一类上出错。
- **新员工检验法**：如果一个聪明的新员工读完你的系统提示词还不知道该怎么做，Agent 也一样不知道。
- **上下文学习是检索而非推理**：模型擅长从已有内容中查找，不擅长在前向传播中归纳统计。位置偏好（Lost in the Middle）意味着开头和结尾注意力最高，中部易被忽视, , 关键信息放两端。
- **与模型厂商的训练方法保持一致**：选择 Agent 交互模式时优先采用厂商专门训练过的模式（Skills、tool_search 等），同生态内表现最佳。

## 实践模式

### 1. 系统提示词四维度

- **语气与风格**：用明确指令而非请求，如 `You MUST answer concisely with fewer than 4 lines`；无法完成任务时 `keep your response to 1-2 sentences` 且不要解释为什么不能做。大写（`NEVER do X`）比 `Please avoid doing X` 更能引起注意，但过度使用会稀释效果，只留给真正关键的约束。
- **结构化**：Markdown 标题（`#`、`##`）提供人可读的层次，XML 标签提供机器可解析的精确语义（`<file_operation>`、`<network_request>`），标签名本身携带语义。双层配合：Markdown 管组织逻辑，XML 管语义边界。
- **流程驱动而非规则堆砌**：写成带分支的 SOP（Step 1 Validation → Step 2 Classification → ... → Step 5 Verification），让模型任何时刻都知道自己在哪个阶段、异常时按阶段处理，而不是遍历上百条零散规则找匹配项。
- **业务规则细化到可执行**：把模糊规则（「根据任务情况选择合适的计费类型」）改写成布尔判断，例如 `NEVER use percentage_based_one_time for refunds and service cancellations. Use fixed_fee instead.`；成功率阈值直接映射到行为（>60% 可退款、<30% 拒绝任务）；计费粒度写死（每分钟 $0.05，汇总四舍五入到整数美元），并明确「节省」只基于现有账单计算。**提示词由产品经理基于线上数据设计，工程师负责准确编码，不擅自决定业务逻辑。**

### 2. few-shot 示例的两个决策点

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/context-engineering/SKILL.md