Harness Engineering

Preface — None of This Is Mine

Introduction — The Discipline, Named

1. The argument in one paragraph
2. How the book is structured
3. A note on Claude as the working example
4. What this book is not
5. How to read it

Part I — Foundations and Taxonomy

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. Canon to harness — what each part applies

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

1. The model is non-deterministic. 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. Workflow variance, not model variance
6. What this book is not
7. The harness idea is not original to this book
8. Reading an unreliable run

Chapter 4 — What a Harness Is, Precisely

1. The working definition
2. The two channels every harness has
3. The harness is code
4. Every artifact in the harness passes the downstream-input test
5. Interactive sessions produce artifacts; headless sessions consume artifacts
6. Tools poke out; contracts stay in
7. Why a tight definition matters
8. A labeled inventory of a representative harness

Chapter 5 — The Taxonomy, Pinned

1. The four neighbors, named
2. The central pin
3. Why the word matters this much
4. The supporting terms
5. Boundary cases, ruled
6. A note on aphorisms
7. The glossary card

Chapter 6 — The Repo as a Behavioral System

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

Chapter 7 — The Layers and the Reliability Levers

1. Five layers, drawn as rings
2. Concentric, not stacked
3. The litmus test for placement
4. The three reliability levers, restated
5. The 5×3 grid
6. Layers do not have to be five
7. Concrete failure modes by layer
8. How the rest of the book uses the grid
9. The blank grid, ready to copy

Part II — The Habitat: Files That Govern

Chapter 8 — CLAUDE.md and the Instruction Layer

1. What the file actually does
2. Eight things the file should say
3. Length matters
4. The hierarchy
5. How the file fails
6. Who owns it, when it gets re-read
7. The skeleton

Chapter 9 — Rule Files: Iron Laws, Golden Rules, Preferences

1. Why rule files exist at all
2. Three tiers, one file
3. Markers on the page
4. Path-scoped activation
5. Traces-to footers
6. The cardinal sin: aspirational rules
7. How rules get written
8. How rules get pruned
9. Rule file skeleton

Chapter 10 — Guides, Corpus, and Playbooks

1. Rules bound a move; playbooks walk a job
2. Corpus is what the agent pulls from when one line is not enough
3. The five corpus layers
4. Where each layer is consulted
5. The lazy-load discipline
6. Stale corpus, and which layer lies loudest
7. Ontologies and knowledge graphs — an honorable mention
8. A playbook is a skill in this taxonomy
9. The full picture, in one walk
10. Two maps, one word
11. Artifact — the corpus map

Chapter 11 — Cascade, Scope, and Inheritance

1. The three rules that resolve the cascade
2. The default rule: specificity wins
3. Memory files: the cascade in one slice
4. The override rule: locks
5. The diagnostic rule: the resolved view is queryable
6. Required declarations and the visible gap
7. Three failure modes, all structural
8. A worked example: test-coverage policy across three layers

Chapter 12 — The Token Budget

1. The number that matters is not the ceiling
2. Three tiers
3. Lazy-load by region
4. Two sample baselines
5. The cost of bloat
6. The pre-flight check
7. Three rules for keeping the budget honest
8. Compact with focus, not by reflex
9. Prompt patterns that respect the budget
10. The context-budget worksheet

Part III — The Codebase: Design for Agent Legibility

Chapter 13 — Architecture as Communication

1. Architecture has a second reader now
2. Dependencies point inward
3. Prefer deep modules
4. Layering as a behavioral guarantee
5. Same feature, two repos
6. What the agent reads in architecture
7. Architecture-legibility checklist

Chapter 14 — Explicit Seams and Bounded Contexts

1. What a seam is, and why the agent uses them
2. Bounded contexts, operationalized
3. The god module
4. Actions and policies inside a context
5. Ports and adapters inside one repo
6. Why this is a Chapter 14 problem, not a Chapter 15 problem
7. When boundaries collapse
8. The seam catalog

Chapter 15 — Naming as a Behavioral Signal

1. Names are constraints on the next token
2. Naming conventions as priors
3. Vocabulary as identity
4. Domain language
5. Aggressive renames over apologetic comments
6. Anti-patterns to notice
7. The naming audit

Chapter 16 — Boring Code: Predictability Over Cleverness

1. No magic
2. Boring is sophistication moved
3. The agent thrives on boring code
4. Cleverness traps the agent amplifies
5. The agent reads what is in front of it
6. The boring-code lift

Chapter 17 — Testing as Agent Infrastructure

1. Tests are guides and sensors
2. TDD as the agent loop
3. The test pyramid still holds
4. Characterization tests before refactoring legacy code
5. Output-based tests beat implementation-based tests
6. Mocks only for unmanaged dependencies
7. What a good test teaches
8. Flaky tests are harness failures
9. A make-this-testable recipe

Chapter 18 — Fast Feedback Gates

1. A 30-second hook beats a five-minute hook the agent skips
2. Three families on the fast layer
3. Type checkers as a deterministic reviewer
4. Linters as encoded preferences
5. What the hook output has to look like
6. Pre-commit catches fast, CI catches slow
7. Concrete patterns that keep the hook fast
8. Hook hygiene
9. The slow ratchet
10. The hook template

Chapter 19 — Documentation as Corpus

1. The agent reads the docs
2. Marketing voice is not teaching voice
3. The README contract
4. Architecture decision records as agent context
5. Diátaxis as a sorting frame
6. C4 for the architecture docs
7. Stale documentation as an aspirational rule in disguise
8. The documentation flywheel
9. Artifact — a docs audit

Part IV — Tools: Extending Agent Capability

Chapter 20 — What Tools Are and Why They Belong Here

1. The working definition
2. Three intents tools serve
3. Why tools sit inside the harness
4. The principle of minimum capability
5. The tool ladder
6. The wider primitive ladder
7. Tool definitions vs tool reach
8. Skills, sub-agents, hooks, plugins, MCP — a map of the part
9. Model selection is part of the primitive design
10. A tool inventory for a representative repo

Chapter 21 — Skills: Reusable Multi-Phase Workflows

1. A skill is a walk, not an instruction
2. The 6–8 checkpoint anatomy
3. Skills as executable playbooks
4. A slash command is not a skill
5. Skill failure modes
6. Acceptance evidence as the closing checkpoint
7. The skill skeleton

Chapter 22 — Agents: Read-Only Specialists, Sub-Agents, Fan-Out

1. The move
2. Three named roles
3. Read-only is the default
4. Fan-out
5. Adversarial verification
6. Compression discipline
7. Sub-agent vs MCP server
8. The agent definition skeleton

Chapter 23 — Hooks: Where the Harness Acts on Its Own

1. Why hooks are special
2. The five events
3. Use cases worth naming
4. Hook hygiene
5. The relationship to skills
6. Anti-patterns
7. The hook configuration skeleton

Chapter 24 — Plugins: Encapsulating Repeatable Agent Behaviors

1. What a plugin is
2. When to write a plugin
3. Plugin anatomy
4. Distribution patterns
5. Versioning
6. Anti-patterns
7. The reference experiment
8. The manifest skeleton

Chapter 25 — MCP: Giving Agents Access to the World

1. What MCP actually gives you
2. The MCP server is a behavior change
3. Wrap vs shell out
4. Designing the surface
5. The trust boundary
6. A short design walkthrough
7. Public, hosted, self-hosted
8. The MCP tool design checklist

Chapter 26 — Designing Tools for Predictable Agent Use

1. What the agent actually reads
2. Tool names as constraints
3. Argument signatures
4. Output shape
5. Error messages as feedback
6. Idempotency, and saying so
7. Description text as a contract
8. Before and after

Chapter 27 — Tool Boundaries and Safety

1. Every tool is a capability grant
2. Permission scopes, named
3. Permission posture as a productivity lever
4. Destructive operations
5. Secret handling
6. Sandboxing
7. Rate limits as a safety mechanism
8. Audit logs that read like a forensic record
9. What the safety layer is not
10. The tool-safety matrix

Chapter 28 — Verifying the Harness Itself

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

Part V — The Team / Delivery Harness

Chapter 29 — 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 before dispatch
9. A context budget per contract
10. What this discipline is borrowed from
11. The honorable mention: spec-driven development
12. What the next two chapters do
13. The contract template

Chapter 30 — The Four Phases

1. Why four
2. Three touchpoints, and no more
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. The phase-transition checklist

Chapter 31 — Interrupts: How Agents Ask

1. Guessing is the failure mode
2. The shape of an interrupt
3. The shape of a resolution
4. One question per interrupt
5. The interrupt rate is a sensor on the harness
6. Anti-patterns
7. When the interrupt is the agent’s only honest move
8. The inverse: when the human has to correct the agent
9. The interrupt template

Chapter 32 — Continuous Delivery as a Harness Constraint

1. Every closed contract must be independently releasable
2. Main stays shippable after merge
3. User-visible behavior gated by flags in the same PR
4. No phase-one-of-N contracts
5. Why this is a harness concern, not a release-process concern
6. The agent-side leverage
7. Slop gates
8. The release-readiness gate

Chapter 33 — The Daemon in the Middle (Reconciler Pattern)

1. What a reconciler is
2. The sixty-second tick
3. Fresh clones, every time
4. Fire-and-forget dispatch
5. The operational concerns the daemon has to handle
6. Daemon versus orchestrator
7. Webhook chains and why I stopped writing them
8. Intent-driven delivery as the reference implementation
9. A worked tick

Chapter 34 — Code Review and PRs as Checkpoints

1. Review as a pattern-recognition activity
2. Reviewer agents for the first pass; humans for judgment calls
3. The PR is a checkpoint, not a delivery vehicle
4. Closing a PR closes a contract
5. Review fatigue as a harness failure
6. The four quadrants of review findings
7. Scope drift and regression risk: where to look first
8. The PR template

Part VI — The Organization: Scaling Behavior Engineering

Chapter 35 — What Belongs at the Org Level

1. Survives a process change. Survives a stack change.
2. Universal principles — the actual ones
3. Org-wide non-negotiables — the iron laws
4. Identity as iron law
5. The rule of three for org promotion
6. What does not belong at the Org level
7. The org-rule charter

Chapter 36 — Project Harness vs Org Harness

1. Two scopes, two masters
2. The harness consumer pattern
3. The promotion path
4. The demotion path
5. Patch propagation, forward-only
6. The org-harness repo
7. The promotion-candidate template

Chapter 37 — Ports and Adapters Across the Org

1. The pattern, scaled up
2. Four surfaces, four ports
3. What the spec contains, what the spec refuses
4. Why this matters more than it sounds
5. Where the spec lives, who owns it
6. The daemon, unchanged
7. Spec artifact — signal source, two adapters

Chapter 38 — Three Artifacts, Three Lifespans

1. Three artifacts, three lifespans, three storage locations
2. Each artifact has one job
3. Why mixing fails
4. Lifespan as the load-bearing rule
5. The decision tree
6. Anti-patterns
7. Tooling, not vigilance

Chapter 39 — Cross-Repo and Multi-Stack Reality

1. The portable subset and the stack-bound subset
2. Translation discipline
3. Multi-language monorepos
4. The walking translation

Chapter 40 — Topology: When One Agent Is Not Enough

1. Three layers, three names
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. Three more patterns for discovery work
7. Two operational rules for any pattern
8. Topology nodes meet the harness
9. “Is this a topology problem or a harness problem?”
10. Honest credit
11. The topology decision tree

Chapter 41 — Multi-Agent, One Harness

1. The shape of the problem
2. What lives in the canonical layer
3. What lives in the adapter directories
4. Where to compromise and where not
5. Adapter discipline — thin translation, nothing else
6. The cascade in a multi-agent world
7. What it costs to skip this discipline
8. Three signs the canonical layer has broken down
9. The reference implementation, briefly
10. The artifact — a multi-agent adapter map

Chapter 42 — Patterns and Anti-Patterns

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

Part VII — Operating the Harness

Chapter 43 — The Two Flywheels: Learning and Pruning

1. The two motions
2. Learning, batched
3. Pruning, audited
4. How the catalog feeds the wheels
5. Cadence
6. The flywheel ledger

Chapter 44 — 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 45 — Harness Debt

1. The symptoms
2. The boy-scout rule applies to the harness
3. The debt ledger
4. What letting debt grow actually costs
5. Debt versus the flywheels
6. The artifact — a harness-debt ledger row

Chapter 46 — Versioning the Harness

1. Why cadence is the answer to drift
2. Forward-only, always
3. Diff and ask
4. Versioning semantics
5. The release loop
6. Changelog discipline
7. Tying back to the chapters that earned this one
8. The CHANGELOG entry template

Chapter 47 — Post-Mortems for Agent Runs

1. When to run a post-mortem
2. Near-misses are free post-mortems
3. Routine retros after every workflow
4. The five recurring patterns
5. Blameless, but for the harness
6. The patch is structural
7. The flywheel consumes the output
8. The template

Chapter 48 — Modes: Paired, Solo, Autopilot

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 harness
8. The rubric

Chapter 49 — The Curator’s Role and Pair-Programming with an Agent

1. The work, named
2. Pair-programming with a constrained partner
3. Anti-patterns — what curation is not
4. Why the framing matters culturally
5. The curator’s daily rhythm
6. What is not the curator’s job
7. The artifact — a curator’s daily checklist

Part VIII — From Experiments to Tool: The Path to Keystone

Chapter 50 — The Experiments: Bridle, Sellier, Intent-Driven Delivery

1. Bridle — the harness as a living system
2. Sellier — defaults over flexibility
3. Intent-driven delivery — the team layer made real
4. What carried forward

Chapter 51 — Keystone: The Synthesis

1. What Keystone is, in one paragraph
2. What survived from each experiment
3. The first command
4. The directory layout
5. Sensors, actions, playbooks, adapters — the lifecycle in markdown
6. The companion MCP server
7. The three-ring principle
8. Multi-agent support, wired in
9. The cascade engine
10. Forward-only patches
11. A worked first task, end-to-end
12. The full chain, every contract
13. What the agent reads on each turn
14. What Keystone does not do
15. Tying back to the experiments
16. A copyable getting-started recipe

Chapter 52 — Composing the Layers in Practice

1. Why composition works at all
2. Example one — small team, single repo
3. Example two — multi-team org, many repos
4. When to add a layer (and when not to)
5. What composition looks like in practice
6. The composition decision tree

Part IX — Where This Goes

Chapter 53 — The Honest State of the Art

1. What works
2. What sort-of works
3. What does not work yet
4. Confidence intervals, named
5. The next two years, my best guess

Chapter 54 — Building Your Own Harness: A 30-Day Plan

1. Day 1–3: Tests and a pre-commit hook
2. Day 4–7: CLAUDE.md, one rule file, one skill
3. Day 8–14: One reviewer agent, one investigator agent, hooks for state capture
4. Day 15–21: First learning audit, first pruning audit, harness-debt ledger
5. Day 22–30: Pick one team-level constraint and encode it
6. Iterate
7. For multi-team and org rollouts
8. The artifact — a 30-day calendar template

Chapter 55 — The Discipline That Was Happening Before Anyone Named It

1. What the reader owes the discipline
2. The work is ongoing
3. A note to the engineer who has not started yet
4. The apprentice

Appendix A — Vocabulary Reference

1. Part I — Foundations and Taxonomy
2. Part II — The Habitat
3. Part III — The Codebase
4. Part V — The Team and Delivery Harness
5. Part VI — The Organization
6. Part VII — Operating the Harness
7. Part VIII — From Experiments to Tool

Appendix B — Reference Implementations

1. Keystone — the synthesis tool
2. Bridle — the maintenance discipline
3. Sellier — the prescriptive scaffold
4. Intent-driven delivery — the team-layer reference
5. Reading a foreign harness

Appendix C — Failure-Pattern Catalog

1. Pattern 1 — Acted on Ambiguous Request
2. Pattern 2 — Worked in Unfamiliar Area Without Orienting
3. Pattern 3 — Followed an Aspirational Rule Too Literally
4. Pattern 4 — Escalated Wrong (Ladder Mistuned)
5. Pattern 5 — Mental Model Drifted from Reality
6. Pattern 6 — Token-Budget Collapse
7. Pattern 7 — Tool Over-Fit
8. Pattern 8 — Imitation Cascade
9. Pattern 9 — Silent Override at Cascade
10. Pattern 10 — Mock Anchoring
11. Pattern 11 — Phase Skipping
12. Pattern 12 — Reviewer Fatigue Collapse

Appendix D — Templates

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

Appendix E — Further Reading

1. Foundational engineering canon
2. Foundational agent literature
3. Adjacent disciplines
4. Mathematics and theory
5. The author’s blog archive

Appendix F — The 90-Day Org Rollout

1. Weeks 1–2: Charter, pilot pick, universal-principles-only org repo
2. Weeks 3–6: Pilot team installs Keystone at the project layer
3. Weeks 7–10: Second team adopts
4. Weeks 11–13: The team layer lands
5. Exit criterion and the maintenance rhythm
6. A note on growing past two teams
7. The artifact — a 90-day calendar template