Codex Harness Engineering¶

核心思想¶

OpenAI 在 Codex 实践中提出/推广 Harness engineering 这个工程视角，其中描述了我们应该如何为 AI 编程 Agent，构建软件工程环境、管道和约束，让 AI 能够稳定可靠地扮演工程师角色。

可以总结为：

Harness 是为 agent 构造一个工程化工作环境，使 agent 能在明确上下文、明确边界、明确流程、明确验证标准和可观察反馈下执行开发任务。

它强调：

不是让 Codex 独立写代码，而是让 Codex 在正确的环境中“执行有意义的工程任务”。
基础不是模型能力，而是“模型 + 环境 + 反馈回路 + 规范结构”的整体系统。
人类工程师从“写代码”转向“设计环境、定义意图、管理反馈循环”。

简单来说：

Agent(模型) + Harness(管道/环境/反馈机制/工具接入) = 可预测的自动化软件工程

核心思想：

人类工程师负责设计环境、定义意图、建立反馈回路；Codex 在这个环境里执行、验证、修复、提交。

方法实践¶

Harness 方法论适合边界清楚的项目，大项目更需要 Harness，但应该从边界清楚的任务切片和反馈闭环开始。

在 Harness 的实践中，至少应该包含以下内容：

上下文：AGENTS.md / docs / ARCHITECTURE.md / task 文件
流程：WORKFLOW.md / runbook / skill
验证：tests / evals / lint / typecheck / CI
反馈：logs / traces / artifacts / PR review
权限：sandbox / approval / branch protection
复盘：task result / tech-debt / failure retrospective

在服务仓库中，建立以下的示例目录结构：

repo/
├── AGENTS.md                 # Codex 指南
├── ARCHITECTURE.md           # 系统架构说明
├── WORKFLOW.md               # 开发、测试、PR 流程
├── Makefile                  # 一键 setup / verify
├── docs/
│   ├── index.md              # 文档索引
│   ├── product.md            # 产品行为说明
│   ├── architecture/
│   │   ├── boundaries.md     # 模块边界
│   │   └── dependency-rules.md # 依赖规则
│   ├── development/
│   │   ├── commands.md       # 命令
│   │   ├── testing.md        # 测试策略
│   │   └── debugging.md      # 调试流程
│   ├── quality/
│   │   ├── code-review.md    # 审查规则
│   │   ├── security.md       # 安全规范
│   │   └── tech-debt.md      # 技术债跟踪
│   └── runbooks/
│       ├── bugfix.md
│       ├── feature.md
│       └── refactor.md
├── tasks/
│   ├── active/
│   ├── completed/
│   └── template.task.yaml    # 任务模板
├── evals/
│   ├── README.md
│   ├── cases/
│   └── scripts/
├── scripts/
│   ├── check_arch.py         # 架构边界检查
│   ├── collect_logs.py       # 收集日志
│   └── smoke_test.py         # 基本验证
├── .codex/
│   └── config.toml           # Codex 配置
├── .agents/
│   └── skills/
│       ├── bugfix-loop/
│       │   └── SKILL.md     # Bugfix 循环 Skill
│       └── pr-review/
│           └── SKILL.md
└── .github/
    └── workflows/
        └── ci.yml            # CI 流程

其中 .codex、.agents、.github 按需添加。

AGENTS.md¶

Codex 会在工作开始前读取 AGENTS.md，并且可以有全局级、仓库级、子目录集指令，靠近当前目录的指令会覆盖上层指令。

它是指导文件，用来写长期稳定的 agent 工作规则，包括：

项目结构
重要目录
启动、测试、lint、验证命令
工程约定
PR 要求
不允许做的事情
任务完成标准
应该阅读哪些入口文档

ARCHITECTURE.md¶

ARCHITECTURE.md 记录当前服务的架构说明，是项目的架构事实源。

它至少应该包含：

系统整体说明
模块分层
依赖方向
禁止依赖
数据流
关键设计取舍
外部系统边界
哪些地方允许扩展
哪些地方不能随便修改

WORKFLOW.md¶

WORKFLOW.md 是当前项目的开发流程契约，应该描述的是：

Codex 和人类在这个仓库中完成任务的标准流程

它至少应该包含：

错误修复
功能实现
重构
测试
验收
PR
review
失败处理

docs 文件夹¶

在 Harness 方法论中，应该把 docs/ 当成是项目知识库，对于不适合塞进 AGENTS.md，但 Codex 和开发者又需要长期参考的信息，都应该放在此处。

包括：

docs/product/
    产品行为、业务规则、用户场景

docs/architecture/
    模块边界、依赖规则、设计原则、架构决策

docs/contracts/
    API 契约、数据库契约、消息队列契约、外部服务契约

docs/development/
    安装、启动、测试、调试、常见问题

docs/testing/
    单元测试、集成测试、回归测试、eval 策略

docs/quality/
    code review 标准、安全规范、可靠性要求、技术债

docs/runbooks/
    常见故障处理、发布流程、回滚流程

docs/decisions/
    ADR，记录关键架构决策

tasks 文件夹¶

这里通过 template.task.yaml 模版来发起任务，把一次具体任务结构化，定义问题、范围、验收标准、证据和结果，具体可参考下面的模版：

id: TASK-0000
标题: "简短任务标题"
状态: active
负责人: codex
创建日期: "2026-06-03"

上下文:
  问题描述: |
    描述具体问题
  用户影响: |
    谁受影响，如何受影响
  相关文档:
    - AGENTS.md
    - ARCHITECTURE.md
    - docs/development/testing.md
  相关文件:
    - src/...
    - tests/...

范围:
  允许修改:
    - src/...
    - tests/...
    - docs/...
  禁止修改:
    - pyproject.toml
    - 数据库迁移文件
    - 公共 API schema

验收标准:
  - bug 可以通过回归测试复现
  - 修复通过 make verify
  - 公共 API 行为无意外变更

执行命令:
  安装: "make setup"
  narrow_test: "pytest tests/path/to/test_file.py -q"
  验证: "make verify"

证据:
  bug_report: |
    填写日志、错误堆栈或用户报告
  期望行为: |
    描述期望行为
  实际行为: |
    描述实际行为

结果:
  总结: ""
  执行命令: []
  风险: []
  后续任务: []

scripts 文件夹和 Makefile¶

这两个部分相互配合，把“应该怎么验证”变成可执行的命令，而不是自然语言建议。

tests / evals 文件夹¶

测试与验证文件夹则包含具体的脚本，协助 scripts/ 和 Makefile 将操作命令化。