| name | claude-code-loop-harness |
| description | Design, pilot, run, and improve bounded Claude Code agent harnesses using the right primitive for the job: /loop for recurring checks, /goal for completion conditions, hooks for deterministic lifecycle enforcement, dynamic workflows for large finite fan-out, and worktrees for write isolation. Use when a user asks to automate recurring engineering work, reproduce Boris Cherny-style loop engineering, coordinate many subagents, build a safe agent fleet, or turn an agent workflow into a reusable Skill. |
Claude Code Loop Harness
Build the smallest harness that can prove the requested outcome. Treat agent count as cost, not progress.
Required reading
Read these references before designing or launching a harness:
Core distinctions
Do not collapse these into one concept:
- The agentic loop is one agent gathering context, acting, verifying, and repeating.
/loop re-runs a prompt on a time cadence inside an open session. It is for recurring observation or maintenance, not large fan-out by itself./goal starts another turn until a condition is satisfied or judged impossible. Use it for a finite outcome that needs repeated attempts.- A Stop hook deterministically decides whether a session may finish. Use it when the completion gate must always run.
- Dynamic workflows are finite JavaScript orchestration programs that can sequence, parallelize, aggregate, and independently verify dozens to hundreds of subagents.
- Routines are durable cloud schedules. Use them when work must survive a closed laptop or session.
- Worktrees isolate concurrent writers. They do not coordinate agents or prove correctness.
Workflow
1. Freeze the task contract
Write a short contract before spawning anything:
- objective and non-goals
- authoritative inputs and allowed scope
- observable acceptance checks
- maximum elapsed time, rounds, agents, and estimated tokens
- allowed tools, network destinations, and write paths
- actions requiring human approval
- stop conditions and rollback path
If acceptance cannot be tested or inspected, design the verifier first. Do not compensate with more prompting or more agents.
2. Route to the correct primitive
Use the routing table in references/architecture-and-routing.md. Prefer this order:
- one normal agent turn
- one agent with a deterministic verifier
- a few isolated subagents
/goal or a Stop hook for bounded completion/loop for recurring checks- a small dynamic workflow for large finite work
- a larger workflow only after the pilot demonstrates value
Never select a large workflow because the user mentioned “hundreds of agents.” Translate that phrase into throughput, independence, verification, and budget requirements.
3. Generate and validate a plan
For non-trivial runs, create a JSON config matching the example in references/architecture-and-routing.md, then run:
node scripts/plan-harness.mjs path/to/harness-config.json path/to/harness-plan.json
Review the warnings. A plan is invalid if it has unbounded rounds, unbounded fan-out, concurrent writes without isolation, destructive or external actions without a human gate, or no independent verifier.
4. Pilot before scaling
Run the full architecture on a representative slice:
- one directory instead of the repository
- five sources instead of fifty
- two workers instead of twenty
- one loop iteration instead of a day
Record elapsed time, total agents, token usage when available, verifier pass rate, false positives, conflicts, and human review time. Scale only if the marginal quality or coverage is worth the marginal cost.
5. Execute as a staged state machine
Use these states and persist a receipt for every transition:
CONTRACT -> PILOT -> PLAN -> FAN_OUT -> VERIFY -> SYNTHESIZE -> HUMAN_GATE -> APPLY -> LEARN -> COMPLETE
Possible terminal states are COMPLETE, STOPPED, BUDGET_EXHAUSTED, and BLOCKED. A worker may not mark its own output verified. A verifier must receive the frozen task contract and the artifact, not the worker's chain of thought.
For parallel work:
- give every worker a scoped task contract and structured output schema
- isolate concurrent writers with worktrees or separate sandboxes
- keep intermediate results out of the coordinator context when possible
- cap concurrency independently from total agent count
- deduplicate before synthesis
- retry only classified transient failures
- stop after two rounds with no measurable progress unless the contract says otherwise
6. Gate consequential actions
Require explicit human approval before merging, pushing, deploying, deleting, spending beyond the approved budget, changing production state, messaging external people, or handling real user data. Autonomous generation does not imply autonomous approval.
7. Improve the harness, not only the artifact
After review, classify every failure as one of:
- bad task contract
- missing context or tool
- wrong routing primitive
- poor decomposition
- worker collision
- inadequate verification
- aggregation loss
- budget or rate-limit failure
- unsafe permission design
Update the skill, workflow, checker, or task contract that caused the failure. Preserve run receipts so the next iteration can be compared against the previous one.
Required run receipt
Archive at least:
- frozen task contract and content hash
- selected primitive and routing reason
- model, effort level, and tool policy
- planned and actual agent counts, concurrency, rounds, elapsed time, and token usage when exposed
- worker outputs or their durable locations
- verifier findings and unresolved claims
- human approvals and applied actions
- final status and stop reason
- lessons folded back into the harness
Output standard
When explaining or handing off a harness, include:
- what is confirmed by first-party sources
- what is an architectural inference
- what remains unknown or product-version-dependent
- the smallest safe example
- the scale-up path and cost controls
- exact verification and human-gate behavior
Do not claim that Boris Cherny's private personal harness has been reconstructed exactly. Public sources establish design principles and product primitives, not every internal prompt, script, permission, or infrastructure detail.
