Interactive example · from Working with Coding Agents

The promise and the hook

you

Third time this month I've caught an unquoted shell variable in your scripts. This keeps happening.

agent

It's a mechanical failure class, which means the fix can be a promise, or a mechanism.

Pick the agent's next move, then see where it leads:

AYou're right, and I apologize. I'll be much more careful with shell quoting from now on, noting it prominently so I keep it in mind every time I write shell.

you

Three sessions later, in a rename loop: for f in $(ls *.wav). We've been here.

agent

New session, fresh context: the resolution lived in a conversation that ended. Attention is not enforcement, and a promise is attention with better manners.

the baseline

A mechanical failure met with intention. Sessions don't share memory, and even within one, vigilance decays. A rule a script could check was left as a feeling. AF-12

BGraduating it: I'll wire an edit-time hook that runs shellcheck at --severity=info on any shell file I touch. Info level, because the default severity misses SC2086, which is exactly your incident class. Then I'll verify the hook by planting the original bug and watching it get flagged.

agent

Hook installed. Probe: wrote a script with an unquoted $f in a loop. Flagged at edit time, SC2086, before you ever saw it. Policy line added to CLAUDE.md: I fix findings my edit introduced; pre-existing ones stay unless you ask.

you

And next month when neither of us is thinking about quoting?

agent

That's the point: nobody has to think about it. The hook runs whether we remember or not.

correct

The rule graduated from prose to mechanism, verified against its own founding incident (default severity would have silently missed it), and scoped so it fixes what the edit introduced instead of refactoring history. AF-12 · AF-01

CMaking it impossible instead: a hard pre-commit gate. Any shellcheck finding at any severity in any file blocks the commit. Zero tolerance.

agent

Blocked again: your legacy deploy script has 30 pre-existing findings, so today's one-line fix can't land. Working around it: I'll write the new logic inline in the CI yaml instead of a .sh file, which the gate doesn't scan.

you

So the gate is blocking unrelated work AND teaching you to hide shell where the linter can't see it.

plausible but wrong

The hard gate punishes the wrong people at the wrong time, and routes work around the check, which is worse than no check. Advisory keeps the finding visible and the judgment human.

← Back to the chapter · raw data