想搞懂 Claude Code 底层怎么设计的，若直接看源码无从入手，而博客又讲得太零散。

最近在 GitHub 上发现 harness-books 用两本书把架构拆解讲清楚了，结构比我预想的清晰。

第一本聚焦运行时结构，权限怎么管、上下文怎么治理、出错了怎么恢复，逐章拆开讲。

重点不是研究代码怎么写，而是让我们了解清楚为什么要这样设计。

GitHub：http://github.com/wquguru/harness-books…

第二本把 Claude Code 和 Codex 放一起进行对比，同一任务两个工具怎么做，设计取舍在哪。

想理解 AI 编码 Agent 的设计逻辑，或者打算自己造一个，这两本读完能省掉不少翻代码的时间。

wquguru/harness-books

Source: https://github.com/wquguru/harness-books

Harness Books

中文 README

Two books on harness engineering. They pursue the same engineering question: once a code-writing model is placed inside terminals, repositories, permission systems, and team workflows, what keeps the overall system bounded, continuous, and accountable for consequences?

Harness Engineering: A Design Guide to Claude Code Read online · Download PDF

The Harness Design Philosophies of Claude Code and Codex Read online · Download PDF

These books are not meant to walk line by line through the source code. They focus on how a harness organizes constraints and execution, and how an inherently unstable model can be folded into a sustainable engineering order. Prompt layering, query loops, permission decisions, context governance, failure recovery, multi-agent verification, local rules, and team institutions together form the organ system of a harness. The real danger is not that a model occasionally says something wrong, but that the system has no structure for handling consequences.

Core Claims

• Harness engineering is about how constraint structures organize execution.
• Once a code-writing model enters a real engineering environment, the main problem is no longer answer quality but behavioral consequences.
• Prompts, tools, permissions, state, recovery, verification, and institutions are not accessories around the system. They are organs in the same control structure.
• When comparing agent systems, the key question is not the feature checklist but where order is actually placed.
• If a team cannot turn individual experience into reusable rules, it will struggle to turn an agent into a stable system.

What The Two Books Focus On

Book 1: A Design Guide to Claude Code

The first book uses Claude Code as the observation target and concentrates on runtime structure. Its concern is why a system eventually has to grow components such as a control plane, query loop, tool permissions, context governance, recovery paths, multi-agent verification, and team rules.

Start with Book 1 if these are the questions you care about:

• Why harness engineering is not just prompt engineering at a larger scale
• Why prompts are fundamentally part of the control plane rather than a chat box
• Why model mistakes should be treated as a runtime norm rather than an exceptional event
• Why multi-agent work and verification should not be blended into one vague mechanism
• How a team can solidify personal experience into reusable engineering institutions

Book 2: Comparing Claude Code and Codex

The second book places Claude Code and Codex side by side and asks where each harness places order. One path starts from runtime discipline; the other starts from a more structured control layer. Both systems can work, but they distribute authority differently.

Start with Book 2 if you care more about system choice, architectural judgment, or what to learn when building your own harness:

• What the biggest control-plane divergence is between Claude Code and Codex
• How to align the roles of query loops, threads, rollouts, and state
• What governance roles are played by permissions, sandboxes, and policy languages
• How skills, hooks, and local rules encode organizational habits into the system
• If you want to build your own harness, who to learn from first and which layer to study first

Suggested Reading Paths

• Want the full frame first: read Book 1, then Book 2.
• Already familiar with coding-agent tools and want the architectural split directly: start with Book 2.
• Only want the conclusions: read Book 1 Chapter 9 plus Book 2 Chapter 7.

Want To Keep Practicing? Try AgentWay

AgentWay is a related but separate practice platform. Harness Books explains control structures, engineering judgments, and architectural divergences. AgentWay is where these ideas continue into training paths, drills, project exercises, and agent PoCs.

Local Build

Build the two locale-aware Honkit sites and then assemble the unified Pages site:

python3 tools/book-kit/build_honkit.py book1-claude-code
python3 tools/book-kit/build_honkit.py book1-claude-code --locale en
python3 tools/book-kit/build_honkit.py book2-comparing
python3 tools/book-kit/build_honkit.py book2-comparing --locale en
python3 tools/book-kit/build_pages_site.py

Final output is written to dist/.

_{Keywords: Harness Engineering, Claude Code guide, Claude Code vs Codex, AI coding agent, control plane, query loop, agent recovery, agent verification, local governance, approval policy}