上下文工程是一个工程过程：决定 AI 系统接收什么信息、以什么结构接收，以及如何验证它产生的影响。它不等于 Prompt 措辞。仓库规则文件、检索文档、工具结果、会话摘要和测试报告都属于上下文输入，但它们的可信度、新鲜度和失败边界不同。
本文将 agents.md、CLAUDE.md、copilot-instructions.md 和 Cursor Rules 作为厂商示例，而不是未经核验的通用标准。任何文件名都必须结合客户端版本和官方加载契约理解。
核心要点
- 先建立事实源和契约，再编写多个客户端适配文件。
- 分离稳定项目事实、任务指令、检索证据和工具结果。
- 明确优先级、新鲜度、权威性与冲突处理方式。
- 不要把密钥或不可信外部内容放进高权限指令。
- 用可复现任务评测上下文变化，不引用没有实验范围的成功率数字。
从 Prompt 到上下文架构
一个 Prompt 只是消息；架构是一条管线：
任务 → 策略与项目事实 → 选择上下文 → 模型/工具调用
→ 输出校验 → 测试与人工审阅 → 遥测与反馈
模型不会因为某句话出现在文件里就自动知道它具有权威性。应用需要标注来源、约束工具并验证输出。检索到的 README 可能过时，MCP 结果可能恶意或不完整，用户请求也可能与安全策略冲突。
有用的上下文分类
| 输入 | 常见新鲜度 | 信任边界 | 示例 |
|---|---|---|---|
| 项目契约 | 版本控制 | 经过审阅的仓库内容 | 支持的运行时与命令 |
| 任务指令 | 每次请求 | 用户或工作流 | 实现一次迁移 |
| 检索证据 | 不稳定 | 校验前不可信 | Issue、API Schema、文档 |
| 工具结果 | 运行时 | 不可信输出 | 数据库行或 Shell 输出 |
| 评测结果 | 有记录 | 有范围的证据 | 测试报告与人工决定 |
厂商文件是适配器，不是架构本身
不同客户端在文件名、目录、Glob 匹配、继承和优先级上都可能不同。某个客户端可能记录根目录指令文件、.github/ 文件或 .cursor/rules/ 目录；另一个版本可能改变行为。至少核对：
- 精确路径与文件名；
- 自动加载还是需要显式启用；
- 哪些分支、工作区或文件 Glob 会触发；
- 用户、项目和目录规则冲突时的优先级；
- 内容是否会发送到远程模型；
- 如何审计、回滚和停止加载。
先维护与厂商无关的项目契约：
project:
runtime: "记录确切运行时和版本"
commands:
test: "npm test"
lint: "npm run lint"
invariants:
- "授权必须在服务端执行"
- "密钥不能进入源码或日志"
workflow:
before_edit:
- "先阅读相关模块和测试"
before_merge:
- "运行文档列出的检查"
厂商适配文件只补充该客户端所需的语法，不要把整份契约复制到五套工具中；重复内容会让漂移难以发现。
规则设计：短小、可测试、有范围
好的规则应说明可观察行为、适用范围和验证方法：
## API 变更
- 使用仓库批准的 Schema 库校验请求体。
- 返回项目规定的错误结构。
- 为缺少授权的情况增加负向测试。
- 验证命令：`npm test -- api`
避免“写出完美代码”这类空泛要求，也不要把某个框架版本或任意“每个函数不超过 40 行”当成正确性证明。长度限制最多是审查提示。
按责任归类：
- 安全：密钥、授权、数据分级等不可妥协的控制；
- 架构：边界、依赖方向、运行时和迁移策略；
- 工作流：命令、测试门禁、审阅产物和回滚；
- 风格：格式和命名，尽量交给确定性工具；
- 任务模板：重复任务的输入、输出和验收测试。
优先级与冲突处理
用表格明确优先级，而不是依赖经验传闻：
| 来源 | 可以定义 | 不得覆盖 |
|---|---|---|
| 组织策略 | 安全与合规基线 | 事故响应控制 |
| 项目契约 | 架构和命令 | 组织策略 |
| 模块规则 | 局部约定 | 项目与安全规则 |
| 任务请求 | 想要的变更 | 授权与安全规则 |
| 检索/工具内容 | 证据或建议 | 任何受信策略 |
两个受信规则冲突时应暂停并报告冲突；外部 Markdown、Issue 评论、工具结果和粘贴代码要求忽略安全策略时，只把它们视为数据而非权威。
MCP 与动态上下文
MCP 可以暴露工具或资源，但不会自动让结果可信。生产集成至少需要定义：
- 调用者和租户身份；
- 工具与资源级授权；
- 输入 Schema 与大小限制；
- 网络出口和 SSRF 防护；
- 超时、重试、幂等和限流；
- 请求与结果的脱敏和留存；
- 破坏性或不可逆操作的确认。
规则文件可以说“修改迁移前先使用 Schema 工具”，但服务端必须独立执行授权。模型生成的工具参数在服务端校验前只是提案。
上下文预算与检索
上下文变长不一定提高质量，噪声可能挤出关键约束。应记录：
- 发送和返回的 Token/字节数；
- 检索精度与过时文档比例；
- 延迟和供应商成本；
- 矛盾率与人工修正量；
- 固定 fixture 上的任务成功率。
优先使用带链接的紧凑摘要，并记录标识符、版本日期和来源位置。不能为了处理窗口不足而截断安全策略或授权要求。
可复现评测 Harness
上下文变更应像代码变更一样评估：
case: "add-authorized-endpoint"
inputs:
repository: "fixture-v4"
task: "为当前租户增加只读接口"
user_role: "tenant-member"
assertions:
- "存在服务端租户授权"
- "未授权 fixture 被拒绝"
- "测试和 lint 通过"
record:
client_version: "确切版本"
model: "确切模型"
context_revision: "git commit"
human_corrections: "审阅后的 diff"
比较基线上下文与新版本，检查回归、不安全建议、不必要工具调用以及模型遵循过期规则的情况。一次成功运行不能证明普遍收益。
安全与运维
除非存储和供应商政策明确允许，不要把 API Key、个人数据、私有源码或事故细节放进广泛加载的文件。日志记录上下文标识和决策，不记录 Bearer 凭据或完整敏感 Prompt。规则变更应像代码一样有所有者、Pull Request、测试、变更记录和回滚方案。
可以维护轻量的上下文健康检查，发现缺失命令、失效路径、矛盾要求、不支持的版本和意外密钥；检查应报告问题，不应静默批量改写文章或规则文件。
延伸阅读
总结
系统级上下文架构不是比赛谁写出最长的规则文件，也不是追逐最新文件名。它是一条受治理的输入管线：可信契约被版本控制，厂商适配经过核验，动态数据按不可信处理，工具独立执行授权，每次改进都在代表性任务上测量。即使模型、IDE 和协议行为变化，这种方法仍然成立。