AI Agent Engineering · Week 00
00-03|你不需要先成为传统程序员:如何使用 Codex 开发
建立 Human × Codex 工程分工,把模糊需求转成带边界、验收与验证命令的开发任务。
“帮我做一个跨境客服 Agent”为什么还不能开工
这句话没有说明客户身份怎样确认、订单来自哪里、退款能执行到哪一步、失败时是否转人工,也没有测试和验收标准。Codex 可以快速生成代码,但无法替业务负责人决定这些条件。
AI Coding 降低了实现门槛,也放大了任务定义的价值。你无需先积累多年传统编程经验才能参与 Agent 项目;你需要学会描述业务、划定边界、阅读变更、运行验证,并对结果作出判断。
本课不讲按钮和快捷键。界面会更新,工程协作的责任分工更稳定。
Human × Codex:谁负责什么
- Business Requirement
- Architecture
- Constraints
- Acceptance Criteria
- Risk Decision
- Repository Inspection
- Implementation
- Tests
- Debug
- Refactor
- Build
人不必预先知道每个文件名,但要能回答“什么结果算完成”。Codex 不应凭空发明业务政策,但可以检查现有仓库,找出内容存放方式、可复用组件、测试命令和受影响范围。
从愿望到工程任务
做一个智能客服,能查订单,效果要好。
缺少对象、输入输出、权限、失败路径和验收方式。
在现有项目中新增意图分类器,把多语言消息转成指定 Schema;缺订单号返回 null;非法输出不得进入下一步;用 12 条测试覆盖正常、模糊和缺字段输入。
结果、边界和证据均可检查。
一份可执行任务至少包含七项:
- Business Goal: 为什么做,改善哪个业务结果。
- Current State: 当前仓库与系统已经有什么。
- Desired Change: 本轮具体增加或改变什么。
- Scope: 允许修改和禁止修改的文件或系统。
- Interface: 输入、输出、Schema、错误形状。
- Acceptance Criteria: 哪些可观察结果必须成立。
- Verification: 要运行哪些测试、类型检查、构建和页面检查。
这些信息不要求一次写得完美。你可以先要求 Codex 只读扫描并报告现状,确认方案后再授权修改。这种“先发现、再实施”的节奏特别适合陌生仓库和高风险变更。
一个可靠的开发闭环
- STEP 1
Inspect读规则、结构、状态与相关代码
- STEP 2
Plan提出最小方案和风险边界
- STEP 3
Implement只在批准范围内修改
- STEP 4
Verify运行测试、类型、lint 与 build
- STEP 5
Review检查 diff、行为与失败分支
- STEP 6
Decide接受、调整或回退
Inspect:让仓库先说话
Codex 应先读取项目规则、相关文件和当前 diff。它需要知道内容系统怎样注册、哪些变更属于用户、项目用什么命令验证。陌生仓库里直接创建新架构,很容易绕过已经存在的正确路径。
Plan:把不确定性摆到修改之前
计划应写清会改哪些文件、哪些文件保持不动、数据如何流动、失败如何处理。如果实现必须突破批准范围,先停下来报告。这个停顿能防止“小功能”悄悄演变成系统重构。
Implement:保持变更可审核
每次只完成一个可验收目标。保存已有未提交修改,避免覆盖用户工作。生成的代码需要沿用仓库命名、类型和测试约定。
Verify 与 Review:命令通过只是证据的一部分
类型检查发现接口错误,lint 检查代码规范,测试验证预期行为,build 验证生产编译。随后仍要查看 diff 和真实页面:测试可能漏掉错误需求,构建成功也不能证明移动端没有溢出。
用 01-04 的任务预演一次
到 Week 01 结束时,我们要得到 Support Agent V0.1。把它写成 Codex 可执行任务:
Business Goal
把多语言客服消息转成可进入业务流程的结构化意图。
Allowed Scope
仅新增意图识别模块与测试;不连接订单系统,不执行退款。
Input
客户原始消息,例如:"Where is my order XB-1024?"
Output
intent, language, orderId, needTool;必须通过 Schema Validation。
Failure
非法输出、未知意图、缺订单号均返回明确状态,不得猜造字段。
Acceptance
给定测试集全部通过;类型检查、lint、测试和 build 通过;diff 中没有范围外文件。
这段任务没有规定每一行代码。Codex 保留实现空间,人保留业务和验收控制权。
Failure Lab
只给目标,不给边界
为什么诱人: “让 Agent 更聪明”写起来快,也给 Codex 最大自由度。
为什么失败: Codex 可能新增依赖、改路由、重构组件,还可能把“识别退款意图”实现成“执行退款”。
更好的设计: 明确允许文件、禁止范围、输入输出和动作上限。遇到范围外依赖就停止报告。
把实现方案写成逐行指令
为什么诱人: 控制感强。
为什么失败: 你可能指定了与仓库冲突的库、路径或模式,Codex 也失去检查并复用现有实现的空间。
更好的设计: 固定业务结果、接口和约束;要求先检查仓库,再提出最小实现方案。
看到 build 通过就验收
为什么诱人: 命令是清晰的绿色信号。
为什么失败: build 只证明能够编译。错误的业务字段、错误导航和移动端拥挤都可能继续存在。
更好的设计: 把行为测试、diff 边界、页面检查和失败场景一起写进 Acceptance Criteria。
实践:把一句需求改造成工程任务
原始需求:“做一个 AI 客服,能判断客户想查物流还是退款。”
先写出你需要向业务方确认的五个问题,再按 Business Goal、Current State、Desired Change、Scope、Interface、Acceptance Criteria、Verification 七段改写。最后让另一位同伴只读你的任务,判断他能否明确知道“做完”和“做错”的区别。
Acceptance Criteria
- ☐ Business Goal 指向一个可观察业务结果。
- ☐ 写明当前系统已有能力与本轮新增能力。
- ☐ 明确允许修改与禁止修改的范围。
- ☐ 输入、输出、缺字段和错误状态均有定义。
- ☐ 至少列出 6 条测试,含正常、多语言、模糊与非法情况。
- ☐ Verification 包含自动检查与至少一项人工行为检查。
- ☐ 写明突破范围时必须停止报告。
- ☐ 没有把业务政策或风险决定交给 Codex 自行猜测。
合上正文,试着回答
- 使用 Codex 开发时,人最不能外包的五项责任是什么?
- 为什么 Repository Inspection 应发生在实现之前?
- Acceptance Criteria 与“功能描述”有什么差别?
- build 通过后还要检查什么?
- 如何给 Codex 实现空间,同时防止范围扩张?
Week 00 到这里完成。下一课进入 V0.1:一次 LLM API 请求究竟经历什么,Token 与 Context 如何限制系统,以及哪些信息应该进入模型。
延伸阅读 / Sources
核查日期:2026-10-17。
- OpenAI Cookbook:Codex Prompting Guide。用于核对 Codex 的仓库指令与任务上下文方式。
- OpenAI Cookbook:Iterating Development Workflows with Codex。用于核对分阶段、证据驱动的工程工作流。
- OpenAI Developers:Using skills to accelerate OSS maintenance。用于核对仓库规则、可重复验证流程和测试要求。
长期有效的原理: 目标、边界、接口、验收和验证证据共同定义工程任务。当前实现方式: Codex 的界面、模型与交互能力会更新,本课不依赖具体按钮位置。