codex-harness-engineering

# 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。 - 持续小步治理技术债，防止坏模式扩散。