上下文工程
"更大的上下文窗口 ≠ 更好的结果。智能策展 > 原始容量。"
上下文工程是管理 AI 工作记忆以最大化有效性的实践。LeanSpec 将上下文工程原则应用于规范管理，确保规范适合工作记忆并提供高信噪比。
核心问题
上下文是有限的
即使有 1M+ 令牌窗口：
- 注意力随长度降低（上下文腐烂）
- N² 复杂度在 transformer 注意力中
- 训练偏差倾向于较短序列
- 成本随令牌线性增长
关键见解：更大的窗口不能解决问题。智能策展可以。
LeanSpec 的关联
LeanSpec 存在的原因：
- 上下文经济 - 规范必须适合工作记忆（人类 + AI）
- 信噪比 - 每个词都必须告知决策
- 上下文失败发生在我们违反这些原则时
本页解释：如何以编程方式维护上下文经济
四种上下文工程策略
1. 分区（写入和选择）
什么：将内容拆分到多个上下文中，并选择性加载
LeanSpec 应用：
# 而不是一个 1,166 行的规范：
specs/045/README.md (203 行 - 概述)
specs/045/DESIGN.md (378 行 - 设计)
specs/045/IMPLEMENTATION.md (144 行 - 计划)
specs/045/TESTING.md (182 行 - 测试)
# AI 仅加载当前任务所需的内容
机制：
- 子规范文件（README + DESIGN + TESTING + CONFIG）
- 延迟加载（按需读取文件）
- 渐进式披露（概述 → 细节）
何时使用：
- ✅ 规范 >400 行
- ✅ 多个不同的关注点（设计 + 测试 + 配置）
- ✅ 不同的关注点独立访问
好处：
- ✅ 每个文件 <400 行（适合工作记忆）
- ✅ 减少不相关的上下文（仅加载所需部分）
- ✅ 并行工作（编辑 DESIGN 不影响 TESTING）
2. 压实（删除冗余）
什么：消除重复或可推断的内容
LeanSpec 应用：
# 压实前（冗长）：
## 认证
认证系统使用 JWT 令牌。JWT 令牌是
行业标准，提供无状态认证。
JWT 令牌的好处是它们不需要服务器端
会话存储...
## 实现
我们将实现 JWT 认证。选择 JWT 是因为...
[重复相同的理由]
# 压实后（简洁）：
## 认证
使用 JWT 令牌（无状态，无会话存储）。
## 实现
[链接到认证部分以获取理由]
机制：
- 重复检测（多个地方的相同内容）
- 推断删除（从上下文明显的内容）
- 参考合并（一个规范来源，其他链接）
何时使用：
- ✅ 跨部分重复的解释
- ✅ 明确陈述了明显/可推断的信息
- ✅ "为完整性"部分，决策价值很小
好处：
- ✅ 更少的令牌 = 更快的处理
- ✅ 更少的分心 = 更好的注意力
- ✅ 更容易维护 = 单一真实来源
3. 压缩（总结）
什么：在保留基本信息的同时进行浓缩
LeanSpec 应用：
# 压缩前：
## 阶段 1：基础设施设置
设置项目结构：
- 创建 src/ 目录
- 创建 tests/ 目录
- 使用 tsconfig.json 配置 TypeScript
- 使用 .eslintrc 设置 ESLint
- 使用 .prettierrc 配置 Prettier
- 为 build、test、lint 添加 npm 脚本
- 使用 GitHub Actions 设置 CI 管道
[50 行详细步骤...]
# 压缩后（完成的阶段）：
## ✅ 阶段 1：基础设施设置（2025-10-15 完成）
使用 TypeScript、测试和 CI 建立了项目结构。
查看 git 提交 abc123 了解实现细节。
机制：
- 历史总结（完成的工作 → 摘要）
- 阶段汇总（详细步骤 → 结果）
- 选择性细节（保留决策，总结执行）
何时使用：
- ✅ 完成的阶段（结果重要，细节不重要）
- ✅ 历史上下文（需要知道它发生了，而不是如何）
- ✅ 接近行数限制（保留信号，减少噪音）
好处：
- ✅ 维护项目历史而不膨胀
- ✅ 专注于活跃工作，而不是过去的细节
- ✅ 如果以后需要，容易扩展细节
4. 隔离（移至单独的上下文）
什么：将不相关的关注点拆分成单独的规范
LeanSpec 应用：
# 隔离前（一个规范）：
specs/045-unified-dashboard/README.md
- 仪表板实现
- 速度跟踪算法
- 健康评分系统
- 图表库评估
- 指标端点的 API 设计
[1,166 行涵盖 5 个不同的关注点]
# 隔离后（多个规范）：
specs/045-unified-dashboard/ # 仪表板 UI
specs/060-velocity-algorithm/ # 速度跟踪
specs/061-health-scoring/ # 健康指标
specs/062-metrics-api/ # API 端点
[每个规范 <400 行，独立生命周期]
机制：
- 关注点提取（识别不相关的主题）
- 依赖分析（什么必须保持在一起？）
- 规范创建（移至带交叉引用的新规范）
何时使用：
- ✅ 具有不同生命周期的多个关注点
- ✅ 章节可以是独立功能
- ✅ 不同人/团队更新的部分
- ✅ 分区后规范仍 >400 行
好处：
- ✅ 独立演变（算法改变 ≠ UI 改变）
- ✅ 清晰的所有权（不同的关注点，不同的所有者）
- ✅ 更容易审查（每个规范的重点范围）
四种上下文失败模式
基于 Drew Breunig 的研究：
1. 上下文中毒
定义：幻觉或错误内容进入上下文并被反复引用
LeanSpec 中的症状：
# AI 在编辑期间产生幻觉：
"认证模块使用 Redis 进行会话存储"
（现实：我们使用 JWT 令牌，而不是 Redis 会话）
# 幻觉被保存到规范
# 后来，AI 读取规范并基于幻觉构建：
"Redis 配置应该使用集群模式以实现高可用性"
（基于原始错误构建）
# 上下文现在中毒了 - 错误信息复合
缓解：
- ✅ 程序验证（保存前捕获）
- ✅ 定期规范-代码同步检查
- ✅ 立即删除损坏的部分
2. 上下文分心
定义：上下文增长如此之大，以至于模型忽略训练并重复历史
LeanSpec 中的症状：
# 规范增长到 800+ 行，包含大量历史记录
# AI 行为改变：
- 重复规范历史中的过去行动
- 忽略训练知识
- 建议规范中记录的过时方法
- 无法综合新解决方案
缓解：
- ✅ 在 400 行处拆分（上下文经济）
- ✅ 压缩历史部分
- ✅ 按关注点分区
研究：Databricks 发现 Llama 3.1 405b 的降级从约 32k 令牌开始，较小模型更早
3. 上下文混淆
定义：多余的内容影响模型做出错误决策
LeanSpec 中的症状：
# 规范包含 20 个集成的 MCP 工具定义
# (GitHub, Jira, Slack, Linear, Notion, Asana, ...)
# 任务："更新 GitHub 问题状态"
# AI 行为：
- 对使用哪个工具感到困惑
- 有时调用错误的工具（Jira 而不是 GitHub）
- 处理速度较慢（评估不相关的选项）
- 准确度降低
缓解：
- ✅ 在 AI 处理前删除不相关的部分
- ✅ 使用选择性加载（仅相关的子规范）
- ✅ 清晰的关注点分离
研究：Berkeley 函数调用排行榜确认所有模型在 >1 个工具时表现更差
4. 上下文冲突
定义：同一上下文中的信息冲突
LeanSpec 中的症状：
# 规范早期：
"我们将使用 PostgreSQL 进行数据存储"
# 规范中间（讨论后）：
"实际上，MongoDB 对此用例更好"
# 规范后期（忘记更新）：
"PostgreSQL 模式设计：..."
# AI 看到冲突信息 - 可能混合方法
缓解：
- ✅ 每个决策的单一真实来源
- ✅ 清楚标记被取代的决策
- ✅ 使用压实删除过时信息
研究：Microsoft/Salesforce 论文显示，当信息在多个回合中收集时，性能下降 39%
策略选择框架
| 情况 | 主要策略 | 次要 | 为什么 |
|---|---|---|---|
| 规范 >400 行，多个关注点 | 分区 | 压实 | 分离关注点，删除冗余 |
| 规范冗长但单一关注点 | 压实 | 压缩 | 删除冗余，如果仍然长就总结 |
| 历史阶段使规范膨胀 | 压缩 | - | 保留结果，删除细节 |
| 同一规范中的不相关关注点 | 隔离 | 分区 | 移至单独规范，然后分区 |
| 规范接近 400 行 | 压实 | - | 在达到限制前主动清理 |
组合策略
通常多个策略一起应用：
示例：大规范（1,166 行）：
- 分区：拆分为 README + DESIGN + IMPLEMENTATION + TESTING
- 压实：删除每个文件中的冗余
- 压缩：总结完成的研究阶段
- 隔离：考虑将算法移至单独的规范
结果：
- 之前：1,166 行（3 倍限制）
- 之后：最大文件 378 行（在限制内）
底线
在使用 AI 构建时，上下文工程是第一要务。这些不仅仅是优化技术——它们是使 AI 辅助规范管理工作的基础。
关键见解：LeanSpec 是用于人机协作软件规范的上下文工程方法论。
记住：
- 更大的上下文窗口不能解决问题
- 智能策展（分区、压实、压缩、隔离）可以
- 主动应用策略以防止上下文失败
- 监控警告标志（>400 行、重复、混淆、冲突）