停止把整个仓库粘贴给 AI Agent

本能反应

这种本能是可以理解的。代理即将修改一个共享工具函数，于是你附加了 utils.ts，接着是它的测试文件，然后是你知道的三个调用方，再然后是 README，最后是生成的类型定义。五分钟后，你已经把 12 个文件粘贴到了提示词中，但代理仍然搞错了，因为那个定义了边缘情况的关键文件——上个季度的迁移脚本——并不在上下文中。

更大的上下文窗口加剧了这种本能反应。既然附加所有内容似乎“免费”，团队便照此行事。结果是一个代理阅读了 4,000 行代码，却只对其中 40 行采取行动，因为相关的信号被噪音稀释了。

上下文窗口内实际发生了什么

模型并不会平等地对待每个文件。它更关注开头和结尾的文件，以及你在问题中明确提及的内容。在一个包含 12 个文件的粘贴内容中，中间部分 effectively 成了背景噪音。你正在为未使用的 token 付费。

还有第二层成本：一旦代理读取了 12 个文件，它就会假设答案存在于其中之一。它会停止提出澄清问题，停止检查实际的架构，并开始基于它收到的最接近正确的文件进行推理。

失败模式不是“上下文不足”，而是“过多未加区分的上下文”。

30 分钟的修复方案

与其被动地粘贴文件，不如维护一个简短的、按文件级别的清单，将任务类型映射到代理应优先读取的文件上。它不需要完美无缺。

# AGENT_CONTEXT.md
task: "change shared API response shape"
files:
  - src/http/contracts/order.ts      # the actual shape
  - src/http/contracts/order.test.ts # what consumers rely on
  - docs/api/order.md                # external examples
read_first: src/http/contracts/order.ts
don_not_inject: src/**/*.generated.ts

重点不在于清单是否完整。重点在于代理从三个关键文件开始工作，并且知道它可以请求更多文件，而不是从你倾倒的 12 个文件中猜测。

对于 API 工作而言，最具杠杆效用的工件并非任何代码文件，而是契约。如果代理首先阅读 OpenAPI 规范，它就不需要你粘贴三个调用点，因为类型和示例负载已经告诉它系统期望的形状。我们围绕这一点构建了 Powerduck：规范保存在本地，代理指向规范文件，生成的类型和示例由此衍生。不再需要猜测要附加哪些调用方。

经受住生产环境考验的两条规则

1. 限制初始上下文，不要最大化它。从 3-5 个文件开始。让代理请求更多内容。一次额外往返的成本是几分钟；而在 4,000 行上下文中因错误编辑导致的构建失败成本则是巨大的。

1. 区分“读取这个”和“这是真理来源”。你粘贴的大多数文件只是参考资料。其中一个文件——契约、架构、迁移脚本或编码不变量的测试——才是代理应视为权威来源的文件。明确标记它。否则，代理会将 README 中的非正式示例置于实际架构之上。

本周该做什么

• 打开你最近的五个代理会话。计算第一轮附加的文件数量。如果超过五个，你就在支付稀释税。
• 选择一个高频任务（如“更改 API 形状”、“添加 CLI 标志”、“修复 X 中的不稳定测试”）并为它编写一个 20 行的清单。每周迭代一次。
• 停止自动附加 README。这几乎总是代理最不需要文件，也几乎总是你最先附加的文件。

目标不是建立一个完美的 RAG 系统。目标是让代理阅读正确的三个文件，而不是在错误的十二个文件中猜测。