Codex Harness Engineering

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

Security Scan

This is a coherent, instruction-only engineering guideline for running Codex-enabled development workflows; it contains no code or hidden installs, but it prescribes actions that assume repository, CI, and monitoring access which the skill does not explicitly declare.

Purpose & Capability

The name/description match the SKILL.md: it's a set of operational rules for integrating Codex into a development lifecycle (PR loops, linters, doc layout, observability). The instructions' capabilities (creating PRs, using gh/locals scripts, querying metrics) are consistent with that purpose.

Instruction Scope

The document tells agents to initiate PRs, self-review changes, use repo tools (gh), start instances with git worktree, expose logs/metrics temporarily, and run background drift-scanning tasks. These instructions are broad and can result in writing to repositories, invoking CI, or querying monitoring systems — all coherent with the stated goals but granting significant operational scope to any agent that actually has those permissions.

Install Mechanism

No install spec or code files are present; this is instruction-only, so no artifacts are downloaded or written by the skill itself.

Credentials

The SKILL.md implicitly relies on tooling and credentials (git/GitHub push/PR rights, CI access, monitoring/log access for PromQL/LogQL) but the registry metadata declares no required env vars or credentials. The implicit requirement for repository and monitoring access is not surfaced in the skill manifest, which could mislead users about what permissions an agent will need to realize these practices.

Persistence & Privilege

The skill does not request always-on presence, but it recommends periodic/background tasks (drift scanning, scheduled PRs). If an agent is permitted to act autonomously and has the stated permissions, this guidance supports ongoing autonomous actions. That behavior is consistent with the document's goals but increases operational risk when combined with broad agent permissions.

Assessment

This file is a policy/operational playbook, not an executable package — it won't install code or ask for credentials itself. However, it instructs an agent to perform actions that require real permissions (create PRs, push to repos, query logs/metrics, run background scans). Before using these guidelines with an agent, validate and restrict the agent's actual permissions: limit repository write/merge rights, provide least-privilege monitoring read access if needed, and prefer human review gates for destructive or wide-reaching automated PRs. Also be aware the manifest does not declare any credentials — you should explicitly provision and audit any tokens the agent will use.

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