A production harness for Claude Code: the workflow, skills, subagents, hooks and scripts I use to take a GitHub issue from plan to merge, with a person deciding at two gates and the agent doing the rest.
It was built from measured session data, and it's measured on every issue it runs. A typical issue now costs about 40% less than one long session did, with less than half the context and fewer messages from me.
Who this is for: developers who already use Claude Code on real projects, and want a repeatable way to run it on issues that keeps cost and context down without giving up review. You'll need GitHub, CI on pull requests, the habit of reading, filtering, and evaluating a plan before it's built, and also the habit of reviewing commits closely against the implementation goal and personal quality standards.
What this is not:
- A framework or a product. It is one owner's working setup, documented so you can adapt it.
- Hands-off. The design assumes someone approves every plan, decides every review finding and merges by hand. Those gates are part of the architecture.
- Settled. The current version (D26) is still being validated against its runs.
flowchart LR
%% --- BLOCK DEFINITIONS ---
A["Block A: Scope"]
B["Block B: Build"]
C["Block C: Review"]
D["Block D: Close"]
G1(["G1: Plan Review"])
G2(["G2: PR Review, <br/>CI, and <br/>Findings Triage"])
%% --- UPWARD GAIT LINES ---
A --> G1
C --> G2
%% --- G1 CONDITIONAL BIFURCATIONS ---
G1 -.->|"Revise"| A
G1 -.->|"Approved"| B
%% --- MAIN AUTOMATION HANDOFF ---
B --> C
%% --- G2 CONDITIONAL BIFURCATIONS ---
G2 -.->|"Fix Findings"| B
G2 -.->|"PR Approved and Merged"| D
/scope <n>: reads the issue, surveys the code, asks its open questions with a recommendation each, and writes one plan. You approve it (G1).build: a forked Sonnet subagent implements the plan one sub-phase at a time, with a check per sub-phase. It opens a draft PR, waits for CI and writes a handoff./review <n>: a fresh Opus session briefs a read-only red-team on the handed-off commit, triages its findings with the PR's comments, and brings you one report with numbered decisions (G2). It fixes what you approve and re-reviews once.- You merge; then
/close <n>cleans up.
Each step starts a new context from a file (the plan, the handoff), so no session carries the whole issue. A Small tier runs the same gates in one session for single-step issues. Hooks enforce the rest: no stop while checks fail, and no commit that leaves a doc stale. Permission rules, backed by a GitHub ruleset, rule out a merge or a force push.
The details are in Docs/01. The workflow.
From Evidence/research/13: 49 issue runs, each re-priced from its transcripts by one script (runs.js). 15 ran before the harness: 10 code issues on BabyBuddyHelper (.NET MAUI) and 5 docs issues on HarnessEngineering101. 34 ran with it, on BabyBuddyHelper, InvoiceMe (MERN) and ThisIsMatheusCastro (Next.js).
| Before the harness (10 code issues) | D24, Standard tier (5 issues) | D25, Standard tier (10 issues) | |
|---|---|---|---|
| Median cost per issue | $9.99 | $6.03 | $8.32 |
| Median main-session peak context | 291k tokens | 125k | 145k |
| Median owner messages per issue | 11 | 7 | 9 |
| Median lines added per issue | — | 243 | 795 |
- The biggest single change was running the build forked on Sonnet. Its cost stayed flat on D25's issues, about three times the size of D24's (builder median $1.02, against $1.11).
- D25 cost more than D24, and none of its own changes caused it. The review session made its G2 fixes on Opus at high context (+$0.78 per run), and planning took more rounds with the owner (+$0.51). D26, the version this repository now ships, sends those fixes to the forked builder.
- Quality held. No blocking finding was left at merge. The first escapes recorded, five doc lines that no longer matched the code, were caught by an Epic's knowledge audit, not by a user.
- Caveats:
- The costs are list-price equivalents; I'm on a subscription.
- The samples are small, with one owner, so the medians show direction, not effect size.
- The columns come from different repositories and issue sizes: the baseline is BabyBuddyHelper only, D24 is mostly InvoiceMe, and D25 is mostly ThisIsMatheusCastro, a new site.
- The Small tier is cheaper when nothing heavy follows the plan: a median of $3.99 on code issues and $5.37 on docs issues under D25.
- D26 is under validation.
Onboard/GET_STARTED.md covers:
- prerequisites;
- describing your project in a
harness.json; - installing with
Onboard/install.cjs, a dry run first; - writing your
CLAUDE.md; - a first issue, end to end.
Not on Claude Code? Platform_Neutral/ separates the ideas that carry over to any agent (the gates, the contracts, the fresh-context reviewer, the docs gate, pricing each run) from the Claude Code features used to build them. It also has a setup prompt for any agent.
- The owner decides; the agent recommends. Every open decision comes as options with one recommended, and nothing outside the plan gets built without asking.
- End the session at the gate. Cost tracks calls × context, so every block starts fresh from a file instead of carrying the conversation.
- The right model for each block. Opus plans and reviews; Sonnet builds and surveys.
- Review one commit, independently. The red-team never sees the builder's reasoning. A push after the handoff makes the review refuse.
- Enforce with code, not with prompts. Exit codes, gates and server-side branch rules, wherever a rule can be checked.
- Measure before claiming. Every change is judged on priced runs, and the data and the script are in the repo.
README.md this page
Docs/ reference: workflow, skills and agents, hooks and scripts, harness.json, installer
Onboard/ Get Started and the installer, install.cjs
Platform_Neutral/ the ideas without Claude Code, and a setup prompt for any agent
harness/.claude/ what gets installed: CLAUDE.md template, settings, skills, agents, hooks, scripts, lib
projects/<Project>/ each project's harness.json, install.json and vendored skills
test/ node --test suites for the hooks, scripts, installer and configs
Evidence/
OPTIMIZATION_PLAN.md the design record: decisions D1–D26, with § numbers the code cites
ADOPTION_PLAN.md how the harness was adopted in the two projects
research/ the measurements, pilot by pilot, and the pricing scripts
Independent_Assessments/ four other AI models' assessments of the first plan, and the reviews of them
harness_optimization_blueprint.md the starting proposal
Run the tests with npm test (Node 22 or later).
- HarnessEngineering101: the study repository this harness came out of.
- bruno-agent-pipeline: A mobile approach to Harness Engineering.
MIT. The vendored frontend-design skill under projects/InvoiceMe/vendor/ keeps its own license (Apache-2.0).