The most expensive sentence a coding agent writes is "Everything should work now." It is said with confidence, and sometimes it is even true. An agent's summary of its own work is the least reliable part of its output, because it describes what the agent meant to do, not what happened.
So on this site the rule is that every report arrives with evidence I can check without re-running anything: command output, numbers and screenshots. Most of the checks are ordinary tools that existed long before agents. The work is in making the agent run them every time, before it calls itself finished, and in refusing to merge when the evidence is missing.
Cheap and precise checks first, slow and visual ones last.
In what order should the checks run?
Cheapest and most precise first. A type error points at a line; a broken screenshot points at nothing in particular. For this site, a Vite, React and TypeScript app with Vercel functions, the sequence is:
-
npm run typecheck, which istsc -bacross the app, the API and the scripts. -
npm run lintwith oxlint, fast enough to run after every change. -
npm run build, which also runs the prerender step, so a page that crashes during server rendering fails here rather than in production. -
npm run budget, the bundle budget described below. - Screenshots of the pages the change touched, at a desktop and a phone width.
The GitHub Actions workflow runs the first four on every push and pull request. Agents run all five locally before reporting, because a red CI run after I have merged is a much slower loop than a red run inside the agent's own worktree.
What does a report have to contain?
The same format for every agent, every task.
Every agent gets the same report format. The files it changed. The actual output of each command, pasted, not paraphrased. For tests, the counts, because "tests pass" from an agent that skipped the suite looks exactly like the real thing. The budget numbers. Paths to the screenshots.
And a last section, which I read first: what it did not check. An agent that writes "I did not test the signed-in view" has saved me a bug. An agent that leaves the section empty after changing the editor has told me where to look. Asking for it explicitly matters, because agents rarely volunteer the limits of their own testing.
One honest gap: this site has no unit test suite. Its checks are types, lint, the build with its prerender step, the budget and screenshots, and for a mostly static portfolio that has been enough. On projects that do have tests, the counts go in the report, and a change that adds behaviour without adding a test gets sent back with a request for one.
How does a Stop hook make done mean green?
Telling an agent to run the checks works most of the time. To make the fast ones unconditional, this repo has a Stop hook: a script Claude Code runs whenever the agent tries to end its turn. If the script exits with code 2, the agent does not stop. It receives the script's stderr as feedback and keeps working. Both files below are committed in the repo, so every session and every worktree gets the same rule.
The agent cannot finish while the fast checks are red.
.claude/settings.json (Stop hook)
{
"hooks": {
"Stop": [
{
"hooks": [
{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify.sh", "timeout": 120 }
]
}
]
}
}
.claude/hooks/verify.sh
#!/usr/bin/env bash
# Stop hook: runs when the agent says it is done.
# If source files changed and typecheck or lint fails, exit 2 keeps the agent
# working and sends the errors back to it.
input=$(cat)
cd "${CLAUDE_PROJECT_DIR:-$(jq -r '.cwd' <<<"$input")}" || exit 0
# Second stop in a row after a block: let it end, so a fix it cannot make
# does not loop forever. The failure is still printed to the user.
active=$(jq -r '.stop_hook_active // false' <<<"$input")
# Only check when code changed (staged, unstaged or untracked).
changed=$( { git diff --name-only HEAD; git ls-files --others --exclude-standard; } 2>/dev/null |
grep -E '\.(ts|tsx|js|mjs)$' )
[[ -z "$changed" ]] && exit 0
out=$( { npx --no-install tsc -b && npx --no-install oxlint; } 2>&1 )
if [[ $? -ne 0 ]]; then
if [[ "$active" == "true" ]]; then
echo "verify.sh: checks still failing after one retry, stopping anyway." >&2
exit 0
fi
echo "Checks failed. Fix these before you finish:" >&2
tail -n 40 <<<"$out" >&2
exit 2
fi
exit 0
Three choices in that script are worth explaining. It only runs when a TypeScript or JavaScript file changed, staged, unstaged or untracked, so a turn spent on a blog draft or a question costs nothing, and a turn that touched code costs about 3.5 seconds. It runs only the fast checks, tsc -b and oxlint; a full build in a Stop hook would make every small answer slow, so the build and the budget stay in the instructions and in CI. And it forces at most one retry: the hook input carries stop_hook_active, which is true when the agent is already continuing because of this hook, and on that second stop the script lets it end instead of trapping the agent on an error it cannot fix. I tested it the obvious way, by planting export const n: number = "oops" in a new file: the first stop exits 2 with TS2322: Type 'string' is not assignable to type 'number', the second exits 0, and a clean change exits 0. The same settings file also wires a PreToolUse guard that blocks secret reads and pushes to main; that one is covered in harness engineering.
Bundle budgets in CI
Type checks catch broken code. They do not catch heavy code, and agents add weight casually: a date library for one format call, a whole icon set for three icons. This site has a 3D view built on three.js, which is large, so from the start it had a budget script, scripts/check-budget.mjs, that runs after the build in CI.
The numbers print on every build, so they land in every report.
scripts/check-budget.mjs (excerpt)
const html = readFileSync(join(dist, 'index.html'), 'utf8')
const refs = [...html.matchAll(/(?:src|href)="\/(assets\/[^"]+\.(?:js|css))"/g)].map((m) => m[1])
let initial = 0
for (const ref of new Set(refs)) {
const buf = readFileSync(join(dist, ref))
initial += gzipSync(buf).length
if (/three|fiber|drei/i.test(ref)) errors.push(`3D code is in the initial payload: ${ref}`)
}
console.log(`initial JS+CSS (gzip): ${fmt(initial)} / ${fmt(BUDGET.initialJsGzip)}`)
if (initial > BUDGET.initialJsGzip) errors.push('initial payload over budget')
It gzips every JS and CSS file that index.html loads up front and fails the build above 250 KB. It also fails if three.js appears in the initial chunks at all, by file name or by the string WebGLRenderer, because the 3D view has to stay lazy-loaded. Every image in public/shots must be webp, avif or svg and under 120 KB, which is one reason the diagrams in this post are SVG.
Today the initial payload is 91.5 KB of the 250 KB budget. The useful part is not the headroom. It is that the number is printed on every run, so it appears in every agent report, and a jump of a few dozen KB from one change is visible before merge instead of in a slow page months later.
Show me the screenshot
Two widths catch most layout breaks.
For anything visual, a passing build proves very little. CSS can be valid and still put the search box underneath the navbar. So agents take screenshots with Playwright, which this repo already uses to capture the project images in its gallery, at two sizes: 1440 by 900 for desktop, and 390 wide at 2x for a phone. Between them, those two widths catch most of the layout breaks worth catching.
The script is short enough that agents can run it without thinking about it, and its output is just file paths, which go straight into the report.
shot.mjs
import { mkdirSync } from 'node:fs'
import { chromium } from 'playwright'
const url = process.argv[2] ?? 'http://localhost:4173/blog'
const sizes = {
desktop: { viewport: { width: 1440, height: 900 }, deviceScaleFactor: 1 },
phone: { viewport: { width: 390, height: 844 }, deviceScaleFactor: 2 },
}
mkdirSync('shots', { recursive: true })
const browser = await chromium.launch()
for (const [name, options] of Object.entries(sizes)) {
const page = await browser.newPage(options)
await page.goto(url, { waitUntil: 'networkidle' })
await page.screenshot({ path: `shots/${name}.png`, fullPage: true })
console.log(`shots/${name}.png`)
await page.close()
}
await browser.close()
Then I open the images myself before merging. Not because the agent cannot look at a PNG (it can, and I ask it to check its own screenshots against the request first), but because the agent decided what "looks right" means when it wrote the code. A look from someone who did not write it is the whole point of review, and it takes seconds per image.
Evidence over trust
None of this assumes the agent is careless. It assumes what we assume of any engineer: "done" should come with something checkable. Agents simply make that cheap to ask for, since five commands and two screenshots cost them a minute. The habit that matters is on my side of the review. I do not merge a change whose report has no evidence in it, however confident the summary sounds. If the evidence is missing, the reply is short: run the checks and send the output. That reply costs me ten seconds and saves the much longer job of finding out myself.
- Order the checks
Typecheck, lint, build, budget, screenshots. Cheap and precise first.
- Fix the report format
Files, pasted output, test counts, budget numbers, screenshot paths, and what was not checked.
- Add a Stop hook for the fast checks
Exit 2 keeps the agent working until typecheck and lint pass.
- Put size in CI
A gzip budget and a per-image limit, printed on every run.
- Look at the screenshots
Two widths, opened by someone who did not write the code, before every merge.
Frequently asked questions
Why not trust a coding agent's summary of its work?
The summary describes what the agent meant to do, not what happened. Ask for evidence you can check without re-running anything: pasted command output, numbers and screenshots.
How does a Claude Code Stop hook keep an agent working?
Claude Code runs the hook script when the agent tries to end its turn. If the script exits with code 2, the agent does not stop: it gets the script's stderr as feedback and keeps working. The hook in this post runs only when source files changed, runs only tsc -b and oxlint, and gives up after one forced retry via stop_hook_active.
What bundle budget does this site use?
The JS and CSS that index.html loads up front must stay under 250 KB gzipped, three.js must not appear in the initial chunks, and every image in public/shots must be webp, avif or svg and under 120 KB.
Which screen sizes should agents screenshot?
Two: 1440 by 900 for desktop, and 390 wide at 2x for a phone. Between them they catch most layout breaks worth catching.
Originally published on my site. More posts and projects at mahmadmanzoor.com.





Top comments (12)
This is the part I stopped trusting at face value. I now require the agent to paste the exact commands it executed together with the pass/fail output for each step, and I do a quick manual spot-check of the resulting diff before marking the task done. A simple Stop hook that only runs the test suite is not enough when the suite itself misses edge cases; the printed command log lets me see whether lint, type-check, and build actually ran and succeeded. If any check is missing or shows a warning, I send the agent back with a concrete fix request. This extra step catches silent failures that a green test run would hide.
Printing the commands is a good check, because a green test run says nothing about what never ran. The spot-check on the diff is the part I wouldn't drop either.
Filling that section in changes how you use the agent, because it makes you name the edges of what it verified. Asking for it explicitly takes effort. An empty section on a change that touched the editor tells you more than a confident paragraph of prose. What made you put it last in the format but read it first?
It goes last because the agent can only say what it skipped once the rest of the report is filled in. I read it first because it tells me where to look before I trust anything above it.
A Stop hook is where done should be decided: the agent that wrote the code should not be the one declaring it finished. Put typecheck and build in the hook, so a run can't end on a failing check or on a claim alone.
Yes, that's the split I want: the agent can claim done, but the hook decides. Typecheck and build are a cheap place to start.
Ran into this exact problem building visual review into an agent loop. The gotcha that got me: resizing a full page screenshot down to fit a token budget can make a layout bug invisible in the resized image even though it is obvious at full res, so the agent happily approves broken layout. I build a screenshot tool for this, the resolution math is on my blog at slimsnap.ai/blog/screenshot-downscaling, if it's useful.
That's a nasty one, because the check passes and the screenshot looks fine. Keeping a full-res crop of the area under review would avoid losing the bug in the resize.
@ahmad_dogar_7d098f5e48f72 Agreed, and keeping it fast is the point. A hook that takes a minute gets skipped on the first bad day, and then it checks nothing.
Exactly, and a skipped hook still looks like a safety net, which is worse than not having one.
@ahmad_dogar_7d098f5e48f72 Yes. The agent can claim done, the hook decides. Typecheck and build are a cheap start, and tests that finish in seconds can go in the same hook.
Yes, tests that finish in seconds fit there too. I'd keep anything slow out, so the hook stays fast enough that nobody wants to bypass it.