AI 编程工具的另一面：不是写代码，是交付

很多工程师第一次接触 AI 编程，都会经历三个阶段。

1. 第一阶段，把它当代码补全工具。它像一个很聪明的 Tab 键，可以补样板代码、补函数骨架、补几行常见逻辑。
2. 第二阶段，把它当问答助手。报错看不懂，问它；方案拿不准，问它；陌生代码想快速理解，也问它。
3. 第三阶段，开始接触 Codex 这类以 Codex 为代表的云端Codex 这类（Chen 注：Codex 是这一阶段最具代表性的工具。它是 OpenAI 推出的云端 coding agent：你提交一个任务，它在独立的云端沙箱里 clone 仓库、读文件、写代码、跑命令、看测试结果，最后把改动推成一个 PR 供你审查。注意 Codex 已于 2026 年 5 月以 SWE-1 模型为基础重新发布为新产品，本文所指为该新版本及其前身。） coding agent，才发现事情变得不太一样了：它不只是回答问题，还能进入项目，读文件、改代码、跑命令、看测试反馈，再继续修正。

这时，一个很关键的分水岭出现了。你到底是在让 AI 「写几段代码」，还是在让 AI 「完成一段工程任务」？这两个问题看上去差不多，实际差很多。前者关心的是答案，后者关心的是交付。也正是因为这个变化，我们写了《Codex 快速入门：Harness 工程落地》这本书。

AI 编程的下半场，不是提示词，而是交付能力

过去一段时间，很多关于 AI 编程的讨论都集中在提示词上：

怎么问，模型才会给出更好的代码？
怎么描述，模型才不会漏掉需求？
怎么写 prompt，才能让它一次生成完整模块？

这些问题当然重要，但它们只解决了一部分问题。在真实项目里，工程师真正头疼的往往不是「AI 能不能写出一段看起来对的代码」，而是：

1. 它改的文件对不对？
2. 它有没有理解项目原有约定？
3. 它有没有漏改测试、文档、序列化、迁移或调用方？
4. 它有没有引入不该引入的依赖？
5. 它跑过什么验证？验证结果可信吗？
6. 最后这组改动能不能被人审查、接受、合并？

这才是 Codex 和普通聊天机器人Codex 这类云端 agent 和本地补全工具Codex 和普通聊天机器人（Chen 注：Codex 和 Copilot/Cursor 的区别也在这里：后两者是本地 inline 补全或对话辅助，改动由你实时控制；Codex 是异步云端 agent，它独立完成整个修改闭环，最终以 PR 的形式交给你审查——这才是「工程交付」的意义。） 的根本差别。普通问答助手更像在项目外部给建议。它可以解释、比较、生成示例，但集成、适配和验证主要还要靠人完成。Codex 的意义在于，它开始进入软件工程现场——在云端沙箱里 clone 仓库，按现有结构定位代码，在合适的位置实施修改，调用测试和检查命令，再根据结果继续调整。

所以我们在书里反复强调一句话：Codex 不是聊天机器人，而是工程交付工具。

---

一个典型误区：把 Codex 用成「更会写代码的 ChatGPT」

很多人第一次用 Codex，会这样问：

怎么写一个 CSV 解析函数？

或者：

帮我生成一个 FastAPI 认证中间件。

这类问题不是不能问，但它们仍然是「问答模式」。但对 Codex 来说，它们仍然是「问答模式」，没有发挥出 agent 的真正优势。但它们仍然是「问答模式」。（Chen 注：用 Copilot 或 Cursor 问这类问题完全合理，它们就是为 inline 补全和对话辅助设计的。但 Codex 是云端 agent，把它用成问答工具，等于用挖掘机挖花盆——工具没问题，场景用错了。） AI 给你一段代码，你再复制、粘贴、适配、测试、修 bug。

如果换成 Codex 更适合的方式，任务应该像这样描述：

请在现有数据导入模块中支持自定义分隔符和编码，保持原有默认行为不变；处理字段中包含分隔符的情况；补充对应单元测试；完成后运行相关测试，并说明验证结果。

这条指令的重点不是更长，而是更像一次工程委托。它包含了目标、范围、约束和验收标准。Codex 需要做的不再是「回答一个问题」，而是在项目中完成一段可验证的变更。

这也是很多开发者从 AI 编程中获得稳定收益的关键：不要只向 AI 要代码，要向它交付任务。

---

为什么提示词不是核心

原标题：为什么我们不想把这本书写成『提示词大全』原标题：为什么我们不想把这本书写成『提示词大全』（Chen 注：原标题是书籍宣传视角，演绎版改为直接陈述核心论点。）

提示词当然有用，但真正决定 Codex 效果的，往往是更底层的工程条件。

项目有没有清楚的目录结构？有没有 README.md、贡献规范、架构说明？有没有可运行的测试、lint、类型检查或统一验证脚本？团队约定是写在文档里 AGENTS.md 里供 Codex 读取文档里（Chen 注：Codex 通过读取仓库根目录的 AGENTS.md 文件来了解项目约定。这是它感知「这个项目怎么工作」的主要入口——测试命令是什么、禁止修改哪些文件、PR 格式要求等，都应该写在这里。没有 AGENTS.md 的仓库，Codex 只能靠猜。），还是只存在某个老员工脑子里？

这些东西过去只是「好工程习惯」，到了 AI 协作时代，它们会直接决定 Codex 能不能正确理解任务。

因为 Codex 再强，也逃不开三类典型错误。

1. 幻觉：不知道，却写得很像。比如调用不存在的 API，混用不同版本的参数，或者写出结构合理但事实不成立的配置。
2. 漏改：局部正确，整体不完整。比如只改了接口和服务层，却漏掉序列化、迁移、测试、文档或调用方。
3. 误判：代码没错，决策不对。比如为了完成一个小功能，引入一个额外依赖，破坏了项目原有技术栈约束。

这些问题不是靠「再写一个神奇 prompt」解决的，而是靠上下文、规则、测试和审查解决的。

---

第一次使用，不要上来就重构整个系统

我们见过不少人第一次用 AI agentCodexAI agent，就直接扔一个巨大任务：

帮我重构整个用户模块。
把这个项目改成微服务。
补齐所有测试，顺便优化架构。

然后很快失望。

我们的建议恰好相反：第一次任务一定要小。比如：

1. 修复一个明确的测试失败。
2. 给一个已有函数补一个边界条件。
3. 在现有模块里增加一个很窄的字段校验。
4. 根据现有风格补一组单元测试。
5. 修改一个可局部验证的工具函数。

任务越小，越容易观察 Codex 的完整工作链路：它读了哪些文件，怎么判断修改位置，改了哪些内容，跑了什么测试，遇到失败后怎么处理，最终 PR diff 是否符合预期。

这比一上来追求「惊艳效果」更重要。

因为 Codex 的真正价值，不是一次生成多少代码，而是能不能跑通一个稳定闭环：

1. 需求澄清：确认到底要改什么。
2. 任务下达：说明目标、范围、约束和验收标准。
3. 执行观察：关注它读了什么、准备改什么、如何验证。关注任务执行日志：它读了哪些文件、跑了什么命令、结果如何。关注它读了什么、准备改什么、如何验证。（Chen 注：Codex 是云端异步执行，你不是坐在旁边实时看它打字。执行过程中它会更新任务状态，完成后提交 PR。「观察」意味着：看它的执行日志、看它读取了哪些文件、看它跑了什么命令和结果——这些都记录在任务详情里。）
4. 结果验证：审查 PR diff，运行测试，确认没有意外改动。
5. 代码提交：确认结果可接受后，再进入版本历史。Merge PR，进入版本历史——Codex 的交付物就是一个标准 PR，和人写的代码走同样的 review 流程。确认结果可接受后，再进入版本历史。（Chen 注：Codex 的标准工作流是：完成任务 → 推送分支 → 创建 PR。你 review PR、确认无误后合并。这和普通 code review 流程完全一致，这也是 Codex 能融入团队协作的关键。）

这个闭环跑通以后，开发者才会真正理解 Codex 的工作方式。它不是魔法按钮，也不是外包程序员，而是一个需要被放进工程流程里的 AI 协作伙伴。

---

Harness：让 AI 协作从「临场发挥」变成「可复用工作流」

书名里有一个关键词：Harness。我用这个词，是想表达一种很朴素的工程思想：不要试图给 AI 写死每一步剧本，而是给它一个稳定的工作约束。Codex 生态有一个关键概念：Harness。这套机制的工程思想是：不要给 Codex 写死每一步剧本，而是给它一个稳定的约束环境——让规则和约定通过 AGENTS.md、task 模板、shell hooks 来表达，而不是每次靠人工提醒。书名里有一个关键词：Harness。我用这个词，是想表达一种很朴素的工程思想：不要试图给 AI 写死每一步剧本，而是给它一个稳定的工作约束。（Chen 注：Harness 在 Codex 里有具体的技术形式：AGENTS.md（项目规则和约定）、task prompt 模板（可复用的任务描述格式）、shell hooks（任务开始/结束时自动执行的脚本）、Skills（可组合的子任务单元）。这套机制让 Codex 的使用方式从「每次临时描述」升级为「标准化工程配置」。）

一个好的 Harness，通常包括三层：

1. 目标层：要交付什么，怎样算完成。
2. 约束层：哪些文件、依赖、行为边界不能越过。
3. 自由层：在前两层之外，允许 Codex 根据仓库现状选择实现路径。

这和传统「提示词技巧」不太一样。提示词更像一次性表达，Harness 更像可复用的工程环境。它可以沉淀成项目规则、任务模板、验证脚本、自动化检查，甚至团队协作规范。

当一个团队开始把反复出现的 Codex 偏差沉淀为 AGENTS.md 规则，把人工反复提醒的事项沉淀为 脚本shell hooks脚本，把模糊的验收口径沉淀为测试，AICodexAI 协作才会从「看运气」变成「可持续」。

---

这本书适合谁？

如果你已经用过 ChatGPT、GitHub Copilot、Cursor、Qoder、Trae 或其他 AI 编程工具，但仍然觉得它们停留在「给代码片段」的层面，这本书会帮你把使用方式升级到「交付任务」的层面。如果你是技术负责人、架构师或资深工程师，正在思考 AI 编程如何进入真实研发流程，而不是只作为个人效率玩具，这本书会重点讨论规则、验证、审查、权限和风险分级。

如果你刚开始接触 Codex，也可以从这本书入门。它会从 Codex 的定位、基本原理、安装登录、CLI、App、本地任务和云端任务讲起，再通过场景案例跑通从任务描述到验证闭环的完整流程。这本书也不只适合 Codex 用户。书里讨论的 Harness、Skills、Subagents、MCP、Worktrees 等方法，本质上是在讲 AI 工具进入工程交付时需要怎样被组织。因此对 Cursor、Qoder、Trae 等 AI 工具用户也有参考价值。

---

我们最想传达的一句话

未来的工程师，不一定要把每一行代码都亲手敲出来。但他必须更清楚地知道：目标是什么，边界在哪里，怎样验证，哪些风险不能交给 Codex 自动决定，哪些经验应该沉淀为 项目AGENTS.md项目 规则。

AI 编程的竞争力，可能不再只是「谁更会写代码」，而是谁更会组织一次可验证、可审查、可复用的人机协作。

这也是我们写《Codex 快速入门：Harness 工程落地》的原因。

如果你正在从「让 AI 帮我写几段代码」，走向「让 Codex 帮我完成一段真实工程任务」，这本书应该会对你有用。