Want to understand how Claude Code is architected under the hood, but diving directly into the source code feels overwhelming, and blog posts are often too fragmented?
Recently, I discovered harness-books on GitHub, which uses two books to clearly break down the architecture — the structure is clearer than I expected.

The first book focuses on runtime structure: how permissions are managed, how context is governed, and how the system recovers from errors, explained chapter by chapter.
The emphasis isn’t on how the code is written, but on helping us understand why it was designed this way.

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

The second book compares Claude Code and Codex side-by-side, examining how each tool approaches the same task and where the design trade-offs lie.
If you want to understand the design logic behind AI coding agents — or if you plan to build one yourself — reading these two books will save you a lot of time spent digging through source code.

wquguru/harness-books

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

Harness Books

中文 README | Read Online | About AgentWay

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.

Full Table of Contents

Book 1 — Harness Engineering: A Design Guide to Claude Code

• Introduction
• Preface: Harness, Terminals, and Engineering Constraints
• Chapter 1 Why Harness Engineering Matters
• Chapter 2 Prompt Is Not Personality, Prompt Is the Control Plane
• Chapter 3 Query Loop: The Heartbeat of an Agent System
• Chapter 4 Tools, Permissions, and Interrupts: Why Agents Cannot Touch the World Directly
• Chapter 5 Context Governance: Memory, CLAUDE.md, and Compact as a Budgeting Regime
• Chapter 6 Errors and Recovery: An Agent System That Keeps Working After Failure
• Chapter 7 Multi-Agent Work and Verification: Managing Instability Through Division of Labor
• Chapter 8 Team Adoption: Turning a Smart Tool into a Reusable Institution
• Chapter 9 Ten Principles of Harness Engineering
• Appendix A Checklists: Turning Principles into Executable Constraints
• Appendix B Diagrams: Drawing the Runtime Skeleton
• Appendix C Source Map: Which Files Ground Each Chapter

Book 2 — The Harness Design Philosophies of Claude Code and Codex

• Introduction
• Reading Map: How to Understand Book 1 and This Comparative Book Together
• Preface: Two Harnesses, Not Accessories on the Same Horse
• Chapter 1: Why We Compare Claude Code and Codex
• Chapter 2: Two Control Planes: Prompt Assembly and Instruction Fragments
• Chapter 3: Where the Heartbeat Lives: Query Loop Compared with Thread, Rollout, and State
• Chapter 4: Tools, Sandboxes, and Policy Languages: Who Stops the Model from Moving Too Fast
• Chapter 5: Skills, Hooks, and Local Rules: How a System Learns Local Discipline
• Chapter 6: Delegation, Verification, and Persistent State: Who Prevents a System from Grading Itself
• Chapter 7: Convergence Through Different Roads, or Separate Branches
• Chapter 8: If You Are Building Your Own Harness, What to Study First
• Appendix A: Source Map That Underpins the Comparison
• Appendix B: Checklist to Determine Where Your Harness Sits

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