# Codex Harness Engineering 最佳实践包

**日期**: 2026-04-16  
**适用环境**: Windows + PowerShell + Codex CLI + Git 仓库  
**目标**: 把 Codex 从一次性对话工具升级为可复用、可审计、可验证的自动化工程执行系统。

## 0. 从哪里开始

如果这是你第一次进入这个目录，先读 `START-HERE.md`，再读 `mode-matrix.md` 理解当前的安装分层，以及默认的 `project/thin + driver-first` 主链路。

## 1. 当前范围

这套文档和模板当前只保留单工作区、单 driver 的执行模型：

```text
task.json
  -> tools/harness/codex-loop.ps1
  -> codex exec
  -> lint/build/test/eval
  -> progress.txt + trace.json
  -> task.json passes=true
  -> git commit
```

额外 Git 执行工作区、外部 worker 编排、控制面状态机和相关模板已经从当前包中移除。

## 2. 主要内容

| 文件 | 用途 |
| --- | --- |
| `README.md` | 当前目录总览 |
| `START-HERE.md` | 首次进入目录时的分流入口 |
| `mode-matrix.md` | `user/project/vendor/full` 的职责边界、状态源、持续运行定位和验证入口 |
| `best-practices.md` | 任务、上下文、权限、测试、阻塞、提交、回归沉淀的最佳实践 |
| `implementation-flow.md` | 从当前能力包仓库结构出发说明安装、bootstrap、driver、验证、知识归档和同步的整体实现流程 |
| `goal-harness-integration-guide.md` | 说明如何把 Codex `/goal` 与 Harness driver/stop hook 结合使用，包含推荐用法和提示词模板 |
| `harness-analysis-and-practice.md` | GitHub 调研后的 Harness 工程分析、当前 `agent/` 目录评估和改进路线图 |
| `harness-quality-model.md` | 定义好的、好用的、完整的 Harness 工程质量模型、成熟度和评分标准 |
| `harness-improvement-plan.md` | 基于质量模型和源码审计的 Harness 改进计划，说明每项改哪里、怎么改、如何验收 |
| `implementation-guide.md` | 在当前 Windows + Codex CLI 工程中落地的步骤 |
| `global-rules-and-bootstrap.md` | 全局规则写法、新项目接入和新环境初始化教程 |
| `codex-global-rules-example.md` | `~/.codex/AGENTS.md` 和 `~/.codex/config.toml` 的推荐配置示例与分层边界 |
| `codex-host-runtime-and-autoload.md` | 深入解释哪些配置由 Codex 宿主自动加载，哪些由 Harness runtime 二次读取，哪些只是本地约定 |
| `knowledge-surface-map.md` | 把 AGENTS、`.codex/*`、`docs/ai/*`、`docs/harness/*`、`docs/knowledge/*`、MCP 和个人知识库边界一次讲清 |
| `doc-update-map.md` | 文档、prompt、rules、skills、模板和 package-assets 的 canonical source 与镜像同步表 |
| `../agent-package-redesign/cli-distribution-design.md` | 云端安装 CLI 的分发方案、命令接口、缓存布局和 release 设计 |
| `agent-ecosystem-practices.md` | 分析大型项目 AI 编程生态实践，说明哪些内容应吸收到当前能力包、模板、skills、hooks 和 MCP 配置 |
| `spec-to-ui-to-code-workflow.md` | 从需求、设计、前端、契约到回归的前端先行闭环 |
| `templates/docs/frontend-quality-rules.md` | 前端审美、动效、响应式、可访问性、性能和证据要求 |
| `templates/docs/service-dependency-matrix.md` | 多服务、多仓库、契约和外部系统影响面的可选 truth source 维护口径 |
| `templates/design/frontend-architecture.md` | 前端页面、feature、组件、状态、API、响应式和测试边界模板 |
| `practices/` | 跨项目可复用的工程实践、配置治理、上线准备和证据边界经验 |
| `examples/goal-templates.md` | `/goal` 启动模板库，强调它是外层控制壳而不是替代 `task.json` / spec 的目标定义 |
| `templates/` | 可复制模板集中目录 |
| `templates/docs/project-agents-template.md` | 根据不同项目事实生成项目根 `AGENTS.md` / 子目录 `AGENTS.md` / `CLAUDE.md` 组合的通用模板 |

## 3. 快速使用方式

1. 先读 `START-HERE.md`。
2. 再读 `global-rules-and-bootstrap.md` 和 `codex-global-rules-example.md`。
3. 读 `codex-host-runtime-and-autoload.md`，并对照 `../../harness-analysis/11-codex-autoload-governance-playbook.md` 确认自动加载面和治理 gate。
4. 读 `knowledge-surface-map.md`，确认知识分层、导航层和外部知识边界。
5. 读 `mode-matrix.md`，确认当前项目默认使用 `project/thin` 安装入口和 `driver-first` 执行链。
6. 运行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-user.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\init-project.ps1
```

7. 如果这是一个刚初始化的全新仓库，先提交一次 bootstrap 基线，避免 driver 因未解释改动直接阻塞。
8. 如果需要把根 `AGENTS.md` 调整为项目专属规则，按 `templates/docs/project-agents-template.md` 扫描项目事实后裁剪生成，不要原样套模板。
9. 先补齐 `docs/ai/repo-map.md`、`docs/ai/architecture-brief.md`、`docs/ai/CURRENT_TASK.md`；复杂项目再补 `PROJECT_CONTEXT.md`、`DECISIONS.md`、`API_MAP.md`、`DB_SCHEMA.md`、`KNOWN_ISSUES.md`。
10. 首次接入时，建议先用 `tools/harness/templates/smoke-task.json` 验证主链路；一旦 spec / plan 确认，就改用 `tools/harness/templates/project-task-template.json` 生成正式 `task.json` 并切回 driver。
11. 正式任务队列落盘前，先补齐 `docs/testing/ACCEPTANCE_CRITERIA.md`、`docs/testing/ACCEPTANCE_EXAMPLES.md`、`docs/testing/TRACEABILITY_MATRIX.md`、`docs/testing/TEST_DATA_MATRIX.md`、`docs/testing/verify-matrix.md` 等测试左移真相源。
12. 如果需要查外部文档、代码语义或本地知识库，先读 `docs/harness/mcp-knowledge-governance.md` 和 `docs/harness/code-semantics-and-navigation.md`。
13. 运行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1
```

### 3.1 内容门禁怎么用

默认安装后的项目使用三档内容门禁：

- `core`：默认档位，只阻塞最小闭环门禁：`spec / context / session / architecture / testing / impact`
- `recommended`：在 `core` 基础上，再启用目录、命名、组件复用、业务规则、状态、UI、性能、文档和验收门禁
- `full`：启用全部默认门禁；只建议对治理要求很高的项目使用

高风险专项门禁通过任务级 `risk_tags` 启用，例如：

- `security`
- `backend`
- `data`
- `integration`
- `mobile`
- `config`
- `observability`
- `refactor`

最常见的 3 种用法：

1. 保持默认轻量：

```json
{
  "runtime": {
    "content_gates": {
      "default_mode": "core"
    }
  }
}
```

2. 整个项目默认更严格：

```json
{
  "runtime": {
    "content_gates": {
      "default_mode": "recommended"
    }
  }
}
```

3. 只给单个高风险任务加专项门禁：

```json
{
  "id": "API-001",
  "task_kind": "feature_impl",
  "risk_tags": ["security", "integration"],
  "content_gate_mode": "core"
}
```

## 4. 推荐项目结构

```text
<project-root>/
  AGENTS.md
  task.json
  progress.txt
  tools/harness/codex-loop.ps1
  .codex/
    task-run-profile.json
  .service-matrix/
    dependencies.yaml
  docs/
    ai/
      repo-map.md
      architecture-brief.md
      CURRENT_TASK.md
      PROJECT_CONTEXT.md
      DECISIONS.md
      API_MAP.md
      DB_SCHEMA.md
      KNOWN_ISSUES.md
      CHANGELOG_AI.md
    harness/
      architecture.md
      code-semantics-and-navigation.md
      frontend-quality-rules.md
      mcp-knowledge-governance.md
      service-dependency-matrix.md
      new-project-usage.md
      regression-rules.md
      sandbox-policy.md
      task-session-strategy.md
      trace-format.md
    testing/
      ACCEPTANCE_CRITERIA.md
      ACCEPTANCE_EXAMPLES.md
      TEST_STRATEGY.md
      TRACEABILITY_MATRIX.md
      RISK_BASED_TEST_PLAN.md
      REGRESSION_PLAN.md
      EVIDENCE_PROTOCOL.md
      TEST_DATA_MATRIX.md
      test-matrix.md
      verify-matrix.md
  traces/
    <task-id>-<timestamp>.json
```

## 5. 参考资料

- OpenAI Codex CLI: https://developers.openai.com/codex/cli
- OpenAI Codex non-interactive mode: https://developers.openai.com/codex/noninteractive
- OpenAI Codex AGENTS.md: https://developers.openai.com/codex/guides/agents-md
- OpenAI Codex MCP: https://developers.openai.com/codex/mcp
- OpenAI Codex hooks: https://developers.openai.com/codex/hooks
- OpenAI Codex GitHub Action: https://developers.openai.com/codex/github-action
- OpenAI Harness Engineering: https://openai.com/index/harness-engineering/
