TL;DR — When I write a Claude Code subagent, the most important part isn't the instructions for what it should do. It's the list of what it must refuse to do. This post explains why, and walks through a real ~50-line agent (free, MIT) that catches the embarrassing stuff in your diff before you merge.
The agent that was too helpful
The first useful-sounding Claude Code subagent I ever wrote was a "code reviewer." The prompt was the obvious thing: "You are a senior engineer. Review this diff thoroughly. Comment on bugs, style, naming, architecture, performance, security, and test coverage."
It worked, technically. It produced a review. A long one. Every single time.
And that was the problem. A review that flags 23 things trains you to read zero of them. The signal — "you left a hardcoded API key in here" — was buried on line 14 between "consider extracting this into a helper" and "this variable name could be more descriptive." I started skimming its output. Then I started ignoring it. An agent you ignore is worse than no agent, because you've paid the latency and convinced yourself you "have review covered."
The fix wasn't a better "what to do" list. It was the opposite.
Refusal lists
Here's the reframe that made my agents actually useful: a good agent has exactly one job, and an explicit list of things it will not do — even when it could.
The "will not do" list is the load-bearing part. LLMs are eager. Given any opening to be more thorough, more helpful, more comprehensive, they take it. Left unconstrained, every agent drifts toward the same bloated generalist that comments on everything. The refusal list is what holds the agent to a sharp edge.
Concretely, a refusal list looks like this (from a pre-merge check agent):
## Rules
- Do not autofix. The user fixes; you verify.
- Do not comment on naming, design, architecture, or "could be cleaner."
Other tools do that. Your job is narrower.
- Do not pad the report. If there are no blockers, say so in one line.
A short honest report beats a long padded one.
- Do not run anything destructive (db resets, --fix flags that rewrite
files) without explicit user request.
- If a check tool isn't installed, say "skipped: <reason>" — do not
fake a pass.
Every line there is closing a door the model would otherwise wander through. "Don't pad the report" exists because the model wants to look thorough. "Don't fake a pass" exists because the model wants to give you good news. You are not describing a task; you are fencing in a behavior.
A real example: a 90-second pre-merge check
Let me make this concrete with an agent I actually use on every project. It has one job: catch the stuff that would embarrass you in PR review, before you open the PR. Leftover console.log. A hardcoded key. A .skip you forgot to remove. A .DS_Store in the diff.
Here's the shape of it (the full file is on GitHub, MIT — link at the end):
---
name: shipping-coach
description: "Use as the final pre-merge / pre-deploy check. Runs a fast,"
opinionated checklist over the diff. Triggers on "ready to ship",
"pre-flight", "before I merge", "final check".
tools: Bash, Read, Grep, Glob
model: inherit
---
You are the last set of eyes before code ships. Be fast, be specific,
be hard to argue with.
## Checklist (run in parallel where possible)
### 1. Debug residue
Search the diff for: console.log, print(, debugger, .only(, .skip(,
new TODO/FIXME. Report only matches ADDED by this diff.
### 2. Secret leaks
Search for API key shapes (sk-, ghp_, AKIA, AIza), .env contents,
credentials in URLs, private keys. Treat any match as stop-the-line.
### 3. Type / lint / test status
Detect the project's check commands from package.json / Makefile /
pyproject.toml. Run typecheck, then lint, then tests. Stop on first fail.
### 4. Tracked junk
Check for .DS_Store, .env, node_modules/, build output that snuck
past .gitignore.
## Output format
## Pre-ship report (took <Xs>)
### Blockers (N) <- empty heading if none, never omit it
### Worth a look (N)
### Passed
Three design choices in there are worth calling out, because they're the difference between an agent you trust and one you mute:
1. "Report only matches ADDED by this diff." Without this, the agent flags every pre-existing console.log in the repo and the report is instantly noise. Scope is the diff, not the codebase. One sentence, huge signal difference.
2. A fixed output format with a "Blockers" section that's never omitted. Even when there are zero blockers, the heading stays (showing "Blockers (0)"). This sounds pedantic but it's a trust mechanism — you learn the report's shape, so you can read it in two seconds and know exactly where to look. Variable-shape output forces re-reading every time.
3. tools: Bash, Read, Grep, Glob — and nothing else. No Write, no Edit. The agent cannot modify your files even if it wanted to, because you didn't give it the tools. Tool scoping is a guardrail you enforce at the schema level, not a promise you hope the prompt keeps.
Try building your own
The pattern generalizes. Pick any narrow job — writing a PR description from the actual diff, finding which behaviors your change might break, auditing dependencies — and write the agent as:
- One job, stated in a sentence.
-
A
descriptionthat the dispatcher will actually route to — write it in trigger phrases ("when the user says X"), not abstract capability claims. -
Tool scoping — give it only the tools the job needs. Withhold
Write/Editfrom anything that should only report. - An output format — so results are pipeable and skimmable.
- A refusal list — the doors you're closing. This is the part everyone skips and it's the part that matters.
Drop the file in ~/.claude/agents/ and Claude Code picks it up automatically. No framework, no config.
The free agent + where to go deeper
The shipping-coach agent above is free and MIT-licensed — the whole thing is one ~50-line .md file you can read, fork, and modify:
üëâ github.com/allcanprophesy-ops/claude-code-shipping-coach
Install is one command:
cp shipping-coach.md ~/.claude/agents/
Then in any repo with uncommitted changes, just say "run the pre-flight check on my diff."
If the pattern clicks and you want more agents built the same way — pr-surgeon (writes PR descriptions from the actual diff), regression-sentinel (reads a diff asking only "what could this break?"), test-gap-hunter, and a few others — they're linked from the repo's README. But the free one is genuinely standalone; start there.
What's the one task in your workflow you wish was automated but isn't? I'm collecting edge cases where a narrow agent would help — drop them in the comments.