Make your toolchain's errors legible to the agent

You ask Claude to fix a failing build. It comes back with a confident fix — for the wrong thing. Reading its reasoning, you realise it never saw the actual compiler error. What it saw was 180 lines of stack frames from your test wrapper, then a generic Command failed with exit code 1, and it worked backwards from those.

This is not a prompting problem. It is an output-plumbing problem, and Claude Code's own limits make it sharper than it is for a human at a terminal.

Why a failing command is the worst case

A human skims a wall of output and their eye lands on the one line that matters. Claude gets a fixed-size window, and a failure gets a much smaller one than a success:

Three consequences worth sitting with:

1. The failure budget is a third of the success budget, and it applies exactly when the output matters most.
2. Head-and-tail means the middle is what gets dropped. If your runner prints a banner and a wrapper trace first, and a summary line last, the informative error is in the part that vanishes.
3. There is no file path on the failure branch. Claude cannot go back and read the rest. What the excerpt contains is all it will ever have.

What to actually change

Do not rewrite your error handling. Pick the two or three failures your agent visibly gets stuck on and treat them as the interface they are.

Put the informative line before the generic one. If your test runner prints per-case failures and then a summary, make sure the per-case output is not buried under a framework banner. If a wrapper script catches an error and re-raises it, print the original message first and the wrapper's trace after. The rule of thumb: the first ~40 lines of a failure should tell you the file, the line, and what was wrong.

Make the noisy layer quieter, not the useful layer louder. --no-banner, --quiet, --reporter=dot, suppressing progress bars — anything that keeps ANSI churn and per-file ticks out of the excerpt. Claude Code already strips ANSI escape sequences from captured error output, but the text those sequences decorated still costs you budget.

Filter at the hook layer when you cannot change the tool. A PreToolUse hook on Bash can rewrite a test invocation to a failures-only form, or a PostToolUse hook can grep the output down before Claude sees it. The official docs present this as a token-cost measure; the legibility payoff is the same mechanism used for a different reason.

Teach it the entry points in CLAUDE.md. Which command builds, which runs one test file rather than the suite, where the logs land. A narrower command produces a shorter failure, which fits in the window.

Close the CI loop

The second half of the claim is that the agent should fetch CI results itself, so the cycle is write → test → push → watch → read the failure → fix, with no human relaying screenshots of a red check.

# the shape worth allowlisting — failed-step logs only, not the whole run
gh run list --branch "$(git branch --show-current)" --limit 5
gh run view --log-failed

gh run view --log-failed matters more than it looks: a full --log of a CI run is routinely megabytes, and piping that into a failing-command result is the head-and-tail problem again at ten times the scale.

Claude Code ships one turnkey version of this loop: /autofix-pr spawns a Claude Code on the web session that watches the current branch's PR and pushes fixes when CI fails or reviewers comment. It detects the PR with gh pr view, so it needs the gh CLI and web access. Use it when you want the loop to run while you are away; wire up gh directly when you want to stay in the terminal.

What is unverified here

The specific practice — deliberately reordering your own build and test output so the informative failure precedes the generic one — comes from a community transcript of a live coding session, not from Anthropic's documentation. The corpus says to give Claude a check that produces a readable pass/fail, and it documents the output limits above precisely. It says nothing about ordering your error output for an agent reader.

So the mechanism is documented and the practice is inferred from it. What would settle it is not an argument but a measurement: produce a failure whose useful line sits in the middle of a lot of noise, and see whether it survives into the transcript.

# a synthetic noisy failure: informative line buried between two walls of frames
cat > /tmp/noisy.py <<'EOF'
import sys
for i in range(600): print("  at wrapper.frame_%d (runner.js:%d)" % (i, i))
print("ERROR: type mismatch at src/auth/token.ts:42 — expected string, got number")
for i in range(600): print("  at teardown.frame_%d (runner.js:%d)" % (i, i))
sys.exit(1)
EOF
python3 /tmp/noisy.py; echo "exit=$?"

Run that inside a Claude Code session, then ask Claude what the error was. If it can name src/auth/token.ts:42, the excerpt caught it. If it describes wrapper frames, you have reproduced the failure mode this tip is about — on your own machine, with your own limits — and you now know whether reordering is worth the afternoon.