五层上下文工程让 AI Agent 少返工

很多人第一次使用 ChatGPT 或 Codex 时，会把效果不稳定归因于版本不够高：Plus 不够就考虑 Pro，任务中断就搜索 Codex 充值，遇到额度提示就立刻准备续费。版本与可用容量当然重要，但在真实开发中，影响结果的另一个关键因素是“上下文工程”——你给 AI Agent 哪些材料、以什么顺序提供、哪些规则被写成文件、怎样让它验证自己的工作。

本文不讨论某个模型的跑分，也不承诺任何套餐能自动解决工程问题。我们从一个更可操作的角度出发：把需求、代码、约束、证据和反馈组织成五层上下文，让 ChatGPT 负责理解与澄清，让 Codex 负责受控执行。即使你正在处理 ChatGPT Plus 充值、Pro 充值、订阅、续费或充值失败，也可以先用这套流程判断瓶颈到底来自账户容量，还是来自任务描述与仓库结构。

普通提示词往往是一段自然语言，例如：“帮我把登录功能修好，顺便优化代码。”它看起来明确，实际包含许多未决问题：什么叫修好？允许修改数据库吗？是否必须兼容旧接口？测试命令是什么？错误日志在哪里？如果没有这些边界，AI Agent 只能猜测。猜测越多，返工越多，上下文窗口也越容易被无效信息占用。

上下文工程不是无限粘贴文件，而是控制信息密度。每一段材料都应该回答至少一个问题：目标是什么、当前事实是什么、不能做什么、如何判断完成、失败后如何恢复。一个高质量任务包可以很短，但必须可验证；一个几万字的聊天记录如果缺少验收标准，仍然不是好上下文。

第一层：任务契约

先不要让 Codex 直接改代码。可以让 ChatGPT 把自然语言愿望整理为任务契约，再由人确认。契约至少包含背景、范围、非目标、完成标准与风险。

下面是一份适合复制到 Issue 的模板：

## 背景
用户在令牌过期后提交表单，页面一直停留在加载状态。

## 本次范围
- 识别 401 响应；
- 清理本地会话；
- 跳转到登录页，并保留返回地址；
- 增加自动化测试。

## 非目标
- 不更换认证供应商；
- 不修改数据库结构；
- 不重构全部网络请求模块。

## 验收标准
1. 令牌有效时行为不变；
2. 令牌失效时 1 秒内结束加载状态；
3. 返回地址经过白名单校验；
4. 单元测试和端到端测试通过。

这里最重要的是“非目标”。AI Agent 擅长把局部问题延伸成系统性优化，但范围扩大也意味着审查成本上升。先锁定一个可回滚的小交付，通常比一次性要求“彻底重构”更可靠。

第二层：事实层

事实层包括复现步骤、运行环境、错误信息、相关文件和最近变更。选择材料时可以用一个问题筛选：如果删除这段信息，Codex 的实施决策会不会改变？不会改变的内容就不必一开始加入。

环境：Node 22，Windows 11，pnpm
复现：登录 -> 等待令牌过期 -> 提交个人资料表单
预期：跳转 /login?next=/profile
实际：按钮持续 loading，控制台显示 401
相关文件：src/http/client.ts、src/auth/session.ts
验证命令：pnpm test auth && pnpm lint

隐私清理是用户自己的责任。 不要把完整生产日志直接交给任何第三方工具。先删除访问令牌、Cookie、邮箱、手机号、订单号和内部域名，再保留时间、状态码、调用位置与可复现参数。无论使用 ChatGPT Plus、Pro 还是 Codex，订阅档位不会替你自动完成数据分级。

第三层：仓库规则

聊天消息会被后续内容淹没，而仓库文件可以与代码一起版本控制。适合写入 AGENTS.md 的内容包括目录责任、允许使用的命令、测试要求、禁止触碰的路径和提交前检查。

# AGENTS.md

## 工作范围
- 前端代码位于 `src/`；测试位于 `tests/`。
- 修改认证逻辑时必须同步更新 `docs/auth.md`。

## 必须执行
- `pnpm lint`
- `pnpm test`
- 认证路径变更后执行 `pnpm test:e2e --grep auth`

## 禁止事项
- 不提交 `.env`、Cookie、令牌或真实用户数据。
- 未经明确批准，不修改数据库迁移和部署配置。
- 不通过删除失败测试来“修复”构建。

## 交付格式
- 说明根因、修改文件、验证结果和剩余风险。

规则要具体、短小并且可执行。“保持高质量”不是规则，“不得删除失败测试；新增分支必须覆盖异常路径”才是。规则还需要定期清理，过期命令会让 Agent 在错误方向上浪费时间。

第四层：自动验收

自然语言验收容易产生解释空间，自动测试则能给出清晰反馈。以令牌失效为例，可以先写失败测试，再让 Codex 实现最小修复。

import { describe, expect, it, vi } from "vitest";
import { requestWithSession } from "../src/http/client";

describe("requestWithSession", () => {
  it("clears the session and returns a safe login target on 401", async () => {
    const clearSession = vi.fn();
    const fetcher = vi.fn().mockResolvedValue({ status: 401 });

    const result = await requestWithSession({
      path: "/profile",
      fetcher,
      clearSession,
    });

    expect(clearSession).toHaveBeenCalledOnce();
    expect(result).toEqual({ redirectTo: "/login?next=%2Fprofile" });
  });
});

测试既是质量门槛，也是压缩上下文的方法。你不必用几百字解释“发生 401 后应该怎么做”，测试已经把输入、动作和期望输出固定下来。Codex 修改后，只要重新运行测试，就能知道变化是否满足契约。

第五层：建立短反馈环

长任务最怕两件事：方向错了仍继续执行，以及局部失败后把全部内容推倒重来。更稳妥的流程是按“理解—计划—局部修改—测试—摘要—下一步”循环。

task: expired-session-fix
stages:
  - inspect:
      output: root_cause.md
  - test:
      command: pnpm test auth
      expected: new_test_fails_before_fix
  - implement:
      allowed_paths:
        - src/http/client.ts
        - src/auth/session.ts
  - verify:
      commands:
        - pnpm lint
        - pnpm test
  - report:
      fields:
        - root_cause
        - changed_files
        - evidence
        - remaining_risks

这并不要求你真的引入工作流引擎。YAML 的价值在于把阶段与输出显式化。每完成一步就保存证据；如果中断，可以从最近一个已验证阶段恢复，而不是让 Agent 根据模糊记忆继续。

最终提示的写法

当五层材料准备好后，最终提示可以非常简洁：

请先阅读根目录 AGENTS.md 和 Issue #128。
只处理令牌过期后表单卡住的问题，不扩大重构范围。
先复现并新增失败测试，再实施最小修改。
每完成一个阶段都运行对应验证命令。
结束时报告：根因、修改文件、测试证据、未解决风险。
如果需要修改数据库或部署配置，停止并说明原因。

这里的关键不是礼貌词，而是执行顺序、边界与停止条件。对于高风险目录，明确“停止并说明原因”比“请小心修改”更有效。

充值与订阅的正确排查顺序

当结果不理想时，不要立刻把所有现象归为充值失败。可以按下面顺序判断：

ChatGPT Plus 充值与 Pro 充值属于消费者订阅场景，API 用量通常需要单独理解；Codex 的可用方式也应以当前账户界面与官方说明为准。不要把 ChatGPT 订阅、API 账单和第三方服务混在同一次排查中。准备续费前，先统计一周内的任务完成率、等待时间、返工次数和真正遇到容量限制的频率，再决定是否需要更高档位。

立刻可以做的四件事

第一，把“帮我优化”改成一个含非目标与验收标准的 Issue。第二，在仓库根目录增加不超过一页的 AGENTS.md。第三，为当前最常见故障补一个可以稳定失败的测试。第四，要求每次交付都附带验证命令和结果摘要。

执行一周后建立简单台账：任务名称、人工准备分钟数、Agent 执行分钟数、测试是否一次通过、返工次数、是否出现明确容量提示。这样你能区分“上下文混乱导致浪费”和“真实用量超过当前计划”。无论是选择 Plus、Pro，还是考虑 Codex 充值、订阅和续费，这类数据都比单次主观体验更可靠。

常见问题

1. 上下文越多，Codex 的效果一定越好吗？

不一定。无关日志、重复文档和互相冲突的规则会降低信息密度。先给任务必需材料，缺什么再补什么。

2. ChatGPT 适合做什么，Codex 适合做什么？

可以让 ChatGPT 帮助澄清需求、解释方案和形成任务契约，让 Codex 在明确仓库、命令和验收标准后实施与验证。实际功能以你的账户界面为准。

3. 小项目也需要 AGENTS.md 吗？

不是强制，但把稳定规则放进版本控制文件，通常比每次在聊天中重复更可靠。小项目也可以从十几行开始。

4. 遇到充值失败，能否通过重新安装 Codex 解决？

通常不能。支付状态、ChatGPT 订阅、API 账单、本地 CLI 环境是不同层。先确认失败发生在哪一层，不要反复安装或重复扣款。

5. 如何判断是否需要升级到更高档位？

先记录实际任务量、限额提示频率、等待成本和返工原因。低频学习与日常辅助可从较低成本方案评估；持续高强度工作再根据官方页面和真实数据判断。不要仅根据第三方文章中的旧价格或旧额度决定。

6. 如何防止 Agent 修改敏感文件？

在仓库规则中写明禁区，限制单次任务允许路径，并在提交前检查差异。密钥应保存在安全的环境变量或密钥系统中，不能写进提示、测试数据或仓库。

7. 如果任务中断，如何恢复？

保留阶段性报告、测试结果和当前差异，从最近一个已验证阶段恢复。不要让 Agent 在不知道当前状态的情况下继续猜测。

结语

AI Agent 的稳定性不是只靠更长提示或更高套餐，而是来自结构化目标、可信事实、明确约束、机器可读验收与短反馈环。先把这五层上下文搭好，再评估 ChatGPT Plus、Pro 与 Codex 的容量，才能让每一次订阅和续费更接近真实生产力投资。