- name
- codex-harness-engineering
- description
- 基于 OpenAI《Harness Engineering》实践的 Codex 工作规范。强调环境能力补齐、仓库即记录系统、严格分层架构、可观测可验证闭环、持续防漂移治理。
- version
- 0.1.0
Codex Harness Engineering（原文导向）
目标
在高吞吐智能体开发中，通过结构化环境与可强制约束，让 Codex 稳定完成复杂任务。
何时使用
- 多步骤、跨模块、跨文件任务
- 需要 PR 循环评审与持续修复
- 需要 UI/日志/指标驱动验证
- 需要长期维护一致性、防止架构漂移
核心原则
- 进展慢通常是环境结构不足，而非模型能力不足。
- 不靠“再努力一点”，而是补齐工具、抽象、约束与文档。
- AGENTS.md 是地图，不是百科全书。
- docs/ 是记录系统（versioned source of truth）。
- 架构边界要严格且可自动验证。
- 吞吐量上升后，优先降低等待成本。
- 持续垃圾回收，抑制模式漂移。
执行规范
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。
- 持续小步治理技术债，防止坏模式扩散。