跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 00

00-03|你不需要先成为传统程序员:如何使用 Codex 开发

建立 Human × Codex 工程分工,把模糊需求转成带边界、验收与验证命令的开发任务。

Codex · AI Coding · 工程协作

“帮我做一个跨境客服 Agent”为什么还不能开工

这句话没有说明客户身份怎样确认、订单来自哪里、退款能执行到哪一步、失败时是否转人工,也没有测试和验收标准。Codex 可以快速生成代码,但无法替业务负责人决定这些条件。

AI Coding 降低了实现门槛,也放大了任务定义的价值。你无需先积累多年传统编程经验才能参与 Agent 项目;你需要学会描述业务、划定边界、阅读变更、运行验证,并对结果作出判断。

本课不讲按钮和快捷键。界面会更新,工程协作的责任分工更稳定。

Human × Codex:谁负责什么

Human|定义与决策
  • Business Requirement
  • Architecture
  • Constraints
  • Acceptance Criteria
  • Risk Decision
Codex|检查与执行
  • Repository Inspection
  • Implementation
  • Tests
  • Debug
  • Refactor
  • Build
共同闭环:需求 → 方案 → 变更 → 验证证据 → 人作出接受或调整决定
图 1|Codex 承担大量实现工作;业务目标、风险接受和最终验收仍需要人负责。

人不必预先知道每个文件名,但要能回答“什么结果算完成”。Codex 不应凭空发明业务政策,但可以检查现有仓库,找出内容存放方式、可复用组件、测试命令和受影响范围。

从愿望到工程任务

Bad Task
做一个智能客服,能查订单,效果要好。

缺少对象、输入输出、权限、失败路径和验收方式。

Engineering Task
在现有项目中新增意图分类器,把多语言消息转成指定 Schema;缺订单号返回 null;非法输出不得进入下一步;用 12 条测试覆盖正常、模糊和缺字段输入。

结果、边界和证据均可检查。

图 2|工程任务让实现者知道做什么,也让审核者知道如何拒绝不合格结果。

一份可执行任务至少包含七项:

  1. Business Goal: 为什么做,改善哪个业务结果。
  2. Current State: 当前仓库与系统已经有什么。
  3. Desired Change: 本轮具体增加或改变什么。
  4. Scope: 允许修改和禁止修改的文件或系统。
  5. Interface: 输入、输出、Schema、错误形状。
  6. Acceptance Criteria: 哪些可观察结果必须成立。
  7. Verification: 要运行哪些测试、类型检查、构建和页面检查。

这些信息不要求一次写得完美。你可以先要求 Codex 只读扫描并报告现状,确认方案后再授权修改。这种“先发现、再实施”的节奏特别适合陌生仓库和高风险变更。

一个可靠的开发闭环

  1. STEP 1
    Inspect

    读规则、结构、状态与相关代码

  2. STEP 2
    Plan

    提出最小方案和风险边界

  3. STEP 3
    Implement

    只在批准范围内修改

  4. STEP 4
    Verify

    运行测试、类型、lint 与 build

  5. STEP 5
    Review

    检查 diff、行为与失败分支

  6. STEP 6
    Decide

    接受、调整或回退

图 3|“代码生成完”只到第三步;验证证据和审核决定才闭合一次工程变更。

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 自行猜测。

合上正文,试着回答

  1. 使用 Codex 开发时,人最不能外包的五项责任是什么?
  2. 为什么 Repository Inspection 应发生在实现之前?
  3. Acceptance Criteria 与“功能描述”有什么差别?
  4. build 通过后还要检查什么?
  5. 如何给 Codex 实现空间,同时防止范围扩张?

Week 00 到这里完成。下一课进入 V0.1:一次 LLM API 请求究竟经历什么,Token 与 Context 如何限制系统,以及哪些信息应该进入模型。

延伸阅读 / Sources

核查日期:2026-10-17。

长期有效的原理: 目标、边界、接口、验收和验证证据共同定义工程任务。当前实现方式: Codex 的界面、模型与交互能力会更新,本课不依赖具体按钮位置。