AI 执行任务时，很多失败不是因为它不会改代码，而是因为它看错了上下文。

它可能读到过时文档，把规划当事实，把辅助开发笔记当产品规则，把某次失败样例当通用规则，或者在全仓库里找到一个名字相似但已经废弃的实现。

所以项目专用 AI 交付流水线不应该只说“让 AI 读仓库”。更稳的做法是为任务准备 context package。

上下文不是越多越好

很多人直觉上希望 AI 看得越多越好。对真实项目来说，这经常适得其反。

上下文太大，AI 会被无关信息干扰。文档太乱，AI 会把临时方案当最终事实。历史讨论太多，AI 会把已经被推翻的决定重新拿出来。

项目需要的是窄上下文，不是全量上下文。

窄上下文的意思是：这次任务需要哪些事实，就把哪些事实打包给 AI；哪些信息会误导它，就不要默认暴露。

source of truth 必须明确

context package 最重要的字段是 source of truth。

在代码项目里，最终真实形态通常以代码和测试为准，而不是旧文档。在产品项目里，公开能力要以 README、用户文档、release artifact 和真实可跑 demo 为准。在知识库发布中，公开内容要回到 source trace，而不是直接相信总结页。

没有 source of truth，AI 会把它能读到的材料平均对待。

这很危险。因为真实项目里的材料天然有层级：

  • 代码和测试可能比旧文档可信；
  • 当前产品文档可能比早期 roadmap 可信；
  • 项目本地事实可能比中央方法论可信；
  • 原始证据可能比 AI 总结可信；
  • public claim 必须比内部想法更保守。

context package 应该把这些优先级说清楚。

一个 context package 应该包含什么

一个可用的上下文包可以很简单：

  • 本任务相关的项目规则；
  • 应该读取的源真相文件；
  • 相关 specs、ADRs、issue、PR 或 runbook；
  • 相关测试、fixture、截图或 trace；
  • 当前已知失败；
  • 验证命令；
  • 允许修改的文件范围；
  • 禁止触碰的文件范围；
  • 如果上下文矛盾，应该信谁。

这比让 AI 自己搜索全仓库更可控。

项目专用价值就在这里

通用 agent 工具可以提供强模型、shell、文件编辑、MCP、subagent、hooks。它们不能天然知道你这个项目的真相层级。

例如，TidalFi 的 AI worker 必须知道哪些链路涉及资金、交易、KYC 或生产发布。SketchUp Agent Harness 的 worker 必须知道 design_model、source evidence 和 SketchUp scene 的关系。中央知识库的 publication worker 必须知道 knowledge 负责双语候选，site 负责渲染和部署。

这些不是通用工具的知识。这些是项目上下文。

context package 也能防止过度泛化

AI 很容易从一个样例里总结出看似通用的规则。

在设计工具里，一张户型图的识别修复不应该直接变成产品通用规则。在交易系统里，一个 issue 的特殊修复不应该变成全局业务语义。在知识库里，一个项目的目录习惯不应该套到所有项目。

context package 可以明确本次材料的作用：

  • 这是事实；
  • 这是证据；
  • 这是猜测；
  • 这是项目局部规则；
  • 这是可晋升的通用方法；
  • 这是不能泛化的 source-specific interpretation。

这会显著降低 AI 把局部经验污染成全局规则的概率。

结论

给 AI 上下文，不是把仓库全部丢给它。

真正有用的是任务级上下文包：小、准、有优先级、有真相源、有边界。

项目专用 AI 交付流水线的价值，很大一部分就来自这里。它不是让模型更聪明，而是让模型在正确事实层上工作。