复杂项目开发流程（基于 OpenAI《Harness Engineering》总结）

来源：OpenAI 官方文章《工程技术：在智能体优先的世界中利用 Codex》，发布日期 2026-02-11。本文在原文基础上做了面向复杂项目落地的流程化整理，适合作为团队内部的项目开发方法说明。

---

1. 文档目的

本文档用于说明：在复杂软件项目中，如何以“人负责目标、约束与反馈；智能体负责执行”的方式，建立一套高效、可扩展、可治理的开发流程。

这套方法尤其适合以下场景：

• 需求复杂、模块较多的大型项目
• 需要长期维护的工程系统
• 依赖自动化测试、CI/CD、可观测性和架构治理的产品
• 希望将 AI/智能体深度纳入研发流程的团队

---

2. 核心理念

复杂项目开发不再只是“人工写代码”，而是围绕以下三个核心展开：

1. 构建可执行环境：让智能体有足够清晰的上下文、工具和边界。
2. 建立反馈闭环：让每次修改都能被自动验证、审查和修复。
3. 把知识沉淀到仓库中：让代码仓库成为唯一可信的记录系统。

换句话说，复杂项目的关键不只是产出代码，而是持续设计一个“能让系统稳定产出正确代码”的工程框架。

---

3. 复杂项目开发总体流程

需求定义
  ↓
项目初始化
  ↓
知识体系搭建
  ↓
任务拆解与执行计划
  ↓
智能体编码与本地验证
  ↓
自动化测试与可观测性验证
  ↓
PR 审查与反馈修复
  ↓
合并与发布
  ↓
文档维护、质量巡检、技术债清理
  ↓
持续迭代

---

4. 第一阶段：需求定义与目标约束

复杂项目开始之前，首先要明确的不是实现细节，而是以下内容：

4.1 业务目标

• 这个项目要解决什么问题
• 面向哪些用户
• 哪些功能是第一优先级
• 哪些结果算“交付成功”

4.2 工程约束

• 技术栈范围
• 性能边界
• 安全要求
• 可靠性要求
• 可维护性要求

4.3 验收标准

要把模糊目标转化为可验证条件，例如：

• 启动时间不超过 800ms
• 核心用户路径耗时不超过 2 秒
• 所有新功能必须附带测试
• 所有改动必须通过 CI 和结构校验

原则：目标由人定义，完成路径交给系统执行。

---

5. 第二阶段：项目初始化

复杂项目建议从空仓库或最小模板开始，先定义工程骨架，而不是急于填充业务代码。

5.1 初始化内容

• 仓库目录结构
• 包管理配置
• 格式化与 lint 规则
• 测试框架
• CI/CD 配置
• 初始工程说明文件

5.2 初始化目标

项目初始化阶段要完成的，不是“做功能”，而是“建立秩序”。

一个好的起点应该让后续任何成员或智能体进入项目时，都能快速理解：

• 代码该放在哪里
• 依赖应如何流动
• 功能如何测试
• 文档更新到哪里
• 变更通过什么机制验证

---

6. 第三阶段：建立知识系统

在复杂项目中，最大的风险之一不是不会写代码，而是上下文丢失。

因此，项目必须把知识写进仓库，而不是散落在聊天记录、会议口头共识或个人记忆里。

6.1 基本原则

• 仓库是记录系统（System of Record）
• 文档必须结构化管理
• 知识入口要简洁，详细内容分层展开
• 文档要能被索引、校验和持续维护

6.2 推荐目录结构

AGENTS.md
ARCHITECTURE.md
/docs
  /design-docs
  /exec-plans
  /product-specs
  /references
  DESIGN.md
  FRONTEND.md
  PLANS.md
  PRODUCT_SENSE.md
  QUALITY_SCORE.md
  RELIABILITY.md
  SECURITY.md

6.3 文档分工建议

• AGENTS.md：作为导航页，只写最关键的入口和规则
• ARCHITECTURE.md：描述系统分层、依赖方向和模块边界
• design-docs/：记录设计理念与关键决策
• exec-plans/：记录复杂任务的执行计划、进展与决策日志
• product-specs/：记录产品需求与业务规则
• QUALITY_SCORE.md：跟踪质量差距和治理目标
• SECURITY.md / RELIABILITY.md：定义安全与可靠性约束

重点：不要把所有规则塞进一个超大的说明文件里。入口要短，内容要分层。

---

7. 第四阶段：任务拆解与执行计划

复杂任务不能直接一句话交给系统完成，必须拆成可以被逐步验证的小单元。

7.1 任务拆解方式

将大目标拆为：

• 设计任务
• 编码任务
• 测试任务
• 审查任务
• 发布任务
• 文档更新任务

7.2 计划分级

轻量变更

适用于：

• 小功能
• 局部修复
• 单模块优化

可直接使用简短任务说明。

复杂变更

适用于：

• 跨模块开发
• 架构调整
• 高风险优化
• 影响用户核心路径的修改

需要建立正式执行计划，至少包含：

# 执行计划

## 目标
## 范围
## 风险点
## 实施步骤
## 验证方式
## 回滚策略
## 决策记录

7.3 关键原则

计划本身也是项目资产，要进入版本控制，而不是临时散落在对话里。

---

8. 第五阶段：智能体执行开发

在 agent-first 的复杂项目中，工程师的角色更像“系统设计者”和“监督者”，而不是传统意义上的逐行编码者。

8.1 人负责什么

• 描述目标
• 指定边界
• 提供上下文
• 定义验收标准
• 审核关键结果

8.2 智能体负责什么

• 编写功能代码
• 生成测试
• 更新文档
• 运行工具链
• 打开 PR
• 响应审查意见
• 修复构建或测试失败

8.3 正确的协作方式

不要只给一句“把这个功能做出来”，而应该给：

• 业务背景
• 涉及模块
• 参考文档路径
• 不允许触碰的边界
• 需要满足的性能/质量要求
• 最终验收方式

---

9. 第六阶段：可读性与可观测性建设

复杂项目要想高效运行，必须让系统“看得见问题、看得懂行为、验证得了结果”。

9.1 可读性建设

项目要对智能体和新人都清晰：

• 目录结构稳定
• 命名清楚
• 模块边界明确
• 文档入口统一
• 代码风格一致

9.2 可观测性建设

项目要具备以下能力：

• 查看日志
• 查看指标
• 查看追踪
• 驱动 UI 路径
• 截图或录制行为
• 重现 bug
• 对比修复前后状态

9.3 实践目标

让一次任务形成完整闭环：

发现问题 → 重现问题 → 修改代码 → 运行验证 → 观察指标 → 确认修复

没有可观测性，复杂项目就只能依赖人工猜测；有了可观测性，系统才能自主验证。

---

10. 第七阶段：架构约束与质量治理

复杂项目不能仅靠“大家自觉”保持整洁，必须把关键约束固化为机器可执行规则。

10.1 为什么要强约束

随着项目规模扩大，最容易失控的是：

• 依赖乱穿透
• 模块职责混乱
• 临时写法扩散
• 质量标准不一致
• 技术债快速累积

10.2 建议治理方式

对以下内容进行自动化校验：

• 分层架构是否被破坏
• 依赖方向是否合法
• 命名是否符合规范
• 文件大小是否超限
• 日志是否结构化
• 类型/模式是否完整
• 平台可靠性约束是否满足

10.3 推荐分层示例

Types → Config → Repo → Service → Runtime → UI

对于跨领域能力，例如：

• 认证
• 遥测
• 连接器
• 功能开关

建议通过统一 Providers 或显式接口接入，避免任意横向耦合。

10.4 原则

• 强制边界，不微观管理实现
• 用规则维护一致性，用自由保留创造力

---

11. 第八阶段：PR、审查与合并

复杂项目中，Pull Request 不只是代码差异，也是反馈循环的载体。

11.1 推荐流程

1. 智能体完成改动
2. 本地运行测试与自检
3. 自动生成 PR
4. 触发 CI、lint、结构测试
5. 收集人工或智能体审查意见
6. 根据反馈自动修复
7. 再次验证
8. 满足条件后合并

11.2 合并策略建议

在高吞吐场景下：

• PR 周期应尽量短
• 小步提交优于大批量堆积
• 对偶发测试失败，优先重试与快速修复
• 不要让低价值阻塞长期占住主流程

11.3 关键判断

在高自动化环境中，等待的成本可能高于纠错的成本。因此流程设计重点应放在“快速发现并快速修复”，而不是无限度追求一次性完美。

---

12. 第九阶段：持续清理与技术债管理

复杂项目一旦进入持续开发阶段，熵一定会上升。

12.1 常见问题

• 相似逻辑重复出现
• 不一致命名增多
• 旧模式继续被复制
• 文档逐渐失真
• 临时方案变成长期方案

12.2 应对方式

要建立“持续垃圾回收”机制，而不是等系统变坏后集中返工。

推荐做法：

• 定期扫描坏味道
• 自动生成重构 PR
• 维护技术债清单
• 定期更新质量评分
• 让文档维护也进入自动化流程

12.3 治理原则

技术债像高利率贷款，小步、持续地偿还，远优于长期拖延后集中爆发。

---

13. 第十阶段：自主水平持续提升

系统成熟后，智能体可以逐步覆盖更多完整链路，例如：

• 校验当前代码状态
• 复现 bug
• 记录问题现象
• 编写修复代码
• 自动运行验证
• 生成演示结果
• 发起并更新 PR
• 处理反馈
• 修复构建问题
• 在满足规则后自动合并

但要注意：

自主能力不是“模型一强就自然出现”的，而是由仓库结构、工具链、文档系统、反馈机制和治理规则共同塑造出来的。

---

14. 适合团队直接落地的流程模板

以下是一份可直接复用的复杂项目开发模板：

# 复杂项目开发标准流程

## A. 立项
- 明确业务目标
- 明确验收标准
- 明确技术边界

## B. 初始化
- 创建仓库骨架
- 建立 CI / lint / test 机制
- 建立核心文档入口

## C. 知识沉淀
- 建立架构文档
- 建立产品规格文档
- 建立执行计划目录
- 建立质量与安全规范

## D. 任务执行
- 拆解任务
- 编写执行计划
- 智能体实现代码与测试
- 自动运行验证

## E. 审查合并
- 自动检查
- 人工/智能体审查
- 修复反馈
- 合并发布

## F. 迭代治理
- 更新文档
- 清理技术债
- 维护质量评分
- 持续优化架构与工具

---

15. 结论

复杂项目开发的本质，正在从“人工逐行实现”转向“设计一个可持续产出正确结果的工程系统”。

真正决定复杂项目成败的，不再只是编码能力，而是以下五项能力：

1. 目标定义能力：能否把模糊需求转成明确约束与验收标准
2. 知识组织能力：能否让所有关键上下文进入仓库并保持可导航
3. 架构治理能力：能否用结构化规则约束系统演化
4. 反馈闭环能力：能否让测试、审查、指标和修复形成自动循环
5. 持续维护能力：能否把技术债、文档老化和模式漂移控制在可承受范围内

如果这五个方面建立起来，那么复杂项目不仅能更快推进，也更有可能在规模增长后保持稳定、清晰和可维护。

---

16. 参考来源

• OpenAI, 《工程技术：在智能体优先的世界中利用 Codex》
• 原文链接：https://openai.com/zh-Hans-CN/index/harness-engineering/
• 发布时间：2026-02-11