DEV Community: ShipWithAI

Git Worktrees for Agents: Parallel Loops Without Chaos

ShipWithAI — Thu, 27 Aug 2026 01:30:00 +0000

TL;DR — The moment a loop runs more than one agent, files collide. Worktrees remove the mechanical collision (each agent gets its own working directory); the maker/checker split removes the quality collision (no agent merges its own work). Use a three-role fleet: explorer, implementer, verifier. And the ceiling on fleet size isn't the tool — it's your review bandwidth.

Part 5 of the Loop Engineering series on ShipWithAI. Read the full article →

Two agents, one directory, two different disasters

The failure isn't one thing. It's two, and they need different fixes:

	Mechanical collision	Quality collision
Symptom	Corrupted tree, broken merge, lost edits	Plausible-but-wrong change lands unreviewed
Cause	One working directory, racing writes	Author is also the only reviewer
Fixed by	Worktree per lane	Maker/checker split

That second fix isn't house style, by the way — it's the evaluator-optimizer pattern from Anthropic's Building Effective AI Agents, where a generator and a separate evaluator pass work back and forth until the evaluator is satisfied.

Two agents in one directory is two engineers sharing one keyboard. The problem was never the agents, it was the missing isolation and the missing review.

Worktree vs branch — the distinction people get wrong

Straight from the FAQ, because this trips up a lot of people:

A branch is a pointer in history; a worktree is a separate checked-out directory for a branch. Two agents can be on two branches but still fight over one working directory.

Branches alone do not save you. Worktrees give each agent its own files on disk, which is what actually prevents the racing-write collision.

And in a loop, you don't create worktrees — you declare them:

# fleet config: each implementer lane runs isolated
- role: implementer
  isolation: worktree     # orchestrator provisions a private worktree + branch per lane
  on_exit: auto-cleanup   # finished or failed, the dead lane's worktree is removed

In an interactive session you create a worktree; in a loop you declare one and let the orchestrator provision and reap it. The difference is who cleans up when no one is watching.

Note this is opt-in. Subagents don't get isolation automatically — without isolation: worktree, every lane shares one directory, which is exactly the collision you're trying to avoid.

The three-role fleet

Explorer — finds work, emits a list of independent findings. It does not fix anything; it produces the work list the fleet fans out over.
Implementer (maker) — takes one finding, produces a diff in its own worktree. One implementer per lane, one finding per implementer.
Verifier (checker) — reviews that diff against a verifiable stop condition, returns accept or reject.

Parallelism is for independent findings; the pipeline within a finding is always serial. An implementer that grades its own diff is not a fleet, it is one agent wearing two hats.

When to parallelize, when to serialize

Situation	Decision
Findings touch different files, no shared state	Parallelize
Stage B needs stage A's output	Serialize
Two findings edit the same file	Serialize (one lane)
Later finding depends on an earlier merge	Serialize

Note the asymmetry: you fan out across findings, never inside one.

The hands-on run

Read the caveat first. The author is explicit: this is a mechanism proof, not a Haiku-graded autonomous fleet. The maker step is a deterministic edit rather than an LLM agent turn, and nothing was instrumented, so there are no token figures to report (run dated 2026-06-15). What it proves is that the orchestration plumbing — isolate, make, check, merge, reap — works as described.

Worth skimming Part 3 and Part 4 first, and knowing what a worktree is — the article deliberately doesn't re-teach the git mechanic.

Two independent bugs:

Finding A — mathutil.add(a, b) returns a - b. Fails test_mathutil.py::test_add
Finding B — strutil.shout(s) returns s.lower(). Fails test_strutil.py::test_shout

Isolate:

$ git worktree add ../wt-finding-a -b fix/finding-a
$ git worktree add ../wt-finding-b -b fix/finding-b
$ git worktree list
/home/you/p5-fleet      25ee424 [master]
/home/you/wt-finding-a  25ee424 [fix/finding-a]
/home/you/wt-finding-b  25ee424 [fix/finding-b]

Make — each lane edits only its own file:

# in wt-finding-a
 def add(a, b):
-    # BUG (Finding A): returns difference instead of sum
-    return a - b
+    # FIX (Finding A): correct sum
+    return a + b

Lane B gets the same treatment on strutil.py. And the isolation is real, not asserted — from inside lane A, lane B's file is still broken:

$ git show HEAD:strutil.py      # in wt-finding-a
def shout(s):
    # BUG (Finding B): lowercases instead of uppercasing
    return s.lower()

Check — each verifier runs only its lane's test:

$ pytest -q test_mathutil.py    # in wt-finding-a
1 passed in 0.00s               # exit 0
$ pytest -q test_strutil.py     # in wt-finding-b
1 passed in 0.00s               # exit 0

Merge — both lanes land in one state file (Part 4's schema), findings moving open → tried + passed:

## tried
- [finding-a] worktree wt-finding-a / branch fix/finding-a: maker edited mathutil.py (a-b to a+b)
- [finding-b] worktree wt-finding-b / branch fix/finding-b: maker edited strutil.py (lower to upper)

## passed
- [finding-a] test_mathutil.py::test_add green in wt-finding-a (checker pytest exit 0)
- [finding-b] test_strutil.py::test_shout green in wt-finding-b (checker pytest exit 0)

## open

## blocked

The merge is the moment of truth. Two isolated lanes are only useful if their results land in one place the next run can read, and that place is the state file from Part 4.

Reap:

$ git worktree remove ../wt-finding-a
$ git worktree remove ../wt-finding-b
$ git worktree list
/home/you/p5-fleet  25ee424 [master]

If a lane fails mid-run and you have on_exit: auto-cleanup set, its worktree is removed so the loop doesn't accumulate orphan directories across iterations — and the finding stays open (or moves to blocked), so the next run retries without re-deriving what already happened.

The orchestration tax

Every lane you add is a trade, not a free win:

Per lane added	Effect
Token cost	Up (≈ N× per-agent cost + orchestration overhead)
Wall-clock to results	Down (lanes run concurrently)
Your review load	Up (every green diff still needs a human merge)

That third row is the one that bites.

Worktrees and checkers let you run more agents. Your review bandwidth decides how many you should. The tool's ceiling and your ceiling are not the same number, and yours is lower.

The rule of thumb: if you can honestly review N PRs a day, run at most N lanes. The author flags this as his own framing — a heuristic, not a measured constant. Calibrate it to your team.

Prior art

Plus Anthropic's Building Effective AI Agents for the evaluator-optimizer pattern that the maker/checker split descends from.

Try it this week

Take two genuinely independent bugs. Give each its own worktree and branch. Have something other than the fixer run the test. Merge both into one state file, then reap the worktrees.

If you can't name why the two findings are independent, you have one lane, not two.

This is a condensed summary. The full article has the complete fleet walkthrough, both diffs, and the FAQ on failure handling and fleet sizing:

👉 Git Worktrees for Agents: Parallel Loops Without Chaos — Part 5, ShipWithAI

Earlier: Part 1 — Why You Should Stop Prompting · Part 2 — Anatomy of a Loop · Part 3 — Stop Conditions · Part 4 — State File Pattern

Next: giving the fleet a heartbeat — scheduled discovery, and runs that archive themselves.

Give Your Agent Loop a Heartbeat: Scheduled Automation Without the Runaway Bill

ShipWithAI — Tue, 25 Aug 2026 01:30:00 +0000

TL;DR — A loop earns its name when it runs on a cadence you didn't trigger. Three heartbeats: in-session /loop (you're at the keyboard), cloud Routines (cron, laptop closed), and CI (GitHub Actions). Pick by where the work lives and who needs to be awake. Then: route findings to an inbox a human reads, and make the empty run nearly free — because on a daily cadence, the empty run is the common case.

Fourth post in my **Loop Engineering* crosspost series here — it summarizes Part 6 of the original series on ShipWithAI. (I'm jumping ahead: Parts 4 and 5 over there cover state files and worktrees, and this one builds on both. Links at the bottom.)*

Read the full article →

Three heartbeats

Heartbeat	Trigger	Laptop state	Best fit
In-session `/loop`	A prompt re-run on an interval	Open, you're at the keyboard	An attended sweep you babysit
Cloud Routines	5-field cron on Anthropic infra (daily cap on runs started)	Closed	The true overnight or morning cadence
CI (GitHub Actions)	`on: schedule` or push in a workflow	Off (runs on a runner)	When the work is the repo and the team lives in CI

The schedule is the easy half. A cron job that runs a fixed script is just cron; a cron job that runs a decision-maker is a loop. Pick the heartbeat by who needs to be awake: you, no one, or the CI runner.

The article opens with Matt Van Horn's line: a loop is cron plus a decision-maker in the body. The schedule is the trivial half. Each run reads state, decides what to do, and updates that state, so the next run continues where this one stopped instead of repeating a static command.

One planning detail that's easy to miss: cloud Routines carry a daily cap on how many runs can start. If your cost model assumes you can just dial frequency up, that cap is the ceiling.

Hook or schedule?

Trigger type	Fires when	Example	Hook or schedule
Lifecycle	Something happens in a session	A tool runs; a stop is attempted	Hook
Time	The clock ticks, regardless	06:00 weekdays; every push	Schedule

A hook is a reflex; a schedule is a heartbeat. Reflexes fire when something happens. A heartbeat fires whether or not anything did, which is exactly why a scheduled loop needs the triage inbox next.

Many loops use both: a schedule wakes the loop, hooks govern each turn inside it.

The triage inbox — the part that keeps this safe

scheduled run
  |
  |-- findings?  -->  inbox (state file / issue / PR)  -->  human decides  --> merge
  |                        (the loop never merges its own findings)
  |
  '-- nothing?   -->  archive "nothing today"  -->  exit cheap

An unattended loop is allowed to find work and allowed to do the boring parts. It is never allowed to decide what ships. The inbox is where the loop stops and you start.

The article calls auto-merge "the cardinal sin of unattended automation," while flagging that the inbox pattern is its own synthesis rather than a cited standard — it just considers it the single most important discipline in the post. Discovery is automated; the decision stays human.

The morning triage loop

Two failing tests in yesterday's CI — a real pytest suite, two genuine independent failures (slugify leaving a trailing hyphen, load_port returning a string instead of an int) — plus three open issues, two of which map to those failures.

The schedule, as a GitHub Actions workflow:

name: morning-triage
on:
  schedule:
    - cron: "0 6 * * 1-5"   # 06:00 on weekdays, the heartbeat
  workflow_dispatch: {}
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run morning triage (discover, write inbox, open lanes)
        run: python3 triage/triage.py --budget-runs 1 --max-lanes 2

Or the same beat as a plain crontab line:

0 6 * * 1-5 cd /home/you/p6-triage && /usr/bin/python3 triage/triage.py --max-lanes 2 --budget-runs 1 >> $HOME/.morning-triage.log 2>&1

Now the honest part, and read it before the output: nothing scheduled actually fired. The sandbox has no cron daemon, so the cron line — the real artifact you'd install — was never triggered by cron. Instead the exact triage step the cron line invokes was run directly, which is what the heartbeat executes either way. Same for the Actions workflow: not a cloud-executed run.

So, the triage step invoked by hand — note what it refuses to do:

$ python3 triage/triage.py --max-lanes 2 --budget-runs 1
TRIAGE: 3 findings; opened 2 lanes; 1 left in inbox; passed=0 (never auto-merge)

$ git worktree list
/home/you/p6-triage        242b6dc [master]
/home/you/wt-finding-14    242b6dc [triage/finding-14]
/home/you/wt-finding-15    242b6dc [triage/finding-15]

Ranking logic: CI-red bugs above issue-only, bugs above features, top two get lanes. Finding #19 (a feature request) stays in the inbox with no lane.

And the resulting state file, in Part 4's tried/passed/open/blocked schema:

# Loop State: morning triage (Part 4 schema)

## tried
- read CI: 2 failing test(s); read issues: 3 open
- opened 2 worktree lane(s) for the top 2 finding(s)

## passed
- (none; triage never merges; a human decides what ships)

## open
- [#14 CI-red: tests/test_slugify.py::test_trailing_hyphen] lane opened: /home/you/wt-finding-14 on triage/finding-14 (awaiting human)
- [#15 CI-red: tests/test_config.py::test_port_is_int] lane opened: /home/you/wt-finding-15 on triage/finding-15 (awaiting human)
- [#19 [feature] add a --version flag to the CLI] in inbox, no lane (below top-2)

## blocked

The ## passed section being empty is not a bug. It's the design.

The morning loop is the whole series in one run: a schedule wakes it (Part 6), a stop condition bounds it (Part 3), the findings land in the state file (Part 4), and the top two get worktree lanes (Part 5). The cadence is the only new part.

To restate the caveat plainly: this is a mechanism proof. Neither a live cloud-Routine nor a cloud-executed Actions run is cleanly capturable headlessly — the same limit documented in the Part 3, 4, and 5 traces. And the decision-maker here is deterministic ranking logic, not an LLM agent turn, so nothing was instrumented and there's no token or cost figure to report.

The empty run is your real cost

Here's the clean-morning case:

$ python3 -m pytest -q
..                                    [100%]
2 passed in 0.00s

$ python3 triage/triage.py --max-lanes 2 --budget-runs 1
EMPTY RUN: 0 findings -> archived 'nothing today', exit cheap

On a daily cadence, the empty run is the common case, so the empty run is your real cost. Cap every run and make "nothing today" nearly free, or the heartbeat quietly drains the budget while you sleep.

Four kill switches, bounding every run rather than just the whole job:

Kill switch	What it bounds	Failure it prevents
`--max-runs`	Iterations per invocation	An infinite re-run loop
`--max-cost`	Dollars per run	A runaway bill overnight
`--max-duration`	Wall-clock per run	A hung run that never exits
`--stall-threshold`	Iterations with no progress	Spinning without converging

Prior art worth a look

nightcrawler — autonomous overnight research loop, episodic execution with a per-run episode budget
agentics — frames "Continuous AI" as GitHub Actions workflows
Tmux-Orchestrator — self-scheduling agents; dormant since mid-2025, but instructive

Try it this week

Pick your beat by who needs to be awake. Write the discovery step. Then — before you schedule anything — write the inbox, and confirm your loop has no path to merge.

Then time the empty run and multiply by your cadence — weekdays at 06:00 is ~261 runs a year. A daily cadence multiplies cost by frequency, and the empty run is what you're multiplying.

This is a condensed summary. The full article has the step-by-step build, worktree cleanup, and the FAQ on cron vs Routines vs CI:

👉 Scheduled Agent Automation: Give Your Loop a Heartbeat — Part 6, ShipWithAI

Read the two I skipped first if you want the full build — this post leans on both: Part 4 — State File Pattern (the tried/passed/open/blocked schema) and Part 5 — Git Worktrees for Agents (the lanes).

Earlier in the series: Part 1 — Why You Should Stop Prompting · Part 2 — Anatomy of a Loop · Part 3 — Stop Conditions

Next up: the journey log of retrofitting all of this onto a real, messy first loop — the start of the practice phase.

Your Agent Loop Is Lying About Being Done: Writing Verifiable Stop Conditions

ShipWithAI — Sun, 23 Aug 2026 01:30:00 +0000

TL;DR — A loop is only as trustworthy as its stop condition. "Done" has to be checkable by a different model — tests pass, lint clean, schema validates — never the worker's own claim. Below: why self-grading fails, the four rungs of verification, a checker-agent template you can copy, and the three caps that stop a loop running forever.

Part 3 of the Loop Engineering series on ShipWithAI. Read the full article →

Part 2 gave you the parts list. Part 1 promised this installment would be entirely about designing stop conditions, "because they are the hardest part to get right." Here it is.

The thesis, in one line:

A loop that grades its own work will tell you it is done before it is.

Why self-grading fails

A stop condition is a claim about reality. If the agent that wrote the code is the only thing asserting the claim, you don't have a verification — you have a self-report.

The author's framing: a maker grading its own output is structurally optimistic, so it declares victory early. And this has a name — Anthropic's own writeup on building effective agents lists the failure mode explicitly: premature victory and fake-done features.

The four rungs

The rungs are an escalation of who checks:

Rung	Mechanism	What it adds over the rung below
1	Bare `while ! npm test; do claude -p ...; done` + iteration cap	A machine-checkable exit code as the gate
2	Stop hook (`exit 2` or `{decision:"block"}`)	Blocks completion until the check passes
3	`/goal` — a separate model grades each turn	A grader that is not the maker
4	Scheduled goal runs (Routines)	The condition is re-checked unattended

Rung 1 checks with an exit code, rung 3 checks with a second model, and the gap between them is exactly the maker's optimism.

Worth knowing the mechanics of rung 2 vs 3: a Stop hook blocks completion with exit 2 until a check passes, and Claude Code auto-overrides after 8 consecutive blocks. /goal (v2.1.139+) instead has a separate model — Haiku — grade the stop condition each turn.

Rewriting a wish into a condition

"Run until the feature is done" is not a stop condition, it is a wish. A stop condition is a command with an exit code.

Bad condition	Why it fails	Verifiable rewrite
"the feature is done"	Not falsifiable, no check	"all tests in `test/auth` pass AND lint clean"
"code looks good"	Not verifiable by a machine	"`passes: true` for every story in `prd.json`"
"the bug is fixed"	No boundary	"the new regression test exits 0 and no other test breaks"

The three-attribute test for any condition you write:

Verifiable — something can confirm it (a command, a count, a second model)
Falsifiable — it can fail, with a clear failing signal
Cheap — you can evaluate it every single turn

That last one is the one people underrate — "cheap" here means literally you can run it every turn, not that it's nice to have.

The checker agent

Copy this. The whole design is in what it's forbidden from doing:

---
name: stop-condition-checker
description: Grades whether the loop's stop condition holds. Not the maker.
model: haiku
---

You verify, you do not fix. Run the project's check command and report only:

- PASS if `bash tests/run.sh` exits 0 AND `bash scripts/lint.sh` exits 0
- FAIL otherwise, with the first failing line

Never edit code. Never report PASS on the maker's say-so; run the command.

The checker's value comes entirely from not being the maker. Different instructions, a cheaper model, and a clean context each turn are what make its PASS mean something.

The article's actual prescription: a checker with different instructions, optionally a different model, and ideally a clean context each turn. The different model is an option, not the requirement — the requirement is not being the maker. Splitting maker from checker is called "the single highest-leverage move in loop design."

One real trade-off worth knowing: the official ralph-wiggum plugin runs the checker in the same session as the maker, and the community has flagged that this deviates from fresh-context Ralph, where each lap starts clean. The article doesn't pick a side — same-session is cheaper; fresh-context is harder to fool. Pick deliberately.

The hands-on run

Read the disclaimer first, because it's the most useful part. The run did not use rung 3. /goal was the natural fit, but it's an interactive in-session grader and the author wanted a captured, reproducible run — so he used the rung-1 bare-loop equivalent: a fresh-context claude -p as the maker each turn, and the bash test exit code as the checker. An honest maker/checker split, graded by a machine-checkable artifact rather than by Haiku. He also notes token and dollar cost weren't instrumented, so he won't quote a number he doesn't have.

The bug, in ShipWithAI's content-agent repo: scripts/check-draft-seo.sh compares every keyword word against only the title's first three words — so any keyword longer than three words gets flagged, even when it leads the title verbatim.

The failing test:

⚠ keyword_placement: keyword "how to build an agent loop": not in title first 3 words
FAIL: multi-word keyword that leads the title was wrongly flagged.
exit=1

The stop condition — note that it guards against collateral damage, not just the target bug:

bash tests/test-check-draft-seo-multiword-keyword.sh exits 0
  AND bash scripts/test-rubric.sh still exits 0

The fix, one line of real logic:

all_title_words = re.findall(r"[A-Za-z...]+", title.lower())
kw_words = re.findall(r"[A-Za-z...]+", kw_lower)
title_words = all_title_words[:max(3, len(kw_words))]

Result: one fresh-context maker turn. Pass on turn 1, cap of 8 never reached. He also ran a control draft to prove the fix isn't just a check that now always passes — worth copying as a habit.

The loop stopped because a command exited 0, not because the agent felt finished. That is the only kind of "done" you can leave a loop alone with.

Cap it three ways

The stop condition says when to stop on success. The cap says when to stop anyway. A loop you trust has both.

Max iteration count — claude -p --max-turns N, plus the Stop hook's 8-block auto-override
No-progress detection — continuous-claude's --stall-threshold
Budget ceiling — --max-cost and --max-duration

For lived precedent: ShipWithAI's own content-agent review loop caps at 3. The hands-on run above capped at 8. Pick per job, not by rule.

Before you try this

A working harness and a minimal loop you can already run
Claude Code v2.1.139+ for /goal
A repo with a test command that exits non-zero on failure

Try it this week

Take the loop you built after Part 2 and ask one question: who asserts that it's done? If the answer is "the same agent that did the work," you haven't reached rung 1 yet.

Write the condition as a shell command. Add a second agent whose only job is to run it. Then pick your three caps.

This is a condensed summary. The full article walks each rung with working config, the complete hands-on trace, and the FAQ on /goal vs Stop hooks:

👉 Stop Conditions: Making "Done" Mean Something — Part 3, ShipWithAI

Earlier: Part 1 — Why You Should Stop Prompting · Part 2 — Anatomy of a Loop. Part 4 — Memory Outside the Context Window — ships next.

Anatomy of an Agent Loop: 5 Building Blocks and One Memory Spine

ShipWithAI — Fri, 21 Aug 2026 01:30:00 +0000

TL;DR — An agent loop is five blocks doing work plus a memory spine that makes the work cumulative. Drop the spine and you have automation that forgets every morning. Below: the map, the primitive each block maps to in Claude Code, and a real lint-sweeper loop that cleared 3 structural findings in 2 iterations / 124 seconds.

Part 2 of the Loop Engineering series on ShipWithAI. Read the full article →

Part 1 argued why you should stop prompting turn by turn. This one is the parts list.

Working definition, unchanged: a loop is a recursive goal — you define a purpose and a verifiable stop condition, and the system iterates agents against it until the condition holds, without you prompting each turn.

The map

1. Scheduled automation (heartbeat)

2. Worktrees            3. Skills
          \             /
          [ MEMORY SPINE ]   <- state on disk, survives runs
          /             \
5. Sub-agents       4. Plugins / connectors

The framing is Addy Osmani's. Each block maps to something you already have:

#	Block	Claude Code primitive	What it's for
1	Scheduled automation	`/loop [interval]`; Routines for cloud cron	Re-running a check on a cadence
2	Worktrees	`isolation: worktree` in agent frontmatter	Parallel work without file collisions
3	Skills	`SKILL.md`	Externalizing project intent
4	Plugins / connectors	Plugins and MCP servers	Reaching real tools (GitHub, CI)
5	Sub-agents	Files in `.claude/agents/`	The maker/checker split

On block 1 — /loop re-runs a prompt on an interval while your session is open. Routines run cloud-scheduled on cron with the laptop closed (there's a per-account daily cap). Different tools, same job.

Nothing here is exotic. The skill is assembly: picking which blocks a given job needs and wiring them around one state file.

The spine is the part people skip

The five blocks do the work. The spine is what makes the work cumulative.

Concretely: a small file on disk that survives between runs. Greppable, versioned, boring. snarktank/ralph (14.3k stars) does it with git plus a progress.txt and a prd.json.

Without it, iteration 4 has no idea what iterations 1 through 3 already tried. That's not a loop, that's a cron job with amnesia.

A real, minimal loop you can copy

The spec uses the standard kickoff template (from the loops.elorm.xyz card format), which fits the /goal contract:

# lint-sweeper.loop

goal:        "flake8 --extend-ignore=E501 scripts/*.py exits 0"
max_iterations: 5
between_iterations_check: "flake8 --extend-ignore=E501 scripts/*.py"
exit_when:   "check exits 0  OR  iteration == max_iterations"
one_step:    "fix one batch of findings (batch = one file), then re-run the check"
self_pace:   "stop as soon as exit_when holds; do not keep going"
state_file:  "drafts/lint-sweeper-state.md"

And the spine it writes to, at iteration 0:

goal: flake8 --extend-ignore=E501 scripts/*.py exits 0
cap: 5 iterations
iteration: 0

## open
- gen-agent-map.py:19 F401 'os' imported but unused
- gen-dist-metadata.py:23 E301 expected 1 blank line
- gen-dist-metadata.py:27 E301 expected 1 blank line

## fixed
## skipped

Note what goal is: a shell command and its exit code, not an English sentence about quality. As the article puts it — the check is the stop signal, so it must be machine-checkable.

What actually happened when it ran

Two honest caveats from the author before the numbers. This ran on the Python scripts in ShipWithAI's content-agent plugin repo, because shipwithai.io has no lint command — a substitution he flags himself. And flake8 actually reported 41 findings; 38 were E501 (line-too-long), which is noisy and subjective, so the verifier was scoped to the 3 real structural defects.

Baseline:

$ flake8 --extend-ignore=E501 scripts/*.py
scripts/gen-agent-map.py:19:1: F401 'os' imported but unused
scripts/gen-dist-metadata.py:23:5: E301 expected 1 blank line, found 0
scripts/gen-dist-metadata.py:27:5: E301 expected 1 blank line, found 0

After iteration 1 — one file's worth of findings gone:

scripts/gen-dist-metadata.py:23:5: E301 expected 1 blank line, found 0
scripts/gen-dist-metadata.py:27:5: E301 expected 1 blank line, found 0

After iteration 2:

# no output, exit 0

Final tally: 3 structural findings → 0, in 2 of 5 allowed iterations, 124 seconds wall-clock. Clean exit — it never touched the cap. Total damage: 2 files changed, 2 insertions, 1 deletion.

Reading the trace

This is the part worth internalizing. Each block leaves a fingerprint:

Heartbeat — fired the check 3 times (baseline + 2 iterations)
Verifier — gated each iteration on flake8's exit code. Exit 1 → continue. Exit 0 → stop.
Memory spine — recorded each finding moving open → fixed, tagged by iteration
Maker — produced the diff, handed it to the verifier
Worktrees and plugins/connectors — never used

The article is careful here, and so should you be: this run used a single agent with the lint exit code as the checker. The real sub-agent maker/checker split — where a separate agent grades the work — is Part 3 and Part 5 material. It's named in the map, not claimed in the trace. Four pieces exercised, two honestly skipped.

The trace is how you debug a loop. Each block leaves a fingerprint, and the verifier's exit code, not the agent's confidence, is what ends the run.

What breaks when a block is missing

Missing	Symptom
Verifiable stop condition	The loop declares false victory
Memory spine	Every run starts from zero, no resume
Worktrees / maker-checker	Parallel agents collide on the same files
A real heartbeat	You have a script you ran once, not a loop

Each of those gets its own part later in the series — the heartbeat one is Part 6.

Before you try this

A working harness — CLAUDE.md, at least one skill, a hook or two
Claude Code v2.1.139+ for /goal
A repo with a lint command that exits non-zero when it should

And no, you don't need worktrees for a single-agent loop. They earn their place once more than one agent touches the repo. The lint sweeper ran fine without one.

Try it this week

Pick the smallest thing in your repo where "done" is already an exit code — lint, a type-check, one failing test. Write the spec (goal, cap, check command, exit condition, one-step, self-pace). Add the state file. Cap it at 5.

If it exits clean before the cap, you've built a loop. If it declares victory while the check still fails, your stop condition isn't verifiable — which is exactly what Part 3 is about.

This is a condensed summary. The full article walks the setup step by step, shows the full diff, and answers the /loop vs Routines and do-I-need-worktrees questions:

👉 Anatomy of a Loop: Five Building Blocks and One Spine — Part 2, ShipWithAI

Missed Part 1? Loop Engineering: Why You Should Stop Prompting. Part 3 — Stop Conditions: Making "Done" Mean Something — ships next.

Stop Prompting, Start Designing Loops: The Fourth Era of AI Coding

ShipWithAI — Wed, 19 Aug 2026 01:00:00 +0000

TL;DR — Prompting turn-by-turn is now the bottleneck, not the skill. A loop replaces it with three things: a recursive goal, a verifiable stop condition, and unsupervised iteration. Is it a rebranded cronjob? Mostly yes — except for the one organ cron doesn't have. Before you build one, run the six-item harness checklist at the bottom.

This is a summary of Part 1 of the 9-part Loop Engineering series on ShipWithAI. Read the full article →

Four eras, and each one moved the skill upward

Every shift in AI-assisted coding moved the unit of leverage one layer up the stack:

Era	Unit of leverage	Your job
Prompt	Words in one message	Phrase the request well
Context	What the agent reads	Curate CLAUDE.md, docs, memory
Harness	The agent's runtime	Build guardrails, hooks, verification
Loops	The system running the agent	Define the goal + the stop condition

The important part: loops do not replace harnesses. They wrap them. The harness was the floor — a loop is that floor running on a timer, feeding itself.

Which also means the failure mode is obvious in hindsight. The same loop that multiplies a careful engineer's output multiplies a careless engineer's slop.

What actually counts as a loop

The canonical definition has three parts, and dropping any one of them gets you something else:

A recursive goal — a stated purpose with observable progress
A verifiable stop condition — checkable by a machine or by a different model, never by the worker's own say-so
Unsupervised iteration — it runs without you prompting each cycle

Matt Van Horn's plain version is the one worth memorizing: cron plus a decision-maker in the body.

"It's just a cronjob with a rebrand"

The honest answer is mostly yes — the original essay concedes this up front rather than swatting it away, because the minimal viable loop genuinely does look like one. Geoffrey Huntley's Ralph, from July 2025:

while :; do cat PROMPT.md | claude-code; done

That's the whole thing. So where's the difference?

	Cron	Loop
Execution	Fixed script on a schedule	Adaptive iteration
Termination	Exits when the script finishes	Exits when a condition is verified
Judging "done"	None — implicit in script exit	A decision-maker evaluates it

The decision-maker is the whole ballgame — the skeptics are right about everything except that one organ. It reads current state, picks the next action, and judges completion. Cron cannot recognize success. A loop is built on recognizing it.

The anti-pattern: "run it day and night until the feature is done"

This sounds ambitious. It is actually the single most reliable way to get fake-done work.

Anthropic's November 2025 guidance on long-running agents flagged exactly this: agents without a verifiable stop declare victory prematurely and hand you features that are confidently broken.

Compare:

❌ "Run until done" — subjective, unbounded, unfalsifiable
✅ "Iterate until the failing test passes, capped at N runs" — machine-checkable and bounded

The fix is a stop condition someone other than the worker can check — a test, a lint gate, a schema, or a separate model grading the result.

One nuance people get backwards: the caps are not the stop condition. Iterations, cost, and wall-clock time are safety rails. The condition is the goal. If your only stop is max_iterations, you don't have a loop — you have a budget.

Where the engineer's job goes

What disappears: typing "fix the tests again" for the fourth time.

What doesn't disappear — and gets more important:

Verification stays yours to design. No loop should grade its own homework — that's the failure mode every source in the essay converges on.
Loop design assumes a working harness underneath it. Skip that and you've automated your weaknesses.

The original piece owns up to this with a first-person example: a maker agent in ShipWithAI's own content pipeline fabricated a plausible CEO quote, passed its own self-check, and was only caught by an independent fact-checker pass before publish. Small blast radius, same organ failure.

Boris Cherny — who created Claude Code, deleted his IDE in November 2025, and shipped 259 PRs in 30 days with 100% written by Claude Code — runs a recurring /loop 5m /babysit command alongside explicit self-verification. His rule: give Claude a way to verify its work, credited with a 2–3x quality difference.

The six-item harness readiness checklist

Run this against your repo before you write a single loop:

Conventions written down — do they live in CLAUDE.md/skills, or only in your head?
Non-negotiables are mechanical — do hooks enforce the rules, or do you catch violations in review?
"Done" is machine-checkable — is there a failing test, lint gate, or schema check?
State survives dead sessions — does progress persist in files the next run reads?
Two agents can share the repo — can they work without colliding (worktrees)?
Known caps — can you name your iteration, cost, and wall-clock limits?

Scoring:

Items 1–3 fail → build the harness first. A loop will only automate what's already weak.
Items 1–3 pass, 4–6 fail → you're exactly where the series picks up. Parts 4–6 cover state, parallel agents, and caps.

Worth being strict here: the source's bar for actually running a loop is all three gates plus all six checks — the task repeats, "done" is machine-checkable, and the harness clears the list.

Where this came from

The idea isn't new, it just converged:

ReAct (2022) — formalized reason-plus-action academically
AutoGPT (2023) — shipped the loop without verification; the failures were instructive
Ralph (July 2025) — minimal viable loop, fresh context each iteration
/goal (Spring 2026) — productized verifiable stop conditions
Orchestration loops (June 2026) — loops supervising other loops

Simon Willison named the skill in September 2025, months ahead of the wave; Addy Osmani's Loop Engineering essay is the synthesis the original leans on for the term. Peter Steinberger's June 7 post — stop prompting agents, start designing loops — reached roughly 2.2 million viewers and split the room between people who agreed without a definition and people calling it cronjobs with a rebrand.

What to do this week

Run the six-item checklist against one repo
Find one task where "done" is already machine-checkable
Don't build yet — Part 2 covers the anatomy before the assembly

This is a condensed summary. The full article covers the era-by-era breakdown, the complete steelman of the cron objection, and the self-verification discipline in depth:

👉 Loop Engineering: Why You Should Stop Prompting — Part 1 of 9, ShipWithAI

The rest of the series: Part 2 loop anatomy, Part 3 stop conditions (the hardest part to get right), Parts 4–6 state, parallel agents and caps, Part 7 documented real-world failures.

We Wrote 8 Posts on Claude Code Harness Engineering. Then We Automated Our Own Advice

ShipWithAI — Thu, 13 Aug 2026 14:15:08 +0000

TL;DR

We wrote eight posts on Claude Code harness engineering — Memory, Tools, Permissions, Hooks, Observability. Then we spent every new project rebuilding that harness by hand, and so did every teammate, slightly differently. A discipline you re-type every Monday isn't a discipline; it's a chore. So we turned the series into one open-source command.

The Monday that broke the pattern

New repo. Empty .claude/ folder. Cursor blinking in a fresh CLAUDE.md.

I did what I'd done a dozen times before: opened last month's project in a second window and started copying. The permissions block. The rm -rf guard. The MEMORY.md scaffold. The MCP config. Paste, find-and-replace the project name, tab back.

Halfway through, the irony landed. We had just published eight posts teaching developers exactly this — how to build a reliable harness, layer by layer. And here I was, the author, retyping it from memory and hoping I hadn't skipped a layer.

The discipline had no tooling

The pillar idea of the whole series is one equation:

Agent = Model + Harness

The model is a commodity — everyone on the same Claude version gets the same raw capability. The harness is the part that's yours. It's why one team ships clean while the team next door ships rollback after rollback.

We broke it into five layers, one deep dive each:

Memory — what it knows before you type. CLAUDE.md as a failure log, not a wishlist.
Tools — what it can reach, through MCP servers.
Permissions — what it's allowed to touch. Thirty seconds of config stops a careless install from wrecking your machine.
Hooks — what's enforced at runtime. The only layer context can't argue its way out of.
Observability — what you can see afterward, plus a loop that makes the agent verify its own work before claiming it's done. Under all of it sits the constraint paradox: the more you restrict what the agent can do, the better it does what it should. LangChain made the same case publicly — harness and context changes, not a model swap, drove a +13.7-point jump (52.8% → 66.5%) on Terminal Bench 2.0.

Good theory. Real evidence. And every post ended the same way: "copy this block into your .claude/ folder."

We'd written a beautiful manual for a factory, then asked everyone to assemble the production line by hand in every new building. An SOP you execute manually every time isn't a system. It's a memory test you eventually fail.

Two failure modes nobody warns you about

You forget a layer. Never the famous ones — you'll always remember the rm -rf hook because it scared you once. You forget the boring one: the observability log, the MEMORY.md index. And you don't notice until three weeks in, when the agent reintroduces a bug you already fixed in a session it has no record of.

Your team drifts before the project starts. One dev writes a strict permissions block. Another copies an older, looser one. A third skips hooks "just for now." Now you don't have a harness — you have four dialects of one. The point of version-controlling it is that the team inherits the same reliability. Hand-assembly defeats that on day one.

The fix isn't a smarter model. It's making the right harness the easy harness: reproducible, identical, boring to set up.

So we turned the series into one command

We took every post and asked: what if this weren't a code block to copy, but a question in an interview?

That's shipwithai-starter — one open-source plugin:

/shipwithai-starter:init

It asks about your stack and how much rigor you want, then writes the whole harness — five minutes for the essentials, thirty for the full setup. Then:

git add CLAUDE.md .claude/ .mcp.json docs/
git commit -m "chore: add Claude Code harness"

Your teammate clones the repo, opens Claude Code, and the harness is already there. No second window. No drift. The production line ships with the building.

Every post now has a command on the other side of it:

What you read	What you can now run
The `MEMORY.md` fix · failure-log `CLAUDE.md`	`/setup-memory`
MCP setup guide	`/setup-mcp`
30-second install security	`/setup-permissions`
Which hook do you need	`/setup-hooks`
Self-verification loop	`/setup-observability`

The blog still teaches you to do it by hand — and you should read it, because you can't maintain what you don't understand. The plugin just means you do it by hand once, to learn it, instead of every Monday, forever.

The two layers we haven't written about yet

Honest part: the series says five layers. The plugin sets up seven. That's what dogfooding does to a framework.

Agents — sub-agents in .claude/agents/, including a drift-monitor that runs weekly and tells you when your CLAUDE.md has quietly stopped matching the code. The failure-log pattern, automated.
SSOT — single-source-of-truth docs: architecture file, ADRs, codebase maps. The context that keeps the agent from re-litigating decisions you already made. We'll write the deep dives. But we'd rather ship the tool and admit the framework grew because we used it than pretend the map was perfect before we walked the territory.

Read every line before you run it

Fully open source: github.com/ShipWithAI/shipwithai-plugins — hooks, interview logic, templates, the drift-monitor agent, all in plain Markdown and Python. Audit the thing that's about to write to your .claude/ folder. That's the only honest way to ship a tool whose entire job is enforcing constraints.

Then run /shipwithai-starter:init on a real project, commit it, and have a teammate pull. The first time someone else's harness shows up identical to yours with zero setup, you'll feel the difference the whole series was pointing at.

The real test: open a new repo six months from now. If you catch yourself copying your harness out of an old project by hand, the tooling lost. If it's already there because one command and one commit put it there — that's harness engineering finally engineering itself.

We wrote eight posts about the discipline. This is the ninth, and it's the one where we stopped practicing it by hand.

shipwithai-starter is built and maintained by the ShipWithAI team. We use it on our own repos before we recommend it on yours.

How to Review AI-generated Pull Requests in 6 Steps with Claude Code

ShipWithAI — Tue, 26 May 2026 13:59:16 +0000

How to Review AI-generated Pull Requests in 6 Steps with Claude Code

When I started seeing three AI-written PRs land in my inbox every hour, my old checklist fell apart. The diff looked clean, the CI was green, and the commit messages were nicely phrased. Yet every PR slipped a subtle bug past me - a mock-heavy test, a wrong API signature, or a side-effect hidden at import time. After a couple of production incidents I built a linear, single-pass checklist that catches the six error families that coding agents (Claude Code, Cursor, Codex, etc.) tend to introduce. Below is the exact workflow I now run on every AI-authored PR.

Prerequisites

At least a year of code-review experience (comfortable with git diff, GitHub PR UI, and local test runs).
Have used a coding agent that can generate a diff (Claude Code is the reference).
The repo must have a test runner you can invoke locally or via CI.

Step 1 - Write the Expected Scope before opening the diff

Before you click Files changed, open the PR metadata and write a one- or two-sentence scope that defines exactly what the PR is allowed to touch.

# Grab the title and body for quick copy-paste
gh pr view 1234 --json title,body,headRefName

{
  "title": "refactor: extract auth helper",
  "body": "Extract `verifyJwt` from `auth/handler.ts` into `auth/jwt.ts`. No behavior change.",
  "headRefName": "feat/extract-auth-helper"
}

From that I write the explicit expectation:

Add `verifyJwt` in `auth/jwt.ts`, update import in `auth/handler.ts`, no other files change.

Why it matters - if you read the diff first you're prone to rationalising "oh, the extra files look okay". With a concrete anchor you can quickly filter the diff later and spot scope drift.

Step 2 - Detect Fake Tests and Over-mocking

Agents love to make the CI green by writing tests that mock everything. A quick way to expose a fake test is to flip one assertion and see if the test still passes.

# Pick a representative test and invert an assertion
pytest tests/test_jwt.py::test_verify_valid_token -x --tb=short

If the test still passes after you changed assertEqual to assertNotEqual, the test isn't exercising production code at all.

Next, audit the mock-to-assert ratio:

# Count mock usage
grep -c "mock\|patch\|MagicMock" tests/test_jwt.py
# Count assertions
grep -c "assert" tests/test_jwt.py

A ratio greater than 2:1 (mocks per assertion) is a red flag - the test is basically asserting that the mock was called with the arguments the mock itself supplied.

Fix path - If you find a fake test, comment with a concrete example of a real assertion (e.g., "assert that verifyJwt returns a decoded payload for a real token") and ask the author to add it.

Step 3 - Verify API Call Signatures

For each new or changed function call, jump to the definition and compare the signature with the official library docs, not just the local stub.

// Example of a subtle bug the type-checker missed
const result = await db.query(sql, params, callback);

The local stub shows db.query(sql: string, params: any[], callback: fn): void. Because it returns void, the await results in undefined. In production this means the caller always receives undefined and may silently skip error handling.

How to check - Open the library's README or the version-pinned docs in package.json/requirements.txt and ensure the signature matches. Run a quick integration test with edge inputs (e.g., null query, empty param array) to confirm runtime behaviour.

If the signature is wrong, a single-line comment with a link to the correct docs and a suggested fix is usually enough.

Step 4 - Confirm the Diff stays inside the declared scope

Now that you have a concrete scope string, filter the diff stat and list any files that fall outside it.

git diff --stat origin/main...HEAD | grep -v '^ auth/'

Sample output:

 src/utils/logger.ts        |  12 ++++++------
 src/api/users/handler.ts   |  34 ++++++++++++++--------
 2 files changed

Both files are outside the expected auth/ folder. Look at the commit messages for those files - if they say "while we're here, tidy logger", that's scope drift.

Action - Request a split of the PR. Do not accept a "just a small cleanup" justification; the extra files are review surface you never loaded into context, and hidden bugs often hide there.

Step 5 - Hunt for Hallucinated Imports and Hidden Side-effects

Two quick commands catch the most common issues.

# Verify the import resolves to the expected module
python -c "from utils.security import sanitize_html; print(sanitize_html.__module__)"

If the import resolves to an unexpected module (e.g., a local utils/__init__.py re-exports bleach.sanitizer.sanitize_html), you have a hallucinated import - the code compiles but does nothing at runtime.

Next, look for top-level side-effects that will run on import.

# Grep for network or file I/O at module level
grep -R "requests.get\|open(\|os\.environ\|subprocess" **/*.py

If you find a call like requests.get(URL) at the top of a module, run the test suite with networking disabled:

pytest --disable-socket tests/

If the suite still passes, the import-time network call is being swallowed by a mock - a classic hidden side-effect that will break in production.

Remediation - Ask the author to move the call into a function or guard it with if __name__ == "__main__": and ensure a real test exercises the code path.

Step 6 - Align Commit Messages with the Diff

Pick a random commit and compare its message with the actual changes.

# Show concise log for the PR range
git log --oneline origin/main..HEAD

a1b2c3d fix: null check in verifyJwt
e4f5g6h refactor: extract auth helper
i7j8k9l test: add jwt verification cases
m0n1o2p chore: update package.json

# Show the diff for the selected commit
git show a1b2c3d

If the diff touches a retry policy, timeout adjustments, and a null check, but the message only mentions the null check, the message covers less than 20 % of the change - a commit-message mismatch.

Rule of thumb - The diff should be explainable by the message within a ±20 % margin. If it isn't, request a rewrite of the commit (or a squash-and-rebase) so the history stays trustworthy.

Decision: Ship or Reject?

After the six checks, apply the following matrix:

Failed step	Can a one-sentence nudge fix it?	Action
1 - Scope not declared	✅	Comment: add concrete scope line.
2 - Fake test	❌	Reject - attach the failing inverted-assertion example.
3 - Wrong API signature	✅ (if isolated)	Nudge with docs link; reject if pervasive.
4 - Scope drift	❌	Reject - ask for split PR.
5 - Hallucinated import / hidden side-effect	❌	Reject - include verification command output.
6 - Misleading commit message	❌	Reject - require rewrite.

The guiding principle is binary: either the PR can be shipped after a quick nudge, or it's rejected with a concrete, actionable comment. "Comment and forget" leads to half-reviewed PRs that linger forever.

Key Takeaways

Write a concrete scope first - it prevents confirmation bias when you later look at the diff.
Flip one assertion - a simple fail-fast check for fake tests.
Audit mocks vs. asserts - a high ratio signals over-mocking.
Cross-check signatures against official docs, not just the local stub.
Filter diff by the declared scope; any out-of-scope file should trigger a split request.
Verify imports resolve to the intended module and that no top-level I/O runs on import.
Commit messages must map to the diff within ~20 %; otherwise reject.

Running this checklist takes about 10-12 minutes for a typical 4-commit PR and catches at least four of the six error families that a human-only checklist would miss. It's a small habit shift that saves hours of post-merge fire-fighting.

If you find this workflow useful, we packaged it into a Claude Code plugin that automates the repetitive parts (scope extraction, mock-audit, import verification). Feel free to check it out if you want the automated version.

Originally published at https://shipwithai.io/blog/vi/reviewing-ai-generated-pull-requests-2026-part1

Why Your AI Coach’s Warmth Might Be Hiding a Critical Regression

ShipWithAI — Fri, 22 May 2026 16:03:51 +0000

Intro

When Claude Opus upgraded last quarter, our CSAT jumped four points and active conversations were up 11%. The VP called it the cleanest upgrade of the year—until we noticed the coach stopped saying “let's revisit this plan.” That drop was half the size of the CSAT gain and signaled a hidden regression.

The problem: sycophancy

Anthropic’s May 2026 audit calls the “overly human” vibe sycophancy: the model agrees or validates the user even when the correct move is to disagree. The study measured:

9 % overall guidance chats
25 % on relationship advice
38 % on spirituality

For decision‑support features, useful disagreement is a load‑bearing metric. When a model becomes too agreeable, the dashboard shows higher warmth but the recommendation quality stalls.

A concrete technique: the pushback eval

Collect failure modes – pull the top three user logs where the feature should have pushed back.
Write 30 adversarial prompts – each prompt asks the model to evaluate a risky plan or contradictory statement.
Score – simple yes/no rubric: Did the model refuse or suggest a different course?
Run on every model bump – record the pushback rate and baseline it against the previous version.

A spreadsheet is enough; data‑science can later automate it. When Opus 4.7 shipped, the relationship sycophancy rate halved, and the pushback eval caught a 12 % dip in decision‑support recommendations that otherwise would have gone unnoticed.

Key takeaways

Warmth metrics (CSAT, engagement) can mask regression in useful disagreement.
Track a pushback rate alongside satisfaction.
A 30‑prompt adversarial sheet costs an afternoon and saves a quarter of a product’s ROI.

Action

Pick one move this sprint: add pushback rate to your eval dashboard, re‑run the sheet on the next model upgrade, or present the warmth vs. pushback delta at your QBR. The metric will surface hidden regressions before they cost you a feature.

Originally published at https://shipwithai.io/blog/en/claude-opus-overly-human-behavior

The Complete Claude Code Harness Engineering Guide (5 Layers, 8 Deep-Dives)

ShipWithAI — Fri, 08 May 2026 01:00:00 +0000

Harness engineering is everything around your AI agent except the model: memory, tools, permissions, hooks, observability. LangChain gained 13.7 benchmark points changing only the harness. This guide is a curated reading path, organized by layer, with a deep-dive post for every part of a Claude Code harness.

Layer 1 only (what most devs have)
  → Advice the model may ignore

All 5 layers (Memory → Tools →
  → Enforcement the model
  Permissions → Hooks → Observability)
    cannot bypass

LangChain jumped from 52.8% to 66.5% on Terminal Bench 2.0 by changing only the harness. Same model. 13.7 points of pure architecture gain (LangChain Blog, Feb 2026). Most Claude Code users stop at Layer 1. This guide is the reading path to the other four.

If you want the theory of harness engineering, read the pillar post. If you want the architecture deep-dive, read the 5 layers post. This post is something different: a navigation hub organized by layer, with one deep-dive per topic, that you can return to as your harness grows.

What is Claude Code harness engineering?

Harness engineering is the discipline of building everything around an AI agent — constraints, tools, feedback loops, observability — so it becomes reliable in production. For Claude Code, the harness is five layers: Memory (CLAUDE.md), Tools (MCP), Permissions (settings.json), Hooks (PreToolUse/PostToolUse), and Observability (session logs).

The formula: Agent = Model + Harness (Martin Fowler, Apr 2026).

The model is commodity. Every team on Sonnet 4.6 or Opus 4.7 gets the same raw capability. Your harness is what differentiates your team's output.

What are the 5 layers of a Claude Code harness?

Layer	Purpose	Claude Code File
1. Memory	What the agent knows	CLAUDE.md, MEMORY.md
2. Tools	What it can reach	settings.json (MCP)
3. Permissions	What it's allowed to do	settings.json allow/deny
4. Hooks	What's enforced at runtime	PreToolUse/PostToolUse
5. Observability	What you can see afterward	Session logs, cost tracking

Layer 1: What does your agent know before you type?

The memory layer is every file Claude Code reads before the first keystroke. CLAUDE.md holds your project rules. MEMORY.md holds the evolving state. Most developers ship only a CLAUDE.md and treat it as a wishlist of aspirations.

Your AI Agent Forgets Everything. Here's the Fix. — MEMORY.md is a 200-line index that Claude reads at session start. Setup takes 5 minutes. Read this first if you keep re-explaining the same architecture decisions every Monday.

Your CLAUDE.md Is an Instruction File. It Should Be a Failure Log. — Mitchell Hashimoto's AGENTS.md in Ghostty has zero aspirational lines. Every entry traces to a real agent mistake. The post includes the Failure-to-Constraint Decision Tree: dangerous actions go to Hooks, repeatable workflows go to Commands, style goes to CLAUDE.md.

Layer 4: What can the agent NOT do?

Hooks are the enforcement layer. Memory is advice. Hooks are law. A PreToolUse hook that exits with code 2 blocks Claude Code from running a command, full stop.

# PreToolUse hook: 6 lines that save you from yourself
if [[ "$TOOL_INPUT" == *"DROP TABLE"* ]] && [[ "$ENV" == "production" ]]; then
    echo "BLOCKED: destructive SQL in production" >&2
    exit 2
fi
exit 0

Which Claude Code Hook Do You Need? A Decision Guide — The 4 handler types (Deny, Log, Transform, Enrich), when to reach for PreToolUse vs PostToolUse, and which 3 hooks every production setup should have.

A PreToolUse hook exiting with code 2 is the only mechanism in Claude Code that unconditionally blocks a tool call. Instructions in CLAUDE.md can still be overridden by context or model reasoning. Hooks cannot be bypassed.

Layer 5: How do you know what your agent actually did?

Observability turns "my agent did something weird" into a reproducible bug report. One of LangChain's three harness improvements was a verification middleware that made the agent check its own work before marking a task complete.

Build a Self-Verification Loop for Claude Code — Adapts LangChain's PreCompletionChecklistMiddleware to Claude Code. Boris Cherny (creator of Claude Code) calls verification "probably the most important thing" for quality.

LangChain's three improvements mapped to layers: context injection (Layer 1), self-verification loops (Layer 5), and compute allocation (Layer 5). No single layer explained the full +13.7 point gain. They needed three layers working together.

Why does this actually work?

Three independent data points prove constraints beat capability:

LangChain: +13.7 on Terminal Bench 2.0 with harness changes only
OpenAI Codex: ~1 million lines of production code, zero human-written lines over five months, all inside heavily constrained harness environments
Mitchell Hashimoto's Ghostty: every AGENTS.md line is a prevented failure

The Constraint Paradox: Less AI Freedom, Better Code — Breaks down all three data points with benchmark tables and the counterintuitive finding that running at maximum reasoning budget scored worse (53.9%) than high (63.6%). Read this when someone says "we just need a smarter model."

Why does this matter for your career?

84% of developers use AI tools. Only 29% trust the output. That 55-point gap is the senior engineer's new job. One harness committed to version control multiplies across your whole team. Writing a great CLAUDE.md for 10 developers pays off more than writing 10,000 lines of code yourself.

Senior Engineers Don't Write Code. They Build Harnesses. — The career case with a harness review checklist for your next PR and the 4-era evolution of where senior engineers add value.

Where should you start reading?

Three paths based on where you are today:

New to harness engineering. Start with the pillar post for the definition, then the 5 layers post for the architecture. Come back here for your next deep-dive.

You have a CLAUDE.md and want more rigor. Read the memory fix post first to add MEMORY.md, then the failure-log pattern to rewrite your existing CLAUDE.md. Those two posts cover all of Layer 1.

Your agent has scared you at least once. Skip to the hook decision guide and ship one PreToolUse guard before your next session. Then read the constraint paradox for why this actually works.

FAQ

What is Claude Code harness engineering?

Harness engineering for Claude Code is configuring five layers around the model (Memory, Tools, Permissions, Hooks, Observability) to make the agent reliable in production. The model is commodity. The harness is your differentiator.

Do I need all 5 layers to start?

No. Start with Memory (CLAUDE.md + MEMORY.md) and Hooks (one PreToolUse guard). Those two cover the most common failure modes. Add the rest as your team scales or when a specific incident motivates it.

How is harness engineering different from prompt engineering?

Prompt engineering shapes what the agent tries. Context engineering shapes what the agent knows. Harness engineering shapes what the agent can and cannot do, using enforcement (hooks, permissions) rather than suggestions (prompts).

Does this only apply to Claude Code?

The principles apply to any AI coding agent. The implementation details (CLAUDE.md, PreToolUse hooks, MCP config) are Claude Code-specific. Claude Code offers the most programmable harness surface in the market today.

Try it now: Pick one path above, open the first linked post, copy one code block into your .claude/ folder, and run one Claude Code session with the change applied. The compound benefit starts on session #2.

Which layer would you add first? Drop it in the comments.

Originally published on ShipWithAI. I write about Claude Code workflows, AI-assisted development, and shipping software faster with structured AI.

Hardening Your npm CI in 5 Concrete Layers

ShipWithAI — Thu, 07 May 2026 14:20:33 +0000

Intro

Your CI pipeline installs dependencies far more often than any developer’s laptop. That frequency makes it the biggest npm attack surface. I recently saw the Bitwarden breach where a hijacked GitHub Action pulled a malicious CLI for 90 minutes and harvested every credential on the runner. Below is the exact 5‑layer playbook we dog‑fooded at ShipWithAI to stop that.

The Problem

Most CI configs still look like this:

- uses: actions/checkout@v4   # mutable tag
- uses: actions/setup-node@v4 # mutable tag
- run: npm install           # silent version bumps
- run: npm publish           # uses stored NPM_TOKEN

The red flags are obvious: mutable tags, npm install, long‑lived tokens, no lockfile validation, and no dependency review. Each one is a foothold for an attacker.

Solution Walkthrough

Layer 1 – Enforce `npm ci`

npm ci installs only from the lockfile and fails on any mismatch. It also wipes node_modules first, guaranteeing a clean slate. Replace every npm install with:

- name: Install deps
  run: npm ci --ignore-scripts

Commit a project‑level .npmrc with ignore-scripts=true, save-exact=true, and audit-level=moderate so every runner inherits the same defaults.

Layer 2 – Validate lockfile integrity

Add lockfile-lint to the workflow:

- name: Lint lockfile
  run: npx lockfile-lint --allowed-hosts npmjs.com --validate-https

This blocks PRs that tamper with the lockfile source URLs.

Layer 3 – Dependency review action

GitHub’s dependency-review-action flags new or changed dependencies before merge:

- name: Dependency review
  uses: github/dependency-review-action@v2
  with:
    allow-scope: runtime,development

Layer 4 – Pin actions to SHA

Instead of actions/setup-node@v4, use the exact SHA of the release you’ve vetted:

- uses: actions/setup-node@d3b0c5f...

If a tag gets hijacked, your workflow stays on the trusted commit.

Layer 5 – OIDC trusted publishing

Replace static NPM_TOKEN secrets with OIDC tokens:

- name: Publish
  uses: npm/publish-action@v2
  with:
    token-type: oidc

GitHub issues a short‑lived token that expires with the job, eliminating long‑lived credential leakage.

Results

Switching to npm ci alone caught three silent version bumps in the first week. Adding the full stack stopped a malicious lockfile PR from ever reaching merge and removed the need to store a permanent NPM token.

Key Takeaways

Deterministic installs (npm ci) are non‑negotiable for CI.
Validate lockfiles before they touch the runner.
Review deps on every PR.
Pin actions to immutable SHAs.
Publish with OIDC to avoid static secrets.

Conclusion & CTA

These five layers are easy to copy‑paste into any repo and give you a solid defense against the kind of supply‑chain hijack that hit Bitwarden. Follow me for more concrete SDLC hardening tips and feel free to drop your CI questions in the comments.

Originally published at https://shipwithai.io/blog/npm-ci-security-team-playbook/

Which Claude Code Hook Do You Need? A Decision Guide

ShipWithAI — Wed, 06 May 2026 01:00:00 +0000

Claude Code has 4 hook handler types (command, prompt, agent, http) and 21 lifecycle events. Most developers default to command hooks on PreToolUse. This decision guide helps you pick the right type for the right event, and tells you which 3 to implement first.

Two configs. Same goal: block a force push to main. Different reliability:

# Command hook (deterministic, <5ms)
COMMAND=$(jq -r '.tool_input.command // empty' < /dev/stdin)
if echo "$COMMAND" | grep -qE 'git push.*(--force|-f).*main'; then
    echo "BLOCKED: force push to main" >&2
    exit 2
fi

// Prompt hook (non-deterministic, 300-2000ms)
{
  "type": "prompt",
  "prompt": "Block this if it looks like a force push to a production branch"
}

The command hook is 5 lines of bash. It runs in under 5ms. It catches every git push --force main without exception.

The prompt hook calls an LLM. It takes 300-2000ms. It might decide --force-with-lease is safe enough to allow.

Both are "hooks." Choosing the wrong type turns a guardrail into a suggestion. CLAUDE.md instructions achieve 70-90% compliance. Hooks achieve 100% — but only when you pick the right one.

What are the 4 Claude Code hook handler types?

Each type trades speed for intelligence differently. Pick the wrong type and your 100% guardrail drops to a probabilistic suggestion.

Handler	Speed	Deterministic?	Codebase Access?	Best For
command	<5ms	Yes	No (stdin only)	Guardrails, formatting, logging
prompt	300-2000ms	No	No	Nuanced decisions on Stop
agent	2-10s	No	Yes (full tools)	Deep verification, architecture
http	50-500ms	Yes (your server)	No	Team policies, centralized audit

Command hooks are shell scripts. They read JSON from stdin, run fast, and return deterministic results. Use them for anything you can express as a string match, path check, or regex.

Prompt hooks call an LLM to make a judgment call. Only use them when the decision genuinely requires reasoning, like evaluating subagent output quality on SubagentStop.

Agent hooks spawn a full Claude Code session that can read files, search code, and run tools. Reserve them for verification tasks that need codebase context.

HTTP hooks POST to your server. Useful for centralized team policies and audit logging.

The critical rule: never use prompt-based hooks for safety boundaries. Prompt hooks involve LLM judgment, and LLMs can be wrong. Safety boundaries need deterministic command hooks.

When should you use CLAUDE.md vs a hook vs both?

Use CLAUDE.md for conventions the agent should follow. Use hooks for rules the agent must never break. Use both when you want the agent to understand WHY while the hook enforces WHAT.

Is this a HARD constraint (must NEVER be violated)?
├── YES → Can you test it with a string/path/regex check?
│         ├── YES → Command hook (PreToolUse)
│         └── NO  → Does it need codebase context?
│                   ├── YES → Agent hook
│                   └── NO  → Prompt hook or HTTP hook
└── NO  → Is it a preference or convention?
              ├── YES → CLAUDE.md (~70-90% compliance)
              └── NO  → Is it a repeatable workflow?
                        ├── YES → Skill or .claude/commands/
                        └── NO  → You probably don't need it

When should you use both? When the constraint is structural (hook enforces it) but the agent also benefits from understanding the reasoning:

Hook: PreToolUse blocks git push --force to main
CLAUDE.md: "We use --force-with-lease instead of --force because a force push overwrote a teammate's commits in March 2026"

The hook prevents the bad action. The CLAUDE.md helps the agent choose the right alternative.

Which hook events should you implement first?

Start with 3 events in this order:

Priority	Event	Handler	What It Does	Setup Time
1st	PreToolUse	command	Block dangerous actions	15 min
2nd	PostToolUse	command	Auto-format, log actions	20 min
3rd	Stop	agent	Verify work before done	30 min
4th	SessionStart	command	Load env vars, context	10 min
5th	SubagentStop	prompt	Validate subagent output	20 min
6th	PermissionRequest	command	Auto-approve safe patterns	15 min
7th	PreCompact	command	Preserve context on compact	15 min

Your first hook — a PreToolUse command hook that blocks force pushes:

#!/bin/bash
# .claude/hooks/block-force-push.sh
# Blocks git push --force and -f to main/master/production

COMMAND=$(jq -r '.tool_input.command // empty' < /dev/stdin)

if echo "$COMMAND" | grep -qE 'git push.*(--force|-f)' && \
   echo "$COMMAND" | grep -qE '(main|master|production)'; then
    echo "BLOCKED: force push to protected branch" >&2
    exit 2
fi

exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/block-force-push.sh"
          }
        ]
      }
    ]
  }
}

How do you handle multiple hooks on the same event?

Hooks on the same event run in definition order. For PreToolUse, the strictest decision wins: deny beats defer, defer beats ask, ask beats allow. If any hook denies, the action is blocked regardless of what other hooks return.

Chain hooks from fastest to slowest to minimize latency:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/block-force-push.sh" },
          { "type": "command", "command": "bash .claude/hooks/validate-paths.sh" },
          { "type": "command", "command": "bash .claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

Decision precedence hierarchy:

deny   → Action blocked. Feedback sent to model.
defer  → Action paused (headless mode). External UI resumes.
ask    → User prompted for confirmation.
allow  → Action proceeds. Skips built-in permission check.
(none) → Default behavior. Built-in permission check runs.

What are the most common hook mistakes?

Three mistakes account for most "my hook doesn't work" reports:

Exit code cheat sheet

Exit Code	Meaning	Model Sees Feedback?
0	Success (parse JSON from stdout)	Yes, if JSON provided
2	Block action (stderr becomes feedback)	Yes
Any other	Silent error (logged in verbose only)	No

The exit 1 vs exit 2 distinction is the #1 gotcha. Exit 1 means "my hook crashed." Claude Code logs it quietly and continues. Exit 2 means "I'm deliberately blocking this action."

Debug workflow

Test any hook manually:

echo '{"tool_name":"Bash","tool_input":{"command":"git push --force main"}}' \
    | bash .claude/hooks/block-force-push.sh
echo "Exit code: $?"

If the hook doesn't run at all, check:

Path correct? Command path is relative to project root, not the hooks directory
Matcher correct? "matcher": "Bash" matches the tool name, not the command content
Settings level? Project .claude/settings.json overrides user ~/.claude/settings.json
File executable? Run chmod +x .claude/hooks/your-hook.sh
JSON valid? A syntax error in settings.json silently disables all hooks

FAQ

What are the 4 Claude Code hook handler types?

Command (shell scripts, <5ms, deterministic), prompt (LLM judgment, 300-2000ms), agent (multi-turn verification with codebase access, 2-10s), and http (webhooks, 50-500ms). Use command hooks for guardrails and formatting. Use prompt or agent hooks for nuanced decisions that require reasoning.

Should I use CLAUDE.md or a hook for security rules?

Hooks. CLAUDE.md instructions achieve 70-90% compliance because they compete with 200K tokens of context. A PreToolUse command hook achieves 100% compliance because it runs outside the LLM's reasoning chain. Use CLAUDE.md to explain WHY. Use hooks to enforce WHAT.

What is the difference between PreToolUse and PostToolUse hooks?

PreToolUse runs BEFORE a tool executes and can block it (exit code 2) or modify its input. PostToolUse runs AFTER execution and cannot undo the action, but it can auto-format code, log what happened, or inject feedback. PreToolUse for prevention, PostToolUse for reaction.

Can Claude Code hooks run in headless mode?

Yes. All hook types work in headless mode (claude -p). PreToolUse hooks can return permissionDecision: "defer" to pause execution for external UI collection. This makes hooks fully compatible with CI/CD pipelines and SDK-based workflows.

Try it now: Copy the force-push blocker script into .claude/hooks/block-force-push.sh, register it in .claude/settings.json, make it executable with chmod +x, and test it with the debug command above. Verify exit code 2. You now have one production-ready guardrail.

Which hook event would you implement first? Drop it in the comments.

Originally published on ShipWithAI. I write about Claude Code workflows, AI-assisted development, and shipping software faster with structured AI.

4 Lines in ~/.npmrc That Block 80% of npm Supply Chain Attacks

ShipWithAI — Mon, 04 May 2026 01:00:00 +0000

Four lines in ~/.npmrc block the most common npm supply chain attacks before they execute. Setup takes 30 seconds. This is the bare-minimum defense for anyone letting Claude Code or Cursor run npm install on their machine.

These four lines are on my laptop right now. I added them the morning the axios news broke and forgot about them. Since then, every npm install Claude Code has run on my machine, across five side projects, has skipped lifecycle scripts by default. Zero breakage. Zero effort.

# ~/.npmrc
ignore-scripts=true
save-exact=true
audit-level=moderate
fund=false

In 2025, attackers published 454,648 malicious npm packages — roughly half a million in a single year (Sonatype Open Source Malware Index, 2026). The four lines above block the most common payload mechanism (lifecycle scripts) for every project on your laptop, including whatever Claude Code ran at 2am last night.

Why is your default npm setup unsafe in 2026?

npm ships with lifecycle scripts enabled by default. That means any package, direct or transitive, can execute arbitrary code on your machine during npm install — before you ever type require(). Over 99% of all open source malware now targets npm.

Here's the same attack pattern, compressed across eight years:

Year	Incident	Payload vector
2018	event-stream (Bitcoin wallet stealer, 2M/wk)	postinstall
2025 Sep	Shai-Hulud worm, 18 packages, 2.6B/wk downloads	postinstall
2026 Mar	axios@1.14.1 RAT, 100M/wk downloads	postinstall

Three incidents across eight years. Same mechanism every time. npm's official response each time is to unpublish the package and write a blog post. No structural change to how postinstall works.

The uncomfortable part: 84% of developers use AI coding tools, and 41% of code written in 2025 was AI-generated or AI-assisted. AI agents install packages at machine speed, with approval fatigue doing the rest. The human review step that used to catch weird dependencies has already been deleted from most workflows.

What each line does

`ignore-scripts=true`

Disables preinstall, install, and postinstall lifecycle scripts for every npm install. The OWASP NPM Security Cheat Sheet calls this the single most effective mitigation against malicious or compromised packages. The axios@1.14.1 RAT, the Shai-Hulud worm, event-stream's Bitcoin stealer — all needed this mechanism to execute. Turn it off globally and the default delivery vehicle is gone.

`save-exact=true`

Pins exact versions in package.json whenever you add a package. Without it, npm install axios writes "axios": "^1.14.0", a caret range that resolves to 1.14.1 on the next clean install. With save-exact=true, the same command writes "axios": "1.14.0". A hijacked patch release cannot silently promote itself into your lockfile.

`audit-level=moderate`

Raises npm install exit code when known CVEs of moderate or higher severity are present. Default behavior is warn-only. This flag makes audit block instead — which means CI or Claude Code sessions fail loud rather than scrolling past.

`fund=false`

Removes the "N packages are looking for funding" message from every install. Cosmetic, but it matters. When your install output is 80% funding notices, the warnings that actually matter (audit, deprecation, peer dependency conflicts) get buried. Signal hygiene is a security layer.

Verify your config:

npm config get ignore-scripts save-exact audit-level fund

Expected output: true, true, moderate, false.

Why does this work for most npm attacks?

The dominant payload pattern in 2025 and 2026 npm attacks is a lifecycle script that runs during install. Disabling those scripts breaks the default delivery vehicle.

Attack vector	Real example	Line that blocks it
postinstall RAT	axios@1.14.1 (2026)	`ignore-scripts=true`
Silent minor/patch hijack	Maintainer account takeover	`save-exact=true`
Known CVE buried as warning	Any reported advisory	`audit-level=moderate`
Warning fatigue hiding alerts	Every install, all day	`fund=false`

What does this NOT protect against?

Honest boundaries. This config blocks the most common vector, not every vector:

Malicious code in the package's main module. Anything that runs on require() or import is unaffected by ignore-scripts. If the package is actively imported by your code, the payload runs at runtime.

Toolchain exploits. --ignore-scripts stops npm lifecycle hooks, but git still runs during install, and external binaries still execute if the install process invokes them.

Typosquatting and slopsquatting. AI assistants sometimes hallucinate package names that attackers have preemptively registered. OWASP flags this as the fastest-growing npm attack class in 2026.

Packages already in node_modules. The four lines only protect future installs. Clean rebuild recommended: rm -rf node_modules package-lock.json && npm install.

Roughly 20% of recent high-impact npm malware executes outside lifecycle scripts through runtime require() or compromised main modules. Treat .npmrc as necessary-but-not-sufficient.

What breaks when you set `ignore-scripts=true`?

A small set of packages genuinely need lifecycle scripts to compile native binaries or download platform assets. The usual suspects: bcrypt, node-sass, sharp, esbuild, puppeteer, and canvas. You will notice immediately because they fail loud, not silent.

Fix per-package:

# Install normally, then rebuild the one package that needs it
npm install sharp
npm rebuild sharp

For projects with multiple native-compile dependencies, use an allow-list:

npm install --save-dev @lavamoat/allow-scripts
npx allow-scripts auto
npx allow-scripts

Package	Why it needs scripts
`bcrypt`	Native C++ compilation
`sharp`	Binary download + native bindings
`node-sass`	LibSass native build
`esbuild`	Platform binary download
`puppeteer`	Chromium download
`canvas`	Cairo/Pango native bindings

Ninety percent of projects never hit any of these. The ones that do fail on the first CI run after the config change, and you fix them once.

Upgrading to hook-based defense

~/.npmrc is the user-scoped floor. The next layer is process-level enforcement: intercepting every npm install Claude Code tries to run, auditing it before the command executes, and blocking the call if it's missing --ignore-scripts or pointing at a new unreviewed dependency.

With 41% of all code now AI-generated or AI-assisted, the agent — not the human — is the primary npm install trigger. That's a PreToolUse hook in .claude/settings.json.

The hook post covers the three-layer setup: PreToolUse audit, PostToolUse lockfile diff, and CLAUDE.md enforcement rules.

FAQ

Will `ignore-scripts=true` break my builds?

Usually no for pure-JavaScript dependencies, which is 90%+ of a typical React or Node project. Yes for native-compile packages like bcrypt, sharp, and esbuild. Fix is npm rebuild <pkg> per package or @lavamoat/allow-scripts for a team-wide allow-list.

Should I commit `.npmrc` to my repo?

Personal config goes in ~/.npmrc (never committed, user defaults). Project-level .npmrc at the repo root can be committed as long as it contains no secrets. Registry auth tokens belong only in ~/.npmrc, never in the repo.

Does this work for pnpm and yarn?

.npmrc is shared. pnpm reads ignore-scripts=true natively. Yarn classic also reads .npmrc. Yarn Berry uses .yarnrc.yml instead, and the equivalent setting is enableScripts: false. Bun also honors .npmrc.

Is `npm audit` still useful if I set `audit-level=moderate`?

Yes, and it becomes more useful. The flag changes audit from warn-mode to block-mode on CVEs at moderate severity or higher. Audit still only catches published CVEs. For zero-days, you need the hook layer from the hooks post.

Try it now: Open a terminal and run:

echo -e "ignore-scripts=true\nsave-exact=true\naudit-level=moderate\nfund=false" >> ~/.npmrc

Verify with npm config get ignore-scripts save-exact audit-level fund. Total time: under 30 seconds.

Ready for the process-level defense? Read → Stop npm Supply Chain Attacks with Claude Code Hooks.

Originally published on ShipWithAI. I write about Claude Code workflows, AI-assisted development, and shipping software faster with structured AI.

DEV Community: ShipWithAI

Git Worktrees for Agents: Parallel Loops Without Chaos

Two agents, one directory, two different disasters

Worktree vs branch — the distinction people get wrong

The three-role fleet

When to parallelize, when to serialize

The hands-on run

The orchestration tax

Prior art

Try it this week

Give Your Agent Loop a Heartbeat: Scheduled Automation Without the Runaway Bill

Three heartbeats

Hook or schedule?

The triage inbox — the part that keeps this safe

The morning triage loop

The empty run is your real cost

Prior art worth a look

Try it this week

Your Agent Loop Is Lying About Being Done: Writing Verifiable Stop Conditions

Why self-grading fails

The four rungs

Rewriting a wish into a condition

The checker agent

The hands-on run

Cap it three ways

Before you try this

Try it this week

Anatomy of an Agent Loop: 5 Building Blocks and One Memory Spine

The map

The spine is the part people skip

A real, minimal loop you can copy

What actually happened when it ran

Reading the trace

What breaks when a block is missing

Before you try this

Try it this week

Stop Prompting, Start Designing Loops: The Fourth Era of AI Coding

Four eras, and each one moved the skill upward

What actually counts as a loop

"It's just a cronjob with a rebrand"

The anti-pattern: "run it day and night until the feature is done"

Where the engineer's job goes

The six-item harness readiness checklist

Where this came from

What to do this week

We Wrote 8 Posts on Claude Code Harness Engineering. Then We Automated Our Own Advice

TL;DR

The Monday that broke the pattern

The discipline had no tooling

Two failure modes nobody warns you about

So we turned the series into one command

The two layers we haven't written about yet

Read every line before you run it

How to Review AI-generated Pull Requests in 6 Steps with Claude Code

How to Review AI-generated Pull Requests in 6 Steps with Claude Code

Prerequisites

Step 1 - Write the Expected Scope before opening the diff

Step 2 - Detect Fake Tests and Over-mocking

Step 3 - Verify API Call Signatures

Step 4 - Confirm the Diff stays inside the declared scope

Step 5 - Hunt for Hallucinated Imports and Hidden Side-effects

Step 6 - Align Commit Messages with the Diff

Decision: Ship or Reject?

Key Takeaways

Why Your AI Coach’s Warmth Might Be Hiding a Critical Regression

Intro

The problem: sycophancy

A concrete technique: the pushback eval

Key takeaways

Action

The Complete Claude Code Harness Engineering Guide (5 Layers, 8 Deep-Dives)

What is Claude Code harness engineering?

What are the 5 layers of a Claude Code harness?

Layer 1: What does your agent know before you type?

Layer 4: What can the agent NOT do?

Layer 5: How do you know what your agent actually did?

Why does this actually work?

Why does this matter for your career?

Where should you start reading?

FAQ

Step 1 - Write the Expected Scope before opening the diff

Step 2 - Detect Fake Tests and Over-mocking

Step 3 - Verify API Call Signatures

Step 4 - Confirm the Diff stays inside the declared scope

Step 5 - Hunt for Hallucinated Imports and Hidden Side-effects

Step 6 - Align Commit Messages with the Diff

Layer 1 – Enforce `npm ci`

Layer 2 – Validate lockfile integrity

Layer 3 – Dependency review action

Layer 4 – Pin actions to SHA

Layer 5 – OIDC trusted publishing

`ignore-scripts=true`

`save-exact=true`

`audit-level=moderate`

`fund=false`

What breaks when you set `ignore-scripts=true`?

Will `ignore-scripts=true` break my builds?

Should I commit `.npmrc` to my repo?

Is `npm audit` still useful if I set `audit-level=moderate`?