【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载在 OpenAI 的四个主流 Agent 产品中Codex 是最彻底贯彻 harness 工程原理的一个——它把「仓库即系统记录repository as the system of record」推到极致AGENTS.md 只做索引页环境用 git worktree 物理隔离反馈回路全部写进仓库约定。本文结合开源仓库 learn-harness-engineering 中的课程框架五子系统模型与真实工程示例逐层拆解 Codex 的指令、上下文、工具、环境与反馈五个子系统并给出可直接迁移到你项目中的五条设计要点。一句话定位当工程师从「写代码」变为「设计 harness」Codex 的设计哲学可以浓缩为一句话仓库是系统记录source of truthAGENTS.md 只是一页索引工程价值在于环境设计、意图表达与反馈回路构建。据原文档引述的 OpenAI「Harness Engineering」一文OpenAI 团队在短短几周内用 Codex 交付了一个最终超过一百万行代码的产品且全部由 Codex 编写。这个实验回答了一个根本问题当工程师的角色从「亲自写代码」转向「设计 harness」时系统该如何组织Codex CLI 本身是一个用 Rust 编写的开源单体二进制github.com/openai/codex 为原文档引用的外部仓库但它对 harness 领域的主要贡献并不在精巧的扩展点上而在conventions约定与context engineering上下文工程。这一点与本仓库的课程主线完全呼应本仓库的 Leçon 02 · Ce que signifie réellement harness 明确指出「如果它不是模型权重它就是 harness」并建立了「指令 / 工具 / 环境 / 状态 / 反馈」五子系统框架——Codex 正是这一框架最忠实的实践样本之一。指令子系统AGENTS.md 是索引页不是百科全书这是 Codex 对 harness 理论最具影响力的贡献。原文档直接转述了「Harness Engineering」一文的核心段落一个巨型单一指令文件难以进行机械化的控制——覆盖度、新鲜度、归属权与交叉链接——最终必然与现实脱节。因此我们不再把 AGENTS.md 当作百科全书而是当作索引页page dindex。代码库的知识存放在结构化的文档中由 AGENTS.md 指向它们。这一理念与本仓库 Leçon 04 · Répartir les instructions entre fichiers 的主题严丝合缝巨型指令文件会因「lost in the middle」效应、优先级模糊Priority Ambiguity、指令膨胀Instruction Bloat而失效。Codex 给出的直接答案是将 AGENTS.md 控制在约 100 行以内——原文建议接近该上限时就把内容迁往docs/其余内容拆分到docs/目录按需读取progressive disclosure这就是「给地图不给手册donner la carte, pas le manuel」原则的权威出处。与之配套的第二个原则是强制执行不变式invariants而不微管理实现dont micromanage the implementation。AGENTS.md 只应包含不可违反的硬约束与验证命令具体如何实现交给模型自行决策。这正是 Leçon 02 中「约束而不微管理contraindre sans micromanager」的课程概念的工程化落地。仓库内的真实范例本仓库的实践项目恰好示范了这种「索引页 主题文档」的结构。以 projects/project-01/solution/AGENTS.md 为例## Startup Rules 1. Read this file completely. It defines the boundaries and conventions for this project. 2. Read docs/ARCHITECTURE.md to understand the Electron layer structure. 3. Read docs/PRODUCT.md to understand the feature requirements. 4. Run bash init.sh to verify the project builds cleanly. ... 5. Read feature_list.json to see the current state of all features.该文件只保留启动顺序、四层架构边界main / preload / renderer / services、约定TypeScript strict、named exports与「Definition of Done」而架构细节、产品需求分别存放在docs/ARCHITECTURE.md、docs/PRODUCT.md中按需加载——正是「索引页 docs/ 拆分」的直观例证。上下文子系统Write-Select-Compress-Isolate 四策略Codex 的上下文工程可概括为四条策略该框架由社区在「context engineering」成为独立学科后归纳并应用到 Codex原文档引用自 Daniel Vaughan 的 Context Engineering for Codex CLI 系列文章Write写到外部把上下文持久化到窗口之外——结论写进文档、状态写进文件而不是留在对话里。这是「仓库即系统记录」原则的直接体现。Select挑选进入的只把必要的 token 载入窗口——AGENTS.md 只给出路径文件按需读取而不是把整个仓库一次性注入。Compress压缩只保留真正重要的内容。Codex 提供自动压缩compaction与手动命令/compact并允许通过compact_prompt自定义压缩提示词。Isolate隔离把上下文按不同边界切分。subagent 隔离任务上下文例如一个前端 subagent 永远看不到后端数据库 schema。此外Codex 有一个非常细腻的环境上下文设计细节。根据原文档引述的社区源码分析 codex-harness-internalsbuild_environment_update_item在环境变化时只产出发生变化的字段——CWD、git 分支、文件系统差异——而不是每一轮都重新拼装整套系统上下文。这是「从上下文中剔除重复 token」的典型实现与 Select / Compress 策略互为表里。工具与环境git worktree 物理隔离 内核级 subagentCodex 依赖两个 harness 层面的基础机制1. 用 git worktree 实现环境隔离「Harness Engineering」一文的 Environment 部分指出每个任务都运行在独立的 git worktree中并配有一整套本地可观测性栈——日志、指标、追踪——从而在隔离环境中验证每一次变更。这是 Leçon 07 · Définir des limites de tâche claires 中「清晰界定 Agent 的每个任务」原则的物理实现任务边界不是靠指令「请求」出来的而是由环境隔离强制出来的。此时环境子系统从「配置管理」升级为「严格隔离」。2. 内核级 subagentspawn_agent与wait_agent是 Codex 的原生工具模型显式创建 subagent为它分配独立的会话历史与工具集然后等待其结果。subagent 继承父级 AGENTS.md 指令但工作在自己的独立上下文中其配置位于.codex/agents/*.toml可指定不同的模型与指令。这正是「上下文隔离」与 Leçon 12 · Laisser un handoff propre à la fin de chaque session 中 handoff 思想的直接实现——每个 subagent 都是一个边界清晰的工作单元不会污染主循环。仓库内的对应实践单功能并发策略本仓库 projects/project-03/solution/AGENTS.md 的「One-Feature-at-a-Time Policy」正是任务边界控制的工程化模板1. Pick exactly one feature from feature_list.json with status not-started. 2. Implement only that feature. Do not touch code unrelated to the chosen feature. 3. Verify the feature works by running npm run check ... 4. Update feature_list.json -- set status to pass and add evidence. 5. Commit the change with a message referencing the feature ID. 6. Only then move to the next feature.并通过feature_list.json见 projects/project-03/solution/feature_list.json以机器可读格式记录每个功能的状态与验证证据——这是「外部化 scope surface」的落地形态与 Codex 把边界写进运行时机制的理念同源。反馈子系统把验证命令写进约定让验证路径成为 harness 默认组件OpenAI 的实践首要强调把验证命令显式写进 AGENTS.md让「如何确认工作是正确的」成为仓库的一部分。在 Codex 的工程流程中测试、CI、文档与可观测性配置全部由 Codex 生成它们共同构成「可执行的验证路径」。面对强大但不可靠的模型答案不是指望它自我约束而是把验证路径做成 harness 的默认组件。审批策略approval policies与 plan mode 提供另一种反馈先产出计划、在执行高风险操作前请求人类批准从而把「任务边界」与「人类决策权」固化进运行时控制。这与 Leçon 07 的「完成证明Completion Evidence必须是可执行的」论断一致——「curl 返回 201」才算完成而不是「代码看起来没问题」。与课程五子系统框架的对照子系统Codex 中的实现评价指令AGENTS.md 作为索引页 拆分到 docs/ 运行时不变式标杆在此定义了「给地图而非手册」原则工具worktree 隔离 subagentspawn_agent以强环境隔离强制边界环境独立 worktree 可观测性栈worktree 隔离是其标志性特征状态Write 策略状态写入文件或文档依赖约定而非内置记忆反馈验证命令内嵌约定 approval policies plan mode反馈路径默认提供值得借鉴的模型这张表可以直接对照 Leçon 02 的五子系统框架逐项阅读。减法哲学Codex 与 Claude Code 的路线对照将 Codex 与 Claude Code 对比极具启发性Claude Code 走「加法」路线把记忆、权限、subagent 集成进内核构建完整的 Agent 运行时Codex 走「减法」路线保持内核尽可能精简把更多责任移交给仓库约定与上下文工程。这正是社区常说「Codex 的 harness 哲学比它的代码更有价值」的原因。五条可直接借鉴的设计把 AGENTS.md 当作索引页控制在约 100 行内指向 docs/ 中的细节使覆盖度、新鲜度等可以机械化检查。只声明不变式不微管理实现只写硬约束与验证命令其余交给模型。用 worktree 隔离环境用环境强制任务边界而不是在指令里请求边界。只传输环境上下文的变化每一轮只输出变化的字段CWD、分支、文件系统差异不重复整套系统上下文。用 subagent 隔离上下文同时隔离任务与上下文让子任务不污染主循环。参考来源说明原文档中每一项论断都锚定于以下来源均为原文档引用此处保留出处描述不附外链OpenAI「Harness Engineering」AGENTS.md 索引页与约 100 行建议、执行不变式 / 不微管理、worktree 隔离 可观测性栈、验证命令内嵌约定、百万行产品案例、approval policies 与 plan mode——本文核心论断的主来源。OpenAI「AGENTS.md」官方规范AGENTS.md 作为跨工具标准约定。Codex CLI 开源仓库Rust 写的单体二进制。Context Engineering for Codex CLI社区Write-Select-Compress-Isolate 框架、/compact与compact_prompt、spawn_agent/wait_agent与.codex/agents/*.toml配置。codex-harness-internals社区源码分析build_environment_update_item增量环境上下文等实现细节。关联课程本仓库内可继续深入Leçon 03 · 让仓库成为唯一事实来源 Leçon 04 · 拆分指令文件 Leçon 07 · 清晰界定任务边界 Leçon 12 · 会话结束时留下干净状态。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Learn Harness Engineering 的 Design-Docs 索引与设计文档治理让 Agent 以仓库为系统记录源Learn Harness Engineering 的 Design Docs 索引与设计文档治理让 Agent 以仓库为系统记录源 本篇文章围绕 learn解析 Codex 的 Harness 设计仓库即系统记录、AGENTS.md 目录页与反馈回路工程解析 Codex 的 Harness 设计仓库即系统记录、AGENTS.md 目录页与反馈回路工程 在 Learn Harness Engineering 课Learn Harness Engineering 前沿 Harness 设计拆解以五子系统框架透视 Pi、Claude Code、Codex 与 DeepSeek HarnessLearn Harness Engineering 前沿 Harness 设计拆解以五子系统框架透视 Pi、Claude Code、Codex 与 DeepS上一篇Unstract 前端工程指南Vite 7 Bun Biome 构建体系、VITE_ 环境变量与 Docker 热更新实践下一篇GTCRN 开源项目使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考