harness-books：把 Claude Code 和 Codex 当作系统来读的两本书
📚 Two books on harness engineering — the design philosophies behind Claude Code & Codex: constraints, query loops, context governance, multi-agent verification. harness-books.agentway.dev
秒懂
- 它是什么？
- harness-books 是一套以 Claude Code 和 Codex 为观察对象的开源书籍，讨论约束结构、查询循环、上下文治理与多智能体验证。它不逐行读源码，而是追问代码写入真实工程环境后，系统如何保持有界、连续和对后果负责。
- 适合谁用？
- harness-books 适合两类人：一类是已经在团队里使用 Claude Code 或 Codex，想把个人经验沉淀成可复用规则的工程师，另一类是想自建 harness 但不知从哪一层入手的架构师。不适合那些只想要 API 对比表或功能清单的读者，这本书刻意回避了 feature checklist。
- 能商用吗？
- 未经许可不能。GitHub 在这个仓库里没有找到许可证文件；没有许可证，默认即「保留所有权利」：你可以阅读代码，但不能复用。使用前请看看 README，或先征得作者同意。
- 还在维护吗？
- 在维护。仓库最近一次提交在 150 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
这本书解决什么问题，写给谁
harness-books 处理的是一个问题：当代码编写模型被放进终端、仓库、权限系统和团队工作流之后，什么机制能让整个系统保持有界、连续，并且对后果负责。项目描述里有一句关键判断：真正的危险不是模型偶尔说错，而是系统没有处理后果的结构。这句话决定了书的立场。它不把模型当作孤立的大脑，而是当作一个运行在工程环境里的组件。目标读者不是提示词调优者，而是那些需要决定如何让智能体在团队里稳定工作的工程师、技术负责人，以及打算自己搭建 harness 的人。如果你关心的是模型回答质量，这本书会告诉你，模型进入真实环境后，主要问题不再是答案质量，而是行为后果。
核心主张：约束结构决定执行
项目 README 列出了几条核心主张，其中一条是：提示词、工具、权限、状态、恢复、验证和制度，不是系统周围的配件，而是同一个控制结构里的器官。这个比喻贯穿两本书。它拒绝把 prompt engineering 当作 harness engineering 的放大版，认为提示词本质上是控制平面的一部分，而不是聊天框里的文本。另一个主张是：比较智能体系统时，关键问题不是功能清单，而是秩序到底放在哪里。这意味着作者认为 Claude Code 和 Codex 都能工作，但它们的权威分配方式不同。这个视角对工程决策有实际影响，因为选择工具不只是选模型，而是选一种控制结构。
两本书的分工：运行时结构 vs 架构比较
Book 1 以 Claude Code 为观察对象，专注运行时结构。它解释为什么一个系统最终必须长出控制平面、查询循环、工具权限、上下文治理、恢复路径、多智能体验证和团队规则。章节目录显示，从第 2 章开始讲提示词作为控制平面，第 3 章讲查询循环作为智能体系统的心跳，第 4 章讲工具、权限和中断，为什么智能体不能直接接触世界，第 5 章讲上下文治理，把 memory、CLAUDE.md 和 compact 视为预算机制，第 6 章讲错误与恢复，第 7 章讲多智能体分工与验证，第 8 章讲团队采纳。Book 2 则把 Claude Code 和 Codex 并排比较，问每个 harness 把秩序放在哪里。一条路径从运行时纪律出发，另一条从更结构化的控制层出发。这个对比对系统选型和架构判断更有用。
阅读路径与获取方式
项目以网页形式提供在线阅读，两个版本都有 PDF 下载链接。README 给出了三条建议路径：想要完整框架就先读 Book 1 再读 Book 2；已经熟悉编码智能体工具，想直接看架构差异，就从 Book 2 开始；只想要结论，就读 Book 1 第 9 章加上 Book 2 第 7 章。仓库里没有提到安装步骤，因为它不是软件，而是一套文档。README 显示项目使用 Python 作为主要语言，但这更可能指构建书籍站点的工具链，而不是书籍内容本身。没有 releases 信息，也没有明确的许可证，这一点在采用前需要确认。
一个真正的局限：不是教程，也不是源码分析
README 明确说，这些书不打算逐行讲解源码。它们关注 harness 如何组织约束和执行，以及如何将不稳定的模型纳入可持续的工程秩序。这意味着如果你期望从中找到具体的 Claude Code 配置技巧或 Codex 的 API 用法，会失望。书中引用了源码文件（附录 C 是源码地图），但它不做源码级教学。另一个潜在局限是，书籍以特定工具为观察对象，而 Claude Code 和 Codex 都在快速迭代。2026 年 4 月的仓库推送说明内容在更新，但工具行为可能已经变化。书中对控制平面分歧的判断，比如 Book 2 说的最大分歧点，可能基于特定版本的行为。读者需要把书当作设计哲学参考，而不是当前功能的权威说明。
与替代方案的差异：不是又一个提示词指南
市面上大量关于 AI 编码工具的书籍和文章聚焦于如何写更好的提示词，或者如何列出工具的功能清单。harness-books 的差异在于它把提示词、权限、状态、恢复、验证和团队制度看作一个整体控制结构。它比较 Claude Code 和 Codex 时，不看谁的功能多，而是看秩序放在哪里。这与典型的工具对比文章有本质区别，后者通常列出特性表格，然后给出谁更好的结论。harness-books 认为两种系统都能工作，但权威分配不同，这对自建 harness 的人更有指导意义。如果你只想快速决定用哪个工具，Book 2 可能有用，但它的目标不是替你选工具，而是教你如何判断工具的架构。
维护与升级成本，许可证需要核实
仓库最后推送时间是 2026 年 4 月 19 日，没有被归档，说明项目还在维护。但没有任何 release 记录，这意味着没有稳定的版本号来跟踪变更。README 提供了在线阅读和 PDF 下载，内容更新时读者需要重新访问网站或拉取仓库。许可证字段显示 unknown，这是一个实际风险。如果你打算在团队内部分发或修改这些书籍，需要先向作者确认许可条款。仓库没有提供贡献指南或 issue 模板，所以参与维护的路径不明确。对于只想阅读的工程师，维护成本几乎为零，因为内容以静态网页和 PDF 形式存在。对于想基于这本书建立内部培训材料的团队，许可证问题必须先解决。
编辑结论
harness-books 适合两类人：一类是已经在团队里使用 Claude Code 或 Codex，想把个人经验沉淀成可复用规则的工程师，另一类是想自建 harness 但不知从哪一层入手的架构师。不适合那些只想要 API 对比表或功能清单的读者，这本书刻意回避了 feature checklist。也不适合期望源码级教程的人，它明确说不逐行讲解源码。在采用前，建议先读 Book 1 第 9 章和 Book 2 第 7 章，这两章浓缩了全书结论，能让你快速判断其论证方式是否对你有用。如果你最终决定深入，请对照附录 C 的源码地图去核实每一章的依据，因为书中的判断建立在特定版本的 Claude Code 和 Codex 行为之上，而这些工具迭代很快。
社区笔记