Codex Harness Engineering

基于 OpenAI《Harness Engineering》实践的 Codex 工作规范。强调环境能力补齐、仓库即记录系统、严格分层架构、可观测可验证闭环、持续防漂移治理。

Codex Harness Engineering（原文导向）

目标

在高吞吐智能体开发中，通过结构化环境与可强制约束，让 Codex 稳定完成复杂任务。

何时使用

• 多步骤、跨模块、跨文件任务
• 需要 PR 循环评审与持续修复
• 需要 UI/日志/指标驱动验证
• 需要长期维护一致性、防止架构漂移

核心原则

1. 进展慢通常是环境结构不足，而非模型能力不足。
2. 不靠“再努力一点”，而是补齐工具、抽象、约束与文档。
3. AGENTS.md 是地图，不是百科全书。
4. docs/ 是记录系统（versioned source of truth）。
5. 架构边界要严格且可自动验证。
6. 吞吐量上升后，优先降低等待成本。
7. 持续垃圾回收，抑制模式漂移。

执行规范

A. 任务推进

• 将大目标拆成构建模块：设计、代码、评审、测试。
• 每次受阻先识别缺失项：工具/约束/文档。
• 将缺失项写回仓库，形成可复用能力。

B. PR 闭环

• 允许 Codex 发起 PR。
• 要求 Codex 本地自审改动。
• 可结合本地/云端智能体审查。
• 对人工与智能体反馈持续响应，直到通过。
• Codex 直接使用标准开发工具（如 gh、本地脚本、仓库技能）取上下文。

C. 可读性与可观测性

• 支持按 git worktree 启动实例。
• 提供 DevTools 能力（DOM 快照、截图、导航）。
• 暴露日志/指标/追踪（临时隔离，任务后清理）。
• 支持 LogQL/PromQL 查询，支撑性能/SLO 提示执行。

D. 文档与知识布局（强制）

• 保持短 AGENTS.md（目录/地图）。
• docs/ 作为结构化知识库，至少包括：
  • design-docs/
  • exec-plans/active/
  • exec-plans/completed/
  • exec-plans/tech-debt-tracker.md
  • generated/
  • product-specs/
  • references/
• 采用渐进式披露：入口精简，深层内容分层索引。
• 用 linter + CI 校验文档新鲜度、交叉链接、结构一致性。

E. 架构分层（强制）

业务域内依赖只允许：

Types -> Config -> Repo -> Service -> Runtime -> UI

横切关注点仅通过 Providers 进入。 通过自定义 linter + 结构测试强制执行。

F. 品味不变式（强制）

将团队偏好编码为机器规则（示例）：

• 结构化日志
• 命名约定
• 文件大小限制
• 平台可靠性规则 并在 lint 报错中给出可执行修复指引。

G. 吞吐量导向合并策略

• 减少阻塞式合并门，缩短 PR 生命周期。
• 偶发失败以快速纠错与重跑优先，避免长期等待。

H. 漂移治理

• 将黄金原则编码进仓库。
• 定期运行后台任务扫描偏差、更新质量评分、发起定向重构 PR。
• 持续小步治理技术债，防止坏模式扩散。