AI 原生开放教材

外观

AI Engineering Lab（24 周自学课程）系统课程·英文原文 ↗原件 ↓仓库 ↗

Week 12, Coding-Agent Harnesses: Claude Code, Cursor, OpenCode, DSH ​

Part of AI Engineering Lab · Week 12 of 24 · Section: Harnesses & Loops · Category: Harnesses

🎯 Use case: Build the ZoroLogistics ETA CLI entirely with a coding agent, from a written spec, in two harnesses, then compare them with numbers.

The problem ​

An operations analyst at ZoroLogistics has a shipment id and one question: "When did this actually arrive, and how late was it?" Today the answer means opening a notebook, importing zoro, and touching the data/shipments.csv that Week 1's generator produced, fine for you, useless for the analyst on the warehouse floor. The job this week is to turn that into a one-command tool, eta-cli S0000001, that prints the row and exits 0, or exits 2 with a clear stderr message when the id is missing.

The twist: you will not write most of it yourself. You will write a spec, hand it to a coding-agent harness, and steer the agent until its tests go green. Without this skill you are the bottleneck, every function typed by hand while the agent sits idle. Done wrong, the agent produces something confident and unchecked: it invents an ETA for a shipment that does not exist, and it looks brilliant right up until someone routes a real truck on the made-up number. The before/after is concrete: before, "shipment status" is a notebook you run for a colleague; after, it is a tested CLI a stranger can clone and run, built, per your spec, by a machine you directed.

Objectives ​

  • [ ] By Friday you can install and authenticate at least two harnesses (Claude Code + OpenCode or DSH) and confirm each with a version check from the shell.
  • [ ] By Friday you can write a SPEC.md an agent can execute, user, constraints, one refused tradeoff, and a six-point test plan for the ETA CLI.
  • [ ] By Friday you can drive an agent to build the CLI, run the tests, iterate until green, then repeat the same task in a second harness.
  • [ ] By Friday you can ship a one-page harness comparison (plan, tokens, cost, quality) backed by the comparison worksheet in the notebook.

Day-by-day plan ​

DayStudyRunShip (by end of day)Time
MonRead the four skill guides; skim KB 09Tool-check cell in the notebook2 harnesses installed + authenticated, version-checked~2 h
TueSPEC.md anatomy; the refused-tradeoff ideaCopy the template into specs/eta-cli-SPEC.md, fill every bracketA complete, reviewed spec~1.5 h
WedPlanning vs execution; verifiersDrive harness A to build the CLI; run the 6-point test planCLI with tests green in harness A~2.5 h
ThuCost control; OpenRouter model routingRe-run the same spec in harness B; fill the worksheetA filled comparison worksheet (plan/tokens/cost/quality)~2.5 h
FriHarness comparison write-upRe-run the final readiness celleta-cli + 1-page comparison committed~1.5 h

Concepts ​

Study this section before you open a terminal. It is the Week 12 heart: every manifest topic, in the order you will meet it, with the numbers you need to make the comparison real.

What a harness is ​

A model is not an agent. A model takes tokens in and returns tokens out. A harness is the software between the model and your machine that turns tokens into work. It supplies four things (KB 09 §1):

ComponentWhat it doesWhy it matters this week
The loopPlan → act → observe → verify → repeat until doneWithout a loop the agent stops after one answer
ToolsShell, file read/edit/write, search, MCP serversTools are how the model touches eta-cli and runs pytest
Context managementDecides what enters the window each turn, and when to compactThe difference between a focused build and a cost blowup
VerifiersTests, type checks, linters that say "still broken, try again"The signal that closes the loop, see below

Memorize the division of labor: the model supplies reasoning; the harness supplies agency. That is why two harnesses pointed at the same model produce different results, they differ on all four rows. The harness does not make the model smarter; it gives the model hands, memory, and a feedback signal.

Choosing a harness is a fit problem ​

"Which harness is best?" is the wrong question. The right one is "which surface matches how my team already works?" The four you touch this week:

HarnessBuilderSurfaceStrengthsCost model
Claude CodeAnthropicTerminal CLI + headless -pPolished daily driver; CLAUDE.md, subagents, hooks, MCP, permission sandboxPro/Max subscription or pay-per-token API
OpenCodeSSTTUI + desktop/web/IDETerminal-native, model- and provider-agnostic; AGENTS.md + opencode.jsonFree (MIT); you pay your provider
CursorAnysphereIDE (VS Code fork)Tab + multi-file Agent; Rules; Cursor Router (Cost/Balance/Intelligence)Free tier → Pro/Pro+/Ultra
DSHDeepSeekWeb GUI + CLI + headlessPlugin-everything (Cordis); skills, goals, subagents, workflows; append-only traceFree (MIT); you bring the model key

The decision rule of thumb from KB 09 §3: terminal-native and scriptable → Claude Code or OpenCode; agent living beside code you are editing → Cursor; a composable, inspectable open harness with a full trace → DSH. All four cost the same thing in the end, your model provider, so the decision is about workflow and control, not a price tag. Read the specifics in reference/skills/claude-code.md, reference/skills/cursor.md, reference/skills/opencode.md, and reference/skills/deepseek-harness.md before installing.

Rules files: the cheapest leverage you own ​

Every harness reads a project memory file at session start so it does not re-derive your conventions. Claude Code reads CLAUDE.md; OpenCode reads AGENTS.md; Cursor reads .cursor/rules/*.mdc. Same job, different filename. A good rules file compounds: the agent stops guessing your build command, and every teammate's agent follows the same conventions. Keep it a few dozen lines, written as commands, with four sections, what this repo is, commands, conventions, and a never-touch list (KB 09 §4).

The never-touch list is the single highest-value line, because it is where you encode blast radius in advance: data/raw/ (edit the generator, not the output), secrets/, .env, *.key. The rules file turns "please remember not to…" into something the harness enforces every session.

Managed context: what goes in, what stays out ​

The agent does not "know" your repo; it knows the slice you hand it. Managed context is the discipline of deciding what enters the window and what stays out (KB 09 §3). Feed it the spec, the rules file, and the few files that matter; keep the rest out.

Goes inStays out
SPEC.md, the rules file, the specific source file being editedThe whole data/ directory pasted into the prompt
The failing test outputSecrets and .env values
The relevant function + its call sitesUnrelated modules "for background"

The rule that makes this concrete: long context is not understanding, it is dilution, and it is also cost. Point at paths and let the agent open the rest itself rather than pasting everything up front.

Planning vs execution ​

Split every task into a plan (the spec: user, constraints, refused tradeoffs) and an execution (the edits). Run the harness in a plan-only mode first, read the plan, then authorize execution. Mixing the two is how an agent silently builds a different product than you asked for.

PlanningExecution
Question it answersWhat should exist, and what must not be traded awayHow to make it exist
ArtifactSPEC.md, the definition of doneThe diff + green tests
You ownThe spec's every lineThe review of every changed file
Agent's jobPropose the plan; you correct itEdit, test, fix until the verifier passes

The spec is not documentation for humans, it is the definition of done the loop closes against (KB 01 §3). That is the bridge to Week 13.

Subagents and parallelism ​

A subagent is a child the harness spawns to do a bounded piece of work in its own context, then report a summary back. Two reasons it matters (KB 09 §5): context isolation (a specialist reads a big file and returns only what matters, keeping your main context small) and parallelism (independent tasks run concurrently). Claude Code defines them under .claude/agents/; DSH exposes subagents, forks, and workflow-style fan-out. Use subagents for independent, clearly-scoped work, not to hide complexity you have not understood yourself.

OpenRouter and cost control ​

OpenRouter is a unified API that reaches hundreds of models with one key and one OpenAI-compatible endpoint, adding automatic failover and model switching by slug (reference/skills/openrouter.md). It is the routing layer behind a harness, and it is how you make the cost comparison honest. The levers, in order of impact (KB 09 §6): narrow the task, trim context, pick the right model per task (a small model for mechanical edits, a strong one for hard reasoning), use :free/local models for plumbing, cap the run, and cache.

Verifiers, SPEC.md, and blast radius ​

Three ideas close the loop this week and become Week 13's whole subject. A verifier is the executable statement of "done", the test suite, type checker, or linter that tells the agent "still broken, try again" (KB 01 §3). A SPEC.md names the user, the constraints, the one tradeoff you refuse, and the test plan that proves the build. A blast-radius rule decides how much autonomy you grant per action, not per session: reading a scratch file is nearly free to get wrong; writing production data is not, the same agent deserves a different leash on the two.

These three, plus the loop itself, are exactly the three loops of KB 01 and Zorost's artifact-gate philosophy in 07-zorost-skills-map-guide.md: Week 12 lives in loop one (agentic coding) and the start of loop two (developer feedback), you review the agent's diff with fresh eyes before you accept it.

The whole discipline is one steering loop:

mermaid
%%{init:{"theme":"base","fontFamily":"Helvetica Neue,Helvetica,Arial,sans-serif","flowchart":{"curve":"basis","padding":14,"nodeSpacing":45,"rankSpacing":55},"themeVariables":{"fontSize":"15px","background":"#FFFFFF","primaryColor":"#EEF2F7","primaryTextColor":"#14213D","primaryBorderColor":"#14213D","secondaryColor":"#FFF1E3","secondaryTextColor":"#14213D","tertiaryColor":"#E7F4F1","tertiaryTextColor":"#14213D","lineColor":"#64748B","textColor":"#14213D","edgeLabelBackground":"#FFFFFF","clusterBkg":"#F5F8FC","clusterBorder":"#94A3B8","nodeBorder":"#14213D","mainBkg":"#EEF2F7","titleColor":"#14213D"}}}%%
flowchart LR
    You[You] -->|write SPEC.md + rules file| H[Harness]
    H -->|plan| M[Model]
    M -->|"act: read / edit / run"| FS[Repo + shell]
    FS -->|observe output| H
    H -->|"verify: pytest / lint"| V{Verifier}
    V -->|red| M
    V -->|green| D[Draft diff]
    D -->|fresh-eyes review| You
    You -->|accept or reject| Ship[Commit + comparison note]

Worked example 1: a SPEC.md the agent can execute ​

This is the SPEC.md the notebook hands you (fill every bracket into specs/eta-cli-SPEC.md). The load-bearing line is the refused tradeoff:

markdown
# SPEC.md, ZoroLogistics ETA CLI
## User
A ZoroLogistics operations analyst who has a shipment id and wants, in one
terminal command, the planned vs. actual arrival and the delay.

## What it does
`eta-cli S0000001` prints: shipment_id, carrier_id, lane_id, commodity,
planned_arrival, actual_arrival, delay_hours, is_on_time.
Reads data/shipments.csv (generated Week 1, seed 42).

## Constraints
- Python 3.12, standard library + pandas only; no network, no API keys.
- Deterministic: same input → same output.
- `--json` emits the same fields as one JSON object.
- Unknown shipment id → exit code 2 + stderr message (never a fabricated row).

## Refused tradeoff
We refuse to trade correctness for a clean exit: the CLI must never invent an
ETA. Absent id or NaN arrival → exit non-zero and say so.

## Test plan (the verifier)
1. Known shipment → correct row, exit 0.  2. Unknown id → exit 2, no stdout row.
3. `--json` → valid JSON, exactly eight fields.  4. NaN arrival → non-zero exit.
5. Empty/missing CSV → non-zero exit.  6. `--help` → usage, exit 0.

Watch what the refused tradeoff does: it is the one place you tell the agent, in advance, where it is not allowed to resolve ambiguity by guessing. A confident wrong ETA is worse than an error, so the spec bans the "helpful" fabrication an eager agent will otherwise produce.

Worked example 2: the cost comparison, in numbers ​

The harness is free; the model is not. Here is a realistic two-harness build of the same SPEC.md, priced at illustrative OpenRouter rates (input/output, per 1M tokens):

HarnessTokens inTokens outRate (in/out)CostTests green first try?
A: Claude Code (Sonnet)52,00011,000$3.00 / $15.00$0.156 + $0.165 = $0.32Yes
B: OpenCode (deepseek-chat)61,00016,000$0.27 / $1.10$0.016 + $0.018 = $0.03No (2 cycles)

The arithmetic for harness A: (52,000 × 3.00 + 11,000 × 15.00) / 1,000,000 = (156,000 + 165,000) / 1,000,000 = $0.321. Harness B is roughly ten times cheaper but burned more tokens and needed an extra fix cycle, the cheap model wandered. The Friday comparison must report all three axes (plan, cost, quality) because a single axis names a false winner. Re-verify current per-token prices before quoting; they shift. (reference/skills/openrouter.md)

How it breaks ​

Every technique this week has a specific failure mode, and each one is a habit you are building against:

  • No verifier → the agent declares victory without running pytest; the ETA CLI "works" until a missing id crashes it in production.
  • Vague spec → the agent silently resolves your ambiguity and builds a different tool; you find out at the demo.
  • Context overload → you paste the whole repo "for background"; cost and latency spike, and the agent loses the thread it was supposed to follow.
  • No rules file → the agent uses the wrong test command or edits data/raw/ directly.
  • Comparison by vibe → "Harness A felt nicer" with no tokens, dollars, or first-try green/red recorded; that is an opinion, not a comparison.
  • Over-autonomy → you let it run against a production path instead of a branch, because you never wrote the never-touch list.
  • Trusting the plan without reading it → you authorize execution of a plan that already contains the wrong assumption.

The common thread: the harness is fast, but you own the commit. Speed multiplies whatever mistake you failed to catch upstream.

Notebook walkthrough ​

notebooks/01-harness-setup-and-comparison.ipynb is the Monday to Thursday spine. It runs with nothing but your Week-1 environment (numpy, pandas) and the local zoro package, no API keys, no GPU.

  • §0: What this lab is for sets the Mon→Fri map and explains the deliberate "unexciting" design: it checks tools, hands you a template, and records evidence.
  • §1: Tool check has two cells. The %%bash cell prints a version line (or a graceful not installed , see reference/skills/…) for claude, opencode, dsh, and ollama. The Python cell uses shutil.which to compute harness_readiness, the count of the three coding harnesses on your PATH, printed as 0-3.
  • §2: The SPEC.md template is a markdown cell you copy verbatim into specs/eta-cli-SPEC.md. Modify nothing but the brackets.
  • §3: The comparison worksheet is a pandas.DataFrame with one row per harness and columns plan_quality_1to5, tokens_used, cost_usd, tests_green_first_try, diff_files_changed, code_quality_1to5. Leave None until you run each build, then fill every cell, "it was fine" is not evidence.
  • §4: Cost-log helper defines log_cost(harness, task, tokens_in, tokens_out, cost_usd) and prints the running totals so Friday can quote a per-build cost instead of a vibe.
  • §5: Final metric recomputes harness_readiness in a standalone cell and prints a single number (e.g. 2).

Which cells you edit versus just run matters: §1, §2, and §5 are read-only (run them); the worksheet in §3 and the log_cost(...) calls in §4 are the fill-in cells you edit as you complete each build. Do not leave the worksheet's numeric columns None, that is the whole evidence base for the Friday write-up.

"Correct" output: the final cell prints a plain integer 0-3, the worksheet has no None left in the numeric columns, and you can point at the SPEC.md the number was produced from. A readiness of 2 or more means you genuinely compared two harnesses; below that, install one more per its reference/skills/ guide and re-run.

The use case (Friday) ​

Deliverable: (a) a working eta-cli built from specs/eta-cli-SPEC.md with all six test-plan points green, and (b) a one-page harness comparison for your team.

Zorost gate: a stranger can clone your fork, run eta-cli S0000001 and see the correct row, and run eta-cli S9999999 and get exit code 2 with a clear stderr message, never a fabricated ETA, and you can show them what the agent did: the spec you wrote, the refused tradeoff it respected, and a comparison table that names which harness produced the better plan, at what token/dollar cost, and why. No spec, no refused tradeoff, no ship.

Stretch variant: add a --by-carrier CARRIER_ID filter that aggregates delay stats (mean, p95) for one carrier, specified in the same SPEC.md style, built by the losing harness from your comparison, then explain whether the underdog closed the gap when the task got harder.

Common pitfalls ​

PitfallFix
Agent "finishes" but tests were never runPut the exact pytest -q command in the rules file; require green before accept
CLI fabricates an ETA for a missing idThe refused-tradeoff line + test-plan point 2 (exit 2)
Build cost spikes mid-taskNarrow the task; point at specific files; /compact; smaller model for edits
Agent edits data/raw/ or reads .envNever-touch list in CLAUDE.md/AGENTS.md; a PreToolUse hook
Comparison is a paragraph of vibesFill every worksheet cell; quote tokens + dollars + first-try green/red
Plan looks right but is wrongRead the plan before authorizing execution; correct it, then run
Two harnesses "behave the same" because both were vagueReuse the identical SPEC.md; change only the harness
Version/usage drift between runsPin the model slug; record model + rates in the cost log

Glossary ​

  • Harness: the software (loop, tools, context, verifiers) that turns a model into a working agent.
  • Rules file: persistent project instructions (CLAUDE.md, AGENTS.md, .cursor/rules) read at session start.
  • Managed context: the discipline of choosing what enters the model window and what stays out.
  • Verifier: an executable check (test, lint, type check) that decides whether the work is done.
  • SPEC.md: the written definition of done: user, constraints, refused tradeoff, test plan.
  • Refused tradeoff: the one place you forbid the agent from resolving ambiguity by guessing.
  • Blast radius: how much damage an action can do if it is wrong; the leash per action, not per session.
  • Subagent: a child agent doing bounded work in its own context, returning a summary.
  • Headless mode: running the agent without a REPL (claude -p), for CI and scripts.
  • OpenRouter: a unified API/router over many models; one key, switch models by slug.
  • :free variant: a rate-limited, zero-cost model tier for testing plumbing, not production.
  • Harness-readiness score: the notebook's 0 to 3 count of installed coding harnesses.

Self-check (quiz) ​

Take quiz.md, 10 questions on concepts and notebook code, 8/10 to pass.

Exercises ​

Four graded exercises (easy / standard / stretch / portfolio) live in exercises.md: run the notebook to a score, fill the SPEC.md and drive one harness, repeat in a second harness and compare, then commit the CLI + comparison. Hints are in the same file.

Sources ​