AI 编程接手项目：上下文工程实战指南
问题本质：上下文缺失
AI 编程工具接手我的项目时，上下文缺失导致的返工比代码质量更致命。工具能写出语法正确的代码，却不了解项目的隐性约束——目录边界、样式约定、验证流程。这些约束藏在代码结构和团队默契里，AI 接手的第一步是把它们变成显性上下文。
截至 2026 年 6 月，AGENTS.md 已被超过 60000 个开源项目采用（agents.md），成为 Claude Code、Codex、Cursor、Copilot 等 30 多种工具共同支持的跨工具标准。Martin Fowler 在 2026 年 2 月的文章中把这件事定义为「上下文工程」（Context Engineering）——给 AI 编程工具提供正确的项目上下文，让它不必每次都靠猜测理解你的仓库。
上下文工程不等于写一个 AGENTS.md 就完事。ETH Zurich 2026 年 3 月的研究发现，写得差的上下文文件反而让成功率下降了约 3%（Medium 分析）。上下文需要精准、结构化、可执行。
本文拆三件事：上下文为什么重要、怎么写一份有效的上下文文件、接手项目时该按什么顺序检查。
上下文工程：四层模型
Sourcegraph 在 2026 年初提出一个四层上下文模型（Sourcegraph Blog），对理解 AI 编程接手项目的问题很有用：
| 层级 | 内容 | 生命周期 | 例子 |
|---|---|---|---|
| 静态上下文 | 项目约束、目录边界、代码风格、验证命令 | 跨会话持久 | AGENTS.md、CLAUDE.md、.cursor/rules |
| 动态上下文 | 当前打开的文件、最近的编辑、对话历史 | 单次会话 | IDE 当前 tab、git diff |
| 检索上下文 | 从代码库搜索到的相关实现、文档、issue | 按需拉取 | grep 结果、API 文档、设计稿链接 |
| 持久上下文 | 跨会话记忆、学到的偏好、历史决策 | 跨会话增量 | 上次的修改记录、review 反馈 |
AI 接手项目时翻车，绝大多数出在静态上下文缺失。项目有约定但没写下来，AI 只能按通用模式猜测。一个 Next.js 项目可能用 App Router 也可能用 Pages Router，可能用 pnpm 也可能用 npm，测试可能在 src/__tests__/ 也可能在顶层 tests/——这些差异，静态上下文文件是唯一可靠的传递方式。
Anthropic 在 2025 年 9 月的工程博客里强调：系统提示应该「清晰、直接、在正确的抽象层级上」（Anthropic Engineering）。套到项目上下文里：给 AI 当前任务需要的约束和边界，别扔一整本架构文档。
arXiv 2026 年 3 月的论文《Building AI Coding Agents for the Terminal》进一步提出，终端 AI 编程工具的架构可以分为四层：agent reasoning、context engineering、tooling、persistence（arXiv）。其中 context engineering 层负责的就是把项目知识从「人脑中的默契」转成「AI 可以消费的指令」。
典型翻车场景与修复路径
案例一：Monorepo 目录归属错位
问题：AI 按通用习惯放代码——组件写在页面文件里、测试扔进 src/——全因不知道我的目录约定。
修复：我在根目录写了 AGENTS.md，记录关键约束：
# AGENTS.md
## 项目事实
- Monorepo，pnpm + Turborepo；Node.js 22+
- `apps/` 是 Next.js App Router 主应用
- `packages/ui/` 是共享 UI 组件
## 代码边界
- 页面文件只做路由装配；复杂 UI 放 `_components/` 或 `features/`
- 环境变量通过 `apps/src/config/env/` 读取，不直接 `process.env`
## 验证命令
- 提交前运行 `pnpm verify`（typecheck + lint + test + build）效果：同样的需求，AI 先读 AGENTS.md，然后从 apps/src/api/ 读数据、组件放 apps/src/components/、测试写在 apps/tests/，完成后跑 pnpm verify。一次通过。
AI 的通用知识和项目特定约束之间存在一条必须显式跨越的鸿沟，AGENTS.md 就是跨越它的方式。
案例二：缺少验证命令导致的静默失败
问题：AI 改完字段名后只跑了 typecheck，通过了。但项目有个自定义的 pnpm validate:content 脚本——检查所有文章的 slug、日期格式和标签白名单。AI 不知道这个脚本，改坏了 slug 格式，部署后才发现。
修复：在 AGENTS.md 按改动类型列出验证命令：
## 验证命令（按改动类型）
- 内容改动：`pnpm validate:content` + `pnpm check:slug` + `pnpm typecheck`
- UI 改动：`pnpm typecheck` + `pnpm build` + 浏览器验收
- API 改动：`pnpm typecheck` + `pnpm test` + `pnpm test:integration`关键在于不同改动类型对应不同验证命令。validate:content 的存在只写在团队流程默契里，AI 无法从代码结构推断出来。
案例三：上下文过载
问题：我把 12000 字架构文档全塞进 AGENTS.md，包含数据库 ER 图、部署拓扑、三年路线图。AI 处理一个简单前端修改时，被无关信息淹没，开始根据后端微服务拆分方式来决定前端组件位置。
ETH Zurich 的研究量化了这个问题：写得差的上下文文件让成功率下降 3%。上下文窗口是有限的认知资源，无关信息会稀释有效指令的权重。
修复：我把 AGENTS.md 拆成三层——根文件只放核心约束（约 50 行），详细架构文档放 docs/ 让 AI 按需检索，流程指南放 .agents/skills/ 按任务匹配加载。Martin Fowler 的建议是上下文要「不多不少」，让信息在正确的层级上可被发现。
项目接手流程图
AI 接手一个项目任务时，建议按以下顺序执行：
这个流程的核心是「先读后做」——在写第一行代码之前，AI 应该能回答三个问题：项目有什么约束、现有代码怎么做的、我准备改什么和不改什么。
好上下文 vs 坏上下文
| 维度 | 坏上下文 | 好上下文 | 为什么 |
|---|---|---|---|
| 项目描述 | 「这是一个现代化的全栈 Web 应用」 | 「Next.js 16 App Router，pnpm monorepo，Node.js 22+」 | 具体技术栈让 AI 不用猜 |
| 目录约定 | 「组件放在 components 目录」 | 「可复用 UI 放 packages/ui/；页面级展示组件放 apps/src/components/；feature 内聚组件放 features/xxx/_components/」 | 三级目录各有归属，AI 能正确放置新组件 |
| 验证命令 | 「记得跑测试」 | 「提交前运行 pnpm verify（含 typecheck + lint + test + build）」 | 具体命令可执行，不是模糊要求 |
| 代码风格 | 「遵循项目代码风格」 | 「Biome：单引号、无尾分号、trailing comma all；TypeScript strict mode」 | 工具 + 配置名 = 可查可执行 |
| 边界约束 | 「不要改不该改的文件」 | 「页面文件只做路由装配，复杂逻辑放 _components/；环境变量走 config/env/，禁止直接 process.env」 | 正反两面都写了，AI 有明确的 do 和 don't |
| 上下文量 | 12000 字架构文档全塞进去 | 根文件 50 行核心约束 + 子目录按需加载 | 精准 > 全面；噪声会稀释有效指令 |
上下文清单模板
以下是一份可以直接复用的项目接手上下文清单。分三层：根文件放全局约束，子目录放模块指南，任务级放单次任务边界。
根目录 AGENTS.md 模板
# AGENTS.md
## 项目事实
- 技术栈：[框架] + [包管理] + [运行时版本]
- 仓库结构：[monorepo / 单应用 / ...]
- 主要目录：[一句话描述每个顶层目录的职责]
## 代码边界
- [归属 A] → 放 [目录 X]
- [归属 B] → 放 [目录 Y]
- [容易出错的归属]：错误做法 → 正确做法（用表格）
## 验证命令
- 内容改动：[具体命令]
- UI 改动：[具体命令]
- API 改动：[具体命令]
- 通用：[提交前必须跑的完整命令]
## 非目标（本项目不做什么）
- [不用的框架/库/模式]
- [不支持的浏览器/环境]
- [明确的技术选型排除项]任务级上下文传递模板
交给 AI 新任务时，除了 AGENTS.md，还需要任务级上下文：
## 本次任务
- 目标：[用户完成什么动作后能看到什么结果]
- 非目标：[本次不处理哪些相邻问题]
- 预计触达：[目录、模块、接口]
- 约束：[兼容性、性能、安全注意事项]
- 验收标准：[必须通过的验证 + 人工检查点]
## 相关上下文
- 相关 issue / PR 链接
- 相关设计稿链接
- 已有实现参考：[类似功能的文件路径]常见踩坑点
| 踩坑点 | 发生场景 | 后果 | 避免方式 |
|---|---|---|---|
| 上下文文件过大 | 把架构文档、API spec、数据库 schema 全塞进一个文件 | AI 被无关信息干扰，引用不相关内容指导当前任务 | 根文件 ≤ 100 行；详细内容放 docs/，按需检索 |
| 缺验证命令 | AGENTS.md 只写了代码约定，没写怎么验证 | AI 改完只跑 typecheck，漏掉 lint、build、集成测试 | 按改动类型列出具体命令，不要只写「记得测试」 |
| 不写非目标 | 只写要做什么，不写不做什么 | AI 范围漂移，顺手改了不该改的模块 | 每次任务显式列出「本期不做」的相邻问题 |
| 测试目录不明 | 没说明测试文件放哪里 | AI 把测试写在 src/ 里，和项目结构不一致 | 明确测试目录 + 镜像规则（源码路径 → 测试路径） |
| 上下文文件互相矛盾 | AGENTS.md 说用 npm，CLAUDE.md 说用 pnpm | AI 不确定该听哪个，可能随机选一个 | 定义优先级：用户指令 > 项目文件 > 工具默认 |
| 只有正面约束没有反面 | 写了「组件放 components」，没写「页面文件不做复杂 UI」 | AI 仍然可能把逻辑写在页面文件里 | 容易出错的地方同时写 do 和 don't |
| 没检查工作区状态 | AI 直接开始改代码，覆盖了他人未提交的改动 | 冲突、丢失工作 | 流程第一步加 git status + git log --oneline -10 |
三个验证问题
写完上下文文件后，我用三个问题自检：
问题一：AI 能根据这份上下文找到正确的文件位置吗？ 给它一个新组件需求，看它放在哪个目录。如果它放对了，说明目录边界写清楚了；如果放错了，说明你的上下文里缺少这条归属规则。
问题二：AI 能选对验证命令吗？ 给它一个内容改动任务，看它跑什么命令验证。如果只跑了 typecheck 没跑 content validate，说明验证命令部分缺少按改动类型的区分。
问题三：AI 能说出「不改什么」吗？ 让它描述任务边界。如果它只能说「我准备改什么」但说不出「我不改什么」，说明非目标没有传递到位。一个理解任务边界的 AI，应该能同时列出目标和非目标。
上下文工程的原则
我归纳出五条可操作的原则：
1. 精准优于全面。上下文窗口的容量是有限的认知资源。给 AI 当前任务需要的约束，不是整个项目的百科全书。根文件控制在 50-100 行，详细内容通过目录结构按需发现。
2. 命令优于描述。「记得跑测试」不如 pnpm verify。「遵循代码风格」不如 `Biome：单引号、无尾分号」。可执行的命令比自然语言描述更不容易被误解。
3. 正反双向约束。容易出错的地方，同时写 do 和 don't。「环境变量走 config/env/」不够，加上「禁止直接 process.env」才能有效防止 AI 凭通用经验犯错。
4. 分层而非堆叠。静态约束放根文件，模块指南放子目录，任务边界在对话中传递。每一层只解决一个抽象层级的问题。PixelMojo 的分析把这种结构称为「五层上下文层级」，AGENTS.md 只是第一层（PixelMojo）。
5. 验证闭环。上下文文件不只是告诉 AI「怎么做」，还要告诉它「怎么证明做对了」。没有验证命令的上下文文件只完成了一半的工作。
结论
上下文工程要做的，是把我们团队的隐性知识——目录约定、验证流程、归属规则、技术选型排除项——转成 AI 可以消费的显性指令。它需要持续维护：项目演进时上下文文件也要同步更新，我发现 AI 反复犯同一个错误时，说明上下文里缺少对应约束。
下次我让 AI 接手项目任务时，先检查三件事：AGENTS.md 是否覆盖了这次任务需要的约束、验证命令是否按改动类型列出、任务边界是否包含非目标。这三件事做到位，AI 的返工率会显著下降。
上下文文件是对齐工具——让 AI 的理解和我的预期在同一个坐标系里。
参考资料
- AGENTS.md 官方规范
- Martin Fowler: Context Engineering for Coding Agents
- Anthropic: Effective Context Engineering for AI Agents
- Sourcegraph: Context Engineering for Developers
- arXiv: Building AI Coding Agents for the Terminal
- PixelMojo: Context Engineering Beyond CLAUDE.md
- Faros AI: Context Engineering for Developers
- ETH Zurich 上下文文件效果研究（Medium 分析）