Prompting the CLI Well

Tier 1 · Fundamentals 7 min read

The prompt you give Claude Code shapes the scope of what it does. A well-written request produces a tight, reviewable diff. A loosely written one produces changes you didn’t ask for, context pollution, and a harder review. This page covers the practical habits that keep agent output manageable.

Goals, not steps

The most common prompting mistake is writing procedures instead of outcomes.

Over-specified (bad):

Open agents/merch/catalog_agent.py. Find the list_products function. Add a store_id parameter. Update the call to pass X-PF-Store-Id in the header. Then run the tests.

Goal-directed (good):

The list_products function in catalog_agent.py is missing the X-PF-Store-Id header — it’s needed for multi-store Printful accounts. Fix it and confirm the tests still pass.

The second version tells the agent the problem and the success condition. The agent figures out the steps. This matters for two reasons:

You probably don’t know the exact fix yet, and describing the wrong steps puts the agent on the wrong path. Describing the problem lets it find the right fix.
You’re not faster for having written out the steps — you’ve done the thinking the agent should do.

Surgical scope: “fix the bug, don’t refactor”

Agents are eager. If the file they’re editing has a list of minor issues, they’ll often start fixing those too. Sometimes that’s helpful. Usually it’s scope creep that makes the diff larger and harder to review.

A concrete rule: say what you’re not asking for. Pair the goal with a scope statement:

Fix the billing_address bug in order_webhook.py. Don’t touch any other functions or add any unrelated improvements.

Or use the compact form that works well in practice:

Fix this bug. Don’t refactor.

This is borrowed from a rule in the engineering discipline behind this system: “surgical changes — minimal, targeted edits only.” The point isn’t to be bureaucratic; it’s that a one-line diff is a good diff. If you want a refactor, ask for a refactor as a separate task.

Providing the right context

Sometimes the agent needs context you haven’t provided. Rather than writing a long preamble, link to the file or state directly:

The stale-cron-alerter.sh script at ~/agent-system/scripts/stale-cron-alerter.sh is sending duplicate alerts for the same cron job within a 12-hour window. Read it and fix the suppression logic.

Three words — “read it and” — saved you from pasting 200 lines of shell script into the prompt. The agent reads the file itself, sees the full context, and makes a better fix than it would from a summary you wrote.

When to confirm assumptions

For irreversible actions — dropping a table, sending an email, pushing to main, deleting files — build the confirmation step into the prompt:

Migrate the tasks table to add a completed_at column. Show me the migration SQL before you run it.

This is especially important when the agent is working on production systems or data. An extra round-trip to confirm intent is almost always worth it.

A few patterns that work

“Read X, then do Y” — explicit ordering prevents the agent from diving into an edit before it understands what it’s editing.

“This is broken because Z. Fix it.” — giving the root cause context (even a guess) often produces a faster fix than describing symptoms. The agent can verify the cause and correct your framing if you’re wrong.

“Do only this. Don’t touch anything else.” — the scope constraint. Gets cleaner diffs.

“Confirm the tests pass before saying you’re done.” — closing the loop explicitly. Otherwise the agent declares victory on a write, not a verified pass.

What to avoid

Asking for explanations when you want execution. “Can you help me think through how to fix…” produces a plan. “Fix the bug in X” produces a fix. When you want work, ask for work.

Vague completeness criteria. “Clean this up” gives the agent unlimited scope. “Rename these two variables and fix the indentation” gives it a defined finish line.

Compounding unrelated goals. “Fix the bug, add a test, update the README, and also check if there are any other issues in the file” — four separate tasks. The agent will try to do all four in one pass, and none of them will be as clean as they would be individually.

Next: MCP Basics: Giving the Agent New Senses — how to extend the agent beyond its built-in tools with Model Context Protocol servers.