从零用 codex 开发复杂软件：从一句需求到可验收的功能

“帮我做一个 ai pipeline，支持数据准备、训练、评估，以后还能部署模型。”

把这句话交给 codex，很快就可能得到一堆目录、接口和配置。代码看起来不少，但系统怎样算做完？训练失败怎么办？服务重启后，之前的任务去哪了？

复杂软件的难点，往往藏在这些问题里。我会先把需求变成能观察、能验收的小目标，再让 codex 一段一段实现。

这篇文章从一个假想的空仓库开始，开发一套小团队使用的 ai pipeline，也就是把多个 ai 工作步骤串起来执行的软件：

提交数据集和训练方案
        ↓
数据准备 → 训练 → 评估
        ↓
查询状态、查看日志、取得结果

模型部署作为后续范围。文中的接口、文件和结果都是设计示例，不代表我已经做出了这套产品，也不对应真实业务项目。

如果还不清楚 agent、skills、tools 等组件的关系，可以先看上一篇文章。这一篇重点讲开发流程。下面的拆分和验收办法是实践建议；涉及 codex 的产品说明依据截至 2026 年 10 月 7 日的官方文档整理。

1 先把一句需求变成可以验收的目标

先不要急着选框架。我会问四件事：谁来用、要解决什么问题、第一版不做什么、受到哪些约束。

在这个案例里，可以先约定：

“支持训练”还不够具体。至少要说清楚：输入是什么、产物是什么、失败怎么报告。

第一阶段只验证执行流程，可以把目标写成：提交一次请求后得到任务 id；三步按顺序模拟运行；任务结束后能查到状态和示例结果；第二步失败时，第三步不能执行。

模拟成功只证明流程可跑。后续接入真实训练时，还要定义数据格式、模型产物、评估方法和资源预算，不能把两种验收混在一起。

可以先给 codex 这段提示词：

我要从零做一个小团队使用的 AI Pipeline，固定执行数据准备、训练、评估。
第一阶段只做三步模拟执行，不做模型部署、可视化编排和分布式训练。

请先梳理用户、输入输出、非目标、约束和可测验收。
把事实、假设和待确认问题分开。问题优先问会改变设计的部分。
这一轮只形成需求草案和阶段计划，暂不生成业务代码。

这里最值得由人决定的是业务含义。例如，“评估失败”是程序出错，还是模型分数不达标？两者会影响状态、重试和后续发布规则。

2 先摸清上下文，再比较方案

“从零”也要先看环境。空仓库可能已经带着模板、提交记录或自动部署配置，不能直接覆盖。

让 codex 查看现有说明、文件、版本状态和可用运行环境。如果已经有代码，先确认入口、测试命令和既有实现；确实是空仓库，再决定如何初始化。

我会要求它回答：哪些事实已经看见，哪些条件还没验证，缺少什么会阻碍第一阶段。

接着比较两条够用的路线，例如：一个服务内运行后台任务，或者 api 服务配一个独立执行进程。比较维护成本、失败影响和后续扩展，而不是只列功能清单。

这个案例可以先选择熟悉的 python 技术栈，用一个服务提供接口，后台顺序运行固定步骤。代码中分开“接收请求”和“执行步骤”，暂时不拆成多个服务。任务记录第一阶段放内存，后续再持久化。

这是为了先验证任务流程的选择，不适用于需要立即保证重启恢复或高并发的第一版。语言和框架也应服从团队经验、已有代码与部署条件。

先检查仓库和运行环境，不覆盖已有文件。
比较单服务后台执行、API 加独立执行进程两种方案。
说明各自的复杂度、风险，以及什么条件下需要升级。

给出满足第一阶段验收的最小建议。
把技术栈选择、数据保存和恢复策略列为决策点，确认后再初始化。

若在 codex cloud 中开发，要在云端实际确认依赖、数据访问与网络，不能拿本机可以运行当作证据。云端任务有自己的文件状态，网络与外部服务权限也要分别确认。官方云端环境说明。

3 先定接口和数据约定，不急着搭大框架

代码开写前，只需要一份短设计：用户怎样提交，系统怎样回应，步骤之间传什么。

对这个案例，最初两个接口就够了：

POST /api/runs
GET /api/runs/{run_id}

提交请求先引用已经准备好的数据集和允许使用的训练方案：

{
  "dataset_id": "sample-v1",
  "recipe_id": "baseline-v1"
}

创建成功返回任务 id。查询接口则返回整体状态、当前步骤和结果引用。第一阶段只有示例结果，接入真实训练后才返回真实产物。

建议先约定 queued、running、succeeded、failed 四种状态。等待执行是 queued，三步都成功才是 succeeded；中间任何一步失败，就记录失败位置和可理解的原因。

步骤之间也要有约定：数据准备返回数据产物引用，训练读取它并返回模型产物引用，评估读取模型与评估数据并返回指标。不要让下游靠猜目录名寻找文件。

这里的数据合同，就是“哪些字段、类型和含义可以依赖”。后续可以增加数据版本、代码版本、参数与产物校验信息，帮助查清一份结果是怎样产生的。

第一版把处理逻辑、执行逻辑和记录存取分清楚即可。只有固定三步时，不必先实现任意流程图和插件系统。需要支持分支、并发步骤或不同任务类型时，再讨论升级。

4 先做一个纵向闭环，再逐层扩展

所谓纵向闭环，就是从用户入口一直做到可见结果。它可以很小，但要真的连起来。

我会先让 codex 做“提交 → 模拟执行三步 → 查询状态 → 取得示例结果”。先不做完整网页，避免接口、前端、调度都写了一半，最后没有一条路径能跑。

后面的阶段可以这样安排：

阶段 a 是 demo。阶段 b 的小数据运行，也不代表已经验证大数据、长时间训练和生产负载。每个阶段只证明自己实际检查过的范围。

进入阶段 b 时，先选一个很小、可以离线运行的训练例子。给耗时、内存和数据规模设上限，不要一上来下载大模型、租 gpu，把流程问题和资源问题搅在一起。

生产使用还涉及运行监控、备份、容量、隔离和运维。表格是开发路线，不是生产就绪保证。

5 每次只给一个有边界的实现任务

同一个大目标，可以拆成几次请求。每次说清楚输入、输出、范围和验收，让 codex 知道什么时候算完成。

阶段 a 的任务提示词可以直接这样写：

按已确认的短设计，实现阶段 a：固定三步模拟闭环。

输入：dataset_id、recipe_id；只接受预置的示例值。
输出：创建接口返回 run_id，查询接口返回整体状态、各步骤状态和示例结果。
范围：内存记录、单进程后台顺序执行，不接真实训练、不增加前端和外部服务。

验收：
1. 成功请求依次执行准备、训练、评估，最终为 succeeded。
2. 模拟训练失败时，整体为 failed，评估不执行。
3. 未知输入被拒绝，查询不存在的任务得到约定错误。

沿用已选技术栈，补齐相关测试和启动说明。
完成后自审差异，运行检查，说明未验证项。
若发现必须改变接口或引入新依赖，先说明理由和影响。

阶段 a 验收后，阶段 b 再明确真实数据、执行入口和产物约定。不要一边修模拟流程，一边悄悄加完整调度平台。

如果 codex 卡住，可以让它报告失败命令、相关错误、已排除的原因和最小修复建议。先判断问题属于环境、需求还是实现，避免反复重写代码。

任务大到难以审阅时，也该继续拆小。例如，把“可靠运行”拆成超时处理、取消、记录保存和重启识别，各自给出验收。

6 用少量记录，让下一次对话接得上

复杂项目通常不是一次会话写完。比起重新讲几十遍背景，我会留下几份短记录。

项目约定写进 AGENTS.md。codex 会读取适用的说明，目录范围会影响哪些约定生效；这与工具实际获得的权限是两回事。官方 AGENTS.md 说明。

下面是这个假想项目的简化示例：

# 项目约定

- 接口负责校验和响应，步骤执行逻辑与记录存取分别组织。
- 每次只实现当前阶段，修改接口或增加依赖时说明原因。
- 使用固定小样本测试，不访问真实业务数据，不启动昂贵训练。
- 修改后运行相关检查；未运行的检查说明原因。
- 保留已有修改，提交和发布按当前任务授权执行。

再用一份短设计记录接口、状态和关键决定，一份状态记录写当前阶段、已完成验收、待解决问题和下一步。文档名称由项目决定，不需要规定一套庞大的目录。

比如状态记录可以写：“阶段 a 完成；当前记录在内存中，重启会丢失；下一步接小样本训练；取消和持久化尚未实现。”这比“基本完成，继续优化”有用得多。

新会话开始时，可以让 codex 先读这些记录，再核对实际代码、工作区差异与测试结果。记录只是导航，可能已经过时，不能替代代码事实。

常做的操作以后再整理成 skill。还没有重复需求时，先把当前流程跑顺，不必为了使用某个组件而增加文档。

7 保留一条集成主线，只把独立工作并行

复杂不等于必须开很多 agent。接口和状态约定还没稳定时，同时开发执行器、存储和前端，很容易各自理解一套字段。

我会让主代理维护计划、处理关键接口并负责集成。真正独立的工作再分出去，例如审查状态转换，或者根据确定的接口整理测试场景。

codex 支持子代理分工，可以直接要求它使用子代理；具体能力仍以当前入口和设置为准。官方 subagents 文档。

对刚开始的项目，我建议先限制为一到两个范围明确的子任务。这是控制协作成本的建议，不是产品数量限制。

例如，主代理实现取消逻辑，一个子代理只读审查“取消与完成同时发生”的情况，另一个只整理测试遗漏。不要让三个人一起修改状态定义和同一个执行文件。

如果确实要并行写代码，先划清负责的模块和文件，约定共享接口，再由一条主线顺序整合，每次整合都验证。无法隔离的工作就串行。

多代理可能减少等待，也可能增加上下文、工具调用和返工。它不保证更省额度，更不保证代码更好；要看任务能否独立完成。

8 验收异常路径，别只看测试变绿

测试要和阶段目标一起增长。第一阶段检查顺序与失败传播，真实执行阶段检查产物和进程，持久化阶段检查重启与重复请求。

单元测试适合检查一个状态转换或输入校验；集成测试检查接口、执行器和记录存取怎样配合；端到端测试从提交请求走到查询最终结果，验证用户实际经过的流程。

对这个 pipeline，进入相应阶段后，我会至少保留下面这些验收：

取消功能需要增加 cancelled 状态。收到取消请求不等于进程已经停止；取消或超时后，未确认执行已停止时，可以保留 cancelling 或待核对状态，不能冒称取消完成。还要处理任务恰好完成、取消重复到达等情况，避免状态来回跳。

重复提交可以约定一个请求键，与使用者和请求内容一起校验。相同键、相同内容返回已有任务；相同键、不同内容应拒绝。有效期和保存方式要写清楚，不能只在接口里做一次查询就宣称并发安全。

重启恢复也要先定策略。先核对真实执行状态：确认已停止但未完成时，记为中断或失败并保留证据；无法确认旧执行进程或容器是否仍在运行时，保留待核对或未知状态，阻止自动重试和重复启动。确认旧执行已停止，或已有足以避免重复副作用的幂等保障后，才允许受控重试。这些状态在恢复阶段按需要扩展，初版四种状态并未覆盖所有情况。不要在没有检查点和重复执行保护时，承诺“从断点自动恢复”。

这些场景不需要第一天全部实现，但到了对应阶段，就必须验证。不能把尚未实现的能力写成已支持。

还要区分“流水线成功”和“模型质量合格”。评估程序正常结束，分数仍可能很差。接入真实训练后，应固定评估数据和指标，避免把评估数据混入训练，并记录数据版本和参数。

ci 全绿，只说明配置进去的检查通过。对真实数据、长任务、并发竞争或权限边界没有覆盖，就仍然存在未验证项。

9 自审、独立审查、修复后再验

完成一个阶段后，先让实现者检查自己的改动：有没有超出范围、偷偷改接口、引入无关依赖，测试是否真正覆盖验收。

随后找另一个审查者，它可以是人，也可以是具备相应能力的独立 agent。给它需求、设计和差异，让它从失败场景检查代码。

请只读审查当前阶段改动，对照已确认的验收。
重点检查失败传播、状态转换和重复执行风险。
指出具体位置、触发条件、影响及缺失的验证。
不要因为测试已通过就假定需求正确，也不要直接修改代码。

审查发现问题后，由主代理修复，再运行受影响的测试；接口或公共状态改变时，还要检查调用方。不能修完代码却继续引用修复前的测试结果。

独立审查能增加发现问题的机会，但仍不是正确性的保证。交付时把结论写实：“小样本端到端已验证；长时间训练、并发和 gpu 环境未验证。”

10 什么时候停下来，以及怎样交付

并不是每个小选择都要人审批。命名、局部整理和符合既有约定的实现，可以让 codex 继续推进。

但涉及目标改变、不可兼容接口、数据删除、昂贵资源或恢复语义时，应先给出具体选项、影响和建议，让人作关键决定。缺少数据格式、凭据或运行条件时，也不要靠猜补齐。

一个阶段完成后，我希望收到的交付很简单：实现了什么，怎样启动，哪些检查实际通过，还有哪些限制和风险，下一阶段从哪里开始。

版本控制按可审阅的小阶段组织，避免把全部功能堆成一次巨大提交。提交、推送、发布是否执行，按当前用户授权和项目流程决定；已获得明确授权的动作，不必反复问。

推送后核对远端提交是否与本次提交一致。如果会触发 ci 或部署，交付约定需要这些结果时，应跟进到明确状态。提交成功、ci 成功、部署成功和用户验收通过，是不同证据，不能互相代替。

模型部署在这个案例里仍属于后续工作，必须另行讨论模型准入、回滚、监控和服务成本。训练结果可下载，不代表已经有了可靠的线上服务。

回到最初那句“帮我做一个 ai pipeline”，真正有用的推进方式是：先把目标说清楚，再做小闭环，随后每次补齐一种能力，用结果检验设计。

codex 可以帮我们写代码、补测试、查问题和推进实现。人需要把握的是软件要解决什么、哪些代价可以接受，以及凭什么相信它已经完成。把这些决定和验收落到具体任务里，复杂项目才会一步步变成可以使用、可以维护的软件。