Harness Engineering

Preface — None of This Is Mine

Introduction — Constraint Engineering, Named

1. The argument in one paragraph
2. How the book is structured
3. Where the evidence comes from
4. A note on Claude Code as the working example
5. Scope and sources
6. How to read it — by use-case

Part I — Foundations

Chapter 1 — The Agent Is Already in Your Codebase

1. A Tuesday with the agent and a Friday with the same agent
2. The naive response and why it breaks
3. Why the book is structured around the repo
4. The repo audit, in concrete terms
5. The one-page repo audit

Chapter 2 — Old Principles, New Substrate

1. The agent did not invent any of this
2. The amplification thesis
3. Two pressures the canon now has to absorb
4. Why “stronger standards” is the wrong slogan
5. I did not invent these standards
6. Where the canon lands in this book
7. The canon-to-charter map

Chapter 3 — The Reliability Problem (and Why Determinism Is the Wrong Goal)

1. The model is non-deterministic, and that part is not a defect
2. Reliability is not determinism
3. The three reliability levers
4. The levers are filters; reliability is what survives them
5. Determinism belongs in the workflow
6. What this book is not
7. None of this is original to this book
8. The claim, made falsifiable
9. Reading an unreliable run

Chapter 4 — Charter and Harness: What Each One Is

1. The charter: what you author
2. The harness: the engine that applies it
3. What’s in each box
4. Sort your own repo

Chapter 5 — Harness and Charter: The Boundary

1. The machine: charter → harness → model → result
2. The standard: the charter
3. The line
4. The case that looks like an exception
5. Where context and the loop sit
6. The word, and where I had it pointed
7. Why the seam is worth the trouble
8. The card

Chapter 6 — Taxonomy: The Seven Words and the One Test That Sorts Them

1. The one test
2. The seven words
3. The symmetry
4. What is neither
5. How to read the rest of the book
6. The artifact: the classifier card

Chapter 7 — The Repo as a Behavioral System

1. Three classes of signal
2. Why instruction loses to imitation
3. The repo is the environment
4. A worked example
5. Why each channel matters on its own
6. What this means for where to invest
7. Repo audit

Chapter 8 — The Charter’s Layers and the Reliability Levers

1. The charter has layers
2. Concentric, not stacked
3. The litmus test for placement
4. The three reliability levers, restated
5. The layer-by-lever grid
6. The layer × concern matrix
7. The policy layer does not have to be one
8. Concrete failure modes by layer
9. How the rest of the book uses the grid
10. The blank grid, ready to copy

Chapter 9 — Objections

1. “The models will eat this”
2. “This is platform engineering with a new coat of paint”
3. “Context engineering already names this”
4. “Hand-authored charters will be compiled away”
5. The ledger

Chapter 10 — Related Work: Where This Sits

1. AGENTS.md: the file the field agreed on
2. Harness engineering at Thoughtworks: the same name, independently
3. Prompt engineering and context engineering: the supplied-versus-authored cut
4. Platform engineering: the nearest older sibling
5. DORA and Accelerate: the measurement standard not yet met
6. SRE: error budgets become gate budgets
7. MLOps and AI engineering: the other axis
8. DSPy: the compiler objection
9. The map on one card

Part II — Authoring the Charter

Chapter 11 — The Instruction Layer

1. The file read on every turn

Chapter 12 — Rule Files: Iron Laws, Golden Rules, and Preferences

1. Three tiers, one file
2. Scope and traces
3. The cardinal sin
4. Where rules come from, and where they go
5. Rules bound a move; a command or a skill walks a job

Chapter 13 — The Corpus and the Docs

1. The corpus
2. Docs are corpus

Chapter 14 — Cascade, Scope, and Inheritance

1. Three rules resolve the cascade
2. Memory files: the cascade in one slice
3. Locks
4. The resolved view
5. Required declarations
6. Three failure modes, all structural
7. A worked example

Chapter 15 — Ontologies: One Meaning Per Term

1. The agent hears only what is written
2. The glossary as charter artifact
3. Ubiquitous language for an absent reader
4. The ontology the agent believes
5. What holds between the terms
6. Terms rot

Chapter 16 — Memory and the Token Budget

1. Three kinds, and only one of them survives
2. The conversion is the discipline
3. The agent’s memory is a budget, not a vault
4. Where it lives in the layers
5. The window is working memory, and it costs you every turn
6. The number that matters is not the ceiling
7. Three tiers
8. Lazy-load by region
9. Two sample baselines
10. The cost of bloat
11. The pre-flight check
12. Three rules for keeping the budget honest
13. Compact with focus
14. Constraint loss: the failure compaction causes
15. Prompt patterns that respect the budget
16. A note on context-reduction tooling
17. The artifact

Part III — Code, Tools, and Checks

Chapter 17 — The Legible Codebase: Architecture and Seams

1. Architecture as Communication
2. Explicit Seams and Bounded Contexts
3. The artifacts

Chapter 18 — The Legible Codebase: Names and Boring Code

1. Naming as a Behavioral Signal
2. Boring Code: Predictability over Cleverness
3. The artifacts

Chapter 19 — Tests and Gates

1. Tests are guides and sensors
2. TDD as the agent loop
3. The test pyramid still holds
4. Characterization tests before legacy refactors
5. Output-based tests beat implementation-based tests
6. Mock the unmanaged, run the managed
7. Flaky tests are charter failures
8. A make-this-testable recipe
9. Tests are coverage; gates are speed
10. The thirty-second budget
11. What runs on the fast layer
12. Two gates, two jobs
13. Hook hygiene
14. The slow ratchet
15. Scoring code health as a sensor
16. The happy path is verified; QA moves to the edges
17. The artifact

Chapter 20 — Declaring Tools: Skills, Sub-Agents, Hooks, Plugins, and MCP

1. What a tool is
2. Contract in the repo, reach in the world
3. Minimum capability and the ladder
4. The tool inventory
5. Skills: reusable multi-phase workflows
6. Sub-agents: specialists with refusal scopes
7. Hooks: declared to the charter, executed by the harness
8. Plugins: behaviors that travel
9. MCP: typed bridges to the world

Chapter 21 — Bounding Tools

1. What the agent actually reads
2. Names and signatures
3. Output shape and error feedback
4. Idempotency, and saying so
5. Description text as a contract
6. Every tool is a capability grant
7. Permission scopes, named
8. Permission posture as a productivity lever
9. Destructive operations
10. Secret handling
11. Sandboxing is a declared policy
12. Rate limits as a safety mechanism
13. Audit logs that read like a forensic record
14. What the safety layer is not
15. The artifact — the tool-safety matrix

Chapter 22 — Verifying the Charter Itself

1. The charter is code; verify it like code
2. Pre-commit safeguards for the charter’s own files
3. Code Health for the charter
4. A failing safeguard is not negotiated away
5. The verify, review, ship loop
6. The charter verifies itself
7. The charter pre-flight
8. The verify skill

Chapter 23 — Retrofitting a Charter into a Repo That Fights You

1. There is no single truth to describe
2. Delete the lies before you write the truth
3. Describe the dominant pattern, not the aspirational one
4. Give the agent a rule for living in a mixed codebase
5. Bound the charter’s authority to a seam you understand
6. Characterize before you let the agent change what you cannot describe
7. Ship the small honest charter and let the flywheel grow it
8. The artifact: a retrofit charter starter

Chapter 24 — Reading an Unfamiliar Codebase with the Agent

1. The claim has to carry a citation
2. The imitation trap, seen from the other side
3. The reconnaissance loop
4. A charter turns reconnaissance into orientation
5. Reading is read-only
6. The artifact: a reconnaissance skill

Part IV — Scaling and Operating the Charter

Chapter 25 — The Org Charter

1. Two scopes, two masters
2. What earns the org layer
3. The rule of three
4. What does not belong
5. Consumed as a dependency
6. One port spec, many adapters
7. Three artifacts, three lifespans
8. Principles travel; idioms stay home
9. One repo, many agents
10. Where a team is on the curve
11. The artifact

Chapter 26 — The Charter as a Queryable Service

1. Ask instead of carry
2. Two halves: policy and context
3. Why an MCP server is the right surface
4. The tradeoff the service does not escape
5. When to serve and when to compile
6. The artifact

Chapter 27 — Patterns and Anti-Patterns

1. Patterns — the shapes that work
2. Anti-patterns — the shapes that fail
3. The artifact — a printable cheat sheet

Chapter 28 — Flywheels and Post-Mortems

1. The two motions
2. Learning, batched
3. Pruning, audited
4. How the catalog feeds the wheels
5. Cadence
6. The flywheel ledger
7. Post-mortems: from incident to charter patch
8. When to run a post-mortem
9. Near-misses are free post-mortems
10. The run has to be legible first
11. Mining the logs for the failures nobody reported
12. A short retrospective after every workflow
13. The five recurring patterns
14. Blameless, but for the charter
15. The patch is structural
16. The flywheel consumes the output
17. The artifact

Chapter 29 — The Codebase That Gets Better With Use

1. The compounding claim
2. The mechanism, in five moves
3. The opposite mechanism, in the absence of discipline
4. Measuring the compounding
5. The cultural signal
6. The quarterly health snapshot

Chapter 30 — Charter Evals

1. The charter’s missing test suite
2. What an eval is, precisely
3. Two questions: capability evals and charter evals
4. The protocol, in full
5. Build the set from your own failures
6. Scoring: deterministic, inferential, and human
7. The numbers that matter
8. Eval-driven charter development
9. The connection to EFC
10. Honest limits
11. Artifact — a starter eval suite

Chapter 31 — Charter Debt and Versioning

1. The symptoms
2. The boy-scout rule applies to the charter
3. The debt ledger
4. The weekly ledger
5. What letting debt grow actually costs
6. Debt versus the flywheels
7. Comprehension debt is charter debt’s twin
8. The artifact — a charter-debt ledger row
9. The release bites back
10. Why cadence is the answer to drift
11. Forward-only, always
12. Diff and ask
13. Versioning semantics
14. The release loop
15. Changelog discipline
16. The artifact — the CHANGELOG entry template

Chapter 32 — Modes and the Curator

1. Pacing, not phasing
2. Paired — the cadence for unknown ground
3. Solo — the cadence for known ground
4. Autopilot — the cadence for high-confidence stretches
5. Modes are not skill levels
6. Stepping up, stepping back
7. Mode selection lives in the charter
8. The rubric
9. From author to curator
10. The work, named
11. Pair-programming with a constrained partner
12. Anti-patterns — what curation is not
13. Why the framing matters culturally
14. The curator’s daily rhythm
15. What is not the curator’s job
16. The artifact

Part V — Harness Engineering

Chapter 33 — What Harness Engineering Is

1. Agent = Model + Harness
2. Two levels of harness
3. The dark factory, and the lit one
4. The five jobs
5. When you actually need to build one
6. When an AI product outgrows the API call
7. The harness does not care where you sit
8. The artifact: should you build a harness?

Chapter 34 — DAG or Loop: The Shape of Control Flow

1. Two shapes, one question
2. A DAG is just composition
3. When the graph earns a framework
4. Branching: the path forks on a value
5. Map-reduce: fan out wide, fold once
6. Failure is an edge, not an exception
7. The single edge that turns a DAG into a loop
8. The double dovetail
9. The symmetry worth naming
10. The artifact: a composable stage pipeline

Chapter 35 — Loop Engineering

1. Two loops
2. What loop engineering is
3. The loop feeds itself, and its memory lives on disk
4. Structured output: the feedback the loop routes on
5. The outer loop: delegate to agents that carry the charter
6. What it looks like in practice
7. The orchestrator is a team, and Brooks already warned you
8. Where it breaks, and how to stop it
9. The artifact: a loop spec with the bounds built in
10. The bug already had a name
11. The orchestrator is a queue
12. The primitives you already built by hand
13. The queue does not replace the single loop
14. Where the queue lives in the stack
15. The artifact: a queue spec

Chapter 36 — RAG: Retrieval as a Harness Job

1. Fetch strategies, plural
2. Search the tree, or search an index
3. The vector store, and why it is a harness job
4. The corpus is the cache; retrieval is the fetch
5. Assembly is a pipeline
6. Three ways the supply chain fails
7. Retrieval in the factory
8. Measuring the supply chain
9. The artifact: a retrieval policy

Chapter 37 — Security, Permissions, and Sandboxing

1. Least privilege, per run
2. Deny by default
3. Production is a human gate
4. The check is a wrapper, not a habit
5. Fail closed
6. Isolation for what the check can’t foresee
7. Secrets live at the boundary
8. Retrieved content is untrusted too
9. Log every privileged call
10. The artifact: a permission and sandbox config

Chapter 38 — Injection Inside the Grant

1. The gate had nothing to refuse
2. Where the instruction comes from
3. Keep the grant tight — then keep going
4. Separate the plan from the payload
5. Spotlight what you cannot reduce
6. Bound the decision, not just the capability
7. Tripwires on the diff
8. Exfiltration rides allowed channels
9. Detection, because prevention leaks
10. The honest limit
11. The artifact: a merge gate the fleet cannot talk past

Chapter 39 — Model Selection and Routing

1. Route the step, not the task
2. The model is a seam, so routing is a policy over it
3. Start cheap, escalate on failure
4. A model version is a dependency — pin it
5. Routing is a decision, and decisions can be wrong
6. The artifact: a routing policy with an escalation ladder

Chapter 40 — Cost and Resource Control

1. Every call costs three things
2. The ceiling has to throw
3. Poison items and attribution
4. Routing and caching: paying less for the same answer
5. Rate limits and backpressure
6. When the ceiling moves up a layer
7. Cost is a sensor on everything upstream
8. What the spend buys
9. The artifact: a budget config

Chapter 41 — Testing the Harness

1. Test what the model doesn’t touch
2. The model is a seam
3. Routing tests: assert every branch, especially the one evals skip
4. Bounds tests: prove the ceiling stops the loop
5. Structured-output tests: prove the retry fires and the giving-up is real
6. Integration tests: prove resume does not repeat work
7. Determinism is a thing you engineer into the test
8. What not to test
9. The artifact: a harness test file

Chapter 42 — Building the Harness on a Framework

1. The account you need first
2. The shape every version builds
3. LangChain
4. LangGraph
5. Deepagents
6. Pydantic AI
7. The three you may want instead
8. Choosing, and not choosing
9. Build vs buy, one layer up
10. The artifact

Chapter 43 — Framework Patterns and Structure

1. LangGraph: control flow as a graph
2. LangChain: output shape as a contract
3. Deepagents: decomposition made explicit
4. Pydantic AI: the contract between model and code
5. The same benefit, four doors
6. The artifact

Chapter 44 — Harness Concerns, Solved

1. Implementing tools
2. Structured output
3. Bounded retries and error feedback
4. Memory and the token budget
5. Streaming
6. Sandboxing the tool surface
7. The artifact

Chapter 45 — Building a Coding Harness

1. The agent loop is the harness
2. The tools the loop turns on
3. The gate closes the loop; the cap catches it
4. Fresh clone, sandboxed tools, PR out
5. The artifact

Chapter 46 — Harness Evals

1. Two targets, one job
2. A corpus is data
3. A scorer is a function you pass in
4. The runner is a map
5. Gating on the number
6. Offline and online
7. The artifact: harness eval template

Part VI — Orchestration Engineering

Chapter 47 — Intent Contracts (and Why Vibe Coding Breaks at Team Scale)

1. What vibe coding hides
2. Narrow the input, at team scale
3. Seven sections, every time
4. Falsifiable matters
5. Tag what is known
6. Goal mode and debate mode
7. The ticket is the contract
8. Split the contract at Intake
9. A context budget per contract
10. What this discipline is borrowed from
11. The honorable mention: spec-driven development
12. The contract template

Chapter 48 — The Six Phases and Interrupts

1. Why six
2. A touchpoint at every phase boundary
3. Each phase has an exit, and the exit is explicit
4. The observability test for any gate
5. The ticket is the contract
6. What goes wrong without phase discipline
7. A short note on tooling
8. Interrupts: how agents ask
9. Guessing is the failure mode
10. The shape of an interrupt
11. The shape of a resolution
12. One question per interrupt
13. The interrupt rate is a sensor on the charter
14. Anti-patterns
15. When the interrupt is the agent’s only honest move
16. The inverse: when the human has to correct the agent
17. The artifact

Chapter 49 — Topology and the Daemon

1. Three names, one system
2. When a second agent earns its slot
3. When the second agent does not earn its slot
4. The four topology patterns
5. Pipeline vs barrier: when stages have to wait
6. Patterns for discovery work
7. Two operational rules for any pattern
8. Topology nodes meet the charter
9. The daemon in the middle
10. The sixty-second tick
11. Fresh clones, every time
12. Fire-and-forget dispatch
13. The dispatch is one line, until it is not
14. The operational surface
15. A worked tick

Chapter 50 — The Orchestrator on a Framework

1. A node is a harness
2. The frameworks, one altitude up
3. Why not one clever agent
4. The artifact

Chapter 51 — Orchestrator Patterns in a Framework

1. Supervisor and router
2. Fan-out and fan-in
3. Pipeline
4. Hierarchy and teams
5. The same benefit, one floor up
6. The artifact

Chapter 52 — Orchestrator Concerns, Solved

1. Shared state across agents
2. Capping the fan-out
3. Durability across a long run
4. Human-in-the-loop, mid-topology
5. Observability across the fleet
6. Cost across the fleet
7. The artifact

Chapter 53 — Reducible Workflows: The DAG That Loops

1. The shape has a name: a reducible graph
2. A single loop
3. Nested loops: TDD
4. Deeper nesting, and where it lives
5. The reducible orchestrator
6. The artifact: a reducible-workflow check

Chapter 54 — Beyond the Reducible Graph: State Machines, Choreography, and Sagas

1. When the process never ends: state machines
2. When there is no orchestrator: choreography
3. When you cannot just stop: sagas and compensation
4. Which shape?

Chapter 55 — Orchestration Patterns

1. The orchestrator is a queue, not an agent
2. The process is data, and there is more than one
3. Bounded, recoverable work is canon, not invention
4. Routing, failover, quotas
5. Human attention is data
6. Everything is a row
7. When to split the agent
8. The review, in one page

Chapter 56 — Dark Factories

1. Where the human stands
2. Sensors report, gates refuse
3. The asymmetry: analyze freely, change under a signer
4. Bounds are policy
5. What the meter says
6. Field notes
7. What the dark cannot do
8. The artifact: a lights-out readiness policy

Chapter 57 — Lights-On Factories

1. The platform layer
2. The autonomy ladder
3. The frozen record
4. Coverage and imitation surfaces
5. Experiments in production
6. What openness costs
7. The openness config

Chapter 58 — Orchestrator Evals

1. The unit of measure changes
2. The failures live between the agents
3. Two ways to run one
4. The artifact: an orchestrator scorecard

Part VII — Cross-Cutting Concerns

Chapter 59 — From Tribal Knowledge to Deterministic Workflow

1. The four rungs
2. The direction is the point
3. Maintaining the ladder against reality
4. The work is the process, not the artifact
5. The artifact

Chapter 60 — Cross-Cutting: The Themes That Hold on Both Sides

1. The three levers are substrate-independent
2. Constraints come in layers, and the layers have precedence
3. Everything accrues debt
4. Everything runs against a finite budget
5. The model’s output is untrusted, so validate at the boundary
6. Measurement over assertion
7. Feedback loops keep both honest
8. Reach for the heavier substrate late
9. Where this hands off
10. The artifact: the cross-cutting audit

Chapter 61 — The Layers a Business Governs

1. The stack is taller than the code
2. Governance is the org charter, grown up
3. Govern before, observe after
4. The hardest question is not whether the rules were followed
5. Authority: the slot the mechanism cannot fill
6. Purpose: the layer that makes the rest worth building
7. The same discipline, all the way up

Epilogue — Containment, Not Completeness

1. The harness does not escape it either
2. Sensors outside the rules
3. What does not change is consistency

Appendix A — Vocabulary Reference

1. Foundations and Taxonomy
2. The Charter: Files That Govern
3. The Codebase
4. The Delivery Process and Orchestration
5. The Organization
6. Operating the Charter
7. From Experiments to Tool
8. Part V — The Harness

Appendix B — Templates

1. CLAUDE.md skeleton (Ch 11)
2. Rule file skeleton — iron, golden, preference (Ch 12)
3. Corpus map — five directories (Ch 13)
4. Skill skeleton — eight checkpoints (Ch 20)
5. Agent definition skeleton (Ch 20)
6. Hook configuration skeleton — five patterns (Ch 20)
7. Plugin manifest skeleton (Ch 20)
8. MCP tool design checklist — eight questions (Ch 20)
9. Intent contract template — seven sections (Ch 47)
10. Phase-transition checklist (Ch 48)
11. Interrupt template (Ch 48)
12. Release-readiness gate — five checks (Ch 48)
13. PR template — five sections (Ch 48)
14. Org-rule charter (Ch 25)
15. Promotion-candidate template (Ch 25)
16. Three-artifact decision tree (Ch 25)
17. Post-mortem template (Ch 28)
18. Charter-debt ledger row (Ch 31)
19. Charter CHANGELOG entry (Ch 31)
20. Mode-selection rubric (Ch 32)
21. Curator’s daily checklist (Ch 32)
22. 30-day calendar template

Appendix C — Sources

1. Foundational engineering canon
2. Foundational agent literature
3. Adjacent disciplines
4. Mathematics and theory
5. Contemporary harness and agent-coding writing
6. Naveen Gaddam — AI Replaced 80% of Coding, Only These 7 Skills Are Left (Medium, 2026). A popular-register version of a thesis the book argues at length: syntax automates, engineering does not. Included as a pointer to how the argument travels outside the practitioner core. medium.com/@gaddamnaveen192/ai-replaced-80-of-coding-only-these-7-skills-are-left-128e13d3020d
7. Honorable mentions: tools, frameworks, and runtimes
8. The author’s blog archive

Appendix D — The Tools Behind the Book

1. sigma — the harness layer, built from scratch
2. open-refinery — the agentic-workflow layer, kept open
3. What the three tools embody
4. Run the post-mortem on your own tool
5. Keystone: the synthesis
6. What Keystone is, in one paragraph
7. The charter discipline, shipped
8. The first command
9. The directory layout
10. Sensors, signals, playbooks, adapters — the lifecycle in markdown
11. The companion surfaces
12. The three-ring principle, mapped
13. The cascade, now a policy tree
14. Forward-only upgrades
15. A worked first task, end-to-end
16. The full chain, every contract
17. What the agent reads on each turn
18. What Keystone does not do
19. What Keystone kept and dropped
20. A copyable getting-started recipe

Appendix E — For the Junior Engineer

1. Comprehension is the job
2. What the team owes you
3. Pair with a senior, and the agent makes three
4. Read open source with an agent
5. Exercises
6. The path