先看一个典型翻车现场

设想一下，你让 Codex“帮我修一下登录有时候失败的问题”，顺手把整个 src/ 目录拖了进去，又补了一句“对了顺便把日志里那些警告也清一清”。它运行了一阵，改了七八个文件：登录那段没真正动，反倒把一个无关模块的告警注释删得干干净净，还顺手改坏了一处你没让它碰的配置。你心里一沉：昨天它还像个高手，今天怎么像没睡醒。

问题不在模型今天“状态不好”。根子出在你给它的上下文上——目标含糊（什么叫“修好”没说清楚）、边界缺失（哪些不能动没交代）、材料过载（一整个目录全塞进去，真正相关的两三个文件被淹没）、还夹带了一件“顺便”的任务把注意力扯散。Codex 并非读心术，它只在你为它搭建的那张“工作台”上做判断。台面乱，结果就乱。

这篇就从那个翻车现场往回倒推：先看清 Codex 是怎么一步步被带偏的，再反过来推导该如何喂信息。上下文工程（context engineering）说到底就一句话——让 Codex 拿到刚好够用的信息去干活，少了它只能猜，多了它会被资料淹没。

下面这张表按你的身份，告诉你这篇该重点看哪里。

整个翻车现场里最常见的一个错误，先说在前面：把所有能想到的资料一次性全塞给 Codex。恰恰是上下文工程最反对的做法——信息不是越多越好，是越准越好。

一、什么是上下文？先把它想成 Codex 桌上的资料

你可以把 Codex 想象成一个坐在你旁边的工程师。它干活前，桌上会放几类资料：公司规矩、项目说明、你这次交代的任务、它刚刚看过的文件、命令跑出来的结果。它写得准不准，很大程度上取决于桌上这些资料是不是刚好。

资料太少，它只能靠猜。你说“帮我修一下登录问题”，但没告诉它入口文件在哪里、错误长什么样、什么叫修好，它就只能在仓库里瞎摸索。资料太多，它会被淹没。你把十几个文件、几千行日志、好几段背景一次性丢进去，它哪知道哪一句最重要。

上下文工程说白了，就是帮 Codex 整理桌面。不是把所有资料都堆上去，而是把这次任务真正需要的东西放在最显眼的位置。

这个动作听起来简单，但其对结果的影响不容小觑。有一个反直觉的事实值得记住：在 SWE-bench 这类编程评测里，同一个模型、同一套题，换一套更好的“信息组织方式”（业界叫 harness，脚手架），成功率能拉开明显差距。独立机构 Epoch AI 的对照实验就发现，光是给同一个模型换脚手架，得分就能差出可观的一截，而且他们明确指出“脚手架的选择对整体表现的影响最大”。换句话说，怎么喂上下文，有时候比换一个更强的模型还重要。

把这件事做到极致是什么样？据 OpenAI 公开分享，他们内部有一个团队从空仓库起步，用 Codex 做出了一个百万行代码量级的产品，源代码没有一行是人手写的（连指挥 AI 干活的 AGENTS.md 都是 Codex 自己写的），人的角色主要是掌舵、定约束、搭反馈环。这些工程师的工作不再是敲代码，而是设计“能让 AI 可靠写对代码的环境”——这套环境，本质就是上下文工程的放大版。新手不必一步到位，但方向是一样的：你管的是“给 AI 什么信息”，不是“替 AI 写答案”。

二、把开篇那次翻车拆成四个原因

回到开头那次翻车。把它拆开看，你会发现 Codex 跑偏几乎都落在四个原因上，而且每一个都对应你能补的一类信息：

• 目标含糊：你只说“修一下登录问题”，没说什么叫“修好”，它就按自己的理解去改。
• 边界缺失：你没说“哪些文件不要碰”，它顺手就改到了别处。
• 材料过载：你把整个目录拖进去，真正相关的两三个文件被一堆无关代码淹没——它注意到开头和结尾，却漏掉了中间那段关键逻辑。
• 任务夹带：你让它“顺便”多做一件事，它的注意力就被扯散，主任务反而做歪了。

这并非在责怪用户，新手本来就很难一上来就知道该喂多少信息。但你需要先建立一个简单的直觉：Codex 不是读心术，它只在当前上下文里做判断，当前上下文乱，结果就容易乱。

把它当成一次任务交接会更好理解。你交接给同事时，不会把整个电脑桌面都倒给他，也不会只说“你看着办”。你会告诉他现在问题是什么、先看哪份材料、不要动哪里、做完怎么确认。给 Codex 也是同一个逻辑。后面几节，就是把这个四个原因逐个补回去。

三、Codex 的上下文怎么分层？新手只用盯紧两层

Codex 桌上的资料不是一团乱麻，而是分层的，从“最稳定、最不该乱动”到“最临时、用完即弃”大致是这样：

别被“五层”吓住，也不用平均用力。看最右一列就够了：系统提示词你管不到，Skills 和长期记忆是进阶项，新手真正要亲自盯紧的只有两层——AGENTS.md（长期项目规则）和会话级上下文（这次任务怎么交代）。回到 § 二那四个翻车原因，会发现它们全落在这两层里：目标、边界、材料、夹带，要么属于“这次怎么交代”，要么该沉淀进“项目规则”。把这两层喂对，大部分跑偏就没了。

这也是为什么本文把篇幅主要集中在这两层上：§ 四专讲 AGENTS.md 怎么写，§ 五到 § 六、§ 九到 § 十专讲会话级上下文怎么交代任务、给文件、给命令输出。Skills、窗口、长期记忆这些进阶层，放到后面用更短的篇幅说清边界即可。

一个常见的混乱是把临时任务写成长期规则。比如今天你说“这次不要跑测试”，它本该只在今天生效；可你要是把这句话沉淀进项目规则，下次它可能真的不测了。上下文工程不是只会加信息，也要知道信息什么时候该消失。

四、AGENTS.md 该写多长？项目规则不要写成杂物间

很多新手第一次写 AGENTS.md，会把所有想到的要求都塞进去。回答风格、测试命令、目录解释、历史教训、临时任务、个人偏好，越写越长。刚开始看着很安心，过一段时间就变成杂物间。

这里有个容易被忽略的事实：指令不是写越多越管用。HumanLayer 团队在公开的《Writing a good CLAUDE.md》里给出过一个很有用的判断依据：当前前沿的“会思考”的大语言模型，大约能比较可靠地遵循 150 到 200 条指令，而系统本身自带的提示词就已经用掉了大约 50 条。也就是说，留给你写项目指令的预算并不多——写太长，AI 反而会开始漏掉其中一些。有意思的是，HumanLayer 自己的根目录配置文件就控制在 60 行以内。

照这个预算反推，AGENTS.md 控制在几十行到两三百行通常就够，再往上多半是在“为了写而写”。新手起步可以先写一个精简版，跑一两周，根据 Codex 反复犯的错再加规则。每加一条前先问自己：这条比已有的哪一条更重要？如果不能替换掉旧的，就别加。

那 Skills（技能）和 AGENTS.md 怎么分工？AGENTS.md 是“每次都生效的项目铁律”，Skills 是“需要时才调用的固定流程”。Vercel 在公开评测《AGENTS.md outperforms skills in our agent evals》里给出过一个反直觉的对照：把文档直接嵌进 AGENTS.md（每次自动加载），通过率到了 100%；而靠 AI 自己决定要不要去读的 Skill，默认配置下通过率只有 53%——和完全不给文档的基线几乎一样。

项目规则最适合写三类内容：长期不变的项目背景、必须遵守的工作方式、固定的验证命令。比如“进入这个目录先读哪个文件”“改完必须跑哪个脚本”“哪些目录不要碰”。临时判断不要放进去——“今天先处理 A 文件”“这次不用发版”这种，留在当前对话就好，任务结束它们就该消失。

一个很简单的判断标准：如果下个月还应该遵守，就写进项目规则；如果只为今天服务，就留在这次对话；如果只是你刚才的想法、还没验证，就先别写进任何固定文件。

五、怎么给 Codex 派任务？说清目标、边界、验收三件事

你给 Codex 发任务时，不需要写长篇大论。真正关键的是三件事：目标、边界、验收。

目标是你要它完成什么。不要只说“优化一下”，要说“把这篇文章改成新手能听懂，减少代码和术语堆叠”。边界是它不能做什么。比如“不发布到 Ghost”“一次最多改三篇”“不要动已发布文章正文”。验收是怎样算完成。比如“正文里重复模板段落清零，FAQ 不再机械复读，中文字数仍达标”。

这三件事说清楚，Codex 就少猜很多。你不需要把所有背景都补完，只要先把任务的方向、范围、完成标准钉住。

很多失败不是因为提示词不够高级，而是这三件事缺了一件。没有目标，它会发散；没有边界，它会越界；没有验收，它会不知道什么时候停。你把这三件事写清楚，哪怕语气很普通，也比一大段漂亮但模糊的话更有用。

六、该给 Codex 多少文件？@ 文件引用怎么用才不跑偏

新手常犯的一个错，是把整个目录都丢给 Codex。看起来很放心，实际很容易稀释重点。它当然可以搜索文件，但你让它一次面对太多材料，它也需要判断哪份重要。

更稳妥的做法是先给一到三个关键文件。比如让它改文章，就给目标文章、写作规范、同类优质样例。让它修 bug，就给报错信息、相关代码、测试用例。让它做审查，就给变更文件和标准规范。

这里要专门讲一下 @ 文件引用。在 Codex 里用 @文件名 引用一个文件，它会把这个文件的完整内容读进当前会话——不是装样子，是真读，你能看到它后续输出会引用文件里的具体函数名、变量名。但正因为是“完整读入”，有三个常见误用：

如果它发现还缺信息，再让它自己查。这样上下文会一层层展开，而不是一开始就把桌面铺满。你还能看到它为什么要查新文件——它说“我需要看测试文件确认预期”，你就知道这一步合理；它如果突然打开一个无关目录，你也能及时拉回来。

七、上下文窗口有多大？为什么塞满反而变笨

聊到这里就绕不开一个新手最爱问的问题：Codex 的上下文窗口到底有多大？

答案分两层。第一层是“上限”：窗口上限随模型版本变化，具体数字以官方当前文档为准，新手不必把某个版本对应多少 token 记死——这类数字几个月就会变一轮。Codex 确实给了你手动调窗口的能力：在 ~/.codex/config.toml 里有一个 model_context_window 配置键，需要时可以按官方说明设置。

第二层、也是更要紧的一层是：窗口大不等于你该塞满。这里要讲一个关键概念——上下文衰减（context rot）。它说的是：当你往窗口里塞的内容越来越多，模型对“中间位置”信息的注意力会下降，头部和尾部记得清楚、腰部容易丢。这不是 Codex 的 bug，是大语言模型共有的特性，业界常叫它“lost in the middle”（迷失在中间）。斯坦福等机构 2023 年的论文《Lost in the Middle》就实测到这种“U 型”位置效应：相关信息放在中间时，模型的表现会明显下滑，而且上下文越长、整体越容易掉。新模型在这件事上有所改善，但“越长越要当心”的方向没变。

八、Codex 能跨会话记住事情吗？长期经验怎么沉淀

真正好用的上下文，不是每次都重新解释一遍，而是把反复出现的经验放到稳定位置。比如某个项目总是需要先跑一个脚本，某个目录不能直接改，某个发布流程必须先生成预览，这些都值得沉淀。

但沉淀不是复制粘贴。不要在 AGENTS.md、README、任务说明、个人备忘里写四份同样的规则。写多了以后，早晚会有一份过期。到时候 Codex 看到互相冲突的规则，还不如没看。

这里也要说清 Codex 的“长期记忆”到底能记住什么。Codex 的桌面应用支持持久的项目记忆——同一个项目下的多个会话之间，能保留你之前告诉它的偏好、踩过的坑、做过的决定。但 Codex 的命令行版本（CLI）当前还没有原生的长期记忆，每开一个新会话上下文都会重置。

建议是：长期规则只放一个权威位置，任务说明只引用它，不重复展开。上下文工程的成熟感，很多时候来自“少而准”，不是“多而全”。这也是团队协作里最省心的做法——大家都该看哪里，Codex 也知道该信哪份文件。

九、Codex 跑久了变笨怎么办？命令输出也会污染上下文

很多人会忽略这一点：命令输出也是上下文。你跑了一个很长的日志、一个巨大的测试报告、一个满屏的依赖树，Codex 都可能把它当成材料。材料越多，重点越容易被冲淡。

所以给命令输出也要有节制。失败时，给关键错误信息，不要一上来就贴几千行。需要搜索时，先用关键词定位，再给相关片段。测试失败时，先看第一个真实错误，不要把所有连锁失败都当成同等重要。

你要训练的是一种习惯：先让 Codex 看证据，而不是看噪音。比如测试失败时，先给第一个失败用例和相关堆栈；文章审核时，先给目标稿和检查标准；功能开发时，先给入口文件和预期行为。你越能把证据缩小到关键处，Codex 越容易给出像样的判断。

还有一个长会话里特别适用的动作：/compact。长会话会不断累积“会话级上下文”（你的所有提问 + AI 的回应 + 工具调用结果），堆到一定量之后注意力就开始分散。/compact 会让 Codex 把之前的对话压成一份摘要，腾出空间继续干活。

十、新手怎么写提问模板？四句话就够

你可以用很朴素的四句话，不需要复杂模板。

第一句：我要做什么。第二句：这次不要做什么。第三句：请先看哪些文件。第四句：完成后怎么验证。

比如：“请把这篇教程改得更适合新手，不要增加大段代码，不要发布。先看目标文章和写作规范。完成后检查重复段落、语义、中文字数和本地链接。”

这几句话听起来普通，但已经包含了目标、边界、材料和验收。Codex 最怕的不是短任务，而是模糊任务。短而清楚，比长而散更好。

如果你怕它理解错，可以再加一句“先说你准备怎么做，再动手”。这句话能让你在它开始改文件之前看到路线图。路线不对，你可以立刻纠正；路线对，再让它继续。这一步对新手很友好：你不用等它改完一堆文件才发现方向错了。先看路线，就像出发前看导航，路线不对，停车调整成本最低。

十一、Codex 出错先别急着换模型，先回头查那四个原因

绕了一圈，回到开篇那次翻车。看到 Codex 跑偏，先别动“换个更强模型”的念头，先把 § 二那四个原因当成排查清单挨个对一遍：

• 它知道目标吗？ 如果你只写了“优化”“修一下”，它很可能按自己的理解去改。
• 它知道边界吗？ 如果没说不能动哪些文件，它可能顺手就改到别处。
• 它看到了关键文件吗？ 如果该给的没给、不该给的塞了一堆，它只能在噪音里猜。
• 它知道怎么验收吗？ 如果没有完成标准，它做完也不知道该停在哪里。

开篇那次翻车，四条几乎全中。这四个问题比“要不要换更强模型”更基础：换模型能缓解一部分能力问题，但只要上面这四件没说清，再强的模型也是在一张乱桌面上做判断，照样会偏。

更关键的是，如果你每次出错都先换模型，很容易错过真正的原因——今天是目标不清，明天是边界没写，后天是日志太长。你以为自己在调模型，其实是在用更强的模型掩盖交接问题；而交接问题不解决，再强的模型也会重复栽在同一个坑里。模型是你最后才去动的那一层，不是第一层。

十二、下一步怎么练上下文工程？

你现在只要带走三句话。

第一，上下文工程就是整理 Codex 桌上的资料。少了会猜，多了会乱，刚好才稳。

第二，任务说明先写目标、边界、材料、验收。新手不要追求华丽提示词，先追求不让 Codex 猜。

第三，盯紧你能控制的那两层：长期规则放 AGENTS.md，这次的临时要求放当前对话，命令输出只给关键证据，窗口再大也别当仓库。

你可以从下一次任务就开始练。不要改工具，不要改模型，只改你的交接方式：先写目标，再写边界，再指定材料，最后写验收。做完一次你就会感受到区别。Codex 不一定突然变得完美，但它会少很多莫名其妙的猜测。

还有一个很实用的练习：下次 Codex 出错时，不要马上重开会话。先把这次任务复盘成四行——我原本要什么、我没说清什么、它误看了什么、下次要提前给什么。复盘两三次，你就会发现错误类型很集中。上下文工程就是从这些重复错误里长出来的。

最后理一下顺序：权限解决的是“它能不能做”，工具解决的是“它能借什么做”，上下文解决的是“它知不知道该怎么做”。顺序反了，新手会很累——工具接了一堆，权限开了一堆，最后 Codex 还是不知道你到底想要什么。配置是手段，理解是方向。方向清楚了，哪怕工具少一点，Codex 也能更稳定地往前走。

如果你下一步继续学，可以看 OpenAI Codex AGENTS.md 配置指南、Codex 沙箱与审批设置 和 Codex 模型怎么选、成本与速度怎么权衡。先把上下文讲清，再谈权限和模型，顺序是很重要的。