同一个模型，为什么别人用Cursor一小时干完你要一整天？

两个人用同一款编码工具、同一个模型，做同一个需求。一个两小时交付，一个折腾一天还改出三个 bug。

差的不是 prompt 技巧，是上下文管理。

一、先理解 Agent 到底在做什么

编码 Agent 的本质是一个循环：读文件 → 想 → 改文件 → 跑验证 → 看结果 → 再改。

它每一步都只能看到”当前上下文窗口里的内容”。窗口里没有的东西，等于不存在。

所以问题的本质是：如何让正确的信息，在对的时刻，出现在窗口里。

二、第一步：写一份项目地图

在仓库根目录放一个 AGENTS.md，不要写产品介绍，只写 Agent 需要的东西：

## 技术栈
- Next.js 15 App Router，TypeScript strict
- 数据层：Drizzle ORM + PostgreSQL，schema 在 src/db/schema.ts
- 组件库：自研 ui/，不要引入新的 UI 依赖

## 命令
- 装依赖：pnpm install
- 类型检查：pnpm typecheck（改完必须跑）
- 测试：pnpm test -- <文件路径>
- 本地起服务：pnpm dev（端口 3000）

## 约定
- 所有 API 走 src/app/api/，返回 { data, error } 结构
- 不写 any，不写 @ts-ignore
- 新增页面必须同时加 e2e 测试
- 不要修改 migrations/ 目录，改 schema 后告诉我手写迁移

## 已知坑
- layout.tsx 里的 theme provider 不要在 client component 里再包一层
- 排序问题在 Safari 上有兼容 bug，用 sortBy util 而不是原生 sort

这份文件价值巨大：它把”新人入职要问同事的问题”一次写清楚。Agent 每次会话都会读它。

三、第二步：任务切片

最坏的情况是丢一句”帮我实现用户中心”。Agent 会开始猜，猜错一路错。

好的任务描述长这样：

目标：用户中心页 /account 展示头像、昵称、邮箱、修改密码入口。

范围：
- 只改 src/app/account/ 下的文件
- 复用 src/components/ui/Card.tsx
- 数据从 GET /api/user/me 取（已存在，别改后端）

不做什么：
- 不做头像上传
- 不做邮箱验证流程
- 不改导航栏

验收：
- pnpm typecheck 通过
- 新增 account.spec.ts，覆盖登录态和未登录态

四个区块：目标 / 范围 / 不做什么 / 验收标准。最后两块最容易被忽略，也最关键。

四、第三步：建立验证回路

这是区分高手和新手的分水岭。

Agent 写完代码，你必须让它自己验证。方法：

1. 类型检查自动跑：在 AGENTS.md 里写死”每次改完跑 pnpm typecheck”，或者配 pre-commit hook 让它自己看到错误。
2. 测试先行：先让 Agent 写失败的测试，再让它实现。它会自动迭代到测试通过。
3. 截图验证：改 UI 时用浏览器工具截图，让 Agent 自己看效果，比”你确认一下效果”强十倍。

没有验证回路，Agent 就是在盲写。盲写的准确率大概 60%，有验证回路能到 90% 以上。

五、第四步：控制上下文腐化

长会话里，Agent 会记得前面试过的错误方案，然后被带偏。

信号：它开始重复犯同一个错，或者开始”我建议重构整个模块”。

处理：开新会话，带上当前状态和最新目标。不要试图在一个 300 条消息的会话里翻盘。

一条实用规则：一个会话只做一件事，超过 20 轮就考虑重启。

六、给 Agent 的”输入卫生”做体检

上下文工程做到后面，你会发现真正决定成败的是信息的新鲜度和精度，而不是数量。

三个可以每天自检的问题：

问题一：窗口里有多少内容是过期的？ 改过的设计文档、已经删掉的文件、上周的接口约定——这些如果还在会话里，Agent 会照着旧版本干活。每切换一次方向，就应该明确告诉它”以下内容作废”。

问题二：报错信息是完整的吗？ 只贴 TypeError: cannot read property of undefined 等于什么都没说。完整堆栈 + 出错文件 + 最近一次改动，这三样凑齐，Agent 定位问题的时间能缩短一半以上。养成习惯：报错就贴全量输出，别自己先”提炼”，人的提炼往往会丢掉关键行。

问题三：它读到的代码风格是谁的？ 如果仓库里同时存在两套写法（老代码用 class 组件、新代码用 hooks），Agent 会随机挑一套。要么让它显式参考某个具体文件作为风格模板，要么先把不一致的地方统一掉。风格混乱是 Agent 写出”看起来对但融合不进去”代码的主因。

还有一个容易被忽略的点：给 Agent 明确的放弃条件。当它发现某种实现不可行时，应该停下来汇报，而不是硬着头皮绕路。在 AGENTS.md 里加一句”如果方案需要改动 schema 或引入新依赖，先停下来问我”，能挡掉大量失控重构。

七、常见错误清单

• ❌ 一次性丢 10 个文件让它”全部看完”
• ❌ 用自然语言描述文件结构而不是让它自己读
• ❌ 让它改完所有东西再统一验证（错误会滚雪球）
• ❌ 报错只贴一行，不贴完整堆栈
• ❌ 不让它读现有代码风格就让它写新代码
• ✅ 一次一个文件、一次一个目标、一次一次验证

写在最后

编码 Agent 不是”更聪明的自动补全”，它是一个需要入职引导的新同事。

你给新同事的 onboarding 越认真，他上手越快。对 Agent 也一样。花两小时写 AGENTS.md，之后每个任务省下的是几十分钟的来回拉扯。